This module defines types and functions for working with versions as defined by Semantic Versioning. It also provides types and functions for working with version constraints as described by npm.

This module doesn't export anything that conflicts with the Prelude, so you can import it unqualified.

>>> import Salve

This module provides lenses for modifying versions. If you want to modify versions, consider importing a lens library like microlens.

The Version data type is the core of this module. Use parseVersion to make versions and renderVersion to convert them into strings.

>>> renderVersion <$> parseVersion "1.2.3"
Just "1.2.3"

The Constraint data type allows you to specify version constraints. Use parseConstraint to make constraints and renderConstraint to convert them into strings.

>>> renderConstraint <$> parseConstraint ">1.2.0"
Just ">1.2.0"

Use satisfiesConstraint to see if a version satisfiesConstraint a constraint.

>>> satisfiesConstraint <$> parseConstraint ">1.2.0" <*> parseVersion "1.2.3"
Just True

If you're coming from Cabal, you might not be familiar with npm's version range syntax. This table shows you how npm version ranges map to Cabal's version constraints.

Salve           | Cabal              | Notes
-----           | -----              | -----
<1.2.3          | <1.2.3             | -
<=1.2.3         | <=1.2.3            | -
=1.2.3          | ==1.2.3            | equals sign is optional
>=1.2.3         | >=1.2.3            | -
>1.2.3          | >1.2.3             | -
1.2.3 || >1.2.3 | ==1.2.3 || >1.2.3  | lower precedence than and
>=1.2.3 <2.0.0  | >=1.2.3 && <2.0.0  | higher precedence than or
1.2.3 - 2.3.4   | >=1.2.3 && <=2.3.4 | inclusive ranges
1.2.x           | ==1.2.*            | can use X or * instead of x
1.x.x           | ==1.*              | -
x.x.x           | ==*                | same as -any
~1.2.3          | ^>=1.2.3           | same as >=1.2.3 && <1.3.0
^1.2.3          | >=1.2.3 && <2      | -
^0.2.3          | >=0.2.3 && <0.3    | -
^0.0.3          | >=0.0.3 && <0.0.4  | -

Haskell's Package Versioning Policy (PVP) defines three things:

1. A spec for versioning your package, which includes how version numbers look and how to encode breaking changes.
2. A spec for constraining the versions of your dependencies, which incldues how version ranges look.
3. A prescription for how to constrain the versions of your dependencies, which includes how the ranges of your dependencies should be.

By comparison, Semantic Versioning only deals with the first thing. npm's version ranges only deal with the second thing. This module deals with the first and second things but leaves the third up to you.

Looking at the first point, why might you want to use SemVer instead of the PVP? The PVP has many problems, as described by the Problematic versioning policy blog post. In short, the PVP is too flexible and it's unique to Haskell, which causes unnecessary friction with developers from other languages.

Moving on to the second point, why should we use npm's version ranges instead of the PVP's? This is a less clear cut. The two syntaxes are broadly compatible. Really the only gains here are compatibility with a widely-used syntax and convenient shorthand for common constraints (like hyphens 1.2.3 - 2.3.4, tildes ~1.2.3, and carets ^1.2.3).

There are already a few modules that provide version numbers. Why do we need another one? Let's take a look at the options.

• Data.Version from the base package:

  • Exposes constructors, which allows creating versions that cannot be parsed.
  • Allows any number of components, from zero to inifinity.
  • Deprecated tags on versions.
  • Does not support build metadata on versions.
  • Does not support constraints.

• Distribution.Version from the Cabal package:

  • Has the same problems as Data.Version because it re-uses that version type.
  • Depends on the array, binary, bytestring, containers, deepseq, directory, filepath, pretty, process, time, and unix packages.

• Data.SemVer from the semver package:

  • Depends on the attoparsec, deepseq, and text packages.
  • Does not support version constraints.

• Data.SemVer from the semver-range package:

  • Depends on the classy-prelude, parsec, text, and unordered-containers packages.
  • Module name collides with the semver package.
  • Supports constraints, but does not provide a way to render them.

• Data.Versions from the versions package:

  • Depends on the deepseq, hashable, megaparsec, and text packages.
  • Intentially allows weird versions.
  • Does not support constraints.

By comparison, this module:

• Does not expose constructors. Any version you create can be rendered and parsed without issue.
• Requires exactly three components. You won't have to wonder if version 1.2.0 is greater than 1.2.
• Allows pre-release identifiers on versions. Go ahead and release version 1.0.0-alpha for early adopters.
• Allows build metadata on versions. Show when a release was made with versions like 1.0.0+2001-02-03.
• Supports version constraints. Just like versions, rendering and parsing constraints is no problem.
• Only depends on the base package. You can use all the functionality without installing any other packages.
• Has a unique module name. You won't have to use the PackageImports extension simply to deal with version numbers.

These functions can be used to unsafely parse strings. Instead of returning Nothing, they raise an exception. Only use these if you are sure the string can be successfully parsed!

These lenses can be used to access and modify specific parts of a Version.

Don't be scared by these type signatures. They are provided in full to avoid the RankNTypes language extension. The type signature Functor f => (a -> f a) -> Version -> f Version is the same as Lens' Version a, which you may already be familiar with.

These examples are provided to showcase functionality and explain weird behavior. If something isn't clear, please open a pull request adding an example!

Leading zeros are not allowed.

>>> parseVersion "01.0.0"
Nothing
>>> parseVersion "0.01.0"
Nothing
>>> parseVersion "0.0.01"
Nothing

Negative numbers are not allowed.

>>> parseVersion "-1.0.0"
Nothing
>>> parseVersion "0.-1.0"
Nothing
>>> parseVersion "0.0.-1"
Nothing

Non-digits are not allowed.

>>> parseVersion "a.0.0"
Nothing
>>> parseVersion "0.a.0"
Nothing
>>> parseVersion "0.0.a"
Nothing

Partial version numbers are not allowed.

>>> parseVersion "0.0"
Nothing

Extra version numbers are not allowed.

>>> parseVersion "0.0.0.0"
Nothing

Spaces are allowed

>>> parseVersion " 0.0.0"
Just (Version {versionMajor = 0, versionMinor = 0, versionPatch = 0, versionPreReleases = [], versionBuilds = []})
>>> parseVersion "0.0.0 "
Just (Version {versionMajor = 0, versionMinor = 0, versionPatch = 0, versionPreReleases = [], versionBuilds = []})

Interior spaces are not allowed.

>>> parseVersion "0 .0.0"
Nothing
>>> parseVersion "0. 0.0"
Nothing

Each version component cannot be larger than a 64-bit unsigned integer.

>>> parseVersion "18446744073709551615.0.0"
Just (Version {versionMajor = 18446744073709551615, versionMinor = 0, versionPatch = 0, versionPreReleases = [], versionBuilds = []})
>>> parseVersion "18446744073709551616.0.0"
Nothing

Numeric pre-releases tags cannot be larger than a 64-bit unsigned integer.

>>> parseVersion "0.0.0-18446744073709551615"
Just (Version {versionMajor = 0, versionMinor = 0, versionPatch = 0, versionPreReleases = [PreReleaseNumeric 18446744073709551615], versionBuilds = []})
>>> parseVersion "0.0.0-18446744073709551616"
Nothing

Build metadata is not numeric so it does not have any limit.

>>> parseVersion "0.0.0+18446744073709551615"
Just (Version {versionMajor = 0, versionMinor = 0, versionPatch = 0, versionPreReleases = [], versionBuilds = [Build "18446744073709551615"]})
>>> parseVersion "0.0.0+18446744073709551616"
Just (Version {versionMajor = 0, versionMinor = 0, versionPatch = 0, versionPreReleases = [], versionBuilds = [Build "18446744073709551616"]})

Partial version numbers are not allowed.

>>> parseConstraint "1.2"
Nothing

Wildcards (also known as "x-ranges") are allowed. The exact character used for the wildcard is not round-tripped.

>>> renderConstraint <$> parseConstraint "1.2.x"
Just "1.2.x"
>>> renderConstraint <$> parseConstraint "1.2.X"
Just "1.2.x"
>>> renderConstraint <$> parseConstraint "1.2.*"
Just "1.2.x"

An optional equals sign can be included with wildcard constraints.

>>> renderConstraint <$> parseConstraint "=1.2.x"
Just "1.2.x"

Wildcards can be combined with other constraints.

>>> renderConstraint <$> parseConstraint "1.2.x 2.3.4"
Just "1.2.x 2.3.4"
>>> renderConstraint <$> parseConstraint "1.2.x || 2.3.4"
Just "1.2.x || 2.3.4"

Wildcards are allowed at any position.

>>> renderConstraint <$> parseConstraint "1.2.x"
Just "1.2.x"
>>> renderConstraint <$> parseConstraint "1.x.x"
Just "1.x.x"
>>> renderConstraint <$> parseConstraint "x.x.x"
Just "x.x.x"

Non-wildcards cannot come after wildcards.

>>> parseConstraint "1.x.3"
Nothing
>>> parseConstraint "x.2.3"
Nothing
>>> parseConstraint "x.x.3"
Nothing
>>> parseConstraint "x.2.x"
Nothing

Wildcards cannot be used with other operators.

>>> parseConstraint "<1.2.x"
Nothing
>>> parseConstraint "<=1.2.x"
Nothing
>>> parseConstraint ">=1.2.x"
Nothing
>>> parseConstraint ">1.2.x"
Nothing
>>> parseConstraint "~1.2.x"
Nothing
>>> parseConstraint "^1.2.x"
Nothing
>>> parseConstraint "1.2.x - 2.3.4"
Nothing
>>> parseConstraint "1.2.3 - 2.3.x"
Nothing

Spaces are allowed in most places. Extra spaces are not round-tripped.

>>> renderConstraint <$> parseConstraint " 1.2.3 "
Just "1.2.3"
>>> renderConstraint <$> parseConstraint "> 1.2.3"
Just ">1.2.3"
>>> renderConstraint <$> parseConstraint "1.2.3  -  2.3.4"
Just "1.2.3 - 2.3.4"
>>> renderConstraint <$> parseConstraint "1.2.3  2.3.4"
Just "1.2.3 2.3.4"
>>> renderConstraint <$> parseConstraint "1.2.3  ||  2.3.4"
Just "1.2.3 || 2.3.4"

Parentheses are not allowed. Note that combining two constraints with a space (and) has higher precedence than combining them with pipes (or). In other words, "a b || c" parses as "(a b) || c", not "a (b || c)".

>>> parseConstraint "(1.2.3)"
Nothing
>>> parseConstraint "(1.2.3 || >1.2.3) <1.3.0"
Nothing
>>> parseConstraint "(>1.2.3 <1.3.0) || 1.2.3"
Nothing

Most constraints can be round-tripped through parsing and rendering.

>>> renderConstraint <$> parseConstraint "<1.2.3"
Just "<1.2.3"
>>> renderConstraint <$> parseConstraint "<=1.2.3"
Just "<=1.2.3"
>>> renderConstraint <$> parseConstraint "1.2.3"
Just "1.2.3"
>>> renderConstraint <$> parseConstraint ">=1.2.3"
Just ">=1.2.3"
>>> renderConstraint <$> parseConstraint ">1.2.3"
Just ">1.2.3"
>>> renderConstraint <$> parseConstraint "1.2.3 - 2.3.4"
Just "1.2.3 - 2.3.4"
>>> renderConstraint <$> parseConstraint "~1.2.3"
Just "~1.2.3"
>>> renderConstraint <$> parseConstraint "^1.2.3"
Just "^1.2.3"
>>> renderConstraint <$> parseConstraint ">1.2.3 <2.0.0"
Just ">1.2.3 <2.0.0"
>>> renderConstraint <$> parseConstraint "1.2.3 || >1.2.3"
Just "1.2.3 || >1.2.3"

Explicit equal signs do not get round-tripped.

>>> renderConstraint <$> parseConstraint "=1.2.3"
Just "1.2.3"

Pre-releases and builds are allowed on any constraints except wildcards.

>>> renderConstraint <$> parseConstraint "1.2.3-p+b"
Just "1.2.3-p+b"
>>> renderConstraint <$> parseConstraint ">1.2.3-p+b"
Just ">1.2.3-p+b"
>>> renderConstraint <$> parseConstraint "1.2.3-p+b - 2.3.4-p+b"
Just "1.2.3-p+b - 2.3.4-p+b"
>>> renderConstraint <$> parseConstraint "~1.2.3-p+b"
Just "~1.2.3-p+b"
>>> renderConstraint <$> parseConstraint "^1.2.3-p+b"
Just "^1.2.3-p+b"

>>> parseConstraint "1.2.x-p+b"
Nothing

These examples show every type of constraint in a single expression.

>>> renderConstraint <$> parseConstraint "<1.2.0 <=1.2.1 =1.2.2 >=1.2.3 >1.2.4 1.2.5 1.2.6 - 1.2.7 ~1.2.8 ^1.2.9 1.2.x"
Just "<1.2.0 <=1.2.1 1.2.2 >=1.2.3 >1.2.4 1.2.5 1.2.6 - 1.2.7 ~1.2.8 ^1.2.9 1.2.x"
>>> renderConstraint <$> parseConstraint "<1.2.0 <=1.2.1 || =1.2.2 >=1.2.3 || >1.2.4 1.2.5 || 1.2.6 - 1.2.7 ~1.2.8 || ^1.2.9 1.2.x"
Just "<1.2.0 <=1.2.1 || 1.2.2 >=1.2.3 || >1.2.4 1.2.5 || 1.2.6 - 1.2.7 ~1.2.8 || ^1.2.9 1.2.x"
>>> renderConstraint <$> parseConstraint "<1.2.0 || <=1.2.1 =1.2.2 || >=1.2.3 >1.2.4 || 1.2.5 1.2.6 - 1.2.7 || ~1.2.8 ^1.2.9 || 1.2.x"
Just "<1.2.0 || <=1.2.1 1.2.2 || >=1.2.3 >1.2.4 || 1.2.5 1.2.6 - 1.2.7 || ~1.2.8 ^1.2.9 || 1.2.x"
>>> renderConstraint <$> parseConstraint "<1.2.0 || <=1.2.1 || =1.2.2 || >=1.2.3 || >1.2.4 || 1.2.5 || 1.2.6 - 1.2.7 || ~1.2.8 || ^1.2.9 || 1.2.x"
Just "<1.2.0 || <=1.2.1 || 1.2.2 || >=1.2.3 || >1.2.4 || 1.2.5 || 1.2.6 - 1.2.7 || ~1.2.8 || ^1.2.9 || 1.2.x"

Although in general you should use satisfiesConstraint, parseVersion, and parseConstraint, doing that here makes it hard to tell what the examples are doing. An operator makes things clearer.

>>> satisfiesConstraint <$> parseConstraint "=1.2.3" <*> parseVersion "1.2.3"
Just True
>>> let version ? constraint = satisfiesConstraint (unsafeParseConstraint constraint) (unsafeParseVersion version)
>>> "1.2.3" ? "=1.2.3"
True

• Less than:

  >>> "1.2.2" ? "<1.2.3"
  True
  >>> "1.2.3" ? "<1.2.3"
  False
  >>> "1.2.4" ? "<1.2.3"
  False
  >>> "1.2.3-pre" ? "<1.2.3"
  True
  

• Less than or equal to:

  >>> "1.2.2" ? "<=1.2.3"
  True
  >>> "1.2.3" ? "<=1.2.3"
  True
  >>> "1.2.4" ? "<=1.2.3"
  False
  

• Equal to:

  >>> "1.2.2" ? "=1.2.3"
  False
  >>> "1.2.3" ? "=1.2.3"
  True
  >>> "1.2.4" ? "=1.2.3"
  False
  >>> "1.2.3-pre" ? "=1.2.3"
  False
  >>> "1.2.3+build" ? "=1.2.3"
  True
  

• Greater than or equal to:

  >>> "1.2.2" ? ">=1.2.3"
  False
  >>> "1.2.3" ? ">=1.2.3"
  True
  >>> "1.2.4" ? ">=1.2.3"
  True
  

• Greater than:

  >>> "1.2.2" ? ">1.2.3"
  False
  >>> "1.2.3" ? ">1.2.3"
  False
  >>> "1.2.4" ? ">1.2.3"
  True
  >>> "1.2.4-pre" ? ">1.2.3"
  True
  

  >>> "1.2.4" ? ">1.2.3-pre"
  True
  

• And:

  >>> "1.2.3" ? ">1.2.3 <1.2.5"
  False
  >>> "1.2.4" ? ">1.2.3 <1.2.5"
  True
  >>> "1.2.5" ? ">1.2.3 <1.2.5"
  False
  

• Or:

  >>> "1.2.2" ? "1.2.3 || 1.2.4"
  False
  >>> "1.2.3" ? "1.2.3 || 1.2.4"
  True
  >>> "1.2.4" ? "1.2.3 || 1.2.4"
  True
  >>> "1.2.5" ? "1.2.3 || 1.2.4"
  False
  

• And & or:

  >>> "1.2.2" ? "1.2.2 || >1.2.3 <1.3.0"
  True
  >>> "1.2.3" ? "1.2.2 || >1.2.3 <1.3.0"
  False
  >>> "1.2.4" ? "1.2.2 || >1.2.3 <1.3.0"
  True
  >>> "1.3.0" ? "1.2.2 || >1.2.3 <1.3.0"
  False
  

• Hyphen:

  >>> "1.2.2" ? "1.2.3 - 1.2.4"
  False
  >>> "1.2.3" ? "1.2.3 - 1.2.4"
  True
  >>> "1.2.4" ? "1.2.3 - 1.2.4"
  True
  >>> "1.2.5" ? "1.2.3 - 1.2.4"
  False
  

• Tilde:

  >>> "1.2.2" ? "~1.2.3"
  False
  >>> "1.2.3" ? "~1.2.3"
  True
  >>> "1.2.4" ? "~1.2.3"
  True
  >>> "1.3.0" ? "~1.2.3"
  False
  

• Caret:

  >>> "1.2.2" ? "^1.2.3"
  False
  >>> "1.2.3" ? "^1.2.3"
  True
  >>> "1.2.4" ? "^1.2.3"
  True
  >>> "1.3.0" ? "^1.2.3"
  True
  >>> "2.0.0" ? "^1.2.3"
  False
  

  >>> "0.2.2" ? "^0.2.3"
  False
  >>> "0.2.3" ? "^0.2.3"
  True
  >>> "0.2.4" ? "^0.2.3"
  True
  >>> "0.3.0" ? "^0.2.3"
  False
  

  >>> "0.0.2" ? "^0.0.3"
  False
  >>> "0.0.3" ? "^0.0.3"
  True
  >>> "0.0.4" ? "^0.0.3"
  False
  

• Wildcard:

  >>> "1.1.0" ? "1.2.x"
  False
  >>> "1.2.3" ? "1.2.x"
  True
  >>> "1.3.0" ? "1.2.x"
  False
  

  >>> "0.1.0" ? "1.x.x"
  False
  >>> "1.0.0" ? "1.x.x"
  True
  >>> "1.2.3" ? "1.x.x"
  True
  >>> "2.0.0" ? "1.x.x"
  False
  

  >>> "0.0.0" ? "x.x.x"
  True
  >>> "1.2.3" ? "x.x.x"
  True
  >>> "2.0.0" ? "x.x.x"
  True