r_packages/conversion.rs
1//! Lossless single-record conversions to and from DESCRIPTION documents.
2
3use r_description::Description;
4
5use crate::PackageRecord;
6
7/// A DESCRIPTION document cannot be represented as a single package record.
8#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
9pub enum RecordConversionError {
10 /// The document contains no records (it is empty or contains only blank lines).
11 #[error("DESCRIPTION contains no records")]
12 NoRecords,
13 /// The document contains multiple records; conversion would discard metadata.
14 #[error("DESCRIPTION contains multiple records")]
15 MultipleRecords,
16}
17
18/// Converts the exact record text into a standalone DESCRIPTION document.
19///
20/// All fields (including custom fields and duplicates), their order, and malformed
21/// text are retained. Lookup remains case-sensitive and last-declaration-wins.
22/// No semantic validation is performed and no missing metadata is invented.
23///
24/// Record-local spacing, continuation indentation, line endings, and the presence
25/// or absence of a final newline are preserved. Surrounding blank lines and
26/// record separators are document-level text and are not included. Syntax
27/// diagnostics are recomputed relative to the standalone document.
28impl From<&PackageRecord> for Description {
29 fn from(record: &PackageRecord) -> Self {
30 Self::parse(&record.to_string())
31 }
32}
33
34/// Owned equivalent of the lossless borrowed conversion.
35impl From<PackageRecord> for Description {
36 fn from(record: PackageRecord) -> Self {
37 Self::from(&record)
38 }
39}
40
41/// Converts a DESCRIPTION containing exactly one record into a package record.
42///
43/// The existing syntax record is retained, including unknown fields, duplicate
44/// declarations, malformed text, and exact record-local formatting. No semantic
45/// validation is performed: missing identity fields and invalid field values are
46/// accepted. Lookup remains case-sensitive and last-declaration-wins.
47/// Surrounding document-level blank lines are not part of the returned record.
48///
49/// Empty/blank documents return [`RecordConversionError::NoRecords`]; documents
50/// with multiple records return [`RecordConversionError::MultipleRecords`].
51impl TryFrom<&Description> for PackageRecord {
52 type Error = RecordConversionError;
53
54 fn try_from(description: &Description) -> Result<Self, Self::Error> {
55 let mut records = description.records();
56 let record = records.next().ok_or(RecordConversionError::NoRecords)?;
57 if records.next().is_some() {
58 return Err(RecordConversionError::MultipleRecords);
59 }
60 Ok(Self { record })
61 }
62}
63
64/// Owned equivalent of the lossless borrowed conversion.
65impl TryFrom<Description> for PackageRecord {
66 type Error = RecordConversionError;
67
68 fn try_from(description: Description) -> Result<Self, Self::Error> {
69 Self::try_from(&description)
70 }
71}