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

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[];

Parameters

| Param | Type | | :----------- | :----------- | | substitution | Ast.Node[] |

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 };
};

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;

Parameters

| Param | Type | | :----- | :-------------------------------- | | tree | Ast.Ast | | macros | Omitted |

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

would result in

\newcommand{\foo}{Y}
X

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

\newcommand{X}{Y}
X

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;

Parameters

| Param | Type | | :----- | :-------------------------------- | | tree | Ast.Ast | | macros | Omitted |

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[];

Parameters

| Param | Type | | :---- | :-------- | | tree | Ast.Ast |

newcommandMacroToName(node)

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

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

Parameters

| Param | Type | | :---- | :---------- | | node | Ast.Macro |

newcommandMacroToSpec(node)

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

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

Parameters

| Param | Type | | :---- | :---------- | | node | Ast.Macro |

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[];

Parameters

| Param | Type | | :---- | :---------- | | node | Ast.Macro |

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)[];

Parameters

| Param | Type | | :---- | :----------- | | ast | Ast.Node[] |

Constants

| Name | Type | | :------------------ | :--------------------------------------------- | | LATEX_NEWCOMMAND | Set<string> | | newcommandMatcher | Ast.TypeGuard<Ast.Macro & { content: any; }> | | XPARSE_NEWCOMMAND | Set<string> |