-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | A package for retrieving a package's version number. -- -- package-version reads the package version number from a cabal -- file. This version number can be retrieved at compile-time via -- TemplateHaskell or runtime via ordinary functions. @package package-version @version 0.4 -- | Internal module. module Data.Version.Package.Internal -- | PackageVersion represents PVP version numbers. It is -- similar to Data.Version's Version except: -- --
    --
  1. PackageVersion has no versionTags.
    2. --
  2. We enforce PVP invariants i.e.
    3. --
  3. Trailing zeroes are ignored in Eq, Ord, -- Semigroup, and Monoid.
    4. --
-- -- That is, we declare an equivalence class up to trailing zeroes. In -- particular, the Monoid identity is -- -- 
--   [0] = { [0], [0,0], [0,0,0], ... }
--
-- -- and its Semigroup instance takes the greatest version (based on -- Ord). -- -- Note: Because we export the underlying list in various ways, (e.g. -- show), Eq's extensionality law, -- -- 
--   x == y ==> f x == f y
--
-- -- can be broken. Take care that you do not rely on this law if you are -- using its underlying NonEmpty Word (or String) -- representation. -- --

Examples

-- -- 
--   >>> MkPackageVersion [0,0,0,0] == MkPackageVersion [0,0,0]
--   True
--
-- -- 
--   >>> MkPackageVersion [4,0,0] > MkPackageVersion [1,2,0,0]
--   True
--
-- -- 
--   >>> MkPackageVersion [5,6,0] <> MkPackageVersion [9,0,0]
--   MkPackageVersion {unPackageVersion = 9 :| [0,0]}
--
-- -- 
--   >>> MkPackageVersion [0,9] <> MkPackageVersion [0,9,0,0]
--   MkPackageVersion {unPackageVersion = 0 :| [9]}
--
newtype PackageVersion MkPackageVersion :: NonEmpty Word -> PackageVersion [unPackageVersion] :: PackageVersion -> NonEmpty Word -- | Errors that can occur when validating PVP version numbers. data ValidationError -- | PVP version number cannot be empty. ValidationErrorEmpty :: ValidationError -- | PVP version numbers cannot be negative. ValidationErrorNegative :: Int -> ValidationError -- | Errors that can occur when reading PVP version numbers. data ReadStringError -- | Error when parsing a string. ReadStringErrorParse :: String -> ReadStringError -- | Validation error. ReadStringErrorValidate :: ValidationError -> ReadStringError -- | Errors that can occur when reading PVP version numbers from a file. data ReadFileError -- | General error when reading a file. ReadFileErrorGeneral :: String -> ReadFileError -- | Error for missing version. ReadFileErrorVersionNotFound :: FilePath -> ReadFileError -- | Read/Validation error. ReadFileErrorReadString :: ReadStringError -> ReadFileError -- | Constructs a PackageVersion from an Int list. The list -- must be non-empty to match PVP's minimal A. Furthermore, all digits -- must be non-negative. -- --

Examples

-- -- 
--   >>> mkPackageVersion [1,2]
--   Right (MkPackageVersion {unPackageVersion = 1 :| [2]})
--
-- -- 
--   >>> mkPackageVersion [2,87,7,1]
--   Right (MkPackageVersion {unPackageVersion = 2 :| [87,7,1]})
--
-- -- 
--   >>> mkPackageVersion [1,2,-3,-4,5]
--   Left (ValidationErrorNegative (-3))
--
-- -- 
--   >>> mkPackageVersion [3]
--   Right (MkPackageVersion {unPackageVersion = 3 :| []})
--
-- -- 
--   >>> mkPackageVersion []
--   Left ValidationErrorEmpty
--
mkPackageVersion :: [Int] -> Either ValidationError PackageVersion -- | Displays PackageVersion in Text format. -- --

Examples

