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, versioning 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

Defined in Data.Versions

Methods

(==) :: Versioning -> Versioning -> Bool

(/=) :: Versioning -> Versioning -> Bool

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.

Defined in Data.Versions

Methods

compare :: Versioning -> Versioning -> Ordering

(<) :: Versioning -> Versioning -> Bool

(<=) :: Versioning -> Versioning -> Bool

(>) :: Versioning -> Versioning -> Bool

(>=) :: Versioning -> Versioning -> Bool

max :: Versioning -> Versioning -> Versioning

min :: Versioning -> Versioning -> Versioning

Show Versioning

Defined in Data.Versions

Methods

showsPrec :: Int -> Versioning -> ShowS

show :: Versioning -> String

showList :: [Versioning] -> ShowS

Generic Versioning

Defined in Data.Versions

Associated Types

type Rep Versioning :: * -> *

Methods

from :: Versioning -> Rep Versioning x

to :: Rep Versioning x -> Versioning

NFData Versioning

Defined in Data.Versions

Methods

rnf :: Versioning -> ()

Hashable Versioning

Defined in Data.Versions

Methods

hashWithSalt :: Int -> Versioning -> Int

hash :: Versioning -> Int

Semantic Versioning

Defined in Data.Versions

Methods

major :: Traversal' Versioning Word

minor :: Traversal' Versioning Word

patch :: Traversal' Versioning Word

release :: Traversal' Versioning [VChunk]

meta :: Traversal' Versioning [VChunk]

semantic :: Traversal' Versioning SemVer

type Rep Versioning

Defined in Data.Versions

type Rep Versioning = D1 (MetaData "Versioning" "Data.Versions" "versions-3.5.0-9PXfYd6LkPmGhgGdn1KXtV" False) (C1 (MetaCons "Ideal" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 SemVer)) :+: (C1 (MetaCons "General" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Version)) :+: C1 (MetaCons "Complex" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Mess))))

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.
3. PREREL and META strings may only contain ASCII alphanumerics.

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

Constructors

SemVer

Fields

• _svMajor :: Word
• _svMinor :: Word
• _svPatch :: Word
• _svPreRel :: [VChunk]
• _svMeta :: [VChunk]

Instances

Eq SemVer

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

Defined in Data.Versions

Methods

(==) :: SemVer -> SemVer -> Bool

(/=) :: SemVer -> SemVer -> Bool

Ord SemVer

Build metadata does not affect version precedence.

Defined in Data.Versions

Methods

compare :: SemVer -> SemVer -> Ordering

(<) :: SemVer -> SemVer -> Bool

(<=) :: SemVer -> SemVer -> Bool

(>) :: SemVer -> SemVer -> Bool

(>=) :: SemVer -> SemVer -> Bool

max :: SemVer -> SemVer -> SemVer

min :: SemVer -> SemVer -> SemVer

Show SemVer

Defined in Data.Versions

Methods

showsPrec :: Int -> SemVer -> ShowS

show :: SemVer -> String

showList :: [SemVer] -> ShowS

Generic SemVer

Defined in Data.Versions

Associated Types

type Rep SemVer :: * -> *

Methods

from :: SemVer -> Rep SemVer x

to :: Rep SemVer x -> SemVer

Semigroup SemVer

Defined in Data.Versions

Methods

(<>) :: SemVer -> SemVer -> SemVer

sconcat :: NonEmpty SemVer -> SemVer

stimes :: Integral b => b -> SemVer -> SemVer

Monoid SemVer

Defined in Data.Versions

Methods

mempty :: SemVer

mappend :: SemVer -> SemVer -> SemVer

mconcat :: [SemVer] -> SemVer

NFData SemVer

Defined in Data.Versions

Methods

rnf :: SemVer -> ()

Hashable SemVer

Defined in Data.Versions

Methods

hashWithSalt :: Int -> SemVer -> Int

hash :: SemVer -> Int

Semantic SemVer

Defined in Data.Versions

Methods

major :: Traversal' SemVer Word

minor :: Traversal' SemVer Word

patch :: Traversal' SemVer Word

release :: Traversal' SemVer [VChunk]

meta :: Traversal' SemVer [VChunk]

semantic :: Traversal' SemVer SemVer

type Rep SemVer

Defined in Data.Versions

