diff options
| -rw-r--r-- | src/libextra/semver.rs | 34 |
1 files changed, 30 insertions, 4 deletions
diff --git a/src/libextra/semver.rs b/src/libextra/semver.rs index 9dabf17162d..1644efb8070 100644 --- a/src/libextra/semver.rs +++ b/src/libextra/semver.rs @@ -8,10 +8,25 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Semver parsing and logic - -#[allow(missing_doc)]; - +//! Semantic version parsing and comparison. +//! +//! Semantic versioning (see http://semver.org/) is a set of rules for +//! assigning version numbers intended to convey meaning about what has +//! changed, and how much. A version number has five parts: +//! +//! * Major number, updated for incompatible API changes +//! * Minor number, updated for backwards-compatible API additions +//! * Patch number, updated for backwards-compatible bugfixes +//! * Pre-release information (optional), preceded by a hyphen (`-`) +//! * Build metadata (optional), preceded by a plus sign (`+`) +//! +//! The three mandatory components are required to be decimal numbers. The +//! pre-release information and build metadata are required to be a +//! period-separated list of identifiers containing only alphanumeric +//! characters and hyphens. +//! +//! An example version number with all five components is +//! `0.8.1-rc.3.0+20130922.linux`. use std::char; use std::cmp; @@ -20,6 +35,8 @@ use std::io; use std::option::{Option, Some, None}; use std::to_str::ToStr; +/// An identifier in the pre-release or build metadata. If the identifier can +/// be parsed as a decimal value, it will be represented with `Numeric`. #[deriving(Clone, Eq)] pub enum Identifier { Numeric(uint), @@ -49,12 +66,20 @@ impl ToStr for Identifier { } +/// Represents a version number conforming to the semantic versioning scheme. #[deriving(Clone, Eq)] pub struct Version { + /// The major version, to be incremented on incompatible changes. major: uint, + /// The minor version, to be incremented when functionality is added in a + /// backwards-compatible manner. minor: uint, + /// The patch version, to be incremented when backwards-compatible bug + /// fixes are made. patch: uint, + /// The pre-release version identifier, if one exists. pre: ~[Identifier], + /// The build metadata, ignored when determining version precedence. build: ~[Identifier], } @@ -202,6 +227,7 @@ fn parse_reader(rdr: @io::Reader) -> Version { } +/// Parse a string into a semver object. pub fn parse(s: &str) -> Option<Version> { if !s.is_ascii() { return None; |