-- -- 
--   >>> toText (MkPackageVersion [2,7,10,0])
--   "2.7.10.0"
--
toText :: PackageVersion -> Text instance GHC.Classes.Eq Data.Version.Package.Internal.PackageVersion instance GHC.Classes.Eq Data.Version.Package.Internal.ReadFileError instance GHC.Classes.Eq Data.Version.Package.Internal.ReadStringError instance GHC.Classes.Eq Data.Version.Package.Internal.ValidationError instance GHC.Exception.Type.Exception Data.Version.Package.Internal.ReadFileError instance GHC.Exception.Type.Exception Data.Version.Package.Internal.ReadStringError instance GHC.Exception.Type.Exception Data.Version.Package.Internal.ValidationError instance GHC.Generics.Generic Data.Version.Package.Internal.PackageVersion instance GHC.Generics.Generic Data.Version.Package.Internal.ReadFileError instance GHC.Generics.Generic Data.Version.Package.Internal.ReadStringError instance GHC.Generics.Generic Data.Version.Package.Internal.ValidationError instance Language.Haskell.TH.Syntax.Lift Data.Version.Package.Internal.PackageVersion instance GHC.Base.Monoid Data.Version.Package.Internal.PackageVersion instance Control.DeepSeq.NFData Data.Version.Package.Internal.PackageVersion instance Control.DeepSeq.NFData Data.Version.Package.Internal.ReadFileError instance Control.DeepSeq.NFData Data.Version.Package.Internal.ReadStringError instance Control.DeepSeq.NFData Data.Version.Package.Internal.ValidationError instance GHC.Classes.Ord Data.Version.Package.Internal.PackageVersion instance GHC.Base.Semigroup Data.Version.Package.Internal.PackageVersion instance GHC.Show.Show Data.Version.Package.Internal.PackageVersion instance GHC.Show.Show Data.Version.Package.Internal.ReadFileError instance GHC.Show.Show Data.Version.Package.Internal.ReadStringError instance GHC.Show.Show Data.Version.Package.Internal.ValidationError -- | This module provides functionality for reading a package's version at -- compile-time, along with a type representing PVP version numbers. If -- only the former is of interest then see packageVersionStringTH, -- as this is likely the most useful function. -- -- The doctest examples use -XOverloadedLists. module Data.Version.Package -- | PackageVersion represents PVP version numbers. It is -- similar to Data.Version's Version except: -- --
    --
  1. PackageVersion has no versionTags.
    2. --
  2. We enforce PVP invariants i.e.
    3. --
  3. Trailing zeroes are ignored in Eq, Ord, -- Semigroup, and Monoid.
    4. --
-- -- That is, we declare an equivalence class up to trailing zeroes. In -- particular, the Monoid identity is -- -- 
--   [0] = { [0], [0,0], [0,0,0], ... }
--
-- -- and its Semigroup instance takes the greatest version (based on -- Ord). -- -- Note: Because we export the underlying list in various ways, (e.g. -- show), Eq's extensionality law, -- -- 
--   x == y ==> f x == f y
--
-- -- can be broken. Take care that you do not rely on this law if you are -- using its underlying NonEmpty Word (or String) -- representation. -- --

Examples

-- -- 
--   >>> MkPackageVersion [0,0,0,0] == MkPackageVersion [0,0,0]
--   True
--
-- -- 
--   >>> MkPackageVersion [4,0,0] > MkPackageVersion [1,2,0,0]
--   True
--
-- -- 
--   >>> MkPackageVersion [5,6,0] <> MkPackageVersion [9,0,0]
--   MkPackageVersion {unPackageVersion = 9 :| [0,0]}
--
-- -- 
--   >>> MkPackageVersion [0,9] <> MkPackageVersion [0,9,0,0]
--   MkPackageVersion {unPackageVersion = 0 :| [9]}
--
newtype PackageVersion MkPackageVersion :: NonEmpty Word -> PackageVersion [unPackageVersion] :: PackageVersion -> NonEmpty Word -- | Constructs a PackageVersion from an Int list. The list -- must be non-empty to match PVP's minimal A. Furthermore, all digits -- must be non-negative. -- --

Examples

