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