Data.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+git123

...or a monstrosity like this:

2:10.2+0.0093r3+1-1

Please switch to Semantic Versioning if you aren't currently using it. It provides consistency in version incrementing and has the best constraints on comparisons.

Using the Parsers

In general, parseV is the function you want. It attempts to parse a given Text using the three individual parsers, semver, version and mess. If one fails, it tries the next. If you know you only want to parse one specific version type, use that parser directly (e.g. semver).

Types

data Versioning

A top-level Versioning type. Acts as a wrapper for the more specific types. This allows each subtype to have its own parser, and for said parsers to be composed. This is useful for specifying custom behaviour for when a certain parser fails.

Constructors

Ideal SemVer

General Version

Complex Mess

Instances

Eq Versioning

Ord Versioning

Comparison of Ideals is always well defined.

If comparison of Generals is well-defined, then comparison of Ideal and General is well-defined, as there exists a perfect mapping from Ideal to General.

If comparison of Complexes is well-defined, then comparison of General and Complex is well defined for the same reason. This implies comparison of Ideal and Complex is also well-defined.

Show Versioning

data SemVer

An (Ideal) version number that conforms to Semantic Versioning. This is a prescriptive parser, meaning it follows the SemVer standard.

Legal semvers are of the form: MAJOR.MINOR.PATCH-PREREL+META

Example: 1.2.3-r1+commithash

Extra Rules:

1. Pre-release versions have lower precedence than normal versions.
2. Build metadata does not affect version precedence.

For more information, see http://semver.org

Constructors

SemVer

Fields

_svMajor :: Int

_svMinor :: Int

_svPatch :: Int

_svPreRel :: [VChunk]

_svMeta :: [VChunk]

Instances

Eq SemVer

Two SemVers are equal if all fields except metadata are equal.

Ord SemVer

Build metadata does not affect version precedence.

Show SemVer

data Version

A (General) Version. Not quite as ideal as a SemVer, but has some internal consistancy from version to version. Generally conforms to the x.x.x-x pattern.

Examples of Version that are not SemVer: 0.25-2, 8.u51-1, 20150826-1

Constructors

Version

Fields

_vChunks :: [VChunk]

_vRel :: [VChunk]

Instances

Eq Version

Ord Version

Show Version

data Mess

A (Complex) Mess. This is a descriptive parser, based on examples of stupidly crafted version numbers used in the wild.

Groups of letters/numbers, separated by a period, can be further separated by the symbols _-+:

Unfortunately, VChunks cannot be used here, as some developers have numbers like 1.003.04 which make parsers quite sad.

Not guaranteed to have well-defined ordering (Ord) behaviour, but so far interal tests show consistency.

Constructors

VLeaf [Text]

VNode [Text] VSep Mess

Instances

Eq Mess

Ord Mess

Show Mess

data VUnit

A single unit of a Version. May be digits or a string of characters. Groups of these are called VChunks, and are the identifiers separated by periods in the source.

Constructors

Digits Int

Str Text

Instances

Eq VUnit

Ord VUnit

Read VUnit

Show VUnit

type VChunk = [VUnit]

A logical unit of a version number. Can consist of multiple letters and numbers.

data VSep

Developers use a number of symbols to seperate groups of digits/letters in their version numbers. These are:

• A colon (:). Often denotes an "epoch".
• A hyphen (-).
• A plus (+). Stop using this outside of metadata if you are. Example: 10.2+0.93+1-1
• An underscore (_). Stop using this if you are.

Constructors

VColon

VHyphen

VPlus

VUnder

Instances

Eq VSep

Show VSep

newtype VParser

A wrapper for a parser function. Can be composed via their Semigroup instance, such that a different parser can be tried if a previous one fails.

Constructors

VParser

Fields

runVP :: Text -> Either ParseError Versioning

Instances

Semigroup VParser

Parsers

semver :: Text -> Either ParseError SemVer

Parse a (Ideal) Semantic Version.

version :: Text -> Either ParseError Version

Parse a (General) Version, as defined above.

mess :: Text -> Either ParseError Mess

Parse a (Complex) Mess, as defined above.

Wrapped Parsers

parseV :: Text -> Either ParseError Versioning

Parse a piece of Text into either an (Ideal) SemVer, a (General) Version, or a (Complex) Mess.

semverP :: VParser

A wrapped SemVer parser. Can be composed with other parsers.

versionP :: VParser

A wrapped Version parser. Can be composed with other parsers.

messP :: VParser

A wrapped Mess parser. Can be composed with other parsers.

Pretty Printing

prettyV :: Versioning -> Text

Convert any parsed Versioning type to its textual representation.

prettySemVer :: SemVer -> Text

Convert a SemVer back to its textual representation.

prettyVer :: Version -> Text

Convert a Version back to its textual representation.

prettyMess :: Mess -> Text

Convert a Mess back to its textual representation.

Lenses

Traversing Text

_Versioning :: Applicative f => (Versioning -> f Versioning) -> Text -> f Text

Traverse some Text for its inner versioning.

_Versioning :: Traversal' Text Versioning

("1.2.3" & _Versioning . _Ideal . svPatch %~ (+ 1)) == "1.2.4"

_SemVer :: Applicative f => (SemVer -> f SemVer) -> Text -> f Text

Traverse some Text for its inner SemVer.

_SemVer :: Traversal' Text SemVer

_Version :: Applicative f => (Version -> f Version) -> Text -> f Text

Traverse some Text for its inner Version.

_Version :: Traversal' Text Version

Versioning Traversals

_Ideal :: Applicative f => (SemVer -> f SemVer) -> Versioning -> f Versioning

_Ideal :: Traversal' Versioning SemVer

_General :: Applicative f => (Version -> f Version) -> Versioning -> f Versioning

_General :: Traversal' Versioning Version

_Complex :: Applicative f => (Mess -> f Mess) -> Versioning -> f Versioning

_Complex :: Traversal' Versioning Mess

(Ideal) SemVer Lenses

svMajor :: Functor f => (Int -> f Int) -> SemVer -> f SemVer

svMajor :: Lens' SemVer Int

svMinor :: Functor f => (Int -> f Int) -> SemVer -> f SemVer

svMinor :: Lens' SemVer Int

svPatch :: Functor f => (Int -> f Int) -> SemVer -> f SemVer

svPatch :: Lens' SemVer Int

svPreRel :: Functor f => ([VChunk] -> f [VChunk]) -> SemVer -> f SemVer

svPreRel :: Lens' SemVer Int

svMeta :: Functor f => ([VChunk] -> f [VChunk]) -> SemVer -> f SemVer

svMeta :: Lens' SemVer Int

(General) Version Lenses

vChunks :: Functor f => ([VChunk] -> f [VChunk]) -> Version -> f Version

vChunks :: Lens' Version [VChunk]

vRel :: Functor f => ([VChunk] -> f [VChunk]) -> Version -> f Version

vRel :: Lens' Version [VChunk]

Misc. Lenses / Traversals

_Digits :: Applicative f => (Int -> f Int) -> VUnit -> f VUnit

_Digits :: Traversal' VUnit Int

_Str :: Applicative f => (Text -> f Text) -> VUnit -> f VUnit

_Str :: Traversal' VUnit Text