Safe Haskell | Safe |
---|---|
Language | Haskell2010 |
WARNING: This module should be considered private! If you find yourself wanting to import something from this module, please open an issue to get that thing exported from Salve.
- data Version = Version {
- versionMajor :: Word
- versionMinor :: Word
- versionPatch :: Word
- versionPreReleases :: [PreRelease]
- versionBuilds :: [Build]
- data PreRelease
- newtype Build = Build String
- data Constraint
- makeVersion :: Word -> Word -> Word -> [PreRelease] -> [Build] -> Version
- initialVersion :: Version
- parseVersion :: String -> Maybe Version
- parsePreRelease :: String -> Maybe PreRelease
- parseBuild :: String -> Maybe Build
- parseConstraint :: String -> Maybe Constraint
- unsafeParseVersion :: String -> Version
- unsafeParsePreRelease :: String -> PreRelease
- unsafeParseBuild :: String -> Build
- unsafeParseConstraint :: String -> Constraint
- renderVersion :: Version -> String
- renderPreRelease :: PreRelease -> String
- renderBuild :: Build -> String
- renderConstraint :: Constraint -> String
- isUnstable :: Version -> Bool
- isStable :: Version -> Bool
- bumpMajor :: Version -> Version
- bumpMinor :: Version -> Version
- bumpPatch :: Version -> Version
- satisfiesConstraint :: Constraint -> Version -> Bool
- majorLens :: Functor f => (Word -> f Word) -> Version -> f Version
- minorLens :: Functor f => (Word -> f Word) -> Version -> f Version
- patchLens :: Functor f => (Word -> f Word) -> Version -> f Version
- preReleasesLens :: Functor f => ([PreRelease] -> f [PreRelease]) -> Version -> f Version
- buildsLens :: Functor f => ([Build] -> f [Build]) -> Version -> f Version
- data Operator
- data Wildcard
- constraintLT :: Version -> Constraint
- constraintLE :: Version -> Constraint
- constraintEQ :: Version -> Constraint
- constraintGE :: Version -> Constraint
- constraintGT :: Version -> Constraint
- constraintAnd :: Constraint -> Constraint -> Constraint
- constraintOr :: Constraint -> Constraint -> Constraint
- constraintHyphen :: Version -> Version -> Constraint
- constraintTilde :: Version -> Constraint
- constraintCaret :: Version -> Constraint
- versionP :: ReadP Version
- preReleasesP :: ReadP [PreRelease]
- preReleaseP :: ReadP PreRelease
- preReleaseNumberP :: ReadP PreRelease
- preReleaseStringP :: ReadP PreRelease
- buildsP :: ReadP [Build]
- buildP :: ReadP Build
- numberP :: ReadP Word
- zeroP :: ReadP Word
- nonZeroP :: ReadP Word
- constraintsP :: ReadP Constraint
- constraintP :: ReadP Constraint
- hyphenatedP :: ReadP Constraint
- simpleP :: ReadP Constraint
- wildcardConstraintP :: ReadP Constraint
- wildcardP :: ReadP Wildcard
- wildcardPatchP :: ReadP Wildcard
- wildcardMinorP :: ReadP Wildcard
- wildcardMajorP :: ReadP Wildcard
- primitiveP :: ReadP Constraint
- operatorP :: ReadP Operator
- hyphenP :: ReadP ()
- orP :: ReadP ()
- spaces1P :: ReadP ()
- spacesP :: ReadP ()
- renderPreReleases :: [PreRelease] -> String
- renderBuilds :: [Build] -> String
- both :: (a -> b) -> (a, a) -> (b, b)
- isAsciiDigitNonZero :: Char -> Bool
- isIdentifier :: Char -> Bool
- isWildcard :: Char -> Bool
- parse :: ReadP a -> String -> Maybe a
- data SimpleConstraint
- mkV :: Word -> Word -> Word -> Version
- satisfiesSC :: SimpleConstraint -> Version -> Bool
- scLE :: Version -> SimpleConstraint
- scGE :: Version -> SimpleConstraint
- toSC :: Constraint -> SimpleConstraint
Documentation
>>>
import Lens.Micro
>>>
import Lens.Micro.Extras
Public
A semantic version number. Versions have five parts:
majorLens
: The major version number.minorLens
: The minor version number.patchLens
: The patch version number.preReleasesLens
: A list of pre-release identifiers.buildsLens
: A list of build metadata.
Use parseVersion
to create versions.
Version | |
|
Eq Version Source # | |
Ord Version Source # | In general,
Numbers are compared numerically, not alphabetically.
If all the numbers are the same, the pre-releases are compared.
A version with a pre-release is always less than a version without one as long as the other parts are the same.
Builds are not considered when comparing versions.
|
Show Version Source # | |
data PreRelease Source #
Pre-release information attached to a version. These can either be numeric or textual. They must not be empty.
- Numeric: Can be any non-negative integer. Cannot have leading zeros.
- Textual: Can be any string of ASCII digits, letters, or hyphens. Cannot be all digits, as that would be numeric.
In general, pre-releases must match the regular expression
/^[-0-9A-Za-z]+$/
.
Use parsePreRelease
to create pre-releases.
Eq PreRelease Source # | |
Ord PreRelease Source # | Numeric pre-releases are always less than textual pre-releases.
Numeric pre-releases are compared numerically.
Textual pre-releases are compared alphabetically.
|
Show PreRelease Source # | |
Build metadata attached to a version. These are similar to
PreRelease
s with some key differences:
- There is no such thing as numeric builds. Even though builds can look like numbers, all builds are textual.
- As a result, builds that look numeric are allowed to have leading zeros.
- Builds cannot be compared. That is, they do not have an
Ord
instance.
Use parseBuild
to create builds.
data Constraint Source #
Constrains allowable version numbers.
Use parseConstraint
to create constraints and satisfiesConstraint
to see
if a version number satisfiesConstraint a constraint.
makeVersion :: Word -> Word -> Word -> [PreRelease] -> [Build] -> Version Source #
Makes a new version number.
>>>
makeVersion 0 0 0 [] []
Version {versionMajor = 0, versionMinor = 0, versionPatch = 0, versionPreReleases = [], versionBuilds = []}
This can be a useful alternative to parseVersion
if you want a total way
to create a version.
initialVersion :: Version Source #
The initial version number for development.
>>>
initialVersion
Version {versionMajor = 0, versionMinor = 0, versionPatch = 0, versionPreReleases = [], versionBuilds = []}
parseVersion :: String -> Maybe Version Source #
Attempts to parse a version. This parser follows SemVer's BNF.
>>>
parseVersion "1.2.3-p.4+b.5"
Just (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [PreReleaseTextual "p",PreReleaseNumeric 4], versionBuilds = [Build "b",Build "5"]})
Returns Nothing
if the parse fails.
>>>
parseVersion "wrong"
Nothing
Whitespace is not allowed and will cause the parser to fail.
>>>
parseVersion " 1.2.3 "
Nothing
parsePreRelease :: String -> Maybe PreRelease Source #
Attempts to parse a pre-release.
>>>
parsePreRelease "pre"
Just (PreReleaseTextual "pre")>>>
parsePreRelease "1"
Just (PreReleaseNumeric 1)
Returns Nothing
if the parse fails.
>>>
parsePreRelease "wrong!"
Nothing
Numeric pre-releases cannot contain leading zeros.
>>>
parsePreRelease "01"
Nothing
parseBuild :: String -> Maybe Build Source #
Attempts to parse a build.
>>>
parseBuild "build"
Just (Build "build")>>>
parseBuild "1"
Just (Build "1")
Returns Nothing
if the parse fails.
>>>
parseBuild "wrong!"
Nothing
Unlike pre-releases, numeric builds can have leading zeros.
>>>
parseBuild "01"
Just (Build "01")
parseConstraint :: String -> Maybe Constraint Source #
Attempts to parse a constraint. This parser follows npm's
BNF,
except that neither the so-called "x-ranges" nor partial version numbers are
not supported. So you cannot use 1.2.x
or >1.2
as version constraints.
>>>
parseConstraint ">1.2.3"
Just (ConstraintOperator OperatorGT (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []}))
Returns Nothing
if the parse fails.
>>>
parseConstraint "wrong"
Nothing
unsafeParseVersion :: String -> Version Source #
Parses a version.
>>>
unsafeParseVersion "1.2.3-p.4+b.5"
Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [PreReleaseTextual "p",PreReleaseNumeric 4], versionBuilds = [Build "b",Build "5"]}
Raises an exception if the parse fails.
>>>
unsafeParseVersion "wrong"
*** Exception: unsafeParseVersion: invalid version: "wrong" ...
See parseVersion
for a safe version of this function.
unsafeParsePreRelease :: String -> PreRelease Source #
Parses a pre-release.
>>>
unsafeParsePreRelease "pre"
PreReleaseTextual "pre"
Raises an exception if the parse fails.
>>>
unsafeParsePreRelease "wrong!"
*** Exception: unsafeParsePreRelease: invalid pre-release: "wrong!" ...
See parsePreRelease
for a safe version of this function.
unsafeParseBuild :: String -> Build Source #
Parses a build.
>>>
unsafeParseBuild "build"
Build "build"
Raises an exception if the parse fails.
>>>
unsafeParseBuild "wrong!"
Build "*** Exception: unsafeParseBuild: invalid build: "wrong!" ...
See parseBuild
for a safe version of this function.
unsafeParseConstraint :: String -> Constraint Source #
Parses a constraint.
>>>
unsafeParseConstraint ">1.2.3"
ConstraintOperator OperatorGT (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []})
Raises an exception if the parse fails.
>>>
unsafeParseConstraint "wrong"
*** Exception: unsafeParseConstraint: invalid constraint: "wrong" ...
See parseConstraint
for a safe version of this function.
renderVersion :: Version -> String Source #
Renders a version.
>>>
renderVersion <$> parseVersion "1.2.3-p.4+b.5"
Just "1.2.3-p.4+b.5"
renderPreRelease :: PreRelease -> String Source #
Renders a pre-release.
>>>
renderPreRelease <$> parsePreRelease "pre"
Just "pre">>>
renderPreRelease <$> parsePreRelease "1"
Just "1"
renderBuild :: Build -> String Source #
Renders a build.
>>>
renderBuild <$> parseBuild "build"
Just "build">>>
renderBuild <$> parseBuild "1"
Just "1"
renderConstraint :: Constraint -> String Source #
Renders a constraint.
>>>
renderConstraint <$> parseConstraint ">1.2.3"
Just ">1.2.3"
Parsing and rendering a constraint doesn't always return what you started with.
>>>
renderConstraint <$> parseConstraint "=1.2.3"
Just "1.2.3"
isUnstable :: Version -> Bool Source #
bumpMajor :: Version -> Version Source #
Increments the major version number.
>>>
bumpMajor <$> parseVersion "0.0.0"
Just (Version {versionMajor = 1, versionMinor = 0, versionPatch = 0, versionPreReleases = [], versionBuilds = []})
The minor and patch numbers are reset to zero.
>>>
bumpMajor <$> parseVersion "1.2.3"
Just (Version {versionMajor = 2, versionMinor = 0, versionPatch = 0, versionPreReleases = [], versionBuilds = []})
The pre-releases and builds are removed.
>>>
bumpMajor <$> parseVersion "0.0.0-pre+build"
Just (Version {versionMajor = 1, versionMinor = 0, versionPatch = 0, versionPreReleases = [], versionBuilds = []})
Consider using majorLens
if you want to arbitrarily change the major
number, or if you don't want the other parts of the version to change.
bumpMinor :: Version -> Version Source #
Increments the minor version number.
>>>
bumpMinor <$> parseVersion "0.0.0"
Just (Version {versionMajor = 0, versionMinor = 1, versionPatch = 0, versionPreReleases = [], versionBuilds = []})
The patch number is reset to zero.
>>>
bumpMinor <$> parseVersion "1.2.3"
Just (Version {versionMajor = 1, versionMinor = 3, versionPatch = 0, versionPreReleases = [], versionBuilds = []})
The pre-releases and builds are removed.
>>>
bumpMinor <$> parseVersion "0.0.0-pre+build"
Just (Version {versionMajor = 0, versionMinor = 1, versionPatch = 0, versionPreReleases = [], versionBuilds = []})
Consider using minorLens
if you want to arbitrarily change the minor
number, or if you don't want the other parts of the version to change.
bumpPatch :: Version -> Version Source #
Increments the patch number.
>>>
bumpPatch <$> parseVersion "0.0.0"
Just (Version {versionMajor = 0, versionMinor = 0, versionPatch = 1, versionPreReleases = [], versionBuilds = []})
The major and minor numbers are not changed.
>>>
bumpPatch <$> parseVersion "1.2.3"
Just (Version {versionMajor = 1, versionMinor = 2, versionPatch = 4, versionPreReleases = [], versionBuilds = []})
The pre-releases and builds are removed.
>>>
bumpPatch <$> parseVersion "0.0.0-pre+build"
Just (Version {versionMajor = 0, versionMinor = 0, versionPatch = 1, versionPreReleases = [], versionBuilds = []})
Consider using patchLens
if you want to arbitrarily change the patch
number, or if you don't want the other parts of the version to change.
satisfiesConstraint :: Constraint -> Version -> Bool Source #
majorLens :: Functor f => (Word -> f Word) -> Version -> f Version Source #
Focuses on the major version number.
>>>
view majorLens <$> parseVersion "1.2.3-pre.4+build.5"
Just 1>>>
set majorLens 4 <$> parseVersion "1.2.3"
Just (Version {versionMajor = 4, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []})
minorLens :: Functor f => (Word -> f Word) -> Version -> f Version Source #
Focuses on the minor version number.
>>>
view minorLens <$> parseVersion "1.2.3-pre.4+build.5"
Just 2>>>
set minorLens 4 <$> parseVersion "1.2.3"
Just (Version {versionMajor = 1, versionMinor = 4, versionPatch = 3, versionPreReleases = [], versionBuilds = []})
patchLens :: Functor f => (Word -> f Word) -> Version -> f Version Source #
Focuses on the patch version number.
>>>
view patchLens <$> parseVersion "1.2.3-pre.4+build.5"
Just 3>>>
set patchLens 4 <$> parseVersion "1.2.3"
Just (Version {versionMajor = 1, versionMinor = 2, versionPatch = 4, versionPreReleases = [], versionBuilds = []})
preReleasesLens :: Functor f => ([PreRelease] -> f [PreRelease]) -> Version -> f Version Source #
Focuses on the pre-release identifiers.
>>>
view preReleasesLens <$> parseVersion "1.2.3-pre.4+build.5"
Just [PreReleaseTextual "pre",PreReleaseNumeric 4]>>>
set preReleasesLens [] <$> parseVersion "1.2.3-pre"
Just (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []})
buildsLens :: Functor f => ([Build] -> f [Build]) -> Version -> f Version Source #
Focuses on the build metadata.
>>>
view buildsLens <$> parseVersion "1.2.3-pre.4+build.5"
Just [Build "build",Build "5"]>>>
set buildsLens [] <$> parseVersion "1.2.3+build"
Just (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []})
Private
Types
Constructors
constraintLT :: Version -> Constraint Source #
Makes a new constraint that must be less than the version number.
>>>
constraintLT <$> parseVersion "1.2.3"
Just (ConstraintOperator OperatorLT (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []}))>>>
parseConstraint "<1.2.3"
Just (ConstraintOperator OperatorLT (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []}))
constraintLE :: Version -> Constraint Source #
Makes a new constraint that must be less than or euqal to the version number.
>>>
constraintLE <$> parseVersion "1.2.3"
Just (ConstraintOperator OperatorLE (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []}))>>>
parseConstraint "<=1.2.3"
Just (ConstraintOperator OperatorLE (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []}))
constraintEQ :: Version -> Constraint Source #
Makes a new constraint that must be equal to the version number.
>>>
constraintEQ <$> parseVersion "1.2.3"
Just (ConstraintOperator OperatorEQ (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []}))>>>
parseConstraint "=1.2.3"
Just (ConstraintOperator OperatorEQ (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []}))
constraintGE :: Version -> Constraint Source #
Makes a new constraint that must be greater than or equal to the version number.
>>>
constraintGE <$> parseVersion "1.2.3"
Just (ConstraintOperator OperatorGE (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []}))>>>
parseConstraint ">=1.2.3"
Just (ConstraintOperator OperatorGE (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []}))
constraintGT :: Version -> Constraint Source #
Makes a new constraint that must be greater than the version number.
>>>
constraintGT <$> parseVersion "1.2.3"
Just (ConstraintOperator OperatorGT (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []}))>>>
parseConstraint ">1.2.3"
Just (ConstraintOperator OperatorGT (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []}))
constraintAnd :: Constraint -> Constraint -> Constraint Source #
Makes a new constraint that must satisfy both constraints.
>>>
constraintAnd <$> (constraintGE <$> parseVersion "1.2.3") <*> (constraintLT <$> parseVersion "2.0.0")
Just (ConstraintAnd (ConstraintOperator OperatorGE (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []})) (ConstraintOperator OperatorLT (Version {versionMajor = 2, versionMinor = 0, versionPatch = 0, versionPreReleases = [], versionBuilds = []})))>>>
parseConstraint ">=1.2.3 <2.0.0"
Just (ConstraintAnd (ConstraintOperator OperatorGE (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []})) (ConstraintOperator OperatorLT (Version {versionMajor = 2, versionMinor = 0, versionPatch = 0, versionPreReleases = [], versionBuilds = []})))
constraintOr :: Constraint -> Constraint -> Constraint Source #
Makes a new constraint that must satisfy either constraint.
>>>
constraintOr <$> (constraintEQ <$> parseVersion "1.2.3") <*> (constraintGT <$> parseVersion "1.2.3")
Just (ConstraintOr (ConstraintOperator OperatorEQ (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []})) (ConstraintOperator OperatorGT (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []})))>>>
parseConstraint "=1.2.3 || >1.2.3"
Just (ConstraintOr (ConstraintOperator OperatorEQ (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []})) (ConstraintOperator OperatorGT (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []})))
constraintHyphen :: Version -> Version -> Constraint Source #
Makes a new constraint that must be between the versions, inclusive.
>>>
constraintHyphen <$> parseVersion "1.2.3" <*> parseVersion "2.3.4"
Just (ConstraintHyphen (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []}) (Version {versionMajor = 2, versionMinor = 3, versionPatch = 4, versionPreReleases = [], versionBuilds = []}))>>>
parseConstraint "1.2.3 - 2.3.4"
Just (ConstraintHyphen (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []}) (Version {versionMajor = 2, versionMinor = 3, versionPatch = 4, versionPreReleases = [], versionBuilds = []}))
constraintTilde :: Version -> Constraint Source #
Makes a new constraint that allows changes to the patch version number.
>>>
constraintTilde <$> parseVersion "1.2.3"
Just (ConstraintOperator OperatorTilde (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []}))>>>
parseConstraint "~1.2.3"
Just (ConstraintOperator OperatorTilde (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []}))
constraintCaret :: Version -> Constraint Source #
Makes a new constraint that allows changes that do not modify the left-most non-zero version number.
>>>
constraintCaret <$> parseVersion "1.2.3"
Just (ConstraintOperator OperatorCaret (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []}))>>>
parseConstraint "^1.2.3"
Just (ConstraintOperator OperatorCaret (Version {versionMajor = 1, versionMinor = 2, versionPatch = 3, versionPreReleases = [], versionBuilds = []}))
Parsing
preReleasesP :: ReadP [PreRelease] Source #
Rendering
renderPreReleases :: [PreRelease] -> String Source #
renderBuilds :: [Build] -> String Source #
Helpers
isAsciiDigitNonZero :: Char -> Bool Source #
isIdentifier :: Char -> Bool Source #
isWildcard :: Char -> Bool Source #
Simple constraints
data SimpleConstraint Source #
Simple constraints are just as expressive as Constraint
s, but they are
easier to reason about. You can think of them as the desugared version of
Constraint
s.
satisfiesSC :: SimpleConstraint -> Version -> Bool Source #
scLE :: Version -> SimpleConstraint Source #
scGE :: Version -> SimpleConstraint Source #
toSC :: Constraint -> SimpleConstraint Source #