oxdock-parser

Parser and AST definitions for the OxDock DSL.

Part of the OxDock workspace.

1. The lexer (powered by pest) tokenizes scripts according to dsl.pest, handling comments and semicolons along the way.
2. Tokens are fed into the existing ScriptParser, which performs guard stack combination, scope tracking, and StepKind construction (no DSL behaviour changed from the previous hand-written line parser).
3. The resulting Vec<Step> is consumed by runtimes (CLI, macros, tests, etc.).

All existing semantics—including guard combinations, case sensitivity, semicolon behaviour, and error messages—remain the same, but they are now enforced through the shared grammar file.

The grammar lives in src/dsl.pest and is consumed directly by the lexer. A copy of the grammar is also exposed at runtime via the oxdock_parser::LANGUAGE_SPEC constant so that downstream tools can embed or inspect the canonical definition without reaching into the crate filesystem.

use oxdock_parser::LANGUAGE_SPEC;

fn dump_grammar() {
    println!("OxDock DSL grammar:\n{}", LANGUAGE_SPEC);
}

Because the parser is generated from this same file, the “spec” and the implementation stay in lockstep—the DSL is exactly what the grammar describes.

Every parse failure is a typed ParseError with a machine readable ParseErrorKind, a 1-based line number, an optional column span with source line and caret, the offending text when known, the expected syntax, and a hint with a concrete example. The contract beginners can rely on: a syntax error is never reported as unknown command. Any line that starts with a known command or structural keyword (WITH_IO, LET, FOR, IF, ASYNC, AWAIT, and the rest) always fails as invalid syntax for command X with an explanation of what was expected. Only a name that matches nothing in any case fails as unknown command.

The kinds:

• PestParse: the grammar could not tokenize the line at all. Always carries line, column span, source line, and caret, plus the expected rule set. Lowercase commands land here with an uppercase note.
• InvalidSyntax { command }: a known command or keyword with malformed arguments, flags, arity, or block shape. Carries the received text, the canonical syntax, and a hint.
• UnknownCommand { name }: a truly unknown name, with a did you mean hint when only the case is wrong.
• Structural { rule }: guard, block, scope, and structural keyword failures. Spans are refined to the exact offending pair, so the caret lands on the token (for example the BOOL in a bad FOR key type), never just the statement start.
• Validation { command }: arity, flag, and static argument type failures for a known command.

String and file parsers always populate line, column span, and source line. Token stream parsers (macro_input) leave the source line empty and keep integer coordinates instead, since proc_macro2::Span carries positions but not source text. Callers keep their own compiler span for syn::Error conversion. Downstream crates receive ParseError by value (ParseResult<T>) and convert to their own error type only at the outer boundary, so matching on kind, line, and columns never depends on message text.

oxdock-parser builds the executable steps for the OxDock DSL that powers the CLI and the embedding macros. The DSL is intentionally compact, but it now has an explicit grammar so that other tooling (formatters, language servers, IDE plugins, etc.) can understand scripts without re‑implementing the parser.

License

oxdock-parser is distributed under the terms of the Apache License (Version 2.0).