rd-ast 0.0.1

Canonical, producer-agnostic AST for R's Rd (documentation) format
Documentation

rd-ast

rd-ast is the canonical, producer-agnostic AST for R's Rd documentation format. It is the common target for help-database lowering and Rd source parsing.

Tree model

The tree is mostly generic. It has closed leaf kinds (Text, RCode, Verb, and Comment), a generic Tagged node carrying the known RdTag vocabulary and preserving unknown tag spellings as RdTag::Unknown, positional Group nodes, and the lossless Raw escape hatch for genuinely non-canonical structures. Producers must preserve ordering, whitespace, options, and unexpected content according to the producer/consumer contract.

Semantic views

Views are borrowed interpretations of the canonical tree; they do not replace its syntax-layer storage.

  • Document and section views expose standard metadata, repeated metadata, and custom section/subsection trees.
  • Link views interpret topic links, href, and S4-class links while leaving resolution and rendering to consumers.
  • List views expose itemize, enumerate, and describe containers and their items.
  • Tabular views expose column alignment, rows, cells, and structural diagnostics.
  • Figure views expose figure file arguments and an optional alt-text or expert-options second argument.
  • Equation views distinguish inline eqn and block deqn forms with LaTeX and optional ASCII content.
  • Encoding views expose the encoded and ASCII alternatives of enc.
  • Conditional views expose if and ifelse branches without selecting a format.
  • Method views expose method, S3method, and S4method names and arguments.
  • Example-control views classify dontrun, donttest, dontshow, dontdiff, and testonly wrappers.
  • System-macro views recognize the documented sibling sequences for curated system macros.
  • Generation-header views recognize roxygen generation comments and preserve the generator name and source paths.

Features and stability

The optional serde feature enables serde derives for AST values. The optional rds feature enables lowering from the rd-rds object model. The serde representation is not a stable interchange format: it is a same-version implementation detail, as documented by CONTRACT.md, and should not be treated as cross-version wire compatibility.

See the workspace stability policy for the 0.0.x compatibility and support commitments.

License

MIT; see the workspace license.