From be18bc3d68215e1fe5d8628ea8931476ec02a64f Mon Sep 17 00:00:00 2001 From: Allstreamer <48365544+Allstreamer@users.noreply.github.com> Date: Sun, 4 Sep 2022 17:57:33 +0200 Subject: [PATCH 1/3] Added doc stuff --- src/ids/dev_id.rs | 19 ++++++++++++-- src/ids/mod.rs | 2 +- src/ids/post_id.rs | 21 +++++++++++++++ src/lib.rs | 64 ++++++++++++++++++++++++++++++++++------------ src/validator.rs | 2 +- 5 files changed, 88 insertions(+), 20 deletions(-) diff --git a/src/ids/dev_id.rs b/src/ids/dev_id.rs index a16dbeb..f53c02a 100644 --- a/src/ids/dev_id.rs +++ b/src/ids/dev_id.rs @@ -1,7 +1,22 @@ -//! # `PEP-440` Developmental release identifier - use serde::{Deserialize, Serialize}; +/// # `PEP-440` Developmental release identifier +/// This identifier is used to mark a developmental release +/// +/// Examples of versions that use this struct: +/// - `1.0.dev456` +/// - `1.0rc1.dev1` +/// +/// ## Example Usage +/// ``` +/// use pyver::DevHead; +/// +/// assert!( +/// DevHead { dev_num: Some(0) } +/// > +/// DevHead { dev_num: None } +/// ); +/// ``` #[derive(Debug, Serialize, Deserialize, Eq, PartialEq, PartialOrd)] pub struct DevHead { pub dev_num: Option, diff --git a/src/ids/mod.rs b/src/ids/mod.rs index 78e2589..0d9a9e6 100644 --- a/src/ids/mod.rs +++ b/src/ids/mod.rs @@ -1,5 +1,5 @@ //! # Identifiers -//! Importing +//! Importing Example //! ``` //! use pyver::ids::{PreHeader, PostHeader, PostHead, DevHead, ReleaseHeader}; //! ``` diff --git a/src/ids/post_id.rs b/src/ids/post_id.rs index 1c5c04a..cb76a58 100644 --- a/src/ids/post_id.rs +++ b/src/ids/post_id.rs @@ -2,6 +2,27 @@ use serde::{Deserialize, Serialize}; use std::cmp::Ordering; /// # `PEP-440` Post-Release identifier +/// This identifier is used to mark a Post Release/Revision Version +/// +/// Examples of versions that use this struct: +/// - `1.0.post456` +/// - `1.0rev` +/// +/// ## Example Usage +/// ``` +/// use pyvar::PostHeader; +/// use pyvar::PostHead; +/// +/// assert!( +/// PostHeader { +/// post_head: Some(PostHead::Post), +/// post_num: Some(0), +/// } > PostHeader { +/// post_head: Some(PostHead::Post), +/// post_num: None, +/// } +/// ); +/// ``` #[derive(Debug, Serialize, Deserialize, Eq, PartialEq)] pub struct PostHeader { pub post_head: Option, diff --git a/src/lib.rs b/src/lib.rs index 4b9f761..dfcb610 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,8 +1,37 @@ -//! # Handling of `PEP-440` -//! -//! This library implements Pythons Package versioning system. -//! Read more at +/*! +# Handling of `PEP-440` +This library implements Pythons Package versioning system. +Read more at + +# Usage +The `pyver` crate is available on [crates.io](https://crates.io/crates/pyver), +you can include it in your project by adding the following to your `Cargo.toml`. +```toml +[dependencies] +pyver = "0.1" +``` +# Example +The following example shows how to parse a package version and +how to compare them +``` +use pyver::PackageVersion; + +let a = PackageVersion::new("v1.0a2.dev456").unwrap(); +let b = PackageVersion::new("v1.1a2.dev457").unwrap(); + +assert!(a < b); +``` + +If you want to verify single version strings do +``` +use pyver::validate_440_version; + +assert!( + validate_440_version("1.0").is_ok() +); +``` +*/ use anyhow::Result; use serde::{Deserialize, Serialize}; use std::fmt; @@ -13,16 +42,15 @@ extern crate derivative; mod validator; pub use validator::validate_440_version; -/// Make Identifiers module available for lib user +/// Identifiers (i.e. the components of a version string) pub mod ids; use ids::{DevHead, PostHead, PostHeader, PreHeader, ReleaseHeader}; /// `PEP-440` Compliant versioning system /// -/// This struct is sorted so that PartialOrd -/// correctly interprets priority -/// -/// Lower == More important +//# This struct is sorted so that PartialOrd +//# correctly interprets priority +//# Lower == More important /// /// # Example Usage /// ``` @@ -32,10 +60,14 @@ use ids::{DevHead, PostHead, PostHeader, PreHeader, ReleaseHeader}; #[derive(Derivative, Debug, Serialize, Deserialize)] #[derivative(PartialOrd, PartialEq)] pub struct PackageVersion { + /// ## Original String + /// Just holds the original string passed in when creating + /// the `PackageVersion` as some formating data is lost + /// when parsing the string #[derivative(PartialOrd = "ignore", PartialEq = "ignore")] pub original: String, - /// # `PEP-440` Local version identifier + /// ## `PEP-440` Local version identifier /// Local version sorting will have to be it's own issue /// since there are no limits to what a local version can be /// @@ -43,26 +75,26 @@ pub struct PackageVersion { /// `[a-z0-9]+(?:(?:[\-_.][a-z0-9]+)+)?` /// /// Here in Rulex: - /// ```ignore + /// ```toml /// ['a'-'z' '0'-'9']+ /// ((["-" "_" "."] ['a'-'z' '0'-'9']+)+)? /// ``` #[derivative(PartialOrd = "ignore", PartialEq = "ignore")] pub local: Option, - /// # `PEP-440` Developmental release identifier + /// ## `PEP-440` Developmental release identifier pub dev: Option, - /// # `PEP-440` Post-Release identifier + /// ## `PEP-440` Post-Release identifier pub post: Option, - /// # `PEP-440` Pre-Release identifier + /// ## `PEP-440` Pre-Release identifier pub pre: Option, - /// # `PEP-440` Release number + /// ## `PEP-440` Release number pub release: ReleaseHeader, - /// # `PEP-440` Version-Epoch + /// ## `PEP-440` Version-Epoch pub epoch: Option, } diff --git a/src/validator.rs b/src/validator.rs index c151fd0..a634a94 100644 --- a/src/validator.rs +++ b/src/validator.rs @@ -3,7 +3,7 @@ use lazy_static::lazy_static; use pomsky_macro::pomsky; use regex::Captures; -/// Utility Function for Checking if a PEP-440 Version String is valid +/// Utility Function for Checking if a `PEP-440` Version String is valid /// and getting it's groups /// /// # Example Usage From f1d21b5f21b391e0f4b84b39dd6a8c64fe450bf4 Mon Sep 17 00:00:00 2001 From: Allstreamer <48365544+Allstreamer@users.noreply.github.com> Date: Sun, 4 Sep 2022 18:23:36 +0200 Subject: [PATCH 2/3] Stuufff --- src/ids/dev_id.rs | 2 +- src/ids/post_id.rs | 20 ++++++++++++++++++-- src/ids/pre_id.rs | 20 ++++++++++---------- 3 files changed, 29 insertions(+), 13 deletions(-) diff --git a/src/ids/dev_id.rs b/src/ids/dev_id.rs index f53c02a..3939c4f 100644 --- a/src/ids/dev_id.rs +++ b/src/ids/dev_id.rs @@ -9,7 +9,7 @@ use serde::{Deserialize, Serialize}; /// /// ## Example Usage /// ``` -/// use pyver::DevHead; +/// use pyver::ids::DevHead; /// /// assert!( /// DevHead { dev_num: Some(0) } diff --git a/src/ids/post_id.rs b/src/ids/post_id.rs index cb76a58..6906f96 100644 --- a/src/ids/post_id.rs +++ b/src/ids/post_id.rs @@ -10,8 +10,8 @@ use std::cmp::Ordering; /// /// ## Example Usage /// ``` -/// use pyvar::PostHeader; -/// use pyvar::PostHead; +/// use pyver::ids::PostHeader; +/// use pyver::ids::PostHead; /// /// assert!( /// PostHeader { @@ -30,9 +30,25 @@ pub struct PostHeader { } /// `PEP-440` Post-Release Identifier Keyword +/// This is a helper enum to tack whether it's a Revision or +/// a Post-Release +/// +/// Examples of versions that use this enum: +/// - `1.0.post456` +/// - `1.0rev` #[derive(Debug, Serialize, Deserialize, Eq, PartialEq)] pub enum PostHead { + /// ``` + /// use pyver::ids::PostHead; + /// + /// PostHead::Post; + /// ``` Post, + /// ``` + /// use pyver::ids::PostHead; + /// + /// PostHead::Rev; + /// ``` Rev, } diff --git a/src/ids/pre_id.rs b/src/ids/pre_id.rs index 63fb122..cb82010 100644 --- a/src/ids/pre_id.rs +++ b/src/ids/pre_id.rs @@ -1,34 +1,34 @@ -//! # `PEP-440` Pre-Release identifier - use serde::{Deserialize, Serialize}; +/// # `PEP-440` Pre-Release identifier +/// This identifier is used to mark a Pre-Release version #[derive(Debug, Serialize, Deserialize, Eq, PartialEq, PartialOrd)] pub enum PreHeader { /// Present in versions like 1.1beta1 or 1.0b1 both are represented the same way /// ``` - ///# use pyver::ids::PreHeader; - /// + /// use pyver::ids::PreHeader; + /// /// PreHeader::Beta(Some(1)); /// ``` Beta(Option), /// Present in versions like 1.0alpha2 or 1.0a2 both are represented the same way /// ``` - ///# use pyver::ids::PreHeader; - /// + /// use pyver::ids::PreHeader; + /// /// PreHeader::Alpha(Some(2)); /// ``` Alpha(Option), /// Present in versions like 1.1pre3 /// ``` - ///# use pyver::ids::PreHeader; - /// + /// use pyver::ids::PreHeader; + /// /// PreHeader::Preview(Some(3)); /// ``` Preview(Option), /// Present in versions like 1.1-rc-4 or 1.1c-4 /// ``` - ///# use pyver::ids::PreHeader; - /// + /// use pyver::ids::PreHeader; + /// /// PreHeader::ReleaseCandidate(Some(4)); /// ``` ReleaseCandidate(Option), From c7d01580f6187e1262c8bc6c2cc5342822d9b65e Mon Sep 17 00:00:00 2001 From: Allstreamer <48365544+Allstreamer@users.noreply.github.com> Date: Sun, 4 Sep 2022 20:16:32 +0200 Subject: [PATCH 3/3] Ran FMT --- src/ids/dev_id.rs | 6 +++--- src/ids/post_id.rs | 14 +++++++------- src/ids/pre_id.rs | 8 ++++---- src/lib.rs | 4 ++-- 4 files changed, 16 insertions(+), 16 deletions(-) diff --git a/src/ids/dev_id.rs b/src/ids/dev_id.rs index 3939c4f..f12a167 100644 --- a/src/ids/dev_id.rs +++ b/src/ids/dev_id.rs @@ -2,15 +2,15 @@ use serde::{Deserialize, Serialize}; /// # `PEP-440` Developmental release identifier /// This identifier is used to mark a developmental release -/// +/// /// Examples of versions that use this struct: /// - `1.0.dev456` /// - `1.0rc1.dev1` -/// +/// /// ## Example Usage /// ``` /// use pyver::ids::DevHead; -/// +/// /// assert!( /// DevHead { dev_num: Some(0) } /// > diff --git a/src/ids/post_id.rs b/src/ids/post_id.rs index 6906f96..4c06a96 100644 --- a/src/ids/post_id.rs +++ b/src/ids/post_id.rs @@ -3,16 +3,16 @@ use std::cmp::Ordering; /// # `PEP-440` Post-Release identifier /// This identifier is used to mark a Post Release/Revision Version -/// +/// /// Examples of versions that use this struct: /// - `1.0.post456` /// - `1.0rev` -/// +/// /// ## Example Usage /// ``` /// use pyver::ids::PostHeader; /// use pyver::ids::PostHead; -/// +/// /// assert!( /// PostHeader { /// post_head: Some(PostHead::Post), @@ -32,7 +32,7 @@ pub struct PostHeader { /// `PEP-440` Post-Release Identifier Keyword /// This is a helper enum to tack whether it's a Revision or /// a Post-Release -/// +/// /// Examples of versions that use this enum: /// - `1.0.post456` /// - `1.0rev` @@ -40,13 +40,13 @@ pub struct PostHeader { pub enum PostHead { /// ``` /// use pyver::ids::PostHead; - /// + /// /// PostHead::Post; /// ``` Post, - /// ``` + /// ``` /// use pyver::ids::PostHead; - /// + /// /// PostHead::Rev; /// ``` Rev, diff --git a/src/ids/pre_id.rs b/src/ids/pre_id.rs index cb82010..b8f78aa 100644 --- a/src/ids/pre_id.rs +++ b/src/ids/pre_id.rs @@ -7,28 +7,28 @@ pub enum PreHeader { /// Present in versions like 1.1beta1 or 1.0b1 both are represented the same way /// ``` /// use pyver::ids::PreHeader; - /// + /// /// PreHeader::Beta(Some(1)); /// ``` Beta(Option), /// Present in versions like 1.0alpha2 or 1.0a2 both are represented the same way /// ``` /// use pyver::ids::PreHeader; - /// + /// /// PreHeader::Alpha(Some(2)); /// ``` Alpha(Option), /// Present in versions like 1.1pre3 /// ``` /// use pyver::ids::PreHeader; - /// + /// /// PreHeader::Preview(Some(3)); /// ``` Preview(Option), /// Present in versions like 1.1-rc-4 or 1.1c-4 /// ``` /// use pyver::ids::PreHeader; - /// + /// /// PreHeader::ReleaseCandidate(Some(4)); /// ``` ReleaseCandidate(Option), diff --git a/src/lib.rs b/src/lib.rs index dfcb610..2ced73d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -12,7 +12,7 @@ you can include it in your project by adding the following to your `Cargo.toml`. pyver = "0.1" ``` # Example -The following example shows how to parse a package version and +The following example shows how to parse a package version and how to compare them ``` use pyver::PackageVersion; @@ -61,7 +61,7 @@ use ids::{DevHead, PostHead, PostHeader, PreHeader, ReleaseHeader}; #[derivative(PartialOrd, PartialEq)] pub struct PackageVersion { /// ## Original String - /// Just holds the original string passed in when creating + /// Just holds the original string passed in when creating /// the `PackageVersion` as some formating data is lost /// when parsing the string #[derivative(PartialOrd = "ignore", PartialEq = "ignore")]