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


-- | Basic versioning library.
--   
@package old-version
@version 1.0.1


-- | A general library for representation and manipulation of versions.
--   
--   Versioning schemes are many and varied, so the version representation
--   provided by this library is intended to be a compromise between
--   complete generality, where almost no common functionality could
--   reasonably be provided, and fixing a particular versioning scheme,
--   which would probably be too restrictive.
--   
--   So the approach taken here is to provide a representation which
--   subsumes many of the versioning schemes commonly in use, and we
--   provide implementations of <a>Eq</a>, <a>Ord</a>, <a>Read</a>, and
--   <a>Show</a>, which will be appropriate for some applications, but not
--   all.
--   
--   This version of the module is forked from base, preserving the
--   <a>versionTags</a> field of the <a>Version</a> type that will be
--   removed in GHC 7.12 (cf.
--   <a>https://ghc.haskell.org/trac/ghc/ticket/2496</a>).
module Data.Old.Version

-- | A <a>Version</a> represents the version of a software entity.
--   
--   An instance of <a>Eq</a> is provided, which implements exact equality
--   by first comparing the <a>versionBranch</a> fields, followed by
--   comparing the <a>versionTags</a> fields.
--   
--   An instance of <a>Ord</a> is also provided, which gives lexicographic
--   ordering on the <a>versionBranch</a> fields (i.e. 2.1 &gt; 2.0, 1.2.3
--   &gt; 1.2.2, etc.). This is expected to be sufficient for many uses,
--   but note that you may need to use a more specific ordering for your
--   versioning scheme. For example, some versioning schemes may include
--   pre-releases which have tags <tt>"pre1"</tt>, <tt>"pre2"</tt>, and so
--   on, and these would need to be taken into account when determining
--   ordering. In some cases, date ordering may be more appropriate, so the
--   application would have to look for <tt>date</tt> tags in the
--   <a>versionTags</a> field and compare those. The bottom line is, don't
--   always assume that <a>compare</a> and other <a>Ord</a> operations are
--   the right thing for every <a>Version</a>.
--   
--   Similarly, concrete representations of versions may differ. One
--   possible concrete representation is provided by the <a>Show</a> and
--   <a>Read</a> instances, but depending on the application a different
--   concrete representation may be more appropriate.
data Version
Version :: [Int] -> [String] -> Version

-- | The numeric branch for this version. This reflects the fact that most
--   software versions are tree-structured; there is a main trunk which is
--   tagged with versions at various points (1,2,3...), and the first
--   branch off the trunk after version 3 is 3.1, the second branch off the
--   trunk after version 3 is 3.2, and so on. The tree can be branched
--   arbitrarily, just by adding more digits.
--   
--   We represent the branch as a list of <a>Int</a>, so version 3.2.1
--   becomes [3,2,1]. Lexicographic ordering (i.e. the default instance of
--   <a>Ord</a> for <tt>[Int]</tt>) gives the natural ordering of branches.
versionBranch :: Version -> [Int]

-- | A version can be tagged with an arbitrary list of strings. The
--   interpretation of the list of tags is entirely dependent on the entity
--   that this version applies to.
versionTags :: Version -> [String]
instance [safe] Typeable Version
instance [safe] Eq Version
instance [safe] Read Version
instance [safe] Show Version
instance [safe] Ord Version