srs-document/node_modules/@unified-latex/unified-latex-util-parse/README.md

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

## What is this?

Functions parse strings to a `unified-latex` Abstract Syntax Tree (AST).

## When should I use this?

If you have a string that you would like to parse to a `unified-latex` `Ast.Ast`, or
if you are building a plugin for `unified()` that manipulates LaTeX.

## Install

```bash
npm install @unified-latex/unified-latex-util-parse
```

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

## `unifiedLatexAstComplier`

Unified complier plugin that passes through a LaTeX AST without modification.

### Usage

`unified().use(unifiedLatexAstComplier)`

### Type

`Plugin<void[], Ast.Root, Ast.Root>`

```typescript
function unifiedLatexAstComplier(): void;
```

## `unifiedLatexFromString`

Parse a string to a LaTeX AST.

### Usage

`unified().use(unifiedLatexFromString[, options])`

#### options

```typescript
{ mode?: "math" | "regular"; macros?: MacroInfoRecord; environments?: EnvInfoRecord; flags?: { atLetter?: boolean; expl3?: boolean; autodetectExpl3AndAtLetter?: boolean; }; }
```

### Type

`Plugin<{ mode?: "math" | "regular"; macros?: MacroInfoRecord; environments?: EnvInfoRecord; flags?: { atLetter?: boolean; expl3?: boolean; autodetectExpl3AndAtLetter?: boolean; }; }[], string, Ast.Root>`

```typescript
function unifiedLatexFromString(options: {
  mode?: "math" | "regular";
  macros?: MacroInfoRecord;
  environments?: EnvInfoRecord;
  flags?: {
    atLetter?: boolean;
    expl3?: boolean;
    autodetectExpl3AndAtLetter?: boolean;
  };
}): void;
```

## `unifiedLatexFromStringMinimal`

Parse a string to a LaTeX AST with no post processing. For example,
no macro arguments will be attached, etc.

### Usage

`unified().use(unifiedLatexFromStringMinimal[, options])`

#### options

```typescript
PluginOptions
```

### Type

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

```typescript
function unifiedLatexFromStringMinimal(options: PluginOptions): void;
```

## `unifiedLatexProcessAtLetterAndExplMacros`

Unified plugin to reprocess macros names to possibly include `@`, `_`, or `:`.
This plugin detects the `\makeatletter` and `\ExplSyntaxOn` commands and reprocesses macro names
inside of those blocks to include those characters.

### Usage

`unified().use(unifiedLatexProcessAtLetterAndExplMacros[, options])`

#### options

```typescript
{ atLetter?: boolean; expl3?: boolean; autodetectExpl3AndAtLetter?: boolean; }
```

### Type

`Plugin<{ atLetter?: boolean; expl3?: boolean; autodetectExpl3AndAtLetter?: boolean; }[], Ast.Root, Ast.Root>`

```typescript
function unifiedLatexProcessAtLetterAndExplMacros(options: {
  atLetter?: boolean;
  expl3?: boolean;
  autodetectExpl3AndAtLetter?: boolean;
}): (tree: Ast.Root) => void;
```

## `unifiedLatexProcessMacrosAndEnvironmentsWithMathReparse`

Unified plugin to process macros and environments. Any environments that contain math content
are reparsed (if needed) in math mode.

### Usage

`unified().use(unifiedLatexProcessMacrosAndEnvironmentsWithMathReparse[, options])`

#### options

```typescript
{ environments: EnvInfoRecord; macros: MacroInfoRecord; }
```

### Type

`Plugin<{ environments: EnvInfoRecord; macros: MacroInfoRecord; }[], Ast.Root, Ast.Root>`

```typescript
function unifiedLatexProcessMacrosAndEnvironmentsWithMathReparse(options: {
  environments: EnvInfoRecord;
  macros: MacroInfoRecord;
}): (tree: Ast.Root) => void;
```

## `unifiedLatexReparseMath`

Reparse math environments/macro contents that should have been parsed in math mode but weren't.