-- -- 
--   >>> mkPackageVersion [1,2]
--   Right (MkPackageVersion {unPackageVersion = 1 :| [2]})
--
-- -- 
--   >>> mkPackageVersion [2,87,7,1]
--   Right (MkPackageVersion {unPackageVersion = 2 :| [87,7,1]})
--
-- -- 
--   >>> mkPackageVersion [1,2,-3,-4,5]
--   Left (ValidationErrorNegative (-3))
--
-- -- 
--   >>> mkPackageVersion [3]
--   Right (MkPackageVersion {unPackageVersion = 3 :| []})
--
-- -- 
--   >>> mkPackageVersion []
--   Left ValidationErrorEmpty
--
mkPackageVersion :: [Int] -> Either ValidationError PackageVersion -- | Safely constructs a PackageVersion at compile-time. If you know -- that your input satisfies both invariants (non-empty and non-negative) -- at compile-time, consider using the MkPackageVersion -- constructor directly. -- --

Examples

-- -- 
--   >>> $$(mkPackageVersionTH [2,4,0])
--   MkPackageVersion {unPackageVersion = 2 :| [4,0]}
--
mkPackageVersionTH :: [Int] -> Code Q PackageVersion -- | Unsafe version of mkPackageVersion, intended to be used with -- known constants. Maybe you should use mkPackageVersionTH or -- MkPackageVersion? -- -- WARNING: This function is not total. Exercise restraint! -- --

Examples

-- -- 
--   >>> unsafePackageVersion [1,2,3]
--   MkPackageVersion {unPackageVersion = 1 :| [2,3]}
--
unsafePackageVersion :: HasCallStack => [Int] -> PackageVersion -- | Creates a PackageVersion from Version. -- -- Note: Because PackageVersion does not have a -- versionTags, fromVersion is not injective even on -- "well-formed" Versions (i.e. non-negative and length > 1). -- That is, toVersion . fromVersion is not -- an isomorphism. -- --

Examples

-- -- 
--   >>> fromVersion (Version [2,13,0] ["alpha"])
--   Right (MkPackageVersion {unPackageVersion = 2 :| [13,0]})
--
-- -- 
--   >>> fromVersion (Version [] [])
--   Left ValidationErrorEmpty
--
fromVersion :: Version -> Either ValidationError PackageVersion -- | Attempts to read a String into a PackageVersion. Leading -- and/or trailing dots will result in an error, as will the empty -- string. -- --

Examples

-- -- 
--   >>> fromString "1.4.27.3"
--   Right (MkPackageVersion {unPackageVersion = 1 :| [4,27,3]})
--
-- -- 
--   >>> fromString ""
--   Left (ReadStringErrorParse "Prelude.read: no parse")
--
-- -- 
--   >>> fromString "1.a.2"
--   Left (ReadStringErrorParse "Prelude.read: no parse")
--
-- -- 
--   >>> fromString ".1.2"
--   Left (ReadStringErrorParse "Prelude.read: no parse")
--
-- -- 
--   >>> fromString "1.2."
--   Left (ReadStringErrorParse "Prelude.read: no parse")
--
-- -- 
--   >>> fromString "-3.1.2"
--   Left (ReadStringErrorValidate (ValidationErrorNegative (-3)))
--
fromString :: String -> Either ReadStringError PackageVersion -- | Attempts to read a Text into a PackageVersion. Leading -- and/or trailing dots will result in an error, as will the empty -- string. -- --

Examples

-- -- 
--   >>> fromText "1.4.27.3"
--   Right (MkPackageVersion {unPackageVersion = 1 :| [4,27,3]})
--
-- -- 
--   >>> fromText ""
--   Left (ReadStringErrorParse "Prelude.read: no parse")
--
-- -- 
--   >>> fromText "1.a.2"
--   Left (ReadStringErrorParse "Prelude.read: no parse")
--
-- -- 
--   >>> fromText ".1.2"
--   Left (ReadStringErrorParse "Prelude.read: no parse")
--
-- -- 
--   >>> fromText "1.2."
--   Left (ReadStringErrorParse "Prelude.read: no parse")
--
-- -- 
--   >>> fromText ""
--   Left (ReadStringErrorParse "Prelude.read: no parse")
--
-- -- 
--   >>> fromText "-3.1.2"
--   Left (ReadStringErrorValidate (ValidationErrorNegative (-3)))
--
fromText :: Text -> Either ReadStringError PackageVersion -- | Creates a Version with empty versionTags from -- PackageVersion. -- --

Examples

-- -- 
--   >>> toVersion (MkPackageVersion [3,2,0])
--   Version {versionBranch = [3,2,0], versionTags = []}
--
toVersion :: PackageVersion -> Version -- | Displays PackageVersion in String format. -- --

Examples

-- -- 
--   >>> toString (MkPackageVersion [2,7,10,0])
--   "2.7.10.0"
--
toString :: PackageVersion -> String -- | Displays PackageVersion in Text format. -- --

Examples

-- -- 
--   >>> toText (MkPackageVersion [2,7,10,0])
--   "2.7.10.0"
--
toText :: PackageVersion -> Text -- | TemplateHaskell for reading the cabal file's version at compile-time. -- Errors encountered will be returned as compilation errors. -- --

Examples

-- -- 
--   >>> $$(packageVersionTH "package-version.cabal")
--   MkPackageVersion {unPackageVersion = 0 :| [4]}
--
packageVersionTH :: FilePath -> Code Q PackageVersion -- | Version of packageVersionTH that returns a String -- representation of PackageVersion at compile-time. Returns -- "UNKNOWN" if any errors are encountered. -- --

Examples

-- -- 
--   >>> $$(packageVersionStringTH "package-version.cabal")
--   "0.4"
--
-- -- 
--   >>> $$(packageVersionStringTH "not-found.cabal")
--   "UNKNOWN"
--
packageVersionStringTH :: FilePath -> Code Q String -- | Version of packageVersionTH that returns a Text -- representation of PackageVersion at compile-time. Returns -- "UNKNOWN" if any errors are encountered. -- --

Examples

-- -- 
--   >>> $$(packageVersionTextTH "package-version.cabal")
--   "0.4"
--
-- -- 
--   >>> $$(packageVersionTextTH "not-found.cabal")
--   "UNKNOWN"
--
packageVersionTextTH :: FilePath -> Code Q Text -- | Version of packageVersionEitherIO that throws an -- Exception if any errors are encountered. -- --

Examples

-- -- 
--   >>> packageVersionThrowIO "package-version.cabal"
--   MkPackageVersion {unPackageVersion = 0 :| [4]}
--
packageVersionThrowIO :: FilePath -> IO PackageVersion -- | Version of packageVersionEitherIO that returns a String -- representation of PackageVersion at runtime. Returns -- "UNKNOWN" if any errors are encountered. -- --

Examples

-- -- 
--   >>> packageVersionStringIO "package-version.cabal"
--   "0.4"
--
-- -- 
--   >>> packageVersionStringIO "not-found.cabal"
--   "UNKNOWN"
--
packageVersionStringIO :: FilePath -> IO String -- | Version of packageVersionEitherIO that returns a Text -- representation of PackageVersion at runtime. Returns -- "UNKNOWN" if any errors are encountered. -- --

Examples

-- -- 
--   >>> packageVersionTextIO "package-version.cabal"
--   "0.4"
--
-- -- 
--   >>> packageVersionTextIO "not-found.cabal"
--   "UNKNOWN"
--
packageVersionTextIO :: FilePath -> IO Text -- | Reads the cabal-file's version. -- --

Examples

-- -- 
--   >>> packageVersionEitherIO "package-version.cabal"
--   Right (MkPackageVersion {unPackageVersion = 0 :| [4]})
--
packageVersionEitherIO :: FilePath -> IO (Either ReadFileError PackageVersion) -- | Errors that can occur when validating PVP version numbers. data ValidationError -- | PVP version number cannot be empty. ValidationErrorEmpty :: ValidationError -- | PVP version numbers cannot be negative. ValidationErrorNegative :: Int -> ValidationError -- | Errors that can occur when reading PVP version numbers. data ReadStringError -- | Error when parsing a string. ReadStringErrorParse :: String -> ReadStringError -- | Validation error. ReadStringErrorValidate :: ValidationError -> ReadStringError -- | Errors that can occur when reading PVP version numbers from a file. data ReadFileError -- | General error when reading a file. ReadFileErrorGeneral :: String -> ReadFileError -- | Error for missing version. ReadFileErrorVersionNotFound :: FilePath -> ReadFileError -- | Read/Validation error. ReadFileErrorReadString :: ReadStringError -> ReadFileError