mirror of
https://github.com/borbann-platform/srs-document.git
synced 2025-12-24 14:54:05 +01:00
123 lines
3.4 KiB
Markdown
123 lines
3.4 KiB
Markdown
<!-- 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;
|
||
};
|
||
```
|