alpm_types/
name.rs

1use std::{
2    fmt::{Display, Formatter},
3    str::FromStr,
4    string::ToString,
5};
6
7use serde::{Deserialize, Serialize};
8use winnow::{
9    ModalResult,
10    Parser,
11    combinator::{Repeat, alt, cut_err, eof, peek, repeat, repeat_till},
12    error::{StrContext, StrContextValue},
13    stream::Stream,
14    token::{any, one_of, rest},
15};
16
17use crate::Error;
18
19/// A build tool name
20///
21/// The same character restrictions as with `Name` apply.
22/// Further name restrictions may be enforced on an existing instances using
23/// `matches_restriction()`.
24///
25/// ## Examples
26/// ```
27/// use std::str::FromStr;
28///
29/// use alpm_types::{BuildTool, Error, Name};
30///
31/// # fn main() -> Result<(), alpm_types::Error> {
32/// // create BuildTool from &str
33/// assert!(BuildTool::from_str("test-123@.foo_+").is_ok());
34/// assert!(BuildTool::from_str(".test").is_err());
35///
36/// // format as String
37/// assert_eq!("foo", format!("{}", BuildTool::from_str("foo")?));
38///
39/// // validate that BuildTool follows naming restrictions
40/// let buildtool = BuildTool::from_str("foo")?;
41/// let restrictions = vec![Name::from_str("foo")?, Name::from_str("bar")?];
42/// assert!(buildtool.matches_restriction(&restrictions));
43/// # Ok(())
44/// # }
45/// ```
46#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd)]
47pub struct BuildTool(Name);
48
49impl BuildTool {
50    /// Create a new BuildTool
51    pub fn new(name: Name) -> Self {
52        BuildTool(name)
53    }
54
55    /// Create a new BuildTool in a Result, which matches one Name in a list of restrictions
56    ///
57    /// ## Examples
58    /// ```
59    /// use alpm_types::{BuildTool, Error, Name};
60    ///
61    /// # fn main() -> Result<(), alpm_types::Error> {
62    /// assert!(BuildTool::new_with_restriction("foo", &[Name::new("foo")?]).is_ok());
63    /// assert!(BuildTool::new_with_restriction("foo", &[Name::new("bar")?]).is_err());
64    /// # Ok(())
65    /// # }
66    /// ```
67    pub fn new_with_restriction(name: &str, restrictions: &[Name]) -> Result<Self, Error> {
68        let buildtool = BuildTool::from_str(name)?;
69        if buildtool.matches_restriction(restrictions) {
70            Ok(buildtool)
71        } else {
72            Err(Error::ValueDoesNotMatchRestrictions {
73                restrictions: restrictions.iter().map(ToString::to_string).collect(),
74            })
75        }
76    }
77
78    /// Validate that the BuildTool has a name matching one Name in a list of restrictions
79    pub fn matches_restriction(&self, restrictions: &[Name]) -> bool {
80        restrictions
81            .iter()
82            .any(|restriction| restriction.eq(self.inner()))
83    }
84
85    /// Return a reference to the inner type
86    pub fn inner(&self) -> &Name {
87        &self.0
88    }
89}
90
91impl FromStr for BuildTool {
92    type Err = Error;
93    /// Create a BuildTool from a string
94    fn from_str(s: &str) -> Result<BuildTool, Self::Err> {
95        Name::new(s).map(BuildTool)
96    }
97}
98
99impl Display for BuildTool {
100    fn fmt(&self, fmt: &mut Formatter) -> std::fmt::Result {
101        write!(fmt, "{}", self.inner())
102    }
103}
104
105/// A package name
106///
107/// Package names may contain the characters `[a-zA-Z0-9\-._@+]`, but must not
108/// start with `[-.]` (see [alpm-package-name]).
109///
110/// ## Examples
111/// ```
112/// use std::str::FromStr;
113///
114/// use alpm_types::{Error, Name};
115///
116/// # fn main() -> Result<(), alpm_types::Error> {
117/// // create Name from &str
118/// assert_eq!(
119///     Name::from_str("test-123@.foo_+"),
120///     Ok(Name::new("test-123@.foo_+")?)
121/// );
122/// assert!(Name::from_str(".test").is_err());
123///
124/// // format as String
125/// assert_eq!("foo", format!("{}", Name::new("foo")?));
126/// # Ok(())
127/// # }
128/// ```
129///
130/// [alpm-package-name]: https://alpm.archlinux.page/specifications/alpm-package-name.7.html
131#[derive(Clone, Debug, Deserialize, Eq, Ord, PartialEq, PartialOrd, Serialize)]
132pub struct Name(String);
133
134impl Name {
135    /// Create a new `Name`
136    pub fn new(name: &str) -> Result<Self, Error> {
137        Self::from_str(name)
138    }
139
140    /// Return a reference to the inner type
141    pub fn inner(&self) -> &str {
142        &self.0
143    }
144
145    /// Recognizes a [`Name`] in a string slice.
146    ///
147    /// Consumes all of its input.
148    ///
149    /// # Errors
150    ///
151    /// Returns an error if `input` contains an invalid _alpm-package-name_.
152    pub fn parser(input: &mut &str) -> ModalResult<Self> {
153        let alphanum = |c: char| c.is_ascii_alphanumeric();
154        let first_char = one_of((alphanum, '_', '@', '+'))
155            .context(StrContext::Label("first character of package name"))
156            .context(StrContext::Expected(StrContextValue::Description(
157                "ASCII alphanumeric character",
158            )))
159            .context(StrContext::Expected(StrContextValue::CharLiteral('_')))
160            .context(StrContext::Expected(StrContextValue::CharLiteral('@')))
161            .context(StrContext::Expected(StrContextValue::CharLiteral('+')));
162
163        let non_first_char = one_of((alphanum, '_', '@', '+', '-', '.'));
164
165        // no .context() because this is infallible due to `0..`
166        // note the empty tuple collection to avoid allocation
167        let remaining_chars: Repeat<_, _, _, (), _> = repeat(0.., non_first_char);
168
169        let full_parser = (
170            first_char,
171            remaining_chars,
172            // bad characters fall through to eof so we insert that context here
173            eof.context(StrContext::Label("character in package name"))
174                .context(StrContext::Expected(StrContextValue::Description(
175                    "ASCII alphanumeric character",
176                )))
177                .context(StrContext::Expected(StrContextValue::CharLiteral('_')))
178                .context(StrContext::Expected(StrContextValue::CharLiteral('@')))
179                .context(StrContext::Expected(StrContextValue::CharLiteral('+')))
180                .context(StrContext::Expected(StrContextValue::CharLiteral('-')))
181                .context(StrContext::Expected(StrContextValue::CharLiteral('.'))),
182        );
183
184        full_parser
185            .take()
186            .map(|n: &str| Name(n.to_owned()))
187            .parse_next(input)
188    }
189}
190
191impl FromStr for Name {
192    type Err = Error;
193
194    /// Creates a [`Name`] from a string slice.
195    ///
196    /// Delegates to [`Name::parser`].
197    ///
198    /// # Errors
199    ///
200    /// Returns an error if [`Name::parser`] fails.
201    fn from_str(s: &str) -> Result<Name, Self::Err> {
202        Ok(Self::parser.parse(s)?)
203    }
204}
205
206impl Display for Name {
207    fn fmt(&self, fmt: &mut Formatter) -> std::fmt::Result {
208        write!(fmt, "{}", self.inner())
209    }
210}
211
212impl AsRef<str> for Name {
213    fn as_ref(&self) -> &str {
214        self.inner()
215    }
216}
217
218/// A shared object name.
219///
220/// This type wraps a [`Name`] and is used to represent the name of a shared object file
221/// that ends with the `.so` suffix.
222#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
223pub struct SharedObjectName(pub(crate) Name);
224
225impl SharedObjectName {
226    /// Creates a new [`SharedObjectName`].
227    ///
228    /// # Errors
229    ///
230    /// Returns an error if the input does not end with `.so`.
231    ///
232    /// # Examples
233    ///
234    /// ```
235    /// use alpm_types::SharedObjectName;
236    ///
237    /// # fn main() -> Result<(), alpm_types::Error> {
238    /// let shared_object_name = SharedObjectName::new("example.so")?;
239    /// # Ok(())
240    /// # }
241    /// ```
242    pub fn new(name: &str) -> Result<Self, Error> {
243        Self::from_str(name)
244    }
245
246    /// Returns the name of the shared object as a string slice.
247    pub fn as_str(&self) -> &str {
248        self.0.as_ref()
249    }
250
251    /// Parses a [`SharedObjectName`] from a string slice.
252    pub fn parser(input: &mut &str) -> ModalResult<Self> {
253        // Make a checkpoint for parsing the full name in one go later on.
254        // The full name will later on include the `.so` extension, but we have to make sure first
255        // that the name has the correct structure.
256        // (a filename followed by one or more `.so` suffixes)
257        let checkpoint = input.checkpoint();
258
259        // Parse the name of the shared object until eof or the `.so` is hit.
260        repeat_till::<_, _, String, _, _, _, _>(1.., any, peek(alt((".so", eof))))
261            .context(StrContext::Label("name"))
262            .parse_next(input)?;
263
264        // Parse at least one or more `.so` suffix(es).
265        cut_err(repeat::<_, _, String, _, _>(1.., ".so").take())
266            .context(StrContext::Label("suffix"))
267            .context(StrContext::Expected(StrContextValue::Description(
268                "shared object name suffix '.so'",
269            )))
270            .parse_next(input)?;
271
272        // Ensure that there is no trailing content
273        cut_err(eof)
274            .context(StrContext::Label(
275                "unexpected trailing content after shared object name.",
276            ))
277            .context(StrContext::Expected(StrContextValue::Description(
278                "end of input.",
279            )))
280            .parse_next(input)?;
281
282        input.reset(&checkpoint);
283        let name = rest
284            .and_then(Name::parser)
285            .context(StrContext::Label("name"))
286            .parse_next(input)?;
287
288        Ok(SharedObjectName(name))
289    }
290}
291
292impl FromStr for SharedObjectName {
293    type Err = Error;
294    /// Create an [`SharedObjectName`] from a string and return it in a Result
295    fn from_str(s: &str) -> Result<Self, Self::Err> {
296        Ok(Self::parser.parse(s)?)
297    }
298}
299
300impl Display for SharedObjectName {
301    fn fmt(&self, fmt: &mut Formatter) -> std::fmt::Result {
302        write!(fmt, "{}", self.0)
303    }
304}
305
306#[cfg(test)]
307mod tests {
308    use proptest::prelude::*;
309    use rstest::rstest;
310
311    use super::*;
312
313    #[rstest]
314    #[case(
315        "bar",
316        ["foo".parse(), "bar".parse()].into_iter().flatten().collect::<Vec<Name>>(),
317        Ok(BuildTool::from_str("bar").unwrap()),
318    )]
319    #[case(
320        "bar",
321        ["foo".parse(), "foo".parse()].into_iter().flatten().collect::<Vec<Name>>(),
322        Err(Error::ValueDoesNotMatchRestrictions {
323            restrictions: vec!["foo".to_string(), "foo".to_string()],
324        }),
325    )]
326    fn buildtool_new_with_restriction(
327        #[case] buildtool: &str,
328        #[case] restrictions: Vec<Name>,
329        #[case] result: Result<BuildTool, Error>,
330    ) {
331        assert_eq!(
332            BuildTool::new_with_restriction(buildtool, &restrictions),
333            result
334        );
335    }
336
337    #[rstest]
338    #[case("bar", ["foo".parse(), "bar".parse()].into_iter().flatten().collect::<Vec<Name>>(), true)]
339    #[case("bar", ["foo".parse(), "foo".parse()].into_iter().flatten().collect::<Vec<Name>>(), false)]
340    fn buildtool_matches_restriction(
341        #[case] buildtool: &str,
342        #[case] restrictions: Vec<Name>,
343        #[case] result: bool,
344    ) {
345        let buildtool = BuildTool::from_str(buildtool).unwrap();
346        assert_eq!(buildtool.matches_restriction(&restrictions), result);
347    }
348
349    #[rstest]
350    #[case("package_name_'''", "invalid character in package name")]
351    #[case("-package_with_leading_hyphen", "invalid first character")]
352    fn name_parse_error(#[case] input: &str, #[case] err_snippet: &str) {
353        let Err(Error::ParseError(err_msg)) = Name::from_str(input) else {
354            panic!("'{input}' erroneously parsed as a Name")
355        };
356        assert!(
357            err_msg.contains(err_snippet),
358            "Error:\n=====\n{err_msg}\n=====\nshould contain snippet:\n\n{err_snippet}"
359        );
360    }
361
362    proptest! {
363        #![proptest_config(ProptestConfig::with_cases(1000))]
364
365        #[test]
366        fn valid_name_from_string(name_str in r"[a-zA-Z0-9_@+]+[a-zA-Z0-9\-._@+]*") {
367            let name = Name::from_str(&name_str).unwrap();
368            prop_assert_eq!(name_str, format!("{}", name));
369        }
370
371        #[test]
372        fn invalid_name_from_string_start(name_str in r"[-.][a-zA-Z0-9@._+-]*") {
373            let error = Name::from_str(&name_str).unwrap_err();
374            assert!(matches!(error, Error::ParseError(_)));
375        }
376
377        #[test]
378        fn invalid_name_with_invalid_characters(name_str in r"[^\w@._+-]+") {
379            let error = Name::from_str(&name_str).unwrap_err();
380            assert!(matches!(error, Error::ParseError(_)));
381        }
382    }
383
384    #[rstest]
385    #[case("example.so", SharedObjectName("example.so".parse().unwrap()))]
386    #[case("example.so.so", SharedObjectName("example.so.so".parse().unwrap()))]
387    #[case("libexample.1.so", SharedObjectName("libexample.1.so".parse().unwrap()))]
388    fn shared_object_name_parser(
389        #[case] input: &str,
390        #[case] expected_result: SharedObjectName,
391    ) -> testresult::TestResult<()> {
392        let shared_object_name = SharedObjectName::new(input)?;
393        assert_eq!(expected_result, shared_object_name);
394        assert_eq!(input, shared_object_name.as_str());
395        Ok(())
396    }
397
398    #[rstest]
399    #[case("noso", "expected shared object name suffix '.so'")]
400    #[case("example.so.1", "unexpected trailing content after shared object name")]
401    fn invalid_shared_object_name_parser(#[case] input: &str, #[case] error_snippet: &str) {
402        let result = SharedObjectName::from_str(input);
403        assert!(result.is_err(), "Expected SharedObjectName parsing to fail");
404        let err = result.unwrap_err();
405        let pretty_error = err.to_string();
406        assert!(
407            pretty_error.contains(error_snippet),
408            "Error:\n=====\n{pretty_error}\n=====\nshould contain snippet:\n\n{error_snippet}"
409        );
410    }
411}
alpm_types/name.rs

alpm_types/
name.rs
