Skip to main content

alpm_types/version/
pkg_generic.rs

1//! A flexible and generic package version.
2
3use std::{
4    cmp::Ordering,
5    fmt::{Display, Formatter},
6    str::FromStr,
7};
8
9use alpm_parsers::prelude::*;
10#[cfg(feature = "serde")]
11use serde::{Deserialize, Serialize};
12use winnow::{combinator::opt, error::ErrMode};
13
14use crate::{Epoch, Error, PackageRelease, PackageVersion};
15#[cfg(doc)]
16use crate::{FullVersion, MinimalVersion};
17
18/// A version of a package
19///
20/// A [`Version`] generically tracks an optional [`Epoch`], a [`PackageVersion`] and an optional
21/// [`PackageRelease`].
22/// See [alpm-package-version] for details on the format.
23///
24/// # Notes
25///
26/// - If [`PackageRelease`] should be mandatory for your use-case, use [`FullVersion`] instead.
27/// - If [`PackageRelease`] should not be used in your use-case, use [`MinimalVersion`] instead.
28///
29/// ## Examples
30/// ```
31/// use std::str::FromStr;
32///
33/// use alpm_types::{Epoch, PackageRelease, PackageVersion, Version};
34///
35/// # fn main() -> Result<(), alpm_types::Error> {
36///
37/// let version = Version::from_str("1:2-3")?;
38/// assert_eq!(version.epoch, Some(Epoch::from_str("1")?));
39/// assert_eq!(version.pkgver, PackageVersion::new("2".to_string())?);
40/// assert_eq!(version.pkgrel, Some(PackageRelease::new(3, None)));
41/// # Ok(())
42/// # }
43/// ```
44///
45/// [alpm-package-version]: https://alpm.archlinux.page/specifications/alpm-package-version.7.html
46#[derive(Clone, Debug, Eq, PartialEq)]
47#[cfg_attr(feature = "serde", derive(Deserialize, Serialize))]
48pub struct Version {
49    /// The version of the package
50    pub pkgver: PackageVersion,
51    /// The epoch of the package
52    pub epoch: Option<Epoch>,
53    /// The release of the package
54    pub pkgrel: Option<PackageRelease>,
55}
56
57impl Version {
58    /// Create a new Version
59    pub fn new(
60        pkgver: PackageVersion,
61        epoch: Option<Epoch>,
62        pkgrel: Option<PackageRelease>,
63    ) -> Self {
64        Version {
65            pkgver,
66            epoch,
67            pkgrel,
68        }
69    }
70
71    /// Compare two Versions and return a number
72    ///
73    /// The comparison algorithm is based on libalpm/ pacman's vercmp behavior.
74    ///
75    /// * `1` if `a` is newer than `b`
76    /// * `0` if `a` and `b` are considered to be the same version
77    /// * `-1` if `a` is older than `b`
78    ///
79    /// ## Examples
80    /// ```
81    /// use std::str::FromStr;
82    ///
83    /// use alpm_types::Version;
84    ///
85    /// # fn main() -> Result<(), alpm_types::Error> {
86    ///
87    /// assert_eq!(
88    ///     Version::vercmp(&Version::from_str("1.0.0")?, &Version::from_str("0.1.0")?),
89    ///     1
90    /// );
91    /// assert_eq!(
92    ///     Version::vercmp(&Version::from_str("1.0.0")?, &Version::from_str("1.0.0")?),
93    ///     0
94    /// );
95    /// assert_eq!(
96    ///     Version::vercmp(&Version::from_str("0.1.0")?, &Version::from_str("1.0.0")?),
97    ///     -1
98    /// );
99    /// # Ok(())
100    /// # }
101    /// ```
102    pub fn vercmp(a: &Version, b: &Version) -> i8 {
103        match a.cmp(b) {
104            Ordering::Less => -1,
105            Ordering::Equal => 0,
106            Ordering::Greater => 1,
107        }
108    }
109}
110
111impl AlpmParser for Version {
112    /// Recognizes a [`Version`] in a string slice.
113    ///
114    /// # Errors
115    ///
116    /// Returns an error if `input` does not begin with a valid [alpm-package-version].
117    ///
118    /// [alpm-package-version]: https://alpm.archlinux.page/specifications/alpm-package-version.7.html
119    fn parser<'a>(input: &mut Input<'a>) -> PResult<'a, Self> {
120        let parser = move |input: &mut Input<'a>| -> PResult<'a, Self> {
121            // Parse an optional epoch, which advances the cursor until after a ':', e.g.:
122            // "1:1.0.0-1" -> "1.0.0-1"
123            //
124            // If no epoch exists, the cursor does not move.
125            let epoch = opt(Epoch::parser_until_inclusive(":")).parse_next(input)?;
126
127            // Advance the parser until the next '-', e.g.:
128            // "1.0.0-1" -> "-1"
129            let pkgver = PackageVersion::parser.parse_next(input)?;
130
131            // Parse an optional PackageRelease, e.g.:
132            // "-1" -> ""
133            //
134            // If an `-` is found, the PackageRelease is expected and must exist
135            let delimiter = opt('-').parse_next(input)?;
136            let pkgrel = if delimiter.is_some() {
137                Some(PackageRelease::parser.parse_next(input)?)
138            } else {
139                None
140            };
141
142            Ok(Self {
143                epoch,
144                pkgver,
145                pkgrel,
146            })
147        };
148
149        parser.layer("alpm-package-version").parse_next(input)
150    }
151
152    fn delimiter_error_context<'a, O, P>(
153        parser: P,
154    ) -> impl Parser<Input<'a>, O, ErrMode<ParseStack<'a>>>
155    where
156        P: Parser<Input<'a>, O, ErrMode<ParseStack<'a>>>,
157    {
158        parser
159            .expected_text("end of the version string")
160            .layer("alpm-package-version")
161    }
162}
163
164impl FromStr for Version {
165    type Err = Error;
166    /// Creates a new [`Version`] from a string slice.
167    ///
168    /// Delegates to [`Version::parser`].
169    ///
170    /// # Errors
171    ///
172    /// Returns an error if [`Version::parser`] fails.
173    fn from_str(s: &str) -> Result<Version, Self::Err> {
174        Ok(Self::parser_until_eof.parse(Input::new(s))?)
175    }
176}
177
178impl Display for Version {
179    /// Formats the [`Version`].
180    ///
181    /// # Note
182    ///
183    /// If an [`Epoch`] exists, it is only written, if its value is not `0` (the value `0` is the
184    /// implied default and not shown).
185    fn fmt(&self, fmt: &mut Formatter) -> std::fmt::Result {
186        if let Some(epoch) = self.epoch
187            && epoch.0 != 0
188        {
189            write!(fmt, "{epoch}:")?;
190        }
191
192        write!(fmt, "{}", self.pkgver)?;
193
194        if let Some(pkgrel) = &self.pkgrel {
195            write!(fmt, "-{pkgrel}")?;
196        }
197
198        Ok(())
199    }
200}
201
202impl Ord for Version {
203    fn cmp(&self, other: &Self) -> Ordering {
204        match (self.epoch, other.epoch) {
205            (Some(self_epoch), Some(other_epoch)) if self_epoch.cmp(&other_epoch).is_ne() => {
206                return self_epoch.cmp(&other_epoch);
207            }
208            (Some(_), None) => return Ordering::Greater,
209            (None, Some(_)) => return Ordering::Less,
210            (_, _) => {}
211        }
212
213        let pkgver_cmp = self.pkgver.cmp(&other.pkgver);
214        if pkgver_cmp.is_ne() {
215            return pkgver_cmp;
216        }
217
218        self.pkgrel.cmp(&other.pkgrel)
219    }
220}
221
222impl PartialOrd for Version {
223    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
224        Some(self.cmp(other))
225    }
226}
227
228#[cfg(test)]
229mod tests {
230    use insta::assert_snapshot;
231    use rstest::rstest;
232    use testresult::TestResult;
233
234    use super::*;
235    use crate::configure_insta;
236
237    /// Ensure that valid version strings are parsed as expected.
238    #[rstest]
239    #[case(
240        "foo",
241        Version {
242            epoch: None,
243            pkgver: PackageVersion::new("foo".to_string())?,
244            pkgrel: None
245        },
246    )]
247    #[case(
248        "1:foo-1",
249        Version {
250            pkgver: PackageVersion::new("foo".to_string())?,
251            epoch: Some(Epoch::new(1)),
252            pkgrel: Some(PackageRelease::new(1, None))
253        },
254    )]
255    #[case(
256        "1:foo",
257        Version {
258            pkgver: PackageVersion::new("foo".to_string())?,
259            epoch: Some(Epoch::new(1)),
260            pkgrel: None,
261        },
262    )]
263    #[case(
264        "foo-1",
265        Version {
266            pkgver: PackageVersion::new("foo".to_string())?,
267            epoch: None,
268            pkgrel: Some(PackageRelease::new(1, None))
269        }
270    )]
271    // yes, this is valid
272    #[case(
273        ".-1",
274        Version {
275            pkgver: PackageVersion::new(".".to_string())?,
276            epoch: None,
277            pkgrel: Some(PackageRelease::new(1, None))
278            }
279    )]
280    fn valid_version_from_string(#[case] version: &str, #[case] expected: Version) -> TestResult {
281        assert_eq!(
282            Version::from_str(version)?,
283            expected,
284            "Expected valid parsing for version {version}"
285        );
286
287        Ok(())
288    }
289
290    /// Ensure that invalid version strings produce the respective errors.
291    #[rstest]
292    #[case::two_pkgrel("1:foo-1-1")]
293    #[case::two_epoch("1:1:foo-1")]
294    #[case::no_version("")]
295    #[case::no_version(":")]
296    #[case::invalid_integer("-1foo:1")]
297    #[case::invalid_integer("1-foo:1")]
298    fn parse_error_in_version_from_string(#[case] version: &str) {
299        let (test_name, _guard) = configure_insta();
300
301        let Err(Error::ParseError(err_msg)) = Version::from_str(version) else {
302            panic!("parsing '{version}' did not fail as expected")
303        };
304
305        assert_snapshot!(test_name, err_msg.to_string());
306    }
307
308    /// Ensure that versions are properly serialized back to their string representation.
309    #[rstest]
310    #[case(Version::from_str("1:1-1")?, "1:1-1")]
311    #[case(Version::from_str("1-1")?, "1-1")]
312    #[case(Version::from_str("1")?, "1")]
313    #[case(Version::from_str("1:1")?, "1:1")]
314    fn version_to_string(#[case] version: Version, #[case] to_str: &str) -> TestResult {
315        assert_eq!(format!("{version}"), to_str);
316        Ok(())
317    }
318
319    #[rstest]
320    // Major version comparisons
321    #[case(Version::from_str("1")?, Version::from_str("1")?, Ordering::Equal)]
322    #[case(Version::from_str("1")?, Version::from_str("2")?, Ordering::Less)]
323    #[case(
324        Version::from_str("20220102")?,
325        Version::from_str("20220202")?,
326        Ordering::Less
327    )]
328    // Major vs Major.Minor
329    #[case(Version::from_str("1")?, Version::from_str("1.1")?, Ordering::Less)]
330    #[case(Version::from_str("01")?, Version::from_str("1")?, Ordering::Equal)]
331    #[case(Version::from_str("001a")?, Version::from_str("1a")?, Ordering::Equal)]
332    #[case(Version::from_str("a1a")?, Version::from_str("a1b")?, Ordering::Less)]
333    #[case(Version::from_str("foo")?, Version::from_str("1.1")?, Ordering::Less)]
334    // Major.Minor version comparisons
335    #[case(Version::from_str("1.0")?, Version::from_str("1..0")?, Ordering::Less)]
336    #[case(Version::from_str("1.1")?, Version::from_str("1.1")?, Ordering::Equal)]
337    #[case(Version::from_str("1.1")?, Version::from_str("1.2")?, Ordering::Less)]
338    #[case(Version::from_str("1..0")?, Version::from_str("1..0")?, Ordering::Equal)]
339    #[case(Version::from_str("1..0")?, Version::from_str("1..1")?, Ordering::Less)]
340    #[case(Version::from_str("1+0")?, Version::from_str("1.0")?, Ordering::Equal)]
341    #[case(Version::from_str("1+1")?, Version::from_str("1+2")?, Ordering::Less)]
342    // Major.Minor version comparisons with alphanumerics
343    #[case(Version::from_str("1.1")?, Version::from_str("1.1.a")?, Ordering::Less)]
344    #[case(Version::from_str("1.1")?, Version::from_str("1.11a")?, Ordering::Less)]
345    #[case(Version::from_str("1.1")?, Version::from_str("1.1_a")?, Ordering::Less)]
346    #[case(Version::from_str("1.1a")?, Version::from_str("1.1")?, Ordering::Less)]
347    #[case(Version::from_str("1.1a1")?, Version::from_str("1.1")?, Ordering::Less)]
348    #[case(Version::from_str("1.a")?, Version::from_str("1.1")?, Ordering::Less)]
349    #[case(Version::from_str("1.a")?, Version::from_str("1.alpha")?, Ordering::Less)]
350    #[case(Version::from_str("1.a1")?, Version::from_str("1.1")?, Ordering::Less)]
351    #[case(Version::from_str("1.a11")?, Version::from_str("1.1")?, Ordering::Less)]
352    #[case(Version::from_str("1.a1a")?, Version::from_str("1.a1")?, Ordering::Less)]
353    #[case(Version::from_str("1.alpha")?, Version::from_str("1.b")?, Ordering::Less)]
354    #[case(Version::from_str("a.1")?, Version::from_str("1.1")?, Ordering::Less)]
355    #[case(
356        Version::from_str("1.alpha0.0")?,
357        Version::from_str("1.alpha.0")?,
358        Ordering::Less
359    )]
360    // Major.Minor vs Major.Minor.Patch
361    #[case(Version::from_str("1.0")?, Version::from_str("1.0.")?, Ordering::Less)]
362    // Major.Minor.Patch
363    #[case(Version::from_str("1.0.")?, Version::from_str("1.0.0")?, Ordering::Less)]
364    #[case(Version::from_str("1.0..")?, Version::from_str("1.0.")?, Ordering::Equal)]
365    #[case(
366        Version::from_str("1.0.alpha.0")?,
367        Version::from_str("1.0.")?,
368        Ordering::Less
369    )]
370    #[case(
371        Version::from_str("1.a001a.1")?,
372        Version::from_str("1.a1a.1")?,
373        Ordering::Equal
374    )]
375    fn version_cmp(
376        #[case] version_a: Version,
377        #[case] version_b: Version,
378        #[case] expected: Ordering,
379    ) -> TestResult {
380        // Derive the expected vercmp binary exitcode from the expected Ordering.
381        let vercmp_result = match &expected {
382            Ordering::Equal => 0,
383            Ordering::Greater => 1,
384            Ordering::Less => -1,
385        };
386
387        let ordering = version_a.cmp(&version_b);
388        assert_eq!(
389            ordering, expected,
390            "Failed to compare '{version_a}' and '{version_b}'. Expected {expected:?} got {ordering:?}"
391        );
392
393        assert_eq!(Version::vercmp(&version_a, &version_b), vercmp_result);
394
395        // If we find the `vercmp` binary, also run the test against the actual binary.
396        #[cfg(feature = "_compatibility_tests")]
397        {
398            let output = std::process::Command::new("vercmp")
399                .arg(version_a.to_string())
400                .arg(version_b.to_string())
401                .output()?;
402            let result = String::from_utf8_lossy(&output.stdout);
403            assert_eq!(result.trim(), vercmp_result.to_string());
404        }
405
406        // Now check that the opposite holds true as well.
407        let reverse_vercmp_result = match &expected {
408            Ordering::Equal => 0,
409            Ordering::Greater => -1,
410            Ordering::Less => 1,
411        };
412        let reverse_expected = match &expected {
413            Ordering::Equal => Ordering::Equal,
414            Ordering::Greater => Ordering::Less,
415            Ordering::Less => Ordering::Greater,
416        };
417
418        let reverse_ordering = version_b.cmp(&version_a);
419        assert_eq!(
420            reverse_ordering, reverse_expected,
421            "Failed to compare '{version_a}' and '{version_b}'. Expected {expected:?} got {ordering:?}"
422        );
423
424        assert_eq!(
425            Version::vercmp(&version_b, &version_a),
426            reverse_vercmp_result
427        );
428
429        Ok(())
430    }
431}