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

> Tools for manipulating unified-latex ASTs

Latest version **1.8.4** (published 2026-04-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install @unified-latex/unified-latex-util-macros
pnpm add @unified-latex/unified-latex-util-macros
yarn add @unified-latex/unified-latex-util-macros
bun add @unified-latex/unified-latex-util-macros
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.8.4 |
| Published | 2026-04-03 |
| First published | 2022-05-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 8 |
| Unpacked size | 88.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 127 |
| Author | Jason Siefken |
| Maintainers | siefkenj |
| Keywords | pegjs, latex, parser, prettier, unified-latex, unified |

## Links

- npm: https://www.npmjs.com/package/@unified-latex/unified-latex-util-macros
- Repository: https://github.com/siefkenj/unified-latex
- Homepage: https://github.com/siefkenj/unified-latex#readme
- Issues: https://github.com/siefkenj/unified-latex/issues
- npm.io page: https://npm.io/package/@unified-latex/unified-latex-util-macros

## Dependencies (8)

- [@unified-latex/unified-latex-types](https://npm.io/package/@unified-latex/unified-latex-types.md) ^1.8.4
- [@unified-latex/unified-latex-util-match](https://npm.io/package/@unified-latex/unified-latex-util-match.md) ^1.8.4
- [@unified-latex/unified-latex-util-parse](https://npm.io/package/@unified-latex/unified-latex-util-parse.md) ^1.8.4
- [@unified-latex/unified-latex-util-pegjs](https://npm.io/package/@unified-latex/unified-latex-util-pegjs.md) ^1.8.4
- [@unified-latex/unified-latex-util-visit](https://npm.io/package/@unified-latex/unified-latex-util-visit.md) ^1.8.4
- [@unified-latex/unified-latex-util-replace](https://npm.io/package/@unified-latex/unified-latex-util-replace.md) ^1.8.4
- [@unified-latex/unified-latex-util-arguments](https://npm.io/package/@unified-latex/unified-latex-util-arguments.md) ^1.8.4
- [@unified-latex/unified-latex-util-print-raw](https://npm.io/package/@unified-latex/unified-latex-util-print-raw.md) ^1.8.4

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 1.8.4 (latest) — 2026-04-03
- 1.8.3 — 2025-06-16
- 1.8.2 — 2025-02-09
- 1.8.1 — 2024-10-21
- 1.8.0 — 2024-08-22
- 1.7.1 — 2024-03-19
- 1.7.0 — 2024-02-25
- 1.6.1 — 2024-02-18
- 1.6.0 — 2024-01-17
- 1.4.2 — 2023-09-30
- 1.4.0 — 2023-06-20
- 1.3.2 — 2023-04-26
- 1.3.1 — 2023-03-05
- 1.3.0 — 2023-02-06
- 1.2.2 — 2022-12-15
- … 12 more at https://npm.io/package/@unified-latex/unified-latex-util-macros/versions

## README

<!-- DO NOT MODIFY -->
<!-- This file was autogenerated by build-docs.ts -->
<!-- Edit the docstring in index.ts and regenerate -->
<!-- rather than editing this file directly. -->
# 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

```bash
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).

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

**Parameters**

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

## `createMatchers()`



```typescript
function createMatchers(): {
  isHash: (node: Ast.Node) => node is Ast.String;
  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.

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

**Parameters**

| Param  | Type                              |
| :----- | :-------------------------------- |
| tree   | `Ast.Ast`                         |
| macros | <span color='gray'>Omitted</span> |

## `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.

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

**Parameters**

| Param  | Type                              |
| :----- | :-------------------------------- |
| tree   | `Ast.Ast`                         |
| macros | <span color='gray'>Omitted</span> |

## `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`).

```typescript
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..

```typescript
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.

```typescript
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}`.

```typescript
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.

```typescript
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>`                                  |

---
_Source: https://npm.io/package/@unified-latex/unified-latex-util-macros · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._