| Copyright | (c) Colin Woodbury 2015 - 2017 |
|---|---|
| License | BSD3 |
| Maintainer | Colin Woodbury <colingw@gmail.com> |
| Safe Haskell | None |
| Language | Haskell2010 |
Data.Versions
Contents
Description
A library for parsing and comparing software version numbers.
We like to give version numbers to our software in a myriad of different 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.
Using the Parsers
In general, parseV 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).
- data Versioning
- data SemVer = SemVer {}
- data Version = Version {}
- data Mess
- data VUnit
- type VChunk = [VUnit]
- data VSep
- newtype VParser = VParser {
- runVP :: Text -> Either ParsingError Versioning
- type ParsingError = ParseError (Token Text) Dec
- semver :: Text -> Either ParsingError SemVer
- version :: Text -> Either ParsingError Version
- mess :: Text -> Either ParsingError Mess
- parseV :: Text -> Either ParsingError Versioning
- semverP :: VParser
- versionP :: VParser
- messP :: VParser
- semver' :: Parser SemVer
- version' :: Parser Version
- mess' :: Parser Mess
- prettyV :: Versioning -> Text
- prettySemVer :: SemVer -> Text
- prettyVer :: Version -> Text
- prettyMess :: Mess -> Text
- parseErrorPretty :: (Ord t, ShowToken t, ShowErrorComponent e) => ParseError t e -> String
- _Versioning :: Applicative f => (Versioning -> f Versioning) -> Text -> f Text
- _SemVer :: Applicative f => (SemVer -> f SemVer) -> Text -> f Text
- _Version :: Applicative f => (Version -> f Version) -> Text -> f Text
- _Ideal :: Applicative f => (SemVer -> f SemVer) -> Versioning -> f Versioning
- _General :: Applicative f => (Version -> f Version) -> Versioning -> f Versioning
- _Complex :: Applicative f => (Mess -> f Mess) -> Versioning -> f Versioning
- svMajor :: Functor f => (Int -> f Int) -> SemVer -> f SemVer
- svMinor :: Functor f => (Int -> f Int) -> SemVer -> f SemVer
- svPatch :: Functor f => (Int -> f Int) -> SemVer -> f SemVer
- svPreRel :: Functor f => ([VChunk] -> f [VChunk]) -> SemVer -> f SemVer
- svMeta :: Functor f => ([VChunk] -> f [VChunk]) -> SemVer -> f SemVer
- vEpoch :: Functor f => (Maybe Int -> f (Maybe Int)) -> Version -> f Version
- vChunks :: Functor f => ([VChunk] -> f [VChunk]) -> Version -> f Version
- vRel :: Functor f => ([VChunk] -> f [VChunk]) -> Version -> f Version
- _Digits :: Applicative f => (Int -> f Int) -> VUnit -> f VUnit
- _Str :: Applicative f => (Text -> f Text) -> VUnit -> f VUnit
Types
data Versioning #
A top-level Versioning type. Acts as a wrapper for the more specific types. This allows each subtype to have its own parser, and for said parsers to be composed. This is useful for specifying custom behaviour for when a certain parser fails.
Instances
| Eq Versioning # | |
| Ord Versioning # | Comparison of If comparison of If comparison of |
| Show Versioning # | |
| Generic Versioning # | |
| NFData Versioning # | |
| Hashable Versioning # | |
| type Rep Versioning # | |
An (Ideal) version number that conforms to Semantic Versioning. This is a prescriptive parser, meaning it follows the SemVer standard.
Legal semvers are of the form: MAJOR.MINOR.PATCH-PREREL+META
Example: 1.2.3-r1+commithash
Extra Rules:
- Pre-release versions have lower precedence than normal versions.
- Build metadata does not affect version precedence.
For more information, see http://semver.org
Constructors
| SemVer | |
A (General) Version.
Not quite as ideal as a SemVer, but has some internal consistancy
from version to version.
Generally conforms to the x.x.x-x pattern, and may optionally have an epoch.
These are prefixes marked by a colon, like in 1:2.3.4.
Examples of Version that are not SemVer: 0.25-2, 8.u51-1, 20150826-1, 1:2.3.4
A (Complex) Mess. This is a descriptive parser, based on examples of stupidly crafted version numbers used in the wild.
Groups of letters/numbers, separated by a period, can be
further separated by the symbols _-+:
Unfortunately, VChunks cannot be used here, as some developers have
numbers like 1.003.04 which make parsers quite sad.
Not guaranteed to have well-defined ordering (Ord) behaviour,
but so far internal tests show consistency.
A single unit of a Version. May be digits or a string of characters.
Groups of these are called VChunks, and are the identifiers separated
by periods in the source.
A logical unit of a version number. Can consist of multiple letters and numbers.
Developers use a number of symbols to seperate groups of digits/letters in their version numbers. These are:
- A colon (:). Often denotes an "epoch".
- A hyphen (-).
- A plus (+). Stop using this outside of metadata if you are. Example:
10.2+0.93+1-1 - An underscore (_). Stop using this if you are.
A wrapper for a parser function. Can be composed via their Monoid instance, such that a different parser can be tried if a previous one fails.
Constructors
| VParser | |
Fields
| |
type ParsingError = ParseError (Token Text) Dec #
A synonym for the more verbose megaparsec error type.
Parsers
Wrapped Parsers
parseV :: Text -> Either ParsingError Versioning #
Parse a piece of Text into either an (Ideal) SemVer, a (General)
Version, or a (Complex) Mess.
Megaparsec Parsers
Pretty Printing
prettyV :: Versioning -> Text #
Convert any parsed Versioning type to its textual representation.
prettySemVer :: SemVer -> Text #
Convert a SemVer back to its textual representation.
prettyMess :: Mess -> Text #
Convert a Mess back to its textual representation.
Arguments
| :: (Ord t, ShowToken t, ShowErrorComponent e) | |
| => ParseError t e | Parse error to render |
| -> String | Result of rendering |
Pretty-print a ParseError. The rendered String always ends with a
newline.
The function is defined as:
parseErrorPretty e = sourcePosStackPretty (errorPos e) ++ ":\n" ++ parseErrorTextPretty e
Since: 5.0.0
Lenses
Traversing Text
_Versioning :: Applicative f => (Versioning -> f Versioning) -> Text -> f Text #
Traverse some Text for its inner versioning.
_Versioning :: Traversal' Text Versioning
("1.2.3" & _Versioning . _Ideal . svPatch %~ (+ 1)) == "1.2.4"_SemVer :: Applicative f => (SemVer -> f SemVer) -> Text -> f Text #
Traverse some Text for its inner SemVer.
_SemVer :: Traversal' Text SemVer
_Version :: Applicative f => (Version -> f Version) -> Text -> f Text #
Traverse some Text for its inner Version.
_Version :: Traversal' Text Version
Versioning Traversals
_Ideal :: Applicative f => (SemVer -> f SemVer) -> Versioning -> f Versioning #
_Ideal :: Traversal' Versioning SemVer
_General :: Applicative f => (Version -> f Version) -> Versioning -> f Versioning #
_General :: Traversal' Versioning Version
_Complex :: Applicative f => (Mess -> f Mess) -> Versioning -> f Versioning #
_Complex :: Traversal' Versioning Mess
(Ideal) SemVer Lenses
svPreRel :: Functor f => ([VChunk] -> f [VChunk]) -> SemVer -> f SemVer #
svPreRel :: Lens' SemVer Int
(General) Version Lenses
vEpoch :: Functor f => (Maybe Int -> f (Maybe Int)) -> Version -> f Version #
vEpoch :: Lens' Version (Maybe Int)
vChunks :: Functor f => ([VChunk] -> f [VChunk]) -> Version -> f Version #
vChunks :: Lens' Version [VChunk]
vRel :: Functor f => ([VChunk] -> f [VChunk]) -> Version -> f Version #
vRel :: Lens' Version [VChunk]