@unified-latex/unified-latex-util-parse

unified-latex-util-parse

What is this?

Functions parse strings to a unified-latex Abstract Syntax Tree (AST).

When should I use this?

If you have a string that you would like to parse to a unified-latex Ast.Ast, or if you are building a plugin for unified() that manipulates LaTeX.

Install

npm install @unified-latex/unified-latex-util-parse

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.

Plugins

unifiedLatexAstComplier

Unified complier plugin that passes through a LaTeX AST without modification.

Usage

unified().use(unifiedLatexAstComplier)

Type

Plugin<void[], Ast.Root, Ast.Root>

function unifiedLatexAstComplier(): void;

unifiedLatexFromString

Parse a string to a LaTeX AST.

Usage

unified().use(unifiedLatexFromString[, options])

options

{ mode?: "math" | "regular"; macros?: MacroInfoRecord; environments?: EnvInfoRecord; flags?: { atLetter?: boolean; expl3?: boolean; autodetectExpl3AndAtLetter?: boolean; }; }

Type

Plugin<{ mode?: "math" | "regular"; macros?: MacroInfoRecord; environments?: EnvInfoRecord; flags?: { atLetter?: boolean; expl3?: boolean; autodetectExpl3AndAtLetter?: boolean; }; }[], string, Ast.Root>

function unifiedLatexFromString(options: {
  mode?: "math" | "regular";
  macros?: MacroInfoRecord;
  environments?: EnvInfoRecord;
  flags?: {
    atLetter?: boolean;
    expl3?: boolean;
    autodetectExpl3AndAtLetter?: boolean;
  };
}): void;

unifiedLatexFromStringMinimal

Parse a string to a LaTeX AST with no post processing. For example, no macro arguments will be attached, etc.

Usage

unified().use(unifiedLatexFromStringMinimal[, options])

options

PluginOptions

Type

Plugin<PluginOptions[], string, Ast.Root>

function unifiedLatexFromStringMinimal(options: PluginOptions): void;

unifiedLatexProcessAtLetterAndExplMacros

Unified plugin to reprocess macros names to possibly include @, _, or :. This plugin detects the \makeatletter and \ExplSyntaxOn commands and reprocesses macro names inside of those blocks to include those characters.

Usage

unified().use(unifiedLatexProcessAtLetterAndExplMacros[, options])

options

{ atLetter?: boolean; expl3?: boolean; autodetectExpl3AndAtLetter?: boolean; }

Type

Plugin<{ atLetter?: boolean; expl3?: boolean; autodetectExpl3AndAtLetter?: boolean; }[], Ast.Root, Ast.Root>

function unifiedLatexProcessAtLetterAndExplMacros(options: {
  atLetter?: boolean;
  expl3?: boolean;
  autodetectExpl3AndAtLetter?: boolean;
}): (tree: Ast.Root) => void;

unifiedLatexProcessMacrosAndEnvironmentsWithMathReparse

Unified plugin to process macros and environments. Any environments that contain math content are reparsed (if needed) in math mode.

Usage

unified().use(unifiedLatexProcessMacrosAndEnvironmentsWithMathReparse[, options])

options

{ environments: EnvInfoRecord; macros: MacroInfoRecord; }

Type

Plugin<{ environments: EnvInfoRecord; macros: MacroInfoRecord; }[], Ast.Root, Ast.Root>

function unifiedLatexProcessMacrosAndEnvironmentsWithMathReparse(options: {
  environments: EnvInfoRecord;
  macros: MacroInfoRecord;
}): (tree: Ast.Root) => void;

unifiedLatexReparseMath

Reparse math environments/macro contents that should have been parsed in math mode but weren't.

Usage

unified().use(unifiedLatexReparseMath[, options])

options

{ mathEnvs: string[]; mathMacros: string[]; }

Type

Plugin<{ mathEnvs: string[]; mathMacros: string[]; }[], Ast.Root, Ast.Root>

function unifiedLatexReparseMath(options: {
  mathEnvs: string[];
  mathMacros: string[];
}): (tree: Ast.Root) => void;

Functions

getParser(options)

Returns the default unified-latex parser, or create a new one with the provided unifiedLatexFromString options

function getParser(options: {
  mode?: "math" | "regular";
  macros?: Ast.MacroInfoRecord;
  environments?: Ast.EnvInfoRecord;
  flags?: {
    atLetter?: boolean;
    expl3?: boolean;
    autodetectExpl3AndAtLetter?: boolean;
  };
}): FrozenProcessor<Ast.Root, Ast.Root, Ast.Root, void>;

Parameters

Param	Type	Description
options	Omitted	Plugin options of unifiedLatexFromString plugin.

parse(str)

Parse the string into an AST.

function parse(str: String): Ast.Root;

Parameters

Param	Type
str	String

parseMath(str)

Parse str into an AST. Parsing starts in math mode and a list of nodes is returned (instead of a "root" node).

function parseMath(str: string | Ast.Ast): Ast.Node[];

Parameters

Param	Type
str	string | Ast.Ast

parseMathMinimal(str)

Parse str to an AST with minimal processing. E.g., macro arguments are not attached to macros, etc. when parsed with this function.

The parsing assumes a math-mode context, so, for example, ^ and _ are parsed as macros (even though arguments are not attached to them).

function parseMathMinimal(str: String): Ast.Node[];

Parameters

Param	Type
str	String

parseMinimal(str)

Parse str to an AST with minimal processing. E.g., macro arguments are not attached to macros, etc. when parsed with this function.

function parseMinimal(str: String): Ast.Root;

Parameters

Param	Type
str	String

unifiedLatexReparseMathConstructPlugin({ mathEnvs, mathMacros, })

Construct the inner function for the unifiedLatexReparseMath plugin. This function should not be used by libraries.

function unifiedLatexReparseMathConstructPlugin({
  mathEnvs,
  mathMacros,
}: {
  mathEnvs: string[];
  mathMacros: string[];
}): (tree: Ast.Root) => void;

Parameters

Param	Type
{ mathEnvs, mathMacros, }	Omitted

Types

PluginOptions

export type PluginOptions =
    | {
          mode?: "math" | "regular";
          macros?: MacroInfoRecord;
          environments?: EnvInfoRecord;
          flags?: {
              /**
               * Whether to parse macros as if `\makeatletter` is set (i.e., parse `@` as a regular macro character)
               */
              atLetter?: boolean;
              /**
               * Whether to parse macros as if `\ExplSyntaxOn` is set (i.e., parse `_` and `:` as a regular macro character)
               */
              expl3?: boolean;
              /**
               * Attempt to autodetect whether there are macros that look like they should contain `@`, `_`, or `:`.
               * Defaults to `false`.
               */
              autodetectExpl3AndAtLetter?: boolean;
          };
      }
    | undefined;

Changelog

v1.8.1

• Changed Peggy to implement a caching parser to prevent large slowdown on some files.