1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223
// Copyright 2012-2013 The Rust Project Developers. See the COPYRIGHT // file at the top-level directory of this distribution and at // http://rust-lang.org/COPYRIGHT. // // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your // option. This file may not be copied, modified, or distributed // except according to those terms. //! Semantic version parsing and comparison. //! //! Semantic versioning (see http://semver.org/) is a set of rules for //! assigning version numbers. //! //! ## SemVer overview //! //! Given a version number MAJOR.MINOR.PATCH, increment the: //! //! 1. MAJOR version when you make incompatible API changes, //! 2. MINOR version when you add functionality in a backwards-compatible //! manner, and //! 3. PATCH version when you make backwards-compatible bug fixes. //! //! Additional labels for pre-release and build metadata are available as //! extensions to the MAJOR.MINOR.PATCH format. //! //! Any references to 'the spec' in this documentation refer to [version 2.0 of //! the SemVer spec](http://semver.org/spec/v2.0.0.html). //! //! ## SemVer and the Rust ecosystem //! //! Rust itself follows the SemVer specification, as does its standard //! libraries. The two are not tied together. //! //! [Cargo](http://crates.io), Rust's package manager, uses SemVer to determine //! which versions of packages you need installed. //! //! ## Versions //! //! [`Version`]: struct.Version.html //! //! At its simplest, the `semver` crate allows you to construct [`Version`] //! objects using the [`parse`] method: //! //! [`parse`]: struct.Version.html#method.parse //! //! ```{rust} //! use semver::Version; //! //! assert!(Version::parse("1.2.3") == Ok(Version { //! major: 1, //! minor: 2, //! patch: 3, //! pre: vec!(), //! build: vec!(), //! })); //! ``` //! //! If you have multiple [`Version`]s, you can use the usual comparison operators //! to compare them: //! //! ```{rust} //! use semver::Version; //! //! assert!(Version::parse("1.2.3-alpha") != Version::parse("1.2.3-beta")); //! assert!(Version::parse("1.2.3-alpha2") > Version::parse("1.2.0")); //! ``` //! //! If you explicitly need to modify a [`Version`], SemVer also allows you to //! increment the major, minor, and patch numbers in accordance with the spec. //! //! Please note that in order to do this, you must use a mutable Version: //! //! ```{rust} //! use semver::Version; //! //! # fn try_increment_patch() -> Result<(), Box<::std::error::Error>> { //! let mut bugfix_release = Version::parse("1.0.0")?; //! bugfix_release.increment_patch(); //! //! assert_eq!(Ok(bugfix_release), Version::parse("1.0.1")); //! # Ok(()) //! # } //! # fn main() { //! # try_increment_patch().unwrap(); //! # } //! ``` //! //! When incrementing the minor version number, the patch number resets to zero //! (in accordance with section 7 of the spec) //! //! ```{rust} //! use semver::Version; //! //! # fn try_increment_minor() -> Result<(), Box<::std::error::Error>> { //! let mut feature_release = Version::parse("1.4.6")?; //! feature_release.increment_minor(); //! //! assert_eq!(Ok(feature_release), Version::parse("1.5.0")); //! # Ok(()) //! # } //! # fn main() { //! # try_increment_minor().unwrap(); //! # } //! ``` //! //! Similarly, when incrementing the major version number, the patch and minor //! numbers reset to zero (in accordance with section 8 of the spec) //! //! ```{rust} //! use semver::Version; //! //! # fn try_increment_major() -> Result<(), Box<::std::error::Error>> { //! let mut chrome_release = Version::parse("41.5.5377")?; //! chrome_release.increment_major(); //! //! assert_eq!(Ok(chrome_release), Version::parse("42.0.0")); //! # Ok(()) //! # } //! # fn main() { //! # try_increment_major().unwrap(); //! # } //! ``` //! //! ## Requirements //! //! The `semver` crate also provides the ability to compare requirements, which //! are more complex comparisons. //! //! For example, creating a requirement that only matches versions greater than //! or equal to 1.0.0: //! //! ```{rust} //! # #![allow(unstable)] //! use semver::Version; //! use semver::VersionReq; //! //! # fn try_compare() -> Result<(), Box<::std::error::Error>> { //! let r = VersionReq::parse(">=1.0.0")?; //! let v = Version::parse("1.0.0")?; //! //! assert!(r.to_string() == ">=1.0.0".to_string()); //! assert!(r.matches(&v)); //! # Ok(()) //! # } //! # fn main() { //! # try_compare().unwrap(); //! # } //! ``` //! //! It also allows parsing of `~x.y.z` and `^x.y.z` requirements as defined at //! https://www.npmjs.com/package/semver //! //! **Tilde requirements** specify a minimal version with some updates: //! //! ```notrust //! ~1.2.3 := >=1.2.3 <1.3.0 //! ~1.2 := >=1.2.0 <1.3.0 //! ~1 := >=1.0.0 <2.0.0 //! ``` //! //! **Caret requirements** allow SemVer compatible updates to a specified //! verion, `0.x` and `0.x+1` are not considered compatible, but `1.x` and //! `1.x+1` are. //! //! `0.0.x` is not considered compatible with any other version. //! Missing minor and patch versions are desugared to `0` but allow flexibility //! for that value. //! //! ```notrust //! ^1.2.3 := >=1.2.3 <2.0.0 //! ^0.2.3 := >=0.2.3 <0.3.0 //! ^0.0.3 := >=0.0.3 <0.0.4 //! ^0.0 := >=0.0.0 <0.1.0 //! ^0 := >=0.0.0 <1.0.0 //! ``` //! //! **Wildcard requirements** allows parsing of version requirements of the //! formats `*`, `x.*` and `x.y.*`. //! //! ```notrust //! * := >=0.0.0 //! 1.* := >=1.0.0 <2.0.0 //! 1.2.* := >=1.2.0 <1.3.0 //! ``` #![doc( html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png", html_favicon_url = "https://www.rust-lang.org/favicon.ico", html_root_url = "https://docs.rs/semver" )] #![deny(missing_docs)] #![cfg_attr(test, deny(warnings))] extern crate semver_parser; // Serialization and deserialization support for version numbers #[cfg(feature = "serde")] extern crate serde; // Database support for version numbers #[cfg(feature = "diesel")] #[macro_use] extern crate diesel; // We take the common approach of keeping our own module system private, and // just re-exporting the interface that we want. pub use semver_parser::Compat; pub use version::Identifier::{AlphaNumeric, Numeric}; pub use version::{Identifier, SemVerError, Version}; pub use version_req::{ReqParseError, VersionReq}; // SemVer-compliant versions. mod version; // advanced version comparisons mod version_req; #[cfg(feature = "diesel")] // Diesel support mod diesel_impls;