### Usage

`unified().use(unifiedLatexReparseMath[, options])`

#### options

```typescript
{ mathEnvs: string[]; mathMacros: string[]; }
```

### Type

`Plugin<{ mathEnvs: string[]; mathMacros: string[]; }[], Ast.Root, Ast.Root>`

```typescript
function unifiedLatexReparseMath(options: {
  mathEnvs: string[];
  mathMacros: string[];
}): (tree: Ast.Root) => void;
```

# Functions

## `getParser(options)`

Returns the default `unified-latex` parser, or create a new one with the
provided `unifiedLatexFromString` options

```typescript
function getParser(options: {
  mode?: "math" | "regular";
  macros?: Ast.MacroInfoRecord;
  environments?: Ast.EnvInfoRecord;
  flags?: {
    atLetter?: boolean;
    expl3?: boolean;
    autodetectExpl3AndAtLetter?: boolean;
  };
}): FrozenProcessor<Ast.Root, Ast.Root, Ast.Root, void>;
```

**Parameters**

| Param   | Type                              | Description                                        |
| :------ | :-------------------------------- | -------------------------------------------------- |
| options | <span color='gray'>Omitted</span> | Plugin options of `unifiedLatexFromString` plugin. |

## `parse(str)`

Parse the string into an AST.

```typescript
function parse(str: String): Ast.Root;
```

**Parameters**

| Param | Type     |
| :---- | :------- |
| str   | `String` |

## `parseMath(str)`

Parse `str` into an AST. Parsing starts in math mode and a list of
nodes is returned (instead of a "root" node).

```typescript
function parseMath(str: string | Ast.Ast): Ast.Node[];
```

**Parameters**

| Param | Type                |
| :---- | :------------------ |
| str   | `string \| Ast.Ast` |

## `parseMathMinimal(str)`

Parse `str` to an AST with minimal processing. E.g., macro
arguments are not attached to macros, etc. when parsed with this
function.

The parsing assumes a math-mode context, so, for example, `^` and `_` are
parsed as macros (even though arguments are not attached to them).

```typescript
function parseMathMinimal(str: String): Ast.Node[];
```

**Parameters**

| Param | Type     |
| :---- | :------- |
| str   | `String` |

## `parseMinimal(str)`

Parse `str` to an AST with minimal processing. E.g., macro
arguments are not attached to macros, etc. when parsed with this
function.

```typescript
function parseMinimal(str: String): Ast.Root;
```

**Parameters**

| Param | Type     |
| :---- | :------- |
| str   | `String` |

`unifiedLatexReparseMathConstructPlugin({
    mathEnvs,
    mathMacros,
})`
---

Construct the inner function for the `unifiedLatexReparseMath` plugin. This function should not be used by libraries.

```typescript
function unifiedLatexReparseMathConstructPlugin({
  mathEnvs,
  mathMacros,
}: {
  mathEnvs: string[];
  mathMacros: string[];
}): (tree: Ast.Root) => void;
```

**Parameters**

| Param                                         | Type                              |
| :-------------------------------------------- | :-------------------------------- |
| {&#xA;    mathEnvs,&#xA;    mathMacros,&#xA;} | <span color='gray'>Omitted</span> |

# Types

## `PluginOptions`

```typescript
export type PluginOptions =
    | {
          mode?: "math" | "regular";
          macros?: MacroInfoRecord;
          environments?: EnvInfoRecord;
          flags?: {
              /**
               * Whether to parse macros as if `\makeatletter` is set (i.e., parse `@` as a regular macro character)
               */
              atLetter?: boolean;
              /**
               * Whether to parse macros as if `\ExplSyntaxOn` is set (i.e., parse `_` and `:` as a regular macro character)
               */
              expl3?: boolean;
              /**
               * Attempt to autodetect whether there are macros that look like they should contain `@`, `_`, or `:`.
               * Defaults to `false`.
               */
              autodetectExpl3AndAtLetter?: boolean;
          };
      }
    | undefined;
```