versions
Types and parsers for software version numbers.
https://github.com/fosskers/versions
Version on this page: | 5.0.0 |
LTS Haskell 23.0: | 6.0.7 |
Stackage Nightly 2024-12-09: | 6.0.7 |
Latest on Hackage: | 6.0.7 |
versions-5.0.0@sha256:4c649d7db19ff25f0e659d7009e26645ae68b2c554497ecc2f7bbd361f3671b3,2002
Module documentation for 5.0.0
- Data
versions
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
5.0.0 (2021-04-14)
This release brings versions
in line with version 2.0.0
of the SemVer spec.
The main addition to the spec is the allowance of hyphens in both the prerelease
and metadata sections. As such, certain versions like 1.2.3+1-1
which
previously would not parse as SemVer now do.
To accomodate this and other small spec updates, the SemVer
and Version
types have received breaking changes here.
Changed
- Breaking: The
_svMeta
field ofSemVer
is now parsed as a dumberMaybe Text
instead of[VChunk]
, due to metadata now being allowed to possess leading zeroes. - Breaking: Like the above, the
_vMeta
field ofVersion
is nowMaybe Text
. - Breaking: The
_vRel
and_vMeta
fields ofVersion
have had their order flipped. Further, the prelease and meta sections are now expected in the same order asSemVer
when parsing (prerel first, meta second).Version
is thus now a quite similar toSemVer
, except allowing letters in more permissive positions. - Breaking: The
meta
traversal has been altered to accomodate the metadata field changes.
Fixed
- Parsing certain legal SemVers specified in the spec.
4.0.3 (2021-02-23)
Changed
- Support for GHC 9.
4.0.2 (2021-01-23)
Fixed
- A bug in zero parsing within SemVer prereleases. #42
4.0.1 (2020-10-22)
Fixed
- An infinite loop in
Version
comparison. aura#652
4.0.0 (2020-10-20)
Changed
- Breaking:
VChunk
now cannot be empty. - Breaking: A
Version
now guaranteesNonEmpty
chunks. - Breaking: A
Mess
now guaranteesNonEmpty
chunks, and its structure has been significantly changed. Particularly,Mess
values are now aware of theInt
values they hold (when they do), as well as “revision” values of the patternrXYZ
. - Comparison of
Version
values is more memory efficient.
Added
Version
now has an extra field,_vMeta :: [VChunk]
for capturing “metadata” like Semver. This prevents otherwise nice-looking versions from being demoted toMess
.- The
MChunk
type to accomodate the changes toMess
mentioned above.
Removed
- Breaking:
Version
no longer has aMonoid
instance.
Fixed
""
no longer parses in any way. #32- Version strings with trailing whitespace no longer parse via
versioning
. #33 - Particular edge cases involving
Mess
comparisons. aura#646 - A particular edge case involving prereleases in
Version
comparisons. aura#586
3.5.4 (2020-05-12)
Added
- The functions
isIdeal
,isGeneral
, andisComplex
forBool
-based inspection of parse results. messMajor
,messMinor
,messPatch
, andmessPatchChunk
for improved introspection intoMess
values.
Changed
- Improved
Mess
comparison logic.
3.5.3
- GHC 8.10 support.
3.5.2
- Added a new
PVP
type and parsers.
3.5.1.1
- GHC 8.8 compatibility.
3.5.0
- Updated to
megaparsec-7
. OurParsingError
type alias has changed to match Megaparsec’s new error model, anderrorBundlePretty
is now exposed instead of the oldparseErrorPretty
.
3.4.0.1
- Enhanced the whitespace handling in
semver'
,version'
, andmess'
.
3.4.0
- Removed
ParseV
and surrounding machinery. Useversioning
now instead of theparseV
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
andVersion
should never contain negative values, so their numeric components were changed fromInt
toWord
.
3.2.0
- Updated for
megaparsec-6
and GHC 8.2.
3.1.1
- Added instances for common typeclasses:
Generic
,NFData
, andHashable
. 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 the1:
in1: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. TheVersion
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
andghc-8
2.0.0
- Switched to
megaparsec
to perform all parsing asText
- Support for legacy
String
removed - Added more Traversals and INLINE’d all Lenses/Traversals
1.1.0
- Added Lenses and Traversals (no
lens
dependency)