Skip to main content

docsrs_cli/
item_kind.rs

1//! ItemKind normalization for rustdoc URLs and all.html filters.
2
3use crate::error::{AppError, AppResult, ErrorKind};
4
5/// Canonical rustdoc item kinds used by docs.rs HTML.
6#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
7#[serde(rename_all = "snake_case")]
8pub enum ItemKind {
9    /// Module page.
10    Module,
11    /// Struct page.
12    Struct,
13    /// Trait page.
14    Trait,
15    /// Enum page.
16    Enum,
17    /// Union page.
18    Union,
19    /// Function or method page.
20    Fn,
21    /// Type alias page.
22    Type,
23    /// Constant page.
24    Constant,
25    /// Static page.
26    Static,
27    /// Macro page.
28    Macro,
29    /// Attribute macro page.
30    Attribute,
31    /// Derive macro page.
32    Derive,
33}
34
35impl ItemKind {
36    /// Stable JSON / filter string.
37    pub fn as_str(self) -> &'static str {
38        match self {
39            Self::Module => "module",
40            Self::Struct => "struct",
41            Self::Trait => "trait",
42            Self::Enum => "enum",
43            Self::Union => "union",
44            Self::Fn => "fn",
45            Self::Type => "type",
46            Self::Constant => "constant",
47            Self::Static => "static",
48            Self::Macro => "macro",
49            Self::Attribute => "attribute",
50            Self::Derive => "derive",
51        }
52    }
53
54    /// Filename prefix in rustdoc HTML (e.g. `struct`, `fn`, `attr`, `constant`).
55    ///
56    /// Modern rustdoc/docs.rs uses `constant.NAME.html` (not legacy `const.NAME.html`).
57    pub fn file_prefix(self) -> &'static str {
58        match self {
59            Self::Module => "module",
60            Self::Struct => "struct",
61            Self::Trait => "trait",
62            Self::Enum => "enum",
63            Self::Union => "union",
64            Self::Fn => "fn",
65            Self::Type => "type",
66            Self::Constant => "constant",
67            Self::Static => "static",
68            Self::Macro => "macro",
69            Self::Attribute => "attr",
70            Self::Derive => "derive",
71        }
72    }
73
74    /// Parse CLI / filter aliases into canonical kind.
75    ///
76    /// # Errors
77    ///
78    /// Returns [`ErrorKind::InvalidInput`] when `input` is not a known kind alias.
79    pub fn parse(input: &str) -> AppResult<Self> {
80        Ok(Self::parse_with_echo(input)?.0)
81    }
82
83    /// Parse kind for URL building plus the wire echo string for `item_type`.
84    ///
85    /// `method` maps to [`ItemKind::Fn`] for rustdoc URLs but echoes as `"method"`.
86    ///
87    /// # Errors
88    ///
89    /// Returns [`ErrorKind::InvalidInput`] when `input` is not a known kind alias.
90    pub fn parse_with_echo(input: &str) -> AppResult<(Self, &'static str)> {
91        let s = input.trim().to_ascii_lowercase();
92        match s.as_str() {
93            "module" | "mod" => Ok((Self::Module, "module")),
94            "struct" => Ok((Self::Struct, "struct")),
95            "trait" => Ok((Self::Trait, "trait")),
96            "enum" => Ok((Self::Enum, "enum")),
97            "union" => Ok((Self::Union, "union")),
98            "fn" | "function" => Ok((Self::Fn, "fn")),
99            "method" => Ok((Self::Fn, "method")),
100            "type" => Ok((Self::Type, "type")),
101            "const" | "constant" => Ok((Self::Constant, "constant")),
102            "static" => Ok((Self::Static, "static")),
103            "macro" => Ok((Self::Macro, "macro")),
104            "attr" | "attribute" => Ok((Self::Attribute, "attribute")),
105            "derive" => Ok((Self::Derive, "derive")),
106            other => Err(AppError::new(
107                ErrorKind::InvalidInput,
108                format!("unknown item type '{other}'"),
109            )),
110        }
111    }
112
113    /// Infer kind from all.html href (e.g. `struct.Name.html`, `attr.foo.html`).
114    ///
115    /// Accepts modern `constant.` and legacy `const.` prefixes for Constant.
116    pub fn from_href(href: &str) -> Option<Self> {
117        let file = href.rsplit('/').next().unwrap_or(href);
118        let file = file.split('#').next().unwrap_or(file);
119        let prefix = file.split('.').next().unwrap_or("");
120        match prefix {
121            "struct" => Some(Self::Struct),
122            "trait" => Some(Self::Trait),
123            "fn" => Some(Self::Fn),
124            "enum" => Some(Self::Enum),
125            "type" => Some(Self::Type),
126            // Modern rustdoc: constant.NAME.html; legacy: const.NAME.html
127            "constant" | "const" => Some(Self::Constant),
128            "static" => Some(Self::Static),
129            "macro" => Some(Self::Macro),
130            "union" => Some(Self::Union),
131            "attr" => Some(Self::Attribute),
132            "derive" => Some(Self::Derive),
133            // Module pages use index.html (no typed prefix).
134            "index" => Some(Self::Module),
135            _ => {
136                // Associated method anchors: `struct.Foo.html#method.bar`
137                if href.contains("#method.") {
138                    Some(Self::Fn)
139                } else {
140                    None
141                }
142            }
143        }
144    }
145}
146
147/// Replace hyphens with underscores for rustc crate/module path segments.
148pub fn rustc_crate_name(pkg: &str) -> String {
149    pkg.replace('-', "_")
150}
151
152#[cfg(test)]
153mod tests {
154    use super::*;
155
156    #[test]
157    fn hyphen_to_underscore() {
158        assert_eq!(rustc_crate_name("async-trait"), "async_trait");
159        assert_eq!(rustc_crate_name("serde"), "serde");
160    }
161
162    #[test]
163    fn fn_aliases() {
164        assert_eq!(ItemKind::parse("fn").unwrap(), ItemKind::Fn);
165        assert_eq!(ItemKind::parse("function").unwrap(), ItemKind::Fn);
166        assert_eq!(ItemKind::parse("method").unwrap(), ItemKind::Fn);
167        let (k, echo) = ItemKind::parse_with_echo("method").unwrap();
168        assert_eq!(k, ItemKind::Fn);
169        assert_eq!(echo, "method");
170        let (_, echo) = ItemKind::parse_with_echo("fn").unwrap();
171        assert_eq!(echo, "fn");
172    }
173
174    #[test]
175    fn href_classifier() {
176        assert_eq!(ItemKind::from_href("fn.foo.html"), Some(ItemKind::Fn));
177        assert_eq!(ItemKind::from_href("union.U.html"), Some(ItemKind::Union));
178        assert_eq!(
179            ItemKind::from_href("attr.async_trait.html"),
180            Some(ItemKind::Attribute)
181        );
182        assert_eq!(
183            ItemKind::from_href("derive.Serialize.html"),
184            Some(ItemKind::Derive)
185        );
186        assert_eq!(
187            ItemKind::from_href("de/trait.Deserialize.html"),
188            Some(ItemKind::Trait)
189        );
190        assert_eq!(ItemKind::from_href("unknown.html"), None);
191    }
192
193    #[test]
194    fn constant_prefix_modern_and_legacy() {
195        assert_eq!(ItemKind::file_prefix(ItemKind::Constant), "constant");
196        assert_eq!(
197            ItemKind::from_href("constant.MAX.html"),
198            Some(ItemKind::Constant)
199        );
200        assert_eq!(
201            ItemKind::from_href("constant._SC_OPEN_MAX.html"),
202            Some(ItemKind::Constant)
203        );
204        // Legacy rustdoc href still classifies as Constant.
205        assert_eq!(
206            ItemKind::from_href("const.MAX.html"),
207            Some(ItemKind::Constant)
208        );
209        assert_eq!(ItemKind::parse("const").unwrap(), ItemKind::Constant);
210        assert_eq!(ItemKind::parse("constant").unwrap(), ItemKind::Constant);
211        assert_eq!(ItemKind::Constant.as_str(), "constant");
212    }
213}