versions: Types and parsers for software version numbers.

[ bsd3, data, library ] [ Propose Tags ]

A library for parsing and comparing software version numbers. We like to give version numbers to our software in a myriad of 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.

This library implements version 2.0.0 of the SemVer spec.


[Skip to Readme]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 1.0.0, 1.0.1, 1.0.2, 1.1.0, 2.0.0, 3.0.0, 3.0.1, 3.0.1.1, 3.0.2, 3.0.2.1, 3.1.0, 3.1.0.1, 3.1.1, 3.2.0, 3.3.0, 3.3.1, 3.3.2, 3.4.0, 3.4.0.1, 3.5.0, 3.5.1, 3.5.1.1, 3.5.2, 3.5.3, 3.5.4, 4.0.0, 4.0.1, 4.0.2, 4.0.3, 5.0.0, 5.0.1, 5.0.2, 5.0.3, 5.0.4, 5.0.5, 6.0.0, 6.0.1, 6.0.2, 6.0.3, 6.0.4, 6.0.5, 6.0.6 (info)
Change log CHANGELOG.md
Dependencies base (>=4.10 && <4.20), deepseq (>=1.4), hashable (>=1.2), megaparsec (>=7), parser-combinators (>=1.0), template-haskell (>=2.15), text (>=1.2 && <1.3 || >=2.0 && <2.2) [details]
License BSD-3-Clause
Author Colin Woodbury
Maintainer colin@fosskers.ca
Category Data
Home page https://github.com/fosskers/versions
Uploaded by fosskers at 2024-03-08T06:01:24Z
Distributions Arch:5.0.5, LTSHaskell:6.0.6, NixOS:6.0.5, Stackage:6.0.6
Reverse Dependencies 9 direct, 18 indirect [details]
Downloads 28131 total (250 in the last 30 days)
Rating 2.25 (votes: 2) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2024-03-08 [all 1 reports]

Readme for versions-6.0.6

[back to package description]

versions

Hackage Stackage Nightly Stackage LTS

A Haskell library for parsing and comparing software version numbers.

About

We like to give version numbers to our software in a myriad of 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.

Usage

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).

Lenses and Traversals

The parse result types have Lenses/Traversals for accessing their data fields. For instance, to increment the patch number of a parsed SemVer, you could:

incPatch :: SemVer -> SemVer
incPatch s = s & patch %~ (+ 1)

Or, something more involved:

-- | Get all major versions of legally parsed SemVers.
majors :: [Text] -> [Word]
majors vs = vs ^.. each . to semver . _Right . major

The to semver . _Right is clunky, so we provide some direct Text Traverals inspired by (micro) lens-aeson:

-- | Get the major version of any `Text` that has one.
majors :: [Text] -> [Word]
majors vs = vs ^.. each . major

We can also use these Text Traversals to increment versions, as above:

incPatch :: Text -> Text
incPatch s = s & patch %~ (+ 1)

> incPatch "1.2.3"
"1.2.4"

Caveats

The largest number that can be parsed as part of a version is:

ghci> maxBound :: Word64
18446744073709551615

However, on 32-bit systems (or smaller), the maximum is their maxBound :: Word. A number larger than that, even if smaller than maxBound :: Word64, will yield a parse error.