wdl_modules/
symbolic_path.rs

1//! Symbolic-module-path parsing.
2
3use std::fmt;
4use std::path::Path;
5use std::path::PathBuf;
6use std::str::FromStr;
7
8use thiserror::Error;
9use wdl_grammar::lexer::v1::is_ident;
10
11use crate::dependency::DependencyName;
12
13/// An error parsing a [`SymbolicPath`].
14#[derive(Debug, Error)]
15#[error(
16    "symbolic module path `{0}` does not match `<dep-name>[/<sub-path>]` with non-empty, \
17     non-`.`/`..` segments"
18)]
19pub struct SymbolicPathError(String);
20
21/// A symbolic module path.
22///
23/// The string form is `<dep-name>[/<sub-path>]`. The `<dep-name>` is the
24/// key declared under `dependencies` in the consumer's `module.json`; the
25/// optional `<sub-path>` addresses a specific document within a module.
26///
27/// Path components are case-sensitive.
28#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
29pub struct SymbolicPath {
30    /// The dependency name component.
31    dep_name: DependencyName,
32    /// The optional sub-path within the dependency source.
33    sub_path: Option<PathBuf>,
34}
35
36impl SymbolicPath {
37    /// Returns the dependency name component.
38    pub fn dep_name(&self) -> &DependencyName {
39        &self.dep_name
40    }
41
42    /// Returns the sub-path component, if present.
43    pub fn sub_path(&self) -> Option<&Path> {
44        self.sub_path.as_deref()
45    }
46}
47
48/// Validates that a string matches `<dep-name>[/<sub-path>]` where every
49/// component (the dep name and each sub-path segment) is a WDL identifier.
50fn validate(s: &str) -> Result<SymbolicPath, SymbolicPathError> {
51    let mut iter = s.split('/');
52    // SAFETY: `str::split` always yields at least one item, even on the
53    // empty string.
54    let head = iter.next().unwrap();
55
56    let dep_name =
57        DependencyName::try_from(head.to_string()).map_err(|_| SymbolicPathError(s.to_string()))?;
58
59    let mut sub_path = PathBuf::new();
60    let mut has_tail = false;
61    for segment in iter {
62        if !is_ident(segment) {
63            return Err(SymbolicPathError(s.to_string()));
64        }
65        sub_path.push(segment);
66        has_tail = true;
67    }
68
69    Ok(SymbolicPath {
70        dep_name,
71        sub_path: if has_tail { Some(sub_path) } else { None },
72    })
73}
74
75impl FromStr for SymbolicPath {
76    type Err = SymbolicPathError;
77
78    fn from_str(s: &str) -> Result<Self, Self::Err> {
79        validate(s)
80    }
81}
82
83impl fmt::Display for SymbolicPath {
84    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
85        f.write_str(self.dep_name.identifier())?;
86        if let Some(sub) = &self.sub_path {
87            for component in sub.iter() {
88                f.write_str("/")?;
89                f.write_str(&component.to_string_lossy())?;
90            }
91        }
92        Ok(())
93    }
94}
95
96#[cfg(test)]
97mod tests {
98    use super::*;
99
100    #[test]
101    fn parses_dep_only() {
102        let p: SymbolicPath = "spellbook".parse().unwrap();
103        assert_eq!(p.dep_name().identifier(), "spellbook");
104        assert!(p.sub_path().is_none());
105    }
106
107    #[test]
108    fn parses_with_sub_path() {
109        let p: SymbolicPath = "spellbook/cauldron".parse().unwrap();
110        assert_eq!(p.dep_name().identifier(), "spellbook");
111        assert_eq!(p.sub_path().unwrap(), Path::new("cauldron"));
112    }
113
114    #[test]
115    fn parses_multi_segment_sub_path() {
116        let p: SymbolicPath = "spellbook/cauldron/runes".parse().unwrap();
117        assert_eq!(p.sub_path().unwrap(), Path::new("cauldron/runes"));
118    }
119
120    #[test]
121    fn rejects_invalid_format() {
122        for bad in [
123            "spellbook/",
124            "spellbook//cauldron",
125            "spellbook/cauldron/",
126            "spellbook/..",
127            "spellbook/.",
128            "1spellbook/cauldron",
129            "spellbook/has-dash",       // non-identifier sub-path segment
130            "spellbook/has space",      // whitespace
131            "spellbook/cauldron.runes", // non-identifier
132        ] {
133            assert!(bad.parse::<SymbolicPath>().is_err(), "accepted `{bad}`");
134        }
135    }
136
137    #[test]
138    fn case_sensitive() {
139        let lower: SymbolicPath = "spellbook/cauldron".parse().unwrap();
140        let mixed: SymbolicPath = "spellbook/Cauldron".parse().unwrap();
141        assert_ne!(lower.sub_path(), mixed.sub_path());
142    }
143
144    #[test]
145    fn round_trips_via_display() {
146        for s in [
147            "spellbook",
148            "spellbook/cauldron",
149            "spellbook/cauldron/runes",
150        ] {
151            let p: SymbolicPath = s.parse().unwrap();
152            assert_eq!(p.to_string(), s);
153        }
154    }
155}
wdl_modules/symbolic_path.rs

wdl_modules/
symbolic_path.rs
