v0.10
Playground
JavaScriptParser

Parser

Python

Construct a Parser, parse LaTeX, configure strictness, and inspect the knowledge base.

Parserclass#

A knowledge-driven LaTeX parser.

Parser turns LaTeX source into a ParseResult by consulting the knowledge base for command and environment signatures. It does not normalize — use TransformEngine for that. Parsing never throws on malformed input; failures surface in the result. For the conceptual model, see the Parsing guide.

Since 0.4.0 the default is ParseConfig LENIENT (rejectUnknown: false, abortOnError: false). Per-call config is a camelCase overlay object: null / undefined / omitted means not set. Unknown keys, snake_case keys, arrays in object positions, and wrong scalar types throw TexformConfigError with a camelCase path. Omit knowledgeBase to share the default instance, or construct a KnowledgeBase to customize packages and entries.

TypeScript
import { Parser, KnowledgeBase } from 'texform';

const parser = new Parser();
parser.parse(String.raw`\frac{x}{y}`).document?.toLatex(); // '\\frac { x } { y }'
const restricted = new Parser({ knowledgeBase: new KnowledgeBase({ packages: ['base', 'ams'] }) });
See also
ParseResultTransformEngineParseConfigTexformConfigErrorKnowledgeBaseParsing

Parser#

Parser(options: ParserOptions | null | undefined)

Construct a parser with an optional shared knowledge base.

ParameterTypeDescription
optionsParserOptions | null | undefined
  • A ParserOptions object, or omit/null to load the default runtime packages with no customization.

parse#

parse(src: string, config: ParseConfig | null | undefined): ParseResult

Parse a LaTeX string into a ParseResult.

Never throws on malformed input: the result has one of three honest states (no tree, complete tree, or partial tree with Error nodes). Empty input ('') yields a clean, complete document, not null.

ParameterTypeDescription
srcstring
  • The LaTeX source string.
configParseConfig | null | undefined
  • A ParseConfig overlay, or omit/null for the defaults.
Returns
ParseResult —

The parse result (document and diagnostics).

TypeScript
const result = new Parser().parse(String.raw`\frac{x}{y}`);
const document = result.document;
const diagnostics = result.diagnostics;
See also
ParseResultParseConfig

defaultParseConfig#

defaultParseConfig(): Complete<ParseConfig>

Return this parser's complete default ParseConfig.

Every field is present. Use it as a starting point when you want to change one key and pass the rest through.

Returns
Complete<ParseConfig>
See also
ParseConfig

Knowledge-base lookups#

Query the knowledge the parser loaded. Predicate methods take a single name; lookup methods take name and a mode of "math" or "text" and return a knowledge-entry object or null.

knowledgeBase#

knowledgeBase(): KnowledgeBase
Returns
KnowledgeBase

Lifecycle#

free#

free(): void

Release the WASM handle for this parser immediately.

Prefer a using declaration so [Symbol.dispose]() runs at scope exit. After free(), further use is invalid. Skipping free() is safe: garbage collection still reclaims the handle, just not at a determined time. Call free() (or use using) when many short-lived parsers would otherwise accumulate WASM memory.

[Symbol.dispose]#

[Symbol.dispose](): void

Release the WASM handle. Same as Parser.free; used by using.

See also
Parser.free

ParserOptionsinterface#

FieldTypeDescription
knowledgeBaseKnowledgeBase | undefined—
defaultParseConfigParseConfig | null | undefined

Overlay applied to ParseConfig LENIENT as this parser's default.

ParseConfiginterface#

Parser strictness configuration overlay, as a plain object with camelCase keys. All fields are optional; null / undefined means not set. Unknown keys, snake_case keys, arrays in object positions, and wrong scalar types throw TexformConfigError with a path.

The two boolean axes are orthogonal: ParseConfig.rejectUnknown controls how unknown names are handled, while ParseConfig.abortOnError controls whether the parser stops at the first error or keeps recovering. Neither implies the other, and neither is equivalent to the resulting tree's Document.hasErrors signal.

FieldTypeDescription
rejectUnknownboolean | undefined

Reject unknown command and environment names. Default false.

When true, an unknown command or environment becomes an unknown-command / unknown-environment diagnostic. When false, unknown names are preserved as known: false nodes for lenient exploration.

abortOnErrorboolean | undefined

Stop at the first error per item instead of recovering. Default false.

When true (strict), the parser stops at the first error per item and produces no recovery Error nodes. When false (lenient), it keeps collecting diagnostics and emits Error placeholder nodes. The max-group-depth guard emits an Error node regardless of this setting. This is a parse-strictness knob, distinct from Document.hasErrors, which is a property of the resulting tree.

maxGroupDepthnumber | undefined

Maximum group nesting depth before the parser aborts a group. Default 128. Exceeding it emits a max-group-depth-exceeded diagnostic and an Error node unconditionally.

TypeScript
new Parser().parse(String.raw`\foobar{x}`, {
  rejectUnknown: true,
  abortOnError: true,
});
See also
TexformConfigErrorParseConfig.rejectUnknownParseConfig.abortOnErrorDocument.hasErrors

ParseResultinterface#

The outcome of Parser.parse (and TransformEngine.parse): an optional Document plus the diagnostics emitted while parsing.

There are exactly three honest states, and parse never throws on malformed input nor fabricates a placeholder tree:

  • Hard failure — document is null; the failure is described entirely by diagnostics.
  • Clean parse — document is a complete, editable tree with hasErrors() === false. Empty input ('') lands here, not in null.
  • Partial parse — document is present with hasErrors() === true; recovery preserved the unparseable parts as read-only Error nodes.
FieldTypeDescription
documentDocument | null

The parsed document, or null on a hard failure with no tree.

diagnosticsParseDiagnostic[]

Diagnostics emitted while parsing; may be empty on a clean parse.

See also
Parser.parseTransformEngine.parseDocument

ParseDiagnosticinterface#

One diagnostic emitted while parsing, describing a recovered or rejected condition.

Diagnostics are a separate channel from Error placeholder nodes: a diagnostic does not by itself make an otherwise editable tree read-only. Within a parser-produced result, however, a tree that Document.hasErrors always comes with at least one diagnostic.

FieldTypeDescription
kindParseDiagnosticKind | null

The diagnostic category, or null when uncategorized.

messagestring

Human-readable description of the problem.

spanSpan

Source span the diagnostic points at.

expectedstring[]

Tokens the parser expected at this position; may be empty.

foundstring | null

The token actually found, or null.

contextsParseDiagnosticContext[]

Enclosing-construct frames, outermost-relevant first; may be empty.

See also
Document.hasErrorsParseResult

ParseDiagnosticContextinterface#

One nested context frame attached to a ParseDiagnostic, locating the enclosing construct (such as the command or environment) the error occurred within.

FieldTypeDescription
labelstring

Human-readable label for the enclosing construct.

spanSpan

Source span of the enclosing construct.

See also
ParseDiagnostic

ParseDiagnosticKindtype#

"ambiguous-infix" | "argument-validation" | "command-mode-error" | "comment-truncated-argument" | "environment-mode-error" | "environment-name-mismatch" | "invalid-character" | "left-right-delimiter" | "max-group-depth-exceeded" | "raw-expected-found" | "text-script-error" | "unclosed-environment" | "unclosed-inline-math" | "unexpected-math-shift" | "unknown-command" | "unknown-environment"

The category of a ParseDiagnostic, or null when the parser emits a diagnostic without a specific category.

Each variant names a distinct recoverable or rejected parse condition, such as an unknown command, an argument-validation failure, or an unclosed inline math span.

See also
ParseDiagnostic

Spaninterface#

A source byte range, half-open as [start, end), indexing into the original LaTeX input.

FieldTypeDescription
startnumber

Inclusive start byte offset.

endnumber

Exclusive end byte offset.

SyntaxNodetype#

{ Root: { mode: SyntaxContentMode; children: SyntaxNode[] } } | { Group: { mode: SyntaxContentMode; kind: GroupKind; children: SyntaxNode[]; }; } | { Command: { name: string; args: ArgumentSlot[]; known: boolean } } | { Infix: { name: string; args: ArgumentSlot[]; left: SyntaxNode; right: SyntaxNode; }; } | { Declarative: { name: string; args: ArgumentSlot[] } } | { Environment: { name: string; args: ArgumentSlot[]; known: boolean; body: SyntaxNode; }; } | { Scripted: { base: SyntaxNode; subscript?: SyntaxNode; superscript?: SyntaxNode; }; } | { Prime: { count: number } } | { Error: { message: string; snippet: string } } | { Text: string } | { Char: string } | "ActiveSpace" | "AlignmentTab"

The lossless, immutable parse snapshot — the single serde wire format.

SyntaxNode is a plain object (not a class instance) that backs JSON snapshots, transport across the binding, and test fixtures. It can represent a partial parse: unparseable fragments survive as Error nodes. It carries no editing behavior; bridge it into an editable tree with Document.fromSyntax, and recover one with Document.toSyntax. The two conversions are symmetric over every node kind, including Error and Prime. A Prime node represents symbols in the current math list; Scripted supplies any superscript binding. A leading quote has an empty group as its scripted base. External snapshots cannot infer the old intent of a bare Prime node; reparse the source or update the tree explicitly.

See also
Document.fromSyntaxDocument.toSyntaxDocument

ContextItemtype#

{ target: "command"; name: string; kind: CommandKind; allowedMode: string; argspec: string; tags?: string[]; } | { target: "environment"; name: string; allowedMode: string; bodyMode: RuntimeContentMode; argspec: string; tags?: string[]; } | { target: "delimiter"; name: string; }

One custom knowledge entry supplied to KnowledgeBase through the items option, discriminated by target.

A command entry carries its kind, allowed mode, and argspec; an environment entry additionally carries its bodyMode; a delimiter entry registers a delimiter-control name. Unknown keys and disallowed fields throw TexformConfigError.

See also
KnowledgeBaseTexformConfigError

CommandInfointerface#

The knowledge-base entry for a command, returned by KnowledgeBase.lookupCommand and related lookups.

FieldTypeDescription
namestring

The command name, without the leading backslash.

kindCommandKind

The command's syntactic role (prefix, infix, declarative).

allowedModestring

The modes the command is allowed in.

specStringstring

The raw xparse-style argument-specification string.

fromPackagesstring[]

The knowledge packages that define this command.

tagsstring[]

Free-form classification tags.

argsParsedArgSpecSlot[]

The parsed argument slots, mirroring validateArgspec output.

See also
KnowledgeBase.lookupCommand

EnvInfointerface#

The knowledge-base entry for an environment, returned by KnowledgeBase.lookupEnv.

FieldTypeDescription
namestring

The environment name.

allowedModestring

The modes the environment is allowed in.

bodyModeRuntimeContentMode

The content mode the environment body is parsed in.

specStringstring

The raw xparse-style argument-specification string.

fromPackagesstring[]

The knowledge packages that define this environment.

tagsstring[]

Free-form classification tags.

argsParsedArgSpecSlot[]

The parsed argument slots for the environment's arguments.

See also
KnowledgeBase.lookupEnv

CharacterInfointerface#

The knowledge-base entry for a special character, returned by KnowledgeBase.lookupCharacter.

FieldTypeDescription
namestring

The character name, without the leading backslash.

allowedModestring

The modes the character is allowed in.

unicodeValuestring

The Unicode code point the character maps to, as a string.

attributesCharacterAttributesInfo

Rendering attributes such as mathvariant.

packagestring

The knowledge package that defines this character.

See also
KnowledgeBase.lookupCharacter

CharacterAttributesInfointerface#

Rendering attributes for a special character in the knowledge base.

FieldTypeDescription
mathvariantstring | null

The MathML mathvariant the character renders with, or null.

AllowedModetype#

"math" | "text" | "both"

The content modes a command, environment, or character is allowed in: "math", "text", or "both".

CommandKindtype#

"prefix" | "infix" | "declarative"

The syntactic role of a command in the knowledge base: "prefix" (takes its arguments after the control sequence), "infix" (binds operands on both sides, like \over), or "declarative" (a scope-affecting declaration).

ArgSpecKindInfotype#

{ type: "content"; mode: RuntimeContentMode } | { type: "operatorname" } | { type: "delimiter" } | { type: "csname" } | { type: "dimension" } | { type: "integer" } | { type: "keyval" } | { type: "column" } | { type: "star" }

The value kind one parsed argument slot accepts, with a type discriminator.

content carries the RuntimeContentMode its body parses in; the other variants are leaf kinds (operatorname, delimiter, csname, dimension, integer, keyval, column, star).

See also
RuntimeContentModeParsedArgSpecSlot

DelimiterTokenInfotype#

{ type: "char"; value: string } | { type: "control-seq"; value: string }

A single delimiter token in an argspec form: a literal char (such as () or a control-seq (such as langle).

ArgSpecFormInfotype#

{ type: "standard" } | { type: "star" } | { type: "group" } | { type: "until"; close: DelimiterTokenInfo } | { type: "delimited"; open: DelimiterTokenInfo; close: DelimiterTokenInfo } | { type: "paired"; pairs: Array<{ open: DelimiterTokenInfo; close: DelimiterTokenInfo }>; }

The syntactic form one parsed argument slot takes, with a type discriminator: a standard argument, a star flag, a brace group, a delimited argument bounded by an open/close pair, or a paired argument accepting any of several interchangeable delimiter pairs.

See also
ParsedArgSpecSlot