v0.10
Playground
PythonParser

Parser

JavaScript

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

Parserclass#

Turn LaTeX source into a parse result.

A Parser consults the knowledge base for command and environment signatures to build structured parse trees. It never raises on malformed input and never fabricates a placeholder tree; instead it reports diagnostics and, in lenient mode, preserves unparseable fragments as Error nodes.

Since 0.4.0 the default parse configuration is LENIENT (reject_unknown=False, abort_on_error=False). Per-call config must be a complete ParseConfig instance; a dict passed as config raises ConfigError. Other keywords are overlays (parse(src, reject_unknown=True)). Construct a KnowledgeBase to customize packages and records, then share it with parsers and engines.

For the conceptual model, see the Parsing guide.

Python
parser = texform.Parser()
result = parser.parse(r"\frac{x}{y}")
result["document"].to_latex()  # '\frac { x } { y }'
parser.parse(r"\frac{x}{y}", config=texform.ParseConfig(reject_unknown=True))
See also
ParseConfigDocumentParseResultParsing

Parser#

Parser(    knowledge_base: KnowledgeBase | None = None,    default_parse_config: ParseConfig | None = None,) -> None

Construct a parser; None uses the process-wide default knowledge base.

ParameterTypeDefault
knowledge_baseKnowledgeBase | NoneNone
default_parse_configParseConfig | NoneNone

parse#

parse(    src: str,    config: ParseConfig | None = None,    **overrides,) -> ParseResult

Parse a LaTeX string into a parse result.

Parsing never raises on malformed input. The result has exactly three honest states: a hard failure (document is None), a clean parse (a Document whose has_errors() is False), or a partial parse (a read-only Document whose has_errors() is True). Empty input is a clean parse, not None.

ParameterTypeDefaultDescription
srcstr—

The LaTeX source string.

configParseConfig | NoneNone

A complete ParseConfig; **overrides are layered on top. None uses the parser default. A dict here raises ConfigError.

**overridesUnpack[ParseOverrides]—

Keyword overlay from ParseOverrides. Nested values must be dicts, not config class instances.

Returns
ParseResult —

A ParseResult dict with two keys: document (a Document or None) and diagnostics (a list of diagnostic dicts).

Raises
  • ConfigError —

    If config is not a ParseConfig, a dict is passed as config, or an override key or value is invalid.

Python
result = texform.Parser().parse(r"\frac{x}{y}")
document = result["document"]
diagnostics = result["diagnostics"]
See also
ParseConfigParseResult

default_parse_config#

default_parse_config() -> ParseConfig

Return a new ParseConfig holding this parser's defaults.

Returns
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 dict or None.

knowledge_base#

knowledge_base() -> KnowledgeBase

Return the immutable knowledge base shared with parsed documents.

Returns
KnowledgeBase

ParseConfigclass#

Complete parse configuration. The only accepted config= type for parse.

Since 0.4.0 this is a complete configuration class, not a dict. Passing a dict as config raises ConfigError; use keyword overlays (parse(src, reject_unknown=True)) or construct this class and pass it as config. Constructor defaults match LENIENT (the parser and engine baseline on both language bindings): reject_unknown=False, abort_on_error=False, max_group_depth=128.

reject_unknown and abort_on_error are independent: the former decides how unknown names are handled, the latter is a strictness knob for error recovery. Neither is equivalent to a parsed tree's has_errors().

Python
cfg = texform.ParseConfig()
cfg.reject_unknown  # False
cfg.abort_on_error  # False
texform.Parser().parse(r"x", config=texform.ParseConfig(reject_unknown=True))
See also
Parser

reject_unknownattribute#

bool

When True, an unknown command or environment becomes a diagnostic; when False (default), unknown names are preserved as nodes for lenient exploration.

abort_on_errorattribute#

bool

When True (strict), the parser stops at the first error per item and produces no recovery Error nodes; when False (default, lenient), it keeps collecting diagnostics and emits Error nodes. The max-group-depth guard emits an Error node regardless of this setting.

max_group_depthattribute#

int

The maximum group nesting depth before the parser aborts a group. Defaults to 128.

ParseConfig#

ParseConfig(    reject_unknown: bool = False,    abort_on_error: bool = False,    max_group_depth: int = 128,) -> None

Construct a parse configuration.

ParameterTypeDefaultDescription
reject_unknownboolFalse

Whether to reject unknown command and environment names with diagnostics instead of preserving them as nodes.

abort_on_errorboolFalse

Whether to stop at the first error per item (strict) instead of collecting diagnostics and emitting Error nodes (lenient).

max_group_depthint128

The maximum group nesting depth before aborting.

ParseOverridesdict type#

Keyword overlays for parse. Omitted keys keep the baseline.

These are overlay keys, not a complete ParseConfig. Passing a dict as the config argument still raises ConfigError; use these keys as keywords (parse(src, reject_unknown=True)) or expand a saved dict with **overrides.

FieldTypeDescription
reject_unknownbool

Overlay for ParseConfig.reject_unknown.

abort_on_errorbool

Overlay for ParseConfig.abort_on_error.

max_group_depthint

Overlay for ParseConfig.max_group_depth.

ParseResultdict type#

The result of Parser.parse: an optional document plus diagnostics.

There are exactly three honest states, distinguished by document and the document's has_errors(): a hard failure (document is None), a clean parse (a Document whose has_errors() is False), and a partial parse (a read-only Document whose has_errors() is True). The parser never fabricates a placeholder tree, and empty input is a clean parse rather than None.

FieldTypeDescription
documentDocument | None

The parsed Document, or None on a hard failure.

diagnosticslist[ParseDiagnostic]

The diagnostics describing what the parser noticed.

See also
ParserDocumentParseDiagnostic

ParseDiagnosticdict type#

A single parse diagnostic emitted alongside a parse result.

Diagnostics are a channel separate from Error placeholder nodes: a diagnostic describes something the parser noticed, while an Error node is a recovered fragment in the tree. A tree that has_errors() always carries diagnostics, but the converse does not hold. All fields are optional.

FieldTypeDescription
kindParseDiagnosticKind

The diagnostic category, one of the ParseDiagnosticKind values such as "unknown-command" or "argument-validation".

messagestr

A human-readable description of the problem.

spanSpan

A {"start": int, "end": int} byte range into the source.

expectedlist[str]

The tokens that would have been accepted (may be empty).

foundstr

The token actually found, or absent when not applicable.

contextslist[dict[str, Any]]

Nested context dicts describing where the diagnostic arose (may be empty).

ParseDiagnosticKindtype#

Literal['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']

Category of a parse diagnostic, such as "unknown-command" or "argument-validation".

Spantype#

dict[str, int]

Half-open UTF-8 byte range {"start": int, "end": int} into the source.

SyntaxNodetype#

dict[str, Any]

Lossless parse snapshot as a plain dict. The tagged-union shape is documented on the TypeScript SyntaxNode type; Python keeps this alias unexpanded.

ContextItemtype#

CommandItem | EnvironmentItem | DelimiterItem

A knowledge-injection item: a command, environment, or delimiter-control dict.

CommandItemdict type#

A custom command injected into parser knowledge.

FieldTypeDescription
targetLiteral['command']

Discriminator; always "command".

namestr

Command name without the leading backslash.

kindLiteral['prefix', 'infix', 'declarative']

Syntactic role: "prefix", "infix", or "declarative".

allowed_modeLiteral['math', 'text', 'both']

Modes in which the command is valid: "math", "text", or "both".

argspecstr

xparse-style argument specification, such as "m m" or "o m".

tagsNotRequired[list[str]]

Optional free-form classification tags carried into the knowledge entry.

EnvironmentItemdict type#

A custom environment injected into parser knowledge.

FieldTypeDescription
targetLiteral['environment']

Discriminator; always "environment".

namestr

Environment name as written in \begin{...}.

allowed_modeLiteral['math', 'text', 'both']

Modes in which the environment may appear.

body_modeLiteral['math', 'text']

Content mode of the environment body ("math" or "text").

argspecstr

xparse-style argument specification for the environment header.

tagsNotRequired[list[str]]

Optional free-form classification tags.

DelimiterItemdict type#

A custom delimiter control injected into parser knowledge.

FieldTypeDescription
targetLiteral['delimiter']

Discriminator; always "delimiter".

namestr

Delimiter-control name without the leading backslash (for example "langle").