Skip to main content

docsrs_cli/domain/
item_path.rs

1//! Validated rustdoc item path.
2
3use std::fmt;
4use std::str::FromStr;
5
6use crate::config::MAX_ITEM_PATH_CHARS;
7use crate::error::{AppError, AppResult, ErrorDetail, Subject};
8
9/// Validated rustdoc item path (`tokio::runtime::Runtime` or `runtime/Runtime`).
10#[derive(Debug, Clone, PartialEq, Eq, Hash)]
11pub struct ItemPath {
12    /// Original trimmed input (preserves `::` vs `/` only for Display of raw when needed).
13    raw: String,
14    /// Normalized path segments.
15    segments: Vec<String>,
16}
17
18impl ItemPath {
19    /// Parses an item path with `::` or `/` separators.
20    ///
21    /// # Errors
22    ///
23    /// Returns [`crate::error::ErrorKind::InvalidInput`] when the path is empty, too long, or
24    /// contains `.` / `..` segments.
25    pub fn parse(path: &str) -> AppResult<Self> {
26        let path = path.trim();
27        if path.is_empty() || path == "::" || path == "/" {
28            return Err(AppError::of(ErrorDetail::Empty {
29                subject: Subject::ItemPath,
30            }));
31        }
32        if path.chars().count() > MAX_ITEM_PATH_CHARS {
33            return Err(AppError::of(ErrorDetail::TooLong {
34                subject: Subject::ItemPath,
35                limit: MAX_ITEM_PATH_CHARS,
36            }));
37        }
38        let normalized = path.replace('/', "::");
39        let parts: Vec<String> = normalized
40            .split("::")
41            .map(|s| s.trim().to_string())
42            .filter(|s| !s.is_empty())
43            .collect();
44        if parts.is_empty() {
45            return Err(AppError::of(ErrorDetail::ItemPathNoSegments));
46        }
47        let mut segments = Vec::with_capacity(parts.len());
48        for seg in &parts {
49            if seg == "." || seg == ".." {
50                return Err(AppError::of(ErrorDetail::Invalid {
51                    subject: Subject::ItemPathSegment,
52                    value: seg.to_string(),
53                }));
54            }
55            if seg.chars().any(|c| c.is_whitespace()) {
56                return Err(AppError::of(ErrorDetail::ContainsWhitespace {
57                    subject: Subject::ItemPathSegment,
58                    value: seg.to_string(),
59                }));
60            }
61            // Accept hyphen (crates.io style) and normalize to underscore (rustc paths).
62            if !seg
63                .chars()
64                .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-')
65            {
66                return Err(AppError::of(ErrorDetail::ItemPathSegmentCharset {
67                    segment: seg.to_string(),
68                }));
69            }
70            segments.push(crate::item_kind::rustc_crate_name(seg));
71        }
72        Ok(Self {
73            raw: path.to_string(),
74            segments,
75        })
76    }
77
78    /// Path segments after normalization.
79    #[must_use]
80    pub fn segments(&self) -> &[String] {
81        &self.segments
82    }
83
84    /// Owned segment list (for APIs that still take `Vec<String>`).
85    #[must_use]
86    pub fn into_segments(self) -> Vec<String> {
87        self.segments
88    }
89
90    /// Original trimmed input string.
91    #[must_use]
92    pub fn as_str(&self) -> &str {
93        &self.raw
94    }
95}
96
97impl AsRef<str> for ItemPath {
98    fn as_ref(&self) -> &str {
99        self.as_str()
100    }
101}
102
103impl fmt::Display for ItemPath {
104    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
105        f.write_str(&self.segments.join("::"))
106    }
107}
108
109impl FromStr for ItemPath {
110    type Err = AppError;
111
112    /// Parses via [`ItemPath::parse`].
113    ///
114    /// # Errors
115    ///
116    /// Returns [`crate::error::ErrorKind::InvalidInput`] for empty, oversized, or illegal paths.
117    fn from_str(s: &str) -> Result<Self, Self::Err> {
118        Self::parse(s)
119    }
120}
121
122#[cfg(test)]
123mod tests {
124    use super::*;
125    use crate::config::MAX_ITEM_PATH_CHARS;
126
127    #[test]
128    fn item_path_segments_and_display() {
129        let p = ItemPath::parse("clap::Parser").unwrap();
130        assert_eq!(p.segments(), &["clap".to_string(), "Parser".to_string()]);
131        assert_eq!(p.to_string(), "clap::Parser");
132        let slash = ItemPath::parse("runtime/Runtime").unwrap();
133        assert_eq!(
134            slash.segments(),
135            &["runtime".to_string(), "Runtime".to_string()]
136        );
137        assert_eq!(
138            ItemPath::parse("async_trait").unwrap().segments(),
139            &["async_trait".to_string()]
140        );
141        // Hyphen normalizes to underscore (rustc path).
142        assert_eq!(
143            ItemPath::parse("async-trait").unwrap().segments(),
144            &["async_trait".to_string()]
145        );
146        assert_eq!(
147            ItemPath::parse("foo-bar::Baz-Quux").unwrap().segments(),
148            &["foo_bar".to_string(), "Baz_Quux".to_string()]
149        );
150    }
151
152    #[test]
153    fn item_path_err() {
154        assert!(ItemPath::parse("").is_err());
155        assert!(ItemPath::parse("::").is_err());
156        assert!(ItemPath::parse("has space").is_err());
157        assert!(ItemPath::parse("foo.bar").is_err());
158        assert!(ItemPath::parse("..").is_err());
159        assert!(ItemPath::parse("a/../b").is_err());
160        assert!(ItemPath::parse(&format!("a::{}", "b".repeat(MAX_ITEM_PATH_CHARS))).is_err());
161    }
162}