versions

Types and parsers for software version numbers.

https://gitlab.com/fosskers/versions

Version on this page:3.4.0.1
LTS Haskell 22.14:6.0.6
Stackage Nightly 2024-03-28:6.0.6
Latest on Hackage:6.0.6

See all snapshots versions appears in

BSD-3-Clause licensed by Colin Woodbury
Maintained by [email protected]
This version can be pinned in stack with:versions-3.4.0.1@sha256:8737afaf930fd7c1206972053b7c293cca316c006293efe669f1a38b61926c63,2478

Module documentation for 3.4.0.1

Used by 1 package in lts-12.19(full list with versions):

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"

Changes

Changelog

3.4.0.1

  • Enhanced the whitespace handling in semver', version', and mess'.

3.4.0

  • Removed ParseV and surrounding machinery. Use versioning now instead of the parseV function.

3.3.2

  • GHC 8.4.1 compatibility.

3.3.0

  • New Semantic typeclass that provides Traversals for SemVer-like data out of all the version types. Text was also given an instance, so its much easier to manipulate directly:
λ "1.2.3" & minor %~ (+ 1)
"1.3.3"

Some Lenses and Traversals had their names changed or were removed entirely to accomodate this new typeclass.

  • SemVer and Version should never contain negative values, so their numeric components were changed from Int to Word.

3.2.0

  • Updated for megaparsec-6 and GHC 8.2.

3.1.1

  • Added instances for common typeclasses: Generic, NFData, and Hashable. This is to avoid having users define these instances themselves as orphans. If there are more instances you want added, please let me know. Data was left out on purpose.

3.1.0

  • Added support for epoch numbers in the Version type. These are numbers like the 1: in 1:2.3.4. These are used in Arch Linux in rare cases where packages change their versioning scheme, but need a reliable integer prefix to establish ordering. The Version type has been given a new field, _vEpoch :: Maybe Int, and a corresponding lens, vEpoch.

3.0.2

  • Expose internal parsers so that they could be used in other parser programs that parse version numbers in larger files.

3.0.0

  • Updated for megaparsec-5 and ghc-8

2.0.0

  • Switched to megaparsec to perform all parsing as Text
  • Support for legacy String removed
  • Added more Traversals and INLINE’d all Lenses/Traversals

1.1.0

  • Added Lenses and Traversals (no lens dependency)