unified-latex-util-replace

What is this?

Functions to help modify a unified-latex Abstract Syntax Tree (AST).

When should I use this?

If you want to recursively replace particular AST nodes.

Install

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

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

unifiedLatexReplaceStreamingCommands

Unified plugin to replace all found streaming commands with their argument-style equivalents. This only applies to sections of the tree with no math ancestor.

Usage

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

options

PluginOptions

Type

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

function unifiedLatexReplaceStreamingCommands(
  options: PluginOptions
): (tree: Ast.Root) => void;

where

type PluginOptions = {
  replacers: Record<
    string,
    (content: Ast.Node[], streamingCommand: Ast.Macro) => Ast.Node | Ast.Node[]
  >;
};

Functions

firstSignificantNode(nodes, parbreaksAreInsignificant)

Returns the first non-whitespace/non-comment node in nodes. If there is no such node, null is returned.

function firstSignificantNode(
  nodes: Ast.Node[],
  parbreaksAreInsignificant: Boolean
): Ast.Node;

Parameters

| Param | Type | | :------------------------ | :----------- | | nodes | Ast.Node[] | | parbreaksAreInsignificant | Boolean |

firstSignificantNodeIndex(nodes, parbreaksAreInsignificant)

Returns the index of the first non-whitespace/non-comment node in nodes. If there is no such node, null is returned.

function firstSignificantNodeIndex(
  nodes: Ast.Node[],
  parbreaksAreInsignificant: Boolean
): number;

Parameters

| Param | Type | | :------------------------ | :----------- | | nodes | Ast.Node[] | | parbreaksAreInsignificant | Boolean |

lastSignificantNode(nodes, parbreaksAreInsignificant)

Returns the last non-whitespace/non-comment node in nodes. If there is no such node, null is returned.

function lastSignificantNode(
  nodes: Ast.Node[],
  parbreaksAreInsignificant: Boolean
): Ast.Node;

Parameters

| Param | Type | | :------------------------ | :----------- | | nodes | Ast.Node[] | | parbreaksAreInsignificant | Boolean |

lastSignificantNodeIndex(nodes, parbreaksAreInsignificant)

Returns the index of the last non-whitespace/non-comment node in nodes. If there is no such node, null is returned.

function lastSignificantNodeIndex(
  nodes: Ast.Node[],
  parbreaksAreInsignificant: Boolean
): number;

Parameters

| Param | Type | | :------------------------ | :----------- | | nodes | Ast.Node[] | | parbreaksAreInsignificant | Boolean |

replaceNode(ast, visitor)

Recursively replace nodes in ast. The visitor function is called on each node. If visitor returns a node or an array of nodes, those nodes replace the node passed to visitor. If null is returned, the node is deleted. If undefined is returned, no replacement happens.

function replaceNode(
  ast: Ast.Ast,
  visitor: (
    node: Ast.Node | Ast.Argument,
    info: VisitInfo
  ) =>
    | Ast.Node
    | Ast.Argument
    | (Ast.Node | Ast.Argument)[]
    | null
    | undefined
    | void
): void;

Parameters

| Param | Type | | :------ | :-------------------------------- | | ast | Ast.Ast | | visitor | Omitted |

replaceNodeDuringVisit(replacement, info)

Replaces the current node with replacement. It is assumed that the current node is in an array that is a child of a parent element. If this is not the case, the function will error.

function replaceNodeDuringVisit(
  replacement: Ast.Node | Ast.Argument | (Ast.Node | Ast.Argument)[],
  info: VisitInfo
): void;

Parameters

| Param | Type | | :---------- | :-------------------------------- | | replacement | Omitted | | info | VisitInfo |

where

type VisitInfo = {
  /**
   * If the element was accessed via an attribute, the attribute key is specified.
   */
  readonly key: string | undefined;
  /**
   * If the element was accessed in an array, the index is specified.
   */
  readonly index: number | undefined;
  /**
   * A list of ancestor nodes, `[parent, grandparent, great-grandparent, ...]`
   */
  readonly parents: (Ast.Node | Ast.Argument)[];
  /**
   * If the element was accessed in an array, the array that it is part of.
   */
  readonly containingArray: (Ast.Node | Ast.Argument)[] | undefined;
  /**
   * The LaTeX context of the current match.
   */
  readonly context: VisitorContext;
};

replaceStreamingCommand(ast, isStreamingCommand, replacer, options)

Given a group or a node array, look for streaming commands (e.g., \bfseries) and replace them with the specified macro. The "arguments" of the streaming command are passed to replacer and the return value of replacer is inserted into the stream.

By default, this command will split at parbreaks (since commands like \textbf{...} do not accept parbreaks in their contents) and call replacer` multiple times, once per paragraph.

Commands are also split at environments and at any macros listed in macrosThatBreakPars.

function replaceStreamingCommand(
  ast: Ast.Group | Ast.Node[],
  isStreamingCommand: (node: any) => node is Ast.Macro,
  replacer: (
    content: Ast.Node[],
    streamingCommand: Ast.Macro
  ) => Ast.Node | Ast.Node[],
  options: {
    macrosThatBreakPars?: string[];
    environmentsThatDontBreakPars?: string[];
  }
): Ast.Node[];

Parameters

| Param | Type | | :----------------- | :-------------------------------- | | ast | Ast.Group \| Ast.Node[] | | isStreamingCommand | Omitted | | replacer | Omitted | | options | Omitted |

replaceStreamingCommandInGroup(group, isStreamingCommand, replacer, options)

Process streaming commands in a group. If needed, "escape" the group. For example, {\bfseries xx} -> \textbf{xx}, but {foo \bfseries xx} -> {foo \textbf{xx}}.

function replaceStreamingCommandInGroup(
  group: Ast.Group,
  isStreamingCommand: (node: any) => node is Ast.Macro,
  replacer: (
    content: Ast.Node[],
    streamingCommand: Ast.Macro
  ) => Ast.Node | Ast.Node[],
  options: {
    macrosThatBreakPars?: string[];
    environmentsThatDontBreakPars?: string[];
  }
): Ast.Node[];

Parameters

| Param | Type | | :----------------- | :-------------------------------- | | group | Ast.Group | | isStreamingCommand | Omitted | | replacer | Omitted | | options | Omitted |