r-packages-parser
Lossless, failure-tolerant parsing, validation, building, and editing of R
repository PACKAGES indexes.
crates.io | API documentation | repository
The package name is r-packages-parser; the Rust library name is r_packages.
use Packages;
let packages = parse;
assert_eq!;
assert_eq!;
assert_eq!;
Every record remains accessible even when its DCF structure or typed fields are malformed. The API provides record-scoped immutable edits, canonical builders, typed field parsing, and index validation while preserving untouched source text exactly.
See the workspace overview for the lower-level syntax and semantic-value crates.
Converting individual records
Conversions with r_description::Description support both borrowed and owned
values:
use Description;
use ;
let packages = parse;
let record = packages.record.unwrap;
let description = from;
let round_trip = try_from.unwrap;
assert_eq!;
Add r-description-parser as a dependency to use Description directly.
Conversion preserves every field, including custom fields and duplicate
declarations, in source order. Lookups remain case-sensitive and use the last
declaration. Missing metadata is never filled in, and invalid semantic values or
malformed DCF lines are retained without panicking or requiring validation.
Record-local text is preserved exactly: spacing, continuation indentation, line endings, and final-newline presence. Surrounding blank lines and PACKAGES record separators belong to the document and are excluded. DESCRIPTION syntax diagnostics are recomputed relative to the standalone record.
PackageRecord::try_from requires exactly one DESCRIPTION record. Empty or
blank-only documents return RecordConversionError::NoRecords; multiple records
return RecordConversionError::MultipleRecords. A single malformed record is
accepted. These conversions do not generate a filtered repository index.
Constructing documents from existing records
Packages::from_records accepts an iterator of owned or borrowed package records.
Normalization remains an explicit caller choice:
use ;
use ;
let mut records = Vecnew;
for name in
let packages = from_records;
assert_eq!;
let mixed = builder
.record
.record
.records
.build;
assert_eq!;
Assembly preserves record order and all record-local text, including custom and
duplicate fields, multiline values, Unicode, and malformed content. It does not
normalize, sort, deduplicate, filter, or validate existing records. Builder format
settings belong to RecordBuilder::format_style(...): every record is built
independently before being assembled. RecordBuilder::new(...) is equivalent to
PackageRecord::builder(...). Initial package/version fields are checked and
added fields must be structurally representable; full semantic validation remains
explicit, including for duplicate identity fields.
Empty input produces empty text. A single existing record is unchanged. Between
records, assembly inserts one blank separator line: if the preceding record has a
trailing newline, that newline convention is reused for the separator; otherwise,
two line endings configured by PackagesBuilder::line_ending(...) are added (LF
by default). This setting never reformats record content. The final record's newline
state is preserved. Document-level blank lines surrounding an original record
are not part of the record and are not copied.
Construction appends text into one buffer and parses the completed document once, with time and memory proportional to total input/output size.
For occasional immutable edits, packages.append_record(&record, LineEnding::Lf)
returns an updated document while preserving the original document text and
reusing existing blank separators. It uses the same boundary rules as assembly,
completing an unterminated trailing blank line when necessary. Repeated append
copies and reparses the growing document; use bulk assembly for large indexes.
Migrating to 0.4
- Build standalone records with
RecordBuilder::build()before passing them to.record(...)orappend_record(...). - Move
.format_style(...)from the document builder to the record builder. - Use
.record(...)and.records(...)for all record origins; no separate existing-record API is needed. - Pass a
LineEndingtoappend_recordinstead of aFormatStyle.
License
MIT