| Copyright | (c) Colin Woodbury 2015 - 2018 |
|---|---|
| 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
- digits :: Word -> VUnit
- str :: Text -> Maybe VUnit
- type VChunk = [VUnit]
- data VSep
- newtype VParser = VParser {
- runVP :: Text -> Either ParsingError Versioning
- type ParsingError = ParseError (Token Text) Void
- 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' :: Parsec Void Text SemVer
- version' :: Parsec Void Text Version
- mess' :: Parsec Void Text Mess
- prettyV :: Versioning -> Text
- prettySemVer :: SemVer -> Text
- prettyVer :: Version -> Text
- prettyMess :: Mess -> Text
- parseErrorPretty :: (Ord t, ShowToken t, ShowErrorComponent e) => ParseError t e -> String
- type Lens' s a = forall f. Functor f => (a -> f a) -> s -> f s
- type Traversal' s a = forall f. Applicative f => (a -> f a) -> s -> f s
- class Semantic v where
- _Versioning :: Traversal' Text Versioning
- _SemVer :: Traversal' Text SemVer
- _Version :: Traversal' Text Version
- _Mess :: Traversal' Text Mess
- _Ideal :: Traversal' Versioning SemVer
- _General :: Traversal' Versioning Version
- _Complex :: Traversal' Versioning Mess
- epoch :: Lens' Version (Maybe Word)
- _Digits :: Traversal' VUnit Word
- _Str :: Traversal' VUnit Text
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 # | |
| Semantic 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.
- PREREL and META strings may only contain ASCII alphanumerics.
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.
Parsers
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) Void #
A synonym for the more verbose megaparsec error type.
Wrapped Parsers
parseV :: Text -> Either ParsingError Versioning #
Megaparsec Parsers
For when you'd like to mix version parsing into some larger parser.
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.
Since: 5.0.0
Lenses
type Lens' s a = forall f. Functor f => (a -> f a) -> s -> f s #
Simple Lenses compatible with both lens and microlens.
type Traversal' s a = forall f. Applicative f => (a -> f a) -> s -> f s #
Simple Traversals compatible with both lens and microlens.
Version types which sanely and safely yield SemVer-like information
about themselves. For instances other than SemVer itself however,
these optics may not yield anything, depending on the actual value being
traversed. Hence, the optics here are all Traversal's.
Consider the Version 1.2.3.4.5. We can imagine wanting to increment
the minor number:
λ "1.2.3.4.5" & minor %~ (+ 1) "1.3.3.4.5"
But of course something like this would fail:
λ "1.e.3.4.5" & minor %~ (+ 1) "1.e.3.4.5"
However!
λ "1.e.3.4.5" & major %~ (+ 1) "2.e.3.4.5"
Methods
major :: Traversal' v Word #
MAJOR.minor.patch-prerel+meta
minor :: Traversal' v Word #
major.MINOR.patch-prerel+meta
patch :: Traversal' v Word #
major.minor.PATCH-prerel+meta
release :: Traversal' v [VChunk] #
major.minor.patch-PREREL+meta
meta :: Traversal' v [VChunk] #
major.minor.patch-prerel+META
semantic :: Traversal' v SemVer #
A Natural Transformation into an proper SemVer.
Traversing Text
When traversing Text, leveraging its Semantic instance will
likely benefit you more than using these Traversals directly.
_Versioning :: Traversal' Text Versioning #
Traverse some Text for its inner versioning.
λ "1.2.3" & _Versioning . _Ideal . patch %~ (+ 1) -- or just: "1.2.3" & patch %~ (+ 1) "1.2.4"
_SemVer :: Traversal' Text SemVer #
Traverse some Text for its inner SemVer.
_Version :: Traversal' Text Version #
Traverse some Text for its inner Version.
_Mess :: Traversal' Text Mess #
Traverse some Text for its inner Mess.
Versioning Traversals
(General) Version Lenses
Misc. Lenses / Traversals
_Digits :: Traversal' VUnit Word #
_Str :: Traversal' VUnit Text #