srs-document/node_modules/@unified-latex/unified-latex-util-catcode/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-catcode

## What is this?

Functions to identify regions of a `unified-latex` Abstract Syntax Tree (AST) that need to be reparsed because of different
category codes. For example, regions between `\makeatletter` and `\makeatother`.

## When should I use this?

If you need to identify regions of the AST that need to be reparsed.

## Install

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

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

## `findExpl3AndAtLetterRegionsInArray(tree)`

Find regions between `\ExplSyntaxOn...\ExplSyntaxOff` and `\makeatletter...\makeatother`.
Returns an object containing regions where one or both syntax's apply.

```typescript
function findExpl3AndAtLetterRegionsInArray(tree: Ast.Node[]): {
  explOnly: Region[];
  atLetterOnly: Region[];
  both: Region[];
};
```

**Parameters**

| Param | Type         |
| :---- | :----------- |
| tree  | `Ast.Node[]` |

## `findRegionInArray(tree, start, end)`

Find all contiguous segments in the array that are between start and end blocks.
The `start` and `end` are functions that determine when a region starts and ends.

```typescript
function findRegionInArray(
  tree: Ast.Node[],
  start: (node: Ast.Node) => boolean,
  end: (node: Ast.Node) => boolean
): Region[];
```

**Parameters**

| Param | Type                          |
| :---- | :---------------------------- |
| tree  | `Ast.Node[]`                  |
| start | `(node: Ast.Node) => boolean` |
| end   | `(node: Ast.Node) => boolean` |

## `hasReparsableMacroNames(tree, allowedTokens)`

Checks whether `tree` has a macro that could be reparsed given the `allowedTokens` but
do not do any reparsing. This function can be used in auto-detection schemes to determine if
macro names should actually be reparsed.

```typescript
function hasReparsableMacroNames(
  tree: Ast.Ast,
  allowedTokens: string | Set<string>
): boolean;
```

**Parameters**

| Param         | Type                    |
| :------------ | :---------------------- |
| tree          | `Ast.Ast`               |
| allowedTokens | `string \| Set<string>` |

## `hasReparsableMacroNamesInArray(tree, allowedTokens)`

Checks whether the array has a macro that could be reparsed given the `allowedTokens` but
do not do any reparsing. This function can be used in auto-detection schemes to determine if
macro names should actually be reparsed.

```typescript
function hasReparsableMacroNamesInArray(
  tree: Ast.Node[],
  allowedTokens: Set<string>
): boolean;
```

**Parameters**

| Param         | Type          |
| :------------ | :------------ |
| tree          | `Ast.Node[]`  |
| allowedTokens | `Set<string>` |

## `reparseExpl3AndAtLetterRegions(tree)`

Find regions between `\ExplSyntaxOn...\ExplSyntaxOff` and `\makeatletter...\makeatother`
and reparse their contents so that the relevant characters (e.g., `@`, `_`, and `:`) become
part of the macro names.

```typescript
function reparseExpl3AndAtLetterRegions(tree: Ast.Ast): void;
```

**Parameters**

| Param | Type      |
| :---- | :-------- |
| tree  | `Ast.Ast` |

## `reparseMacroNames(tree, allowedTokens)`

Reparses all macro names so that they may optionally include characters listed in `allowedTokens`.
This is used, for example, when parsing expl3 syntax which allows `_` to be used in a macro name (even though
`_` is normally stops the parsing for a macro name). Thus, a macro `\foo_bar:Nn` would be parsed as having
the name `foo_bar:Nn` rather than as `foo` followed by the strings `_`, `bar`, `:`, `Nn`.

```typescript
function reparseMacroNames(
  tree: Ast.Ast,
  allowedTokens: string | Set<string>
): void;
```

**Parameters**

| Param         | Type                    |
| :------------ | :---------------------- |
| tree          | `Ast.Ast`               |
| allowedTokens | `string \| Set<string>` |

## `reparseMacroNamesInArray(tree, allowedTokens)`

Reparses all macro names in the array so that they may optionally include characters listed in `allowedTokens`.
This is used, for example, when parsing expl3 syntax which allows `_` to be used in a macro name (even though
`_` is normally stops the parsing for a macro name).

```typescript
function reparseMacroNamesInArray(
  tree: Ast.Node[],
  allowedTokens: Set<string>
): void;
```

**Parameters**

| Param         | Type          |
| :------------ | :------------ |
| tree          | `Ast.Node[]`  |
| allowedTokens | `Set<string>` |