type Rep SemVer = D1 (MetaData "SemVer" "Data.Versions" "versions-3.5.0-9PXfYd6LkPmGhgGdn1KXtV" False) (C1 (MetaCons "SemVer" PrefixI True) ((S1 (MetaSel (Just "_svMajor") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Word) :*: S1 (MetaSel (Just "_svMinor") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Word)) :*: (S1 (MetaSel (Just "_svPatch") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Word) :*: (S1 (MetaSel (Just "_svPreRel") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [VChunk]) :*: S1 (MetaSel (Just "_svMeta") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [VChunk])))))

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, and may optionally have an epoch. These are prefixes marked by a colon, like in 1:2.3.4.

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

Constructors

Version

Fields

• _vEpoch :: Maybe Word
• _vChunks :: [VChunk]
• _vRel :: [VChunk]

Instances

Eq Version

Defined in Data.Versions

Methods

(==) :: Version -> Version -> Bool

(/=) :: Version -> Version -> Bool

Ord Version

Customized.

Defined in Data.Versions

Methods

compare :: Version -> Version -> Ordering

(<) :: Version -> Version -> Bool

(<=) :: Version -> Version -> Bool

(>) :: Version -> Version -> Bool

(>=) :: Version -> Version -> Bool

max :: Version -> Version -> Version

min :: Version -> Version -> Version

Show Version

Defined in Data.Versions

Methods

showsPrec :: Int -> Version -> ShowS

show :: Version -> String

showList :: [Version] -> ShowS

Generic Version

Defined in Data.Versions

Associated Types

type Rep Version :: * -> *

Methods

from :: Version -> Rep Version x

to :: Rep Version x -> Version

Semigroup Version

Defined in Data.Versions

Methods

(<>) :: Version -> Version -> Version

sconcat :: NonEmpty Version -> Version

stimes :: Integral b => b -> Version -> Version

Monoid Version

Defined in Data.Versions

Methods

mempty :: Version

mappend :: Version -> Version -> Version

mconcat :: [Version] -> Version

NFData Version

Defined in Data.Versions

Methods

rnf :: Version -> ()

Hashable Version

Defined in Data.Versions

Methods

hashWithSalt :: Int -> Version -> Int

hash :: Version -> Int

Semantic Version

Defined in Data.Versions

Methods

major :: Traversal' Version Word

minor :: Traversal' Version Word

patch :: Traversal' Version Word

release :: Traversal' Version [VChunk]

meta :: Traversal' Version [VChunk]

semantic :: Traversal' Version SemVer

type Rep Version

Defined in Data.Versions

type Rep Version = D1 (MetaData "Version" "Data.Versions" "versions-3.5.0-9PXfYd6LkPmGhgGdn1KXtV" False) (C1 (MetaCons "Version" PrefixI True) (S1 (MetaSel (Just "_vEpoch") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Maybe Word)) :*: (S1 (MetaSel (Just "_vChunks") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [VChunk]) :*: S1 (MetaSel (Just "_vRel") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [VChunk]))))

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 internal tests show consistency.

Constructors

VLeaf [Text]

VNode [Text] VSep Mess

Instances

Eq Mess

Defined in Data.Versions

Methods

(==) :: Mess -> Mess -> Bool

(/=) :: Mess -> Mess -> Bool

Ord Mess

Defined in Data.Versions

Methods

compare :: Mess -> Mess -> Ordering

(<) :: Mess -> Mess -> Bool

(<=) :: Mess -> Mess -> Bool

(>) :: Mess -> Mess -> Bool

(>=) :: Mess -> Mess -> Bool

max :: Mess -> Mess -> Mess

min :: Mess -> Mess -> Mess

Show Mess

Defined in Data.Versions

Methods

showsPrec :: Int -> Mess -> ShowS

show :: Mess -> String

showList :: [Mess] -> ShowS

Generic Mess

Defined in Data.Versions

Associated Types

type Rep Mess :: * -> *

Methods

from :: Mess -> Rep Mess x

to :: Rep Mess x -> Mess

NFData Mess

Defined in Data.Versions

Methods

rnf :: Mess -> ()

Hashable Mess

Defined in Data.Versions

Methods

hashWithSalt :: Int -> Mess -> Int

hash :: Mess -> Int

Semantic Mess

Defined in Data.Versions

Methods

major :: Traversal' Mess Word

minor :: Traversal' Mess Word

patch :: Traversal' Mess Word

release :: Traversal' Mess [VChunk]

meta :: Traversal' Mess [VChunk]

semantic :: Traversal' Mess SemVer

type Rep Mess

Defined in Data.Versions

type Rep Mess = D1 (MetaData "Mess" "Data.Versions" "versions-3.5.0-9PXfYd6LkPmGhgGdn1KXtV" False) (C1 (MetaCons "VLeaf" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [Text])) :+: C1 (MetaCons "VNode" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [Text]) :*: (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 VSep) :*: S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 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 Word

Str Text

Instances

Eq VUnit

Defined in Data.Versions

Methods

(==) :: VUnit -> VUnit -> Bool

(/=) :: VUnit -> VUnit -> Bool

Ord VUnit

Defined in Data.Versions

Methods

compare :: VUnit -> VUnit -> Ordering

(<) :: VUnit -> VUnit -> Bool

(<=) :: VUnit -> VUnit -> Bool

(>) :: VUnit -> VUnit -> Bool

(>=) :: VUnit -> VUnit -> Bool

max :: VUnit -> VUnit -> VUnit

min :: VUnit -> VUnit -> VUnit

Read VUnit

Defined in Data.Versions

Methods

readsPrec :: Int -> ReadS VUnit

readList :: ReadS [VUnit]

readPrec :: ReadPrec VUnit

readListPrec :: ReadPrec [VUnit]

Show VUnit

Defined in Data.Versions

Methods

showsPrec :: Int -> VUnit -> ShowS

show :: VUnit -> String

showList :: [VUnit] -> ShowS

Generic VUnit

Defined in Data.Versions

Associated Types

type Rep VUnit :: * -> *

Methods

from :: VUnit -> Rep VUnit x

to :: Rep VUnit x -> VUnit

Semigroup VUnit

Defined in Data.Versions

Methods

(<>) :: VUnit -> VUnit -> VUnit

sconcat :: NonEmpty VUnit -> VUnit

stimes :: Integral b => b -> VUnit -> VUnit

Monoid VUnit

Defined in Data.Versions

Methods

mempty :: VUnit

mappend :: VUnit -> VUnit -> VUnit

mconcat :: [VUnit] -> VUnit

NFData VUnit

Defined in Data.Versions

Methods

rnf :: VUnit -> ()

Hashable VUnit

Defined in Data.Versions

Methods

hashWithSalt :: Int -> VUnit -> Int

hash :: VUnit -> Int

type Rep VUnit

Defined in Data.Versions

type Rep VUnit = D1 (MetaData "VUnit" "Data.Versions" "versions-3.5.0-9PXfYd6LkPmGhgGdn1KXtV" False) (C1 (MetaCons "Digits" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Word)) :+: C1 (MetaCons "Str" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Text)))

digits :: Word -> VUnit

Smart constructor for a VUnit made of digits.

str :: Text -> Maybe VUnit

Smart constructor for a VUnit made of letters.

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

Defined in Data.Versions

Methods

(==) :: VSep -> VSep -> Bool

(/=) :: VSep -> VSep -> Bool

Show VSep

Defined in Data.Versions

Methods

showsPrec :: Int -> VSep -> ShowS

show :: VSep -> String

showList :: [VSep] -> ShowS

Generic VSep

Defined in Data.Versions

Associated Types

type Rep VSep :: * -> *

Methods

from :: VSep -> Rep VSep x

to :: Rep VSep x -> VSep

NFData VSep

Defined in Data.Versions

Methods

rnf :: VSep -> ()

Hashable VSep

Defined in Data.Versions

Methods

hashWithSalt :: Int -> VSep -> Int

hash :: VSep -> Int

type Rep VSep

Defined in Data.Versions

type Rep VSep = D1 (MetaData "VSep" "Data.Versions" "versions-3.5.0-9PXfYd6LkPmGhgGdn1KXtV" False) ((C1 (MetaCons "VColon" PrefixI False) (U1 :: * -> *) :+: C1 (MetaCons "VHyphen" PrefixI False) (U1 :: * -> *)) :+: (C1 (MetaCons "VPlus" PrefixI False) (U1 :: * -> *) :+: C1 (MetaCons "VUnder" PrefixI False) (U1 :: * -> *)))

Parsing Versions

type ParsingError = ParseErrorBundle Text Void

A synonym for the more verbose megaparsec error type.

versioning :: Text -> Either ParsingError Versioning

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

semver :: Text -> Either ParsingError SemVer

Parse a (Ideal) Semantic Version.

version :: Text -> Either ParsingError Version

Parse a (General) Version, as defined above.

mess :: Text -> Either ParsingError Mess

Parse a (Complex) Mess, as defined above.

Megaparsec Parsers

For when you'd like to mix version parsing into some larger parser.

versioning' :: Parsec Void Text Versioning

Parse a Versioning. Assumes the version number is the last token in the string.

semver' :: Parsec Void Text SemVer

Internal megaparsec parser of semver.

