-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Types and parsers for software version numbers.
--   
--   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 <i>any</i> style of versioning, be it a
--   nice Semantic Version like this:
--   
--   <pre>
--   1.2.3-r1+git123
--   </pre>
--   
--   ...or a monstrosity like this:
--   
--   <pre>
--   2:10.2+0.0093r3+1-1
--   </pre>
--   
--   Please switch to <a>Semantic Versioning</a> if you aren't currently
--   using it. It provides consistency in version incrementing and has the
--   best constraints on comparisons.
@package versions
@version 1.0.2


-- | 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 <i>any</i> style of versioning, be it a
--   nice Semantic Version like this:
--   
--   <pre>
--   1.2.3-r1+git123
--   </pre>
--   
--   ...or a monstrosity like this:
--   
--   <pre>
--   2:10.2+0.0093r3+1-1
--   </pre>
--   
--   Please switch to <a>Semantic Versioning</a> if you aren't currently
--   using it. It provides consistency in version incrementing and has the
--   best constraints on comparisons.
--   
--   <h2>Using the Parsers</h2>
--   
--   In general, <a>parseV</a> is the function you want. It attempts to
--   parse a given <tt>Text</tt> using the three individual parsers,
--   <a>semver</a>, <a>version</a> and <a>mess</a>. 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. <a>semver</a>).
module Data.Versions

-- | 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.
data Versioning
Ideal :: SemVer -> Versioning
General :: Version -> Versioning
Complex :: Mess -> Versioning

-- | An (Ideal) version number that conforms to Semantic Versioning. This
--   is a <i>prescriptive</i> 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:
--   
--   <ol>
--   <li>Pre-release versions have <i>lower</i> precedence than normal
--   versions.</li>
--   <li>Build metadata does not affect version precedence.</li>
--   </ol>
--   
--   For more information, see <a>http://semver.org</a>
data SemVer
SemVer :: Int -> Int -> Int -> [VChunk] -> [VChunk] -> SemVer
[svMajor] :: SemVer -> Int
[svMinor] :: SemVer -> Int
[svPatch] :: SemVer -> Int
[svPreRel] :: SemVer -> [VChunk]
[svMeta] :: SemVer -> [VChunk]

-- | A (General) Version. Not quite as ideal as a <a>SemVer</a>, but has
--   some internal consistancy from version to version. Generally conforms
--   to the <tt>x.x.x-x</tt> pattern.
--   
--   Examples of <tt>Version</tt> that are not <tt>SemVer</tt>: 0.25-2,
--   8.u51-1, 20150826-1
data Version
Version :: [VChunk] -> [VChunk] -> Version
[vChunks] :: Version -> [VChunk]
[vRel] :: Version -> [VChunk]

-- | A (Complex) Mess. This is a <i>descriptive</i> 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 <tt>_-+:</tt>
--   
--   Unfortunately, <tt>VChunk</tt>s cannot be used here, as some
--   developers have numbers like <tt>1.003.04</tt> which make parsers
--   quite sad.
--   
--   Not guaranteed to have well-defined ordering (<tt>Ord</tt>) behaviour,
--   but so far interal tests show consistency.
data Mess
VLeaf :: [Text] -> Mess
VNode :: [Text] -> VSep -> Mess -> Mess

-- | A single unit of a Version. May be digits or a string of characters.
--   Groups of these are called <a>VChunk</a>s, and are the identifiers
--   separated by periods in the source.
data VUnit
Digits :: Int -> VUnit
Str :: Text -> VUnit

-- | A logical unit of a version number. Can consist of multiple letters
--   and numbers.
type VChunk = [VUnit]

-- | Developers use a number of symbols to seperate groups of
--   digits/letters in their version numbers. These are:
--   
--   <ul>
--   <li>A colon (:). Often denotes an "epoch".</li>
--   <li>A hyphen (-).</li>
--   <li>A plus (+). Stop using this outside of metadata if you are.
--   Example: <tt>10.2+0.93+1-1</tt></li>
--   <li>An underscore (_). Stop using this if you are.</li>
--   </ul>
data VSep
VColon :: VSep
VHyphen :: VSep
VPlus :: VSep
VUnder :: VSep

-- | A wrapper for a parser function. Can be composed via their Semigroup
--   instance, such that a different parser can be tried if a previous one
--   fails.
newtype VParser
VParser :: (Text -> Either ParseError Versioning) -> VParser
[runVP] :: VParser -> Text -> Either ParseError Versioning

-- | Parse a (Ideal) Semantic Version.
semver :: Text -> Either ParseError SemVer

-- | Parse a Semantic Version, as a legacy String.
semver' :: String -> Either ParseError SemVer

-- | Parse a (General) <a>Version</a>, as defined above.
version :: Text -> Either ParseError Version

-- | Parse a <a>Version</a>, where the input is a legacy String.
version' :: String -> Either ParseError Version

-- | Parse a (Complex) <a>Mess</a>, as defined above.
mess :: Text -> Either ParseError Mess

-- | Parse a <a>Mess</a>, where the input is a legacy String.
mess' :: String -> Either ParseError Mess

-- | Parse a piece of <tt>Text</tt> into either an (Ideal) SemVer, a
--   (General) Version, or a (Complex) Mess.
parseV :: Text -> Either ParseError Versioning

-- | A wrapped <a>SemVer</a> parser. Can be composed with other parsers.
semverP :: VParser

-- | A wrapped <a>Version</a> parser. Can be composed with other parsers.
versionP :: VParser

-- | A wrapped <a>Mess</a> parser. Can be composed with other parsers.
messP :: VParser

-- | Convert any parsed Versioning type to its textual representation.
prettyV :: Versioning -> Text

-- | Convert a <a>SemVer</a> back to its textual representation.
prettySemVer :: SemVer -> Text

-- | Convert a <a>Version</a> back to its textual representation.
prettyVer :: Version -> Text

-- | Convert a <a>Mess</a> back to its textual representation.
prettyMess :: Mess -> Text
instance GHC.Show.Show Data.Versions.Versioning
instance GHC.Classes.Eq Data.Versions.Versioning
instance GHC.Show.Show Data.Versions.Mess
instance GHC.Classes.Eq Data.Versions.Mess
instance GHC.Show.Show Data.Versions.VSep
instance GHC.Classes.Eq Data.Versions.VSep
instance GHC.Show.Show Data.Versions.Version
instance GHC.Classes.Ord Data.Versions.Version
instance GHC.Classes.Eq Data.Versions.Version
instance GHC.Show.Show Data.Versions.SemVer
instance GHC.Classes.Ord Data.Versions.VUnit
instance GHC.Read.Read Data.Versions.VUnit
instance GHC.Show.Show Data.Versions.VUnit
instance GHC.Classes.Eq Data.Versions.VUnit
instance GHC.Classes.Ord Data.Versions.Versioning
instance GHC.Classes.Eq Data.Versions.SemVer
instance GHC.Classes.Ord Data.Versions.SemVer
instance GHC.Classes.Ord Data.Versions.Mess
instance Data.Semigroup.Semigroup Data.Versions.VParser