Parser

Parsing of QVR domain-specific language syntax.

parser

Parser for the quivers DSL.

The lexer/parser pipeline is delegated to panproto via the qvr tree-sitter grammar registered in panproto-grammars-all. The public parse entry point consumes .qvr source bytes and returns a Module of dataclass AST nodes.

This package's submodules group the walker logic by topic:

• ._registry for the panproto registry singleton, ParseError, and the _Tree view that every walker reads from.
• ._helpers for the low-level helpers _required_text, _required_field, _field_text, and _walk_draw_arg.
• .options for the [k=v, ...] option-block walkers.
• .expressions for type / space / morphism-expression / let-arith walkers.
• .program_steps for program-block step walkers.
• .statements for the top-level _walk_statement dispatcher and every per-declaration walker (object, morphism, deduction, contraction, signature, encoder, decoder, loss, ...).
• .core for the public parse / parse_file entry points and the whole-tree syntax validation that rejects ERROR and missing nodes.

Every public name is re-exported here so from quivers.dsl.parser import X keeps working unchanged.

ParseError

Bases: Exception

Raised when the .qvr source fails to parse or wrap into AST nodes.

parse

parse(source: str | bytes, file_path: str = '<source>') -> Module

Parse .qvr source bytes into a Module.

Source code in src/quivers/dsl/parser/core.py

def parse(source: str | bytes, file_path: str = "<source>") -> Module:
    """Parse `.qvr` source bytes into a `Module`."""
    if isinstance(source, str):
        source_bytes = source.encode("utf-8")
    else:
        source_bytes = source

    try:
        schema = _registry().parse_with_protocol("qvr", source_bytes, file_path)
    except panproto.PanprotoError as exc:
        raise ParseError(f"{file_path}: panproto failed to parse: {exc}") from exc
    tree = _Tree(schema, source_bytes)

    _reject_malformed(tree, file_path)

    root_id = next(
        (vid for vid in tree.vertices if tree.kind(vid) == "source_file"),
        None,
    )
    if root_id is None:
        raise ParseError(
            f"{file_path}: source failed to parse (the tree has no source_file "
            "root); check that every program body ends with a return step"
        )

    statements: list[Statement] = []
    for child in tree.positional(root_id):
        ckind = tree.kind(child)
        if ckind in ("line_comment", "block_comment"):
            # plain comments are extras and are dropped at parse time;
            # `#!` doc comments ride each declaration's `docs` field
            # and are attached by the per-declaration walkers.
            continue
        result = _walk_statement(tree, child)
        if isinstance(result, list):
            statements.extend(result)
        else:
            statements.append(result)
    return Module(statements=tuple(statements))

parse_file

parse_file(path: str | Path) -> Module

Parse a .qvr file at path.

Source code in src/quivers/dsl/parser/core.py

def parse_file(path: str | Path) -> Module:
    """Parse a `.qvr` file at `path`."""
    p = Path(path)
    return parse(p.read_bytes(), str(p))