@unified-latex/unified-latex-util-macros

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>