<!-- 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-visit

## What is this?

Functions to traverse a `unified-latex` Abstract Syntax Tree (AST). `visit` is
very similar to [estree-util-visit](https://github.com/syntax-tree/estree-util-visit).

## When should I use this?

If you want to recursively replace particular AST nodes.

## Install

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

```typescript
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 | <span color='gray'>Omitted</span> | Function to run for each node |
| options | `VisitOptions`                    | *see below*                   |

where

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

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

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