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


-- | Representation, manipulation, and de/serialisation of Semantic Versions.
--   
--   Representation, manipulation, and de/serialisation of a Version type
--   following the Semantic Versioning specification.
--   
--   For more information see: <a>http://semver.org</a>
@package semver
@version 0.4.0.1


-- | A set of delimiters can be used to encode/decode a <a>Version</a> and
--   specify alternative serialisation strategies.
--   
--   Lenses can be used to modify the default delimiter set, as in the
--   following example - using alpha characters to encode the version as a
--   valid DNS CNAME (assuming operators from lens or lens-family-core):
--   
--   <pre>
--   let Right v = fromText "1.2.3+40"
--   let alpha = semantic &amp; major .~ 'm' &amp; patch .~ 'p' &amp; release .~ 'r' &amp; metadata .~ 'd' &amp; identifier .~ 'i'
--   
--   Data.Text.Lazy.Builder.toLazyText ("app01-" &lt;&gt; toBuilder alpha v &lt;&gt; ".dmz.internal")
--   </pre>
--   
--   Would result in the following <a>Text</a>:
--   
--   <pre>
--   app01-1m2p3d40.dmz.internal
--   </pre>
--   
--   Using the same <a>Delimiters</a> set with <a>parser</a> would ensure
--   correct decoding behaviour.
module Data.SemVer.Delimited

-- | An opaque set representing the seperators used to delimit semantic
--   version components.
data Delimiters

-- | The default set of delimiters used in the semantic version
--   specification.
--   
--   Example: Given exhaustive version components would result in the
--   following hypothetical version:
--   
--   <pre>
--   1.2.3-alpha.1+sha.exp.12ab3d9
--   </pre>
semantic :: Delimiters

-- | Lens for the minor version delimiter. Default: <tt>.</tt>
minor :: Functor f => (Char -> f Char) -> Delimiters -> f Delimiters

-- | Lens for the patch version delimiter. Default: <tt>.</tt>
patch :: Functor f => (Char -> f Char) -> Delimiters -> f Delimiters

-- | Lens for the release component delimiter. Default: <tt>-</tt>
release :: Functor f => (Char -> f Char) -> Delimiters -> f Delimiters

-- | Lens for the metadata component delimiter. Default: <tt>+</tt>
metadata :: Functor f => (Char -> f Char) -> Delimiters -> f Delimiters

-- | Lens for the individual identifier delimiter. Default: <tt>.</tt>
identifier :: Functor f => (Char -> f Char) -> Delimiters -> f Delimiters

-- | Convert a <a>Version</a> to a <a>Builder</a> using the specified
--   <a>Delimiters</a> set.
toBuilder :: Delimiters -> Version -> Builder

-- | A greedy attoparsec <a>Parser</a> using the specified
--   <a>Delimiters</a> set which requires the entire <tt>Text</tt> input to
--   match.
parser :: Delimiters -> Bool -> Parser Version


-- | An implementation of the Semantic Versioning Constraints. In absence
--   of a standard around constraints, the behavior of node-semver is
--   closely followed. The behavior is outlined here:
--   <a>https://github.com/npm/node-semver#ranges</a>
module Data.SemVer.Constraint
data Constraint
CAny :: Constraint
CLt :: !Version -> Constraint
CLtEq :: !Version -> Constraint
CGt :: !Version -> Constraint
CGtEq :: !Version -> Constraint
CEq :: !Version -> Constraint
CAnd :: !Constraint -> !Constraint -> Constraint
COr :: !Constraint -> !Constraint -> Constraint

-- | Checks whether the <a>Version</a> satisfies the <a>Constraint</a>
--   
--   Note: Semantics of this are strange in the presence of pre-release
--   identifiers. Without a proper standard for how constraint satisfaction
--   should behave, this implementation attempts to follow the behavior of
--   node-semver which can be found here:
--   <a>https://github.com/npm/node-semver#prerelease-tags</a>.
--   
--   This choice was made because node-semver is the most widely deployed
--   implementation of semantic versioning with the best documentation
--   around how to treat pre-release identifiers.
--   
--   The summary is that you must opt into using pre-release identifiers by
--   specifying them in the constraint and they <b>must</b> match the
--   <b>exact</b> version that attempts to use a pre-release identifier.
satisfies :: Version -> Constraint -> Bool

-- | Parsing function to create a <a>Constraint</a> from <a>Text</a>
--   according to the rules specified here:
--   <a>https://github.com/npm/node-semver#ranges</a>
--   
--   Advanced syntax is not yet supported.
fromText :: Text -> Either String Constraint
instance GHC.Classes.Eq Data.SemVer.Constraint.Constraint
instance GHC.Internal.Show.Show Data.SemVer.Constraint.Constraint


-- | An implementation of the Semantic Versioning specification located at
--   <a>http://semver.org</a>.
--   
--   A canonical <a>Version</a> type and functions representing behaviour
--   as outlined in the specification are defined alongside additional
--   lenses, traversals, common manipulations, and serialisation
--   primitives.
module Data.SemVer

-- | An opaque type representing a successfully decoded or constructed
--   semantic version. See the related functions and lenses for
--   modification and update.
--   
--   <ul>
--   <li>The <a>Eq</a> instance represents exhaustive equality with all
--   components considered.</li>
--   <li>The <a>Ord</a> instance implements the precedence rules from the
--   semantic version specification with metadata being ignored.</li>
--   </ul>
data Version

-- | Smart constructor fully specifying all available version components.
version :: Int -> Int -> Int -> [Identifier] -> [Identifier] -> Version

-- | A default <a>Version</a> which can be used to signify initial
--   development.
--   
--   Note: Equivalent to <tt>0.0.0</tt>
initial :: Version

-- | Lens for the major version component.
major :: Functor f => (Int -> f Int) -> Version -> f Version

-- | Lens for minor version component.
minor :: Functor f => (Int -> f Int) -> Version -> f Version

-- | Lens for the patch version component.
patch :: Functor f => (Int -> f Int) -> Version -> f Version

-- | Lens for the list of release identifiers.
release :: Functor f => ([Identifier] -> f [Identifier]) -> Version -> f Version

-- | Lens for the list of metadata identifiers.
metadata :: Functor f => ([Identifier] -> f [Identifier]) -> Version -> f Version

-- | Increment the major component of a <a>Version</a> by 1, resetting the
--   minor and patch components.
--   
--   <ul>
--   <li>Major version X (X.y.z | X &gt; 0) MUST be incremented if any
--   backwards incompatible changes are introduced to the public API.</li>
--   <li>It MAY include minor and patch level changes.</li>
--   <li>Patch and minor version MUST be reset to 0 when major version is
--   incremented.</li>
--   </ul>
incrementMajor :: Version -> Version

-- | Increment the minor component of a <a>Version</a> by 1, resetting the
--   patch component.
--   
--   <ul>
--   <li>Minor version Y (x.Y.z | x &gt; 0) MUST be incremented if new,
--   backwards compatible functionality is introduced to the public
--   API.</li>
--   <li>It MUST be incremented if any public API functionality is marked
--   as deprecated.</li>
--   <li>It MAY be incremented if substantial new functionality or
--   improvements are introduced within the private code.</li>
--   <li>It MAY include patch level changes.</li>
--   <li>Patch version MUST be reset to 0 when minor version is
--   incremented.</li>
--   </ul>
incrementMinor :: Version -> Version

-- | Increment the patch component of a <a>Version</a> by 1.
--   
--   <ul>
--   <li>Patch version Z (x.y.Z | x &gt; 0) MUST be incremented if only
--   backwards compatible bug fixes are introduced.</li>
--   <li>A bug fix is defined as an internal change that fixes incorrect
--   behavior.</li>
--   </ul>
incrementPatch :: Version -> Version

-- | Check if the <a>Version</a> is considered unstable.
--   
--   <ul>
--   <li>Major version zero (0.y.z) is for initial development.</li>
--   <li>Anything may change at any time.</li>
--   <li>The public API should not be considered stable.</li>
--   </ul>
isDevelopment :: Version -> Bool

-- | Check if the <a>Version</a> is considered stable.
--   
--   Version 1.0.0 defines the public API. The way in which the version
--   number is incremented after this release is dependent on this public
--   API and how it changes.
isPublic :: Version -> Bool

-- | Convert a <a>Version</a> to it's readable <a>String</a>
--   representation.
--   
--   Note: This is optimised for cases where you require <a>String</a>
--   output, and as such is faster than the semantically equivalent
--   <tt>unpack . toLazyText</tt>.
toString :: Version -> String

-- | Convert a <a>Version</a> to a strict <a>Text</a> representation.
--   
--   Note: Equivalent to <tt>toStrict . toLazyText</tt>
toText :: Version -> Text

-- | Convert a <a>Version</a> to a <a>Text</a> representation.
--   
--   Note: This uses a lower <a>Builder</a> buffer size optimised for
--   commonly found version formats. If you have particuarly long version
--   numbers using <a>toBuilder</a> and <a>toLazyTextWith</a> to control
--   the buffer size is recommended.
toLazyText :: Version -> Text

-- | Convert a <a>Version</a> to a <a>Builder</a>.
toBuilder :: Version -> Builder

-- | Parse a <a>Version</a> from <a>Text</a>, returning an attoparsec error
--   message in the <a>Left</a> case on failure.
fromText :: Text -> Either String Version

-- | Parse a <a>Version</a> from <a>Text</a>, returning an attoparsec error
--   message in the <a>Left</a> case on failure.
--   
--   Note: The underlying attoparsec <a>Parser</a> is based on <a>Text</a>
--   and this is equivalent to <tt>fromText . toStrict</tt>
fromLazyText :: Text -> Either String Version

-- | A greedy attoparsec <a>Parser</a> which requires the entire
--   <a>Text</a> input to match.
parser :: Parser Version

-- | A type representing an individual identifier from the release or
--   metadata components of a <a>Version</a>.
--   
--   <ul>
--   <li>The <a>Ord</a> instance implements precedence according to the
--   semantic version specification, with numeric identifiers being of
--   <i>lower</i> precedence than textual identifiers, otherwise
--   lexicographic ordering is used.</li>
--   </ul>
--   
--   The functions <tt>numeric</tt> and <tt>textual</tt> can be used to
--   construct an <a>Identifier</a>.
data Identifier

-- | Safely construct a numeric identifier.
numeric :: Int -> Identifier

-- | Construct an identifier from the given <a>Text</a>, returning
--   <a>Nothing</a> if neither a numeric or valid textual input is
--   supplied.
textual :: Text -> Maybe Identifier

-- | A prism into the numeric branch of an <a>Identifier</a>.
_Numeric :: Applicative f => (Int -> f Int) -> Identifier -> f Identifier

-- | A prism into the textual branch of an <a>Identifier</a>.
_Textual :: Applicative f => (Text -> f Text) -> Identifier -> f (Maybe Identifier)