version' :: Parsec Void Text Version

Internal megaparsec parser of version.

mess' :: Parsec Void Text Mess

Internal megaparsec parser of mess.

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.

errorBundlePretty

Arguments

:: (Stream s, ShowErrorComponent e)

=> ParseErrorBundle s e

Parse error bundle to display

-> String

Textual rendition of the bundle

Pretty-print a ParseErrorBundle. All ParseErrors in the bundle will be pretty-printed in order together with the corresponding offending lines by doing a single efficient pass over the input stream. The rendered String always ends with a newline.

Since: megaparsec-7.0.0

Lenses

type Lens' s a = forall f. Functor f => (a -> f a) -> s -> f s

Simple Lenses compatible with both lens and microlens.

type Traversal' s a = forall f. Applicative f => (a -> f a) -> s -> f s

Simple Traversals compatible with both lens and microlens.

class Semantic v where

Version types which sanely and safely yield SemVer-like information about themselves. For instances other than SemVer itself however, these optics may not yield anything, depending on the actual value being traversed. Hence, the optics here are all Traversal's.

Consider the Version 1.2.3.4.5. We can imagine wanting to increment the minor number:

λ "1.2.3.4.5" & minor %~ (+ 1)
"1.3.3.4.5"

But of course something like this would fail:

λ "1.e.3.4.5" & minor %~ (+ 1)
"1.e.3.4.5"

However!

λ "1.e.3.4.5" & major %~ (+ 1)
"2.e.3.4.5"

Minimal complete definition

major, minor, patch, release, meta, semantic

Methods

major :: Traversal' v Word

MAJOR.minor.patch-prerel+meta

minor :: Traversal' v Word

major.MINOR.patch-prerel+meta

patch :: Traversal' v Word

major.minor.PATCH-prerel+meta

release :: Traversal' v [VChunk]

major.minor.patch-PREREL+meta

meta :: Traversal' v [VChunk]

major.minor.patch-prerel+META

semantic :: Traversal' v SemVer

A Natural Transformation into an proper SemVer.

Instances

Semantic Text

Defined in Data.Versions

Methods

major :: Traversal' Text Word

minor :: Traversal' Text Word

patch :: Traversal' Text Word

release :: Traversal' Text [VChunk]

meta :: Traversal' Text [VChunk]

semantic :: Traversal' Text SemVer

Semantic Mess

Defined in Data.Versions

Methods

major :: Traversal' Mess Word

minor :: Traversal' Mess Word

patch :: Traversal' Mess Word

release :: Traversal' Mess [VChunk]

meta :: Traversal' Mess [VChunk]

semantic :: Traversal' Mess SemVer

Semantic Version

Defined in Data.Versions

Methods

major :: Traversal' Version Word

minor :: Traversal' Version Word

patch :: Traversal' Version Word

release :: Traversal' Version [VChunk]

meta :: Traversal' Version [VChunk]

semantic :: Traversal' Version SemVer

Semantic SemVer

Defined in Data.Versions

Methods

major :: Traversal' SemVer Word

minor :: Traversal' SemVer Word

patch :: Traversal' SemVer Word

release :: Traversal' SemVer [VChunk]

meta :: Traversal' SemVer [VChunk]

semantic :: Traversal' SemVer SemVer

Semantic Versioning

Defined in Data.Versions

Methods

major :: Traversal' Versioning Word

minor :: Traversal' Versioning Word

patch :: Traversal' Versioning Word

release :: Traversal' Versioning [VChunk]

meta :: Traversal' Versioning [VChunk]

semantic :: Traversal' Versioning SemVer

Traversing Text

When traversing Text, leveraging its Semantic instance will likely benefit you more than using these Traversals directly.

_Versioning :: Traversal' Text Versioning

Traverse some Text for its inner versioning.

λ "1.2.3" & _Versioning . _Ideal . patch %~ (+ 1)  -- or just: "1.2.3" & patch %~ (+ 1)
"1.2.4"

_SemVer :: Traversal' Text SemVer

Traverse some Text for its inner SemVer.

_Version :: Traversal' Text Version

Traverse some Text for its inner Version.

_Mess :: Traversal' Text Mess

Traverse some Text for its inner Mess.

Versioning Traversals

_Ideal :: Traversal' Versioning SemVer

_General :: Traversal' Versioning Version

_Complex :: Traversal' Versioning Mess

(General) Version Lenses

epoch :: Lens' Version (Maybe Word)

Misc. Lenses / Traversals

_Digits :: Traversal' VUnit Word

_Str :: Traversal' VUnit Text