unified-latex-util-macros

What is this?

Functions to manipulate macros and their arguments in a unified-latex Abstract Syntax Tree (AST).

When should I use this?

If you want to expand macros or get a list of macros defined via \newcommand.

Install

npm install @unified-latex/unified-latex-util-macros
Copy

This package contains both esm and commonjs exports. To explicitly access the esm export, import the .js file. To explicitly access the commonjs export, import the .cjs file.

Functions

createMacroExpander(substitution)

A factory function. Given a macro definition, creates a function that accepts the macro's arguments and outputs an Ast with the contents substituted (i.e., it expands the macro).

function createMacroExpander(
  substitution: Ast.Node[]
): (macro: Ast.Macro) => Ast.Node[];
Copy

Parameters

createMatchers()

function createMatchers(): {
  isHash: (node: Ast.Node) => boolean;
  isNumber: (node: Ast.Node) => boolean;
  splitNumber: (
    node: Ast.String
  ) =>
    | { number: number; rest: { type: string; content: string } }
    | { number: number; rest?: undefined };
};
Copy

expandMacros(tree, macros)

Expands macros in ast as specified by macros. Each macro in macros should provide the substitution AST (i.e., the AST with the #1, etc. in it). This function assumes that the appropriate arguments have already been attached to each macro specified. If the macro doesn't have it's arguments attached, its contents will be wholesale replaced with its substitution AST.

function expandMacros(
  tree: Ast.Ast,
  macros: { name: string; body: Ast.Node[] }[]
): void;
Copy

Parameters

expandMacrosExcludingDefinitions(tree, macros)

Expands macros in ast as specified by macros, but do not expand any macros that appear in the context of a macro definition. For example, expanding \foo to X in

\newcommand{\foo}{Y}
\foo
Copy

would result in

\newcommand{\foo}{Y}
X
Copy

If expandMacros(...) were used, macros would be expanded in all contexts and the result would be

\newcommand{X}{Y}
X
Copy

Each macro in macros should provide the substitution AST (i.e., the AST with the #1, etc. in it). This function assumes that the appropriate arguments have already been attached to each macro specified. If the macro doesn't have it's arguments attached, its contents will be wholesale replaced with its substitution AST.

function expandMacrosExcludingDefinitions(
  tree: Ast.Ast,
  macros: { name: string; body: Ast.Node[] }[]
): void;
Copy

Parameters

listNewcommands(tree)

List all new commands defined in tree. This lists commands defined LaTeX-style with \newcommand etc., and defined with xparse-style \NewDocumentCommand etc. It does not find commands defined via \def (it is too difficult to parse the argument signature of commands defined with \def).

function listNewcommands(tree: Ast.Ast): NewCommandSpec[];
Copy

Parameters

newcommandMacroToName(node)

Get the name of the macro defined with \newcommand/\renewcommand/etc..

function newcommandMacroToName(node: Ast.Macro): string;
Copy

Parameters

newcommandMacroToSpec(node)

Compute the xparse argument signature of the \newcommand/\renewcommand/etc. macro.

function newcommandMacroToSpec(node: Ast.Macro): string;
Copy

Parameters

newcommandMacroToSubstitutionAst(node)

Returns the AST that should be used for substitution. E.g., \newcommand{\foo}{\bar{#1}} would return \bar{#1}.

function newcommandMacroToSubstitutionAst(node: Ast.Macro): Ast.Node[];
Copy

Parameters

parseMacroSubstitutions(ast)

Parse for macro substitutions. For example, in "\foo{#1}", the #1 is recognized as a HashNumber ({type: "hash_number"}). Double hashes are automatically replaced with their single-hash substitutions.

The resulting AST is ready for substitutions to be applied to it.

function parseMacroSubstitutions(ast: Ast.Node[]): (Ast.Node | HashNumber)[];
Copy

Parameters

Constants