# unified-latex-builder
## What is this?
Functions to help build a `unified-latex` Abstract Syntax Tree (AST)
with [hyperscript](https://github.com/dominictarr/hyperscript)-like syntax.
## When should I use this?
If you want to programmatically create `Ast.Node` nodes.
## Install
```bash
npm install @unified-latex/unified-latex-builder
```
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
## `arg(args, special)`
Create an Argument. `special.braces` can optionally specify
the signature of the open/close marks that each argument uses. For example
arg("a", { braces: "[]" });
will result in arguments `[a]`. Valid braces are `*`, `[`, `{`, `<`, and `(`.
`null` may be passed as the value of an empty optional argument. If `null` is passed,
the `openBrace` and `closeBrace` of the argument will be set to empty strings and the
contents will be set to an empty array. For example,
args([null, "b"], { braces: "[]{}" });
will produce the same structure as if the the first "optional argument" were omitted in regular parsing.
```typescript
function arg(
args: CoercibleArgument | Ast.Node[],
special: ArgumentSpecialOptions
): Ast.Argument;
```
**Parameters**
| Param | Type |
| :------ | :-------------------------------- |
| args | Omitted |
| special | `ArgumentSpecialOptions` |
where
```typescript
type ArgumentSpecialOptions = {
braces?: string;
openMark?: string;
closeMark?: string;
};
```
## `args(args, special)`
Create an Argument list. `special.braces` can optionally specify
the signature of the open/close marks that each argument uses. For example
args(["a", "b"], { braces: "[]{}" });
will result in arguments `[a]{b}`. Valid braces are `*`, `[`, `{`, `(`, and `<`.
`null` may be passed as the value of an empty optional argument. If `null` is passed,
the `openBrace` and `closeBrace` of the argument will be set to empty strings and the
contents will be set to an empty array. For example,
args([null, "b"], { braces: "[]{}" });
will produce the same structure as if the the first "optional argument" were omitted in regular parsing.
```typescript
function args(
args: CoercibleArgument | CoercibleArgument[],
special: ArgumentsSpecialOptions
): Ast.Argument[];
```
**Parameters**
| Param | Type |
| :------ | :-------------------------------- |
| args | Omitted |
| special | `ArgumentsSpecialOptions` |
where
```typescript
type ArgumentsSpecialOptions = {
braces?: string;
defaultOpenMark?: string;
defaultCloseMark?: string;
};
```
## `env(name, body, envArgs, special)`
Create an Environment node.
```typescript
function env(
name: String,
body: CoercibleNode | CoercibleNode[],
envArgs: CoercibleArgument | CoercibleArgument[],
special: {}
): Ast.Environment;
```
**Parameters**
| Param | Type |
| :------ | :-------------------------------- |
| name | `String` |
| body | Omitted |
| envArgs | Omitted |
| special | `{}` |
## `m(name, marcoArgs, special)`
Create a Macro with the given `name`. The macro
may be followed by any number of arguments.
```typescript
function m(
name: String,
marcoArgs: CoercibleArgument | CoercibleArgument[],
special: MacroSpecialOptions
): Ast.Macro;
```
**Parameters**
| Param | Type |
| :-------- | :-------------------------------- |
| name | `String` |
| marcoArgs | Omitted |
| special | `MacroSpecialOptions` |
where
```typescript
type MacroSpecialOptions = {
escapeToken?: string;
};
```
## `s(value)`
Create a String node from `value`
```typescript
function s(value: string | Ast.String): Ast.String;
```
**Parameters**
| Param | Type |
| :---- | :--------------------- |
| value | `string \| Ast.String` |
# Constants
| Name | Type | Description |
| :--- | :--------------- | :--------------- |
| `SP` | `Ast.Whitespace` | Whitespace node. |