r_description/lib.rs
1#![deny(missing_docs)]
2
3//! Lossless, failure-tolerant operations on R `DESCRIPTION` files.
4//!
5//! [`RDescription::parse`] always returns a recovered document, even when its
6//! DCF structure is malformed. Structural issues remain available through
7//! [`RDescription::syntax_issues`], while typed fields are validated only when
8//! their accessors are called. A malformed field therefore does not prevent
9//! access to valid unrelated fields.
10//!
11//! Unmodified syntax is retained byte-for-byte. Named setters validate and
12//! canonically format the field they replace while preserving unrelated syntax.
13//!
14//! ```rust
15//! use r_description::{RDescription, Relation};
16//!
17//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
18//! let source = "Package example\n\
19//! Version: 1.2-0\n\
20//! Imports: cli (>= 3.0), glue\n\
21//! URL: not-a-url\n";
22//! let description = RDescription::parse(source);
23//!
24//! assert!(!description.syntax_issues().is_empty());
25//! assert_eq!(description.version()?.as_str(), "1.2-0");
26//! let imports: Vec<Relation> = description.imports()?.collect();
27//! assert_eq!(imports.len(), 2);
28//! assert!(description.urls().is_err());
29//! assert_eq!(description.to_string(), source);
30//! # Ok(())
31//! # }
32//! ```
33//!
34//! Structural issues, [`Spanned`] values, and positioned collection errors use
35//! absolute ranges into the current document rendering. Standalone parsers and
36//! nested errors such as [`VersionParseError`] may use ranges relative to their
37//! typed input, as documented by those types. Reacquire document-relative
38//! issues and spanned values after mutation.
39
40mod description;
41mod relations;
42mod remotes;
43mod scalar;
44mod url;
45mod version;
46
47pub use ::url::Url;
48pub use deb822_lossless::{PositionedParseError, TextRange};
49pub use description::{FieldMutationError, RDescription, Spanned};
50pub use relations::{
51 DependsError, EnhancesError, ImportsError, InvalidRelationPackage, LinkingToError,
52 PositionedRelationParseError, Relation, RelationParseError, SuggestsError, VersionRequirement,
53};
54pub use remotes::{
55 BioconductorCredentials, BioconductorRemote, CranRemote, GenericGitRemote, HostedGitRemote,
56 LocalRemote, PositionedRemoteParseError, Remote, RemoteMutationError, RemoteParseError,
57 RemoteSource, RemotesError, SvnRemote, UnknownRemote, UrlRemote,
58};
59pub use scalar::*;
60pub use url::{
61 AdditionalRepositoriesError, PositionedUrlParseError, UrlError, UrlMutationError, UrlParseError,
62};
63pub use version::{Version, VersionError, VersionParseError};