rd-source 0.3.1

Parser for R documentation source files into rd-ast documents
Documentation

rd-source

rd-source parses R documentation source files and produces the shared rd_ast::RdDocument model. It is a source producer rather than a second, source-specific document representation.

Parsing and recovery

The parser accepts UTF-8 Rd source, including R-like and verbatim contexts, comments, groups, options, and recognized Rd tags. A successful parse returns Parsed, containing the document and any diagnostics. Recoverable syntax problems are reported as diagnostics with Severity::Warning or Severity::Error while preserving a recovered document. Fatal input or resource failures return ParseError and no partial Parsed value; these include invalid UTF-8, embedded NUL bytes, an input larger than 64 MiB, unsupported encoding declarations, and excessive parser nesting.

Resource limits

The current implementation limits complete input to 64 MiB and parser frame nesting to 128 levels. These are implementation limits, not user-configurable parser options.

Conformance tests

The curated oracle corpus is catalogued in tests/fixtures/cases.toml and contains 76 cases at the time of writing. The committed fixtures are generated with pinned R scripts and compared with tools::parse_Rd; the parser's canonical output is lowered to the same rd_ast::RdDocument model used by other producers.

The mass differential test is opt-in and ignored by default. Run it by supplying RD_SOURCE_CORPUS as colon-separated roots of .Rd files and selecting the test explicitly, for example:

RD_SOURCE_CORPUS=/path/to/R/src/library cargo test -p rd-source --test corpus_differential -- --ignored

Stability

Parsing behavior and the fatal-versus-recoverable split are specified by CONTRACT.md, which requires parity with the pinned tools::parse_Rd oracle for grammar-native Rd syntax within the documented scope. Patch releases preserve parse results, diagnostic codes, spans, and recovery positions that already conformed to the previous release's contract, and may correct them where the previous behavior violated it. Diagnostic message text is not a machine-readable contract and may change in any release. See the workspace stability policy.

License

MIT; see the workspace license.