Crate versions

A library for parsing and comparing software version numbers.

We like to give version numbers to our software in a myriad of different ways. Some ways follow strict guidelines for incrementing and comparison. Some follow conventional wisdom and are generally self-consistent. Some are just plain asinine. This library provides a means of parsing and comparing any style of versioning, be it a nice Semantic Version like this:

1.2.3-r1

…or a monstrosity like this:

2:10.2+0.0093r3+1-1

Usage

If you’re parsing several version numbers that don’t follow a single scheme (say, as in system packages), then use the Versioning type and its parser Versioning::new. Otherwise, each main type - SemVer, Version, or Mess - can be parsed on their own via the new method (e.g. SemVer::new).

Examples

use versions::Versioning;

let good = Versioning::new("1.6.0").unwrap();
let evil = Versioning::new("1.6.0a+2014+m872b87e73dfb-1").unwrap();

assert!(good.is_ideal());   // It parsed as a `SemVer`.
assert!(evil.is_complex()); // It parsed as a `Mess`.
assert!(good > evil);       // We can compare them anyway!

Version Constraints

Tools like cargo also allow version constraints to be prepended to a version number, like in ^1.2.3.

use versions::{Requirement, Versioning};

let req = Requirement::new("^1.2.3").unwrap();
let ver = Versioning::new("1.2.4").unwrap();
assert!(req.matches(&ver));

In this case, the incoming version 1.2.4 satisfies the “caret” constraint, which demands anything greater than or equal to 1.2.3.

See the Requirement type for more details.

Usage with nom

In constructing your own nom parsers, you can integrate the parsers used for the types in this crate via Versioning::parse, SemVer::parse, Version::parse, and Mess::parse.

Features

You can enable Serde support for serialization and deserialization with the serde feature.

By default the version structs are serialized/deserialized as-is. If instead you’d like to deserialize directly from a raw version string like 1.2.3, see [Versioning::deserialize_pretty].

Structs

• Chunks
  Chunks that have a comparison behaviour specific to Version.
• Mess
  A complex version number with no specific structure.
• Release
  Chunks that have comparison behaviour according to SemVer’s rules for prereleases.
• Requirement
  A version requirement expression, like ^1.4.163.
• SemVer
  An ideal version number that conforms to Semantic Versioning.
• Version
  A version number with decent structure and comparison logic.

Enums

• Chunk
  A logical unit of a version number.
• Error
  Errors unique to the parsing of version numbers.
• MChunk
  Possible values of a section of a Mess.
• Op
  Versioning comparison operators used in a Requirement: =, >, >=, <, <=, ~, ^, *.
• Sep
  Symbols that separate groups of digits/letters in a version number. Used in the Mess.
• Versioning
  A top-level Versioning type which acts as a wrapper for the more specific types.