Skip to main content

r_metadata/
relation.rs

1//! Package dependency relations.
2
3use crate::{Span, Spanned, Version, VersionParseError};
4use std::str::FromStr;
5
6/// An R source-control revision such as `r56550`.
7#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
8pub struct Revision {
9    original: Box<str>,
10    number: u64,
11}
12
13impl Revision {
14    /// Returns the exact spelling supplied to the parser.
15    pub fn as_str(&self) -> &str {
16        &self.original
17    }
18    /// Returns the numeric revision.
19    pub const fn number(&self) -> u64 {
20        self.number
21    }
22}
23
24impl FromStr for Revision {
25    type Err = RevisionParseError;
26
27    fn from_str(input: &str) -> Result<Self, Self::Err> {
28        let digits = input
29            .strip_prefix('r')
30            .filter(|digits| !digits.is_empty())
31            .ok_or(RevisionParseError::Invalid)?;
32        if !digits.bytes().all(|byte| byte.is_ascii_digit()) {
33            return Err(RevisionParseError::Invalid);
34        }
35        let number = digits.parse().map_err(|_| RevisionParseError::Overflow)?;
36        Ok(Self {
37            original: input.into(),
38            number,
39        })
40    }
41}
42
43/// Error parsing an R source revision.
44#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
45pub enum RevisionParseError {
46    /// The value is not `r` followed by one or more ASCII digits.
47    #[error("revision must be r followed by ASCII digits")]
48    Invalid,
49    /// The numeric revision exceeds `u64`.
50    #[error("revision number is too large")]
51    Overflow,
52}
53
54impl std::fmt::Display for Revision {
55    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
56        f.write_str(&self.original)
57    }
58}
59
60/// The right-hand operand of a version requirement.
61#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
62pub enum RequirementVersion {
63    /// A numeric package version.
64    Version(Version),
65    /// An R source revision.
66    Revision(Revision),
67}
68
69impl RequirementVersion {
70    fn parse(input: &str) -> Result<Self, RequirementVersionParseError> {
71        if input.starts_with('r') {
72            return input
73                .parse()
74                .map(Self::Revision)
75                .map_err(RequirementVersionParseError::Revision);
76        }
77        input
78            .parse()
79            .map(Self::Version)
80            .map_err(RequirementVersionParseError::Version)
81    }
82}
83
84impl FromStr for RequirementVersion {
85    type Err = RequirementVersionParseError;
86
87    fn from_str(input: &str) -> Result<Self, Self::Err> {
88        Self::parse(input)
89    }
90}
91
92/// Error parsing a numeric version or an R source revision.
93#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
94pub enum RequirementVersionParseError {
95    /// Invalid numeric package version.
96    #[error("invalid package version: {0}")]
97    Version(#[source] VersionParseError),
98    /// Invalid R source revision.
99    #[error("invalid R revision: {0}")]
100    Revision(#[source] RevisionParseError),
101}
102
103impl From<Version> for RequirementVersion {
104    fn from(value: Version) -> Self {
105        Self::Version(value)
106    }
107}
108impl From<Revision> for RequirementVersion {
109    fn from(value: Revision) -> Self {
110        Self::Revision(value)
111    }
112}
113impl std::fmt::Display for RequirementVersion {
114    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
115        match self {
116            Self::Version(value) => value.fmt(f),
117            Self::Revision(value) => value.fmt(f),
118        }
119    }
120}
121
122/// A package version constraint.
123#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
124pub enum VersionRequirement {
125    /// No constraint.
126    Any,
127    /// `<`.
128    LessThan(RequirementVersion),
129    /// `<=`.
130    LessThanEqual(RequirementVersion),
131    /// `==`.
132    Equal(RequirementVersion),
133    /// `!=`.
134    NotEqual(RequirementVersion),
135    /// `>`.
136    GreaterThan(RequirementVersion),
137    /// `>=`.
138    GreaterThanEqual(RequirementVersion),
139}
140
141impl VersionRequirement {
142    /// Tests a numeric version. Revision requirements cannot match a package version.
143    pub fn matches(&self, candidate: &Version) -> bool {
144        let compare = |required: &RequirementVersion| match required {
145            RequirementVersion::Version(version) => Some(candidate.cmp(version)),
146            RequirementVersion::Revision(_) => None,
147        };
148        match self {
149            Self::Any => true,
150            Self::LessThan(v) => compare(v).is_some_and(std::cmp::Ordering::is_lt),
151            Self::LessThanEqual(v) => compare(v).is_some_and(std::cmp::Ordering::is_le),
152            Self::Equal(v) => compare(v).is_some_and(std::cmp::Ordering::is_eq),
153            Self::NotEqual(v) => compare(v).is_some_and(|o| !o.is_eq()),
154            Self::GreaterThan(v) => compare(v).is_some_and(std::cmp::Ordering::is_gt),
155            Self::GreaterThanEqual(v) => compare(v).is_some_and(std::cmp::Ordering::is_ge),
156        }
157    }
158}
159
160/// A case-sensitive package name and optional version requirement.
161///
162/// Ordering compares package names case-insensitively, then uses their exact
163/// spelling and version requirement as deterministic tie-breakers.
164#[derive(Debug, Clone, PartialEq, Eq, Hash)]
165pub struct Relation {
166    package: String,
167    requirement: VersionRequirement,
168}
169
170impl PartialOrd for Relation {
171    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
172        Some(self.cmp(other))
173    }
174}
175
176impl Ord for Relation {
177    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
178        self.package
179            .bytes()
180            .map(|byte| byte.to_ascii_lowercase())
181            .cmp(other.package.bytes().map(|byte| byte.to_ascii_lowercase()))
182            .then_with(|| self.package.cmp(&other.package))
183            .then_with(|| self.requirement.cmp(&other.requirement))
184    }
185}
186
187impl Relation {
188    /// Constructs a relation after checking list-syntax ambiguity.
189    ///
190    /// # Errors
191    ///
192    /// Returns [`InvalidRelationPackage`] when the name is empty or contains
193    /// whitespace, control characters, commas, or parentheses.
194    pub fn new(
195        package: impl Into<String>,
196        requirement: VersionRequirement,
197    ) -> Result<Self, InvalidRelationPackage> {
198        let package = package.into();
199        if !valid_package(&package) {
200            return Err(InvalidRelationPackage { package });
201        }
202        Ok(Self {
203            package,
204            requirement,
205        })
206    }
207    /// Constructs an unconstrained relation.
208    ///
209    /// # Errors
210    ///
211    /// Returns [`InvalidRelationPackage`] when the name cannot be represented
212    /// unambiguously in relation list syntax.
213    pub fn any(package: impl Into<String>) -> Result<Self, InvalidRelationPackage> {
214        Self::new(package, VersionRequirement::Any)
215    }
216    /// Returns the case-sensitive package name.
217    pub fn package(&self) -> &str {
218        &self.package
219    }
220    /// Returns the version requirement.
221    pub const fn requirement(&self) -> &VersionRequirement {
222        &self.requirement
223    }
224}
225
226impl std::fmt::Display for Relation {
227    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
228        f.write_str(&self.package)?;
229        let (op, version) = match &self.requirement {
230            VersionRequirement::Any => return Ok(()),
231            VersionRequirement::LessThan(v) => ("<", v),
232            VersionRequirement::LessThanEqual(v) => ("<=", v),
233            VersionRequirement::Equal(v) => ("==", v),
234            VersionRequirement::NotEqual(v) => ("!=", v),
235            VersionRequirement::GreaterThan(v) => (">", v),
236            VersionRequirement::GreaterThanEqual(v) => (">=", v),
237        };
238        write!(f, " ({op} {version})")
239    }
240}
241
242impl FromStr for Relation {
243    type Err = PositionedRelationParseError;
244    fn from_str(input: &str) -> Result<Self, Self::Err> {
245        let (value, mut issues) = parse_one(input, 0, input.len());
246        value
247            .filter(|_| issues.is_empty())
248            .map(|(value, _)| value)
249            .ok_or_else(|| {
250                issues
251                    .pop()
252                    .unwrap_or_else(|| issue(RelationParseError::Empty, 0, 0))
253            })
254    }
255}
256
257/// Recovered result of parsing a comma-separated relation list.
258#[derive(Debug, Clone, PartialEq, Eq, Default)]
259pub struct RelationList {
260    entries: Vec<Spanned<Relation>>,
261    issues: Vec<PositionedRelationParseError>,
262}
263
264impl RelationList {
265    /// Parses all entries, recovering after every comma.
266    pub fn parse(input: &str) -> Self {
267        let mut result = Self::default();
268        let segments = segments(input);
269        for (index, &(start, end)) in segments.iter().enumerate() {
270            if input[start..end].trim().is_empty()
271                && (segments.len() == 1 || index == segments.len() - 1)
272            {
273                continue;
274            }
275            let (entry, entry_issues) = parse_one(input, start, end);
276            if let Some((value, span)) = entry {
277                result.entries.push(Spanned { value, span });
278            }
279            result.issues.extend(entry_issues);
280        }
281        result
282    }
283    /// Returns valid entries in source order.
284    pub fn entries(&self) -> &[Spanned<Relation>] {
285        &self.entries
286    }
287    /// Returns all issues in source order.
288    pub fn issues(&self) -> &[PositionedRelationParseError] {
289        &self.issues
290    }
291    /// Splits the recovered result into owned vectors.
292    pub fn into_parts(self) -> (Vec<Spanned<Relation>>, Vec<PositionedRelationParseError>) {
293        (self.entries, self.issues)
294    }
295}
296
297/// Error constructing a relation from an ambiguous package name.
298#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
299#[error("invalid relation package name {package:?}")]
300pub struct InvalidRelationPackage {
301    package: String,
302}
303impl InvalidRelationPackage {
304    /// Returns the rejected package name.
305    pub fn package(&self) -> &str {
306        &self.package
307    }
308}
309
310/// A relation syntax error.
311#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
312pub enum RelationParseError {
313    /// Empty comma-delimited entry.
314    #[error("empty package relation")]
315    Empty,
316    /// Missing package name.
317    #[error("package relation is missing a package name")]
318    MissingPackage,
319    /// Package name contains list syntax or control characters.
320    #[error("invalid package name in relation")]
321    InvalidPackage,
322    /// Expected a parenthesized requirement.
323    #[error("expected a parenthesized version requirement")]
324    ExpectedVersionClause,
325    /// Missing `)`.
326    #[error("version requirement is missing a closing parenthesis")]
327    MissingClosingParenthesis,
328    /// Text follows `)`.
329    #[error("unexpected text after package relation")]
330    UnexpectedTrailingText,
331    /// Missing operator.
332    #[error("version requirement is missing a comparison operator")]
333    MissingOperator,
334    /// Unsupported operator.
335    #[error("unsupported version comparison operator")]
336    InvalidOperator,
337    /// Operator is not followed by whitespace.
338    #[error("version comparison operator must be followed by whitespace")]
339    MissingOperatorWhitespace,
340    /// Missing version operand.
341    #[error("version requirement is missing a version")]
342    MissingVersion,
343    /// Invalid version operand.
344    #[error("invalid required version: {0}")]
345    InvalidVersion(#[source] RequirementVersionParseError),
346}
347
348/// A relation error and its precise input span.
349#[derive(Debug, Clone, PartialEq, Eq)]
350pub struct PositionedRelationParseError {
351    error: RelationParseError,
352    span: Span,
353}
354impl PositionedRelationParseError {
355    /// Returns the typed issue.
356    pub const fn error(&self) -> &RelationParseError {
357        &self.error
358    }
359    /// Returns the relative byte span.
360    pub const fn span(&self) -> Span {
361        self.span
362    }
363    /// Alias for [`Self::span`].
364    pub const fn range(&self) -> Span {
365        self.span
366    }
367}
368impl std::fmt::Display for PositionedRelationParseError {
369    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
370        self.error.fmt(f)
371    }
372}
373impl std::error::Error for PositionedRelationParseError {
374    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
375        Some(&self.error)
376    }
377}
378
379#[allow(clippy::too_many_lines)]
380fn parse_one(
381    input: &str,
382    raw_start: usize,
383    raw_end: usize,
384) -> (Option<(Relation, Span)>, Vec<PositionedRelationParseError>) {
385    let (start, end) = trim_bounds(input, raw_start, raw_end);
386    if start == end {
387        return (None, vec![issue(RelationParseError::Empty, start, end)]);
388    }
389    let text = &input[start..end];
390    let package_len = text
391        .char_indices()
392        .find_map(|(i, c)| (c.is_whitespace() || matches!(c, '(' | ')' | ',')).then_some(i))
393        .unwrap_or(text.len());
394    if package_len == 0 {
395        return (
396            None,
397            vec![issue(RelationParseError::MissingPackage, start, start)],
398        );
399    }
400    let package = &text[..package_len];
401    if !valid_package(package) {
402        return (
403            None,
404            vec![issue(
405                RelationParseError::InvalidPackage,
406                start,
407                start + package_len,
408            )],
409        );
410    }
411    let mut cursor = skip_ws(input, start + package_len, end);
412    if cursor == end {
413        return (
414            Some((
415                Relation {
416                    package: package.into(),
417                    requirement: VersionRequirement::Any,
418                },
419                Span::new(start, end),
420            )),
421            vec![],
422        );
423    }
424    if input.as_bytes()[cursor] != b'(' {
425        return (
426            None,
427            vec![issue(
428                RelationParseError::ExpectedVersionClause,
429                cursor,
430                char_end(input, cursor),
431            )],
432        );
433    }
434    let open = cursor;
435    let mut issues = Vec::new();
436    let close = input[open + 1..end].find(')').map(|i| open + 1 + i);
437    let clause_end = close.unwrap_or(end);
438    if close.is_none() {
439        issues.push(issue(
440            RelationParseError::MissingClosingParenthesis,
441            end,
442            end,
443        ));
444    }
445    if let Some(close) = close {
446        cursor = skip_ws(input, close + 1, end);
447        if cursor != end {
448            issues.push(issue(
449                RelationParseError::UnexpectedTrailingText,
450                cursor,
451                end,
452            ));
453        }
454    }
455    let inner = skip_ws(input, open + 1, clause_end);
456    let Some((op, op_len)) = parse_operator(&input[inner..clause_end]) else {
457        let op_end = input[inner..clause_end]
458            .find(char::is_whitespace)
459            .map_or(clause_end, |i| inner + i);
460        issues.push(issue(
461            if inner == clause_end {
462                RelationParseError::MissingOperator
463            } else {
464                RelationParseError::InvalidOperator
465            },
466            inner,
467            op_end,
468        ));
469        return (None, issues);
470    };
471    let op_end = inner + op_len;
472    if op_end == clause_end {
473        issues.push(issue(RelationParseError::MissingVersion, op_end, op_end));
474        return (None, issues);
475    }
476    if !input[op_end..clause_end]
477        .chars()
478        .next()
479        .is_some_and(char::is_whitespace)
480    {
481        issues.push(issue(
482            RelationParseError::MissingOperatorWhitespace,
483            op_end,
484            char_end(input, op_end),
485        ));
486    }
487    let version_start = skip_ws(input, op_end, clause_end);
488    let version_end = clause_end
489        - (input[version_start..clause_end].len()
490            - input[version_start..clause_end].trim_end().len());
491    if version_start == version_end {
492        issues.push(issue(
493            RelationParseError::MissingVersion,
494            version_start,
495            version_start,
496        ));
497        return (None, issues);
498    }
499    let value = match RequirementVersion::parse(&input[version_start..version_end]) {
500        Ok(value) => value,
501        Err(error) => {
502            let span = match &error {
503                RequirementVersionParseError::Version(error) => error.span(),
504                RequirementVersionParseError::Revision(_) => None,
505            }
506            .map_or(Span::new(version_start, version_end), |s| {
507                Span::new(version_start + s.start(), version_start + s.end())
508            });
509            issues.push(PositionedRelationParseError {
510                error: RelationParseError::InvalidVersion(error),
511                span,
512            });
513            return (None, issues);
514        }
515    };
516    if !issues.is_empty() {
517        return (None, issues);
518    }
519    let requirement = match op {
520        "<" => VersionRequirement::LessThan(value),
521        "<=" => VersionRequirement::LessThanEqual(value),
522        "==" => VersionRequirement::Equal(value),
523        "!=" => VersionRequirement::NotEqual(value),
524        ">" => VersionRequirement::GreaterThan(value),
525        ">=" => VersionRequirement::GreaterThanEqual(value),
526        _ => unreachable!(),
527    };
528    (
529        Some((
530            Relation {
531                package: package.into(),
532                requirement,
533            },
534            Span::new(start, end),
535        )),
536        issues,
537    )
538}
539
540fn segments(input: &str) -> Vec<(usize, usize)> {
541    let mut start = 0;
542    let mut segments = input
543        .match_indices(',')
544        .map(|(end, _)| {
545            let segment = (start, end);
546            start = end + 1;
547            segment
548        })
549        .collect::<Vec<_>>();
550    segments.push((start, input.len()));
551    segments
552}
553fn trim_bounds(input: &str, start: usize, end: usize) -> (usize, usize) {
554    let s = &input[start..end];
555    (
556        start + s.len() - s.trim_start().len(),
557        end - (s.len() - s.trim_end().len()),
558    )
559}
560fn skip_ws(input: &str, mut at: usize, end: usize) -> usize {
561    while at < end {
562        let c = input[at..].chars().next().expect("cursor is in bounds");
563        if !c.is_whitespace() {
564            break;
565        }
566        at += c.len_utf8();
567    }
568    at
569}
570fn char_end(input: &str, at: usize) -> usize {
571    at + input[at..].chars().next().map_or(0, char::len_utf8)
572}
573fn issue(error: RelationParseError, start: usize, end: usize) -> PositionedRelationParseError {
574    PositionedRelationParseError {
575        error,
576        span: Span::new(start, end),
577    }
578}
579fn parse_operator(input: &str) -> Option<(&'static str, usize)> {
580    [">=", "<=", "==", "!=", ">", "<"]
581        .into_iter()
582        .find(|op| input.starts_with(op))
583        .map(|op| (op, op.len()))
584}
585fn valid_package(package: &str) -> bool {
586    !package.is_empty()
587        && !package
588            .chars()
589            .any(|c| c.is_control() || c.is_whitespace() || matches!(c, ',' | '(' | ')'))
590}