Rust crates for reading and modeling R documentation (Rd), from both the help databases of installed R packages and .Rd source text.
This repository is pre-release software in the 0.x series. APIs are unstable. The crates are published on crates.io. The test oracles are built against R 4.6.x, currently including R 4.6.1-generated fixtures.
See the stability policy, changelog, and release procedure for compatibility, support, and release-history details.
| Crate | Scope |
|---|---|
rd-rds |
Scoped, read-only RDS reader: decompressed parsing, a bounded file layer for gzip, xz, bzip2, and zstd envelopes, and typed package-metadata and selected repository-index views. |
rd-helpdb |
Reader for installed help databases: aliases.rds, .rdx/.rdb, and hsearch. |
rd-ast |
Canonical, producer-agnostic Rd document model and semantic views. |
rd-source |
Rd source parser producing rd_ast::RdDocument, conformant to tools::parse_Rd, with diagnostics and recovery. |
rd-writer |
Strict serializer from rd_ast::RdDocument back to Rd source text. |
- Scoped rather than general:
rd-rdsis not a general RDS library. Unknown SEXPs are hard errors, with a documented exception for selected environment internals that are consumed as opaque or discarded wire data. - Oracle-driven testing: fixtures are generated by committed R scripts. Differential tests compare with
tools::parse_Rd, including a mass corpus over installed base packages. - Producer-agnostic AST: help-database lowering and source parsing both target
rd-ast. LosslessRawandUnknownescape hatches are available to consumers operating in strict or lossy modes.
To accept gzip-enveloped .rds files while keeping the other codec
dependencies out of a consumer, disable default features on all three
relevant dependency edges. rd-helpdb's mandatory lazyload feature already
enables gzip for installed-package .rdx files, so its compatibility gzip
forwarding feature does not need to be named explicitly:
[dependencies]
rd-rds = { version = "0.5.0", default-features = false, features = ["gzip"] }
rd-helpdb = { version = "0.5.0", default-features = false }
rd-ast = { version = "0.5.0", default-features = false, features = ["rds", "gzip"] }All three settings are needed because Cargo unions features across dependency edges. Leaving even one of these crates at its defaults re-enables every codec in the unified dependency graph.
Workspace crates are under crates/. Fixtures live next to the tests that consume them: help-database fixtures under tests/fixtures/, RDS and Rd-object fixtures under crates/rd-rds/tests/fixtures/, and Rd source fixtures with their oracle scripts under crates/rd-source/tests/fixtures/. The rd-ast and rd-helpdb test suites use crate-local copies under crates/rd-ast/tests/fixtures/data/ and crates/rd-helpdb/tests/fixtures/data/ of artifacts generated elsewhere in the workspace; the copies stay crate-local so each packaged crate's tests run standalone and must remain byte-identical to their originals. The rd-rds fixture directory likewise contains copies of repo-root-generated artifacts alongside fixtures produced by its own scripts. Generated binary fixtures come from committed generator scripts; the hand-authored .Rd source cases under crates/rd-source/tests/fixtures/ are inputs, and the synthetic fixturepkg-package.rds fixture is generated by its documented fixture script. Copy locations are synchronized by copying, never regenerated in place, and CI enforces their byte identity. Run the standard test suite with:
cargo test --workspace --all-features
The regeneration scripts are needed only when regenerating fixtures; they are not required to run the committed tests. The Rd-source oracle and the envelope, package, and system-macro generators enforce R 4.6.1; the remaining generators do not enforce an R version but record the version used to produce the committed fixtures in their script headers.
This project is not affiliated with or endorsed by the R Foundation or the R Project; it reads file formats produced by R without incorporating R's code.
MIT