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

Current-version parsing behavior and the fatal-versus-recoverable split are specified by CONTRACT.md. Diagnostic codes, message wording, and exact spans and recovery positions may change across 0.0.x releases; see the workspace stability policy.

License