@unified-latex/unified-latex-util-visit

unified-latex-util-visit

What is this?

Functions to traverse a unified-latex Abstract Syntax Tree (AST). visit is very similar to estree-util-visit.

When should I use this?

If you want to recursively replace particular AST nodes.

Install

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

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

visit(tree, visitor, options)

Visit children of tree which pass a test

function visit<Opts extends VisitOptions>(
  tree: Ast.Ast,
  visitor:
    | Visitor<NarrowArraysBasedOnOptions<GuardFromOptions<Opts, Ast.Ast>, Opts>>
    | Visitors<
        NarrowArraysBasedOnOptions<GuardFromOptions<Opts, Ast.Ast>, Opts>
      >,
  options: VisitOptions
): void;

Parameters

Param	Type	Description
tree	Ast.Ast	Abstract syntax tree to walk
visitor	Omitted	Function to run for each node
options	VisitOptions	see below

where

type VisitOptions = {
  startingContext?: VisitorContext;
  /**
   * Type guard for types that are passed to the `visitor` function.
   */
  test?: (node: Ast.Ast, info: VisitInfo) => boolean;
  /**
   * Whether arrays will be sent to the `visitor` function. If falsy,
   * only nodes will be past to `visitor`.
   */
  includeArrays?: boolean;
};

Constants

Name	Type	Description
CONTINUE	Symbol	Continue traversing as normal
EXIT	Symbol	Stop traversing immediately
SKIP	Symbol	Do not traverse this node’s children

Types

VisitInfo

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

VisitorContext

export type VisitorContext = {
    /**
     * Whether the node is being processed in math mode.
     *
     * This happens when the node is a director or indirect child
     * of a math environment (e.g. `$abc$`), but not when an environment
     * re-establishes text mode (e.g. `$\text{abc}$`)
     */
    inMathMode?: boolean;
    /**
     * Whether the node has any ancestor that is processed in math mode.
     */
    hasMathModeAncestor?: boolean;
};