-- 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.3 -- | Internal module. Exposes the invariant-breaking -- UnsafePackageVersion constructor. module Data.Version.Package.Internal -- | PackageVersion represents PVP version numbers. It is -- similar to Data.Version's Version (i.e. wraps a -- [Int]) except: -- --
    --
  1. PackageVersion has no versionTags.
    2. --
  2. We enforce PVP's "tags must be at least A" invariant via the -- smart-constructor pattern.
    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 [Int] (or String) -- representation. -- --

Examples

-- -- 
--   >>> UnsafePackageVersion [0,0,0,0] == UnsafePackageVersion [0,0,0]
--   True
--
-- -- 
--   >>> UnsafePackageVersion [4,0,0] > UnsafePackageVersion [1,2,0,0]
--   True
--
-- -- 
--   >>> UnsafePackageVersion [5,6,0] <> UnsafePackageVersion [9,0,0]
--   UnsafePackageVersion [9,0,0]
--
-- -- 
--   >>> UnsafePackageVersion [0,9] <> UnsafePackageVersion [0,9,0,0]
--   UnsafePackageVersion [0,9]
--
-- -- 
--   >>> TR.readEither @PackageVersion "UnsafePackageVersion [3,2,1]"
--   Right (UnsafePackageVersion [3,2,1])
--
-- -- 
--   >>> TR.readEither @PackageVersion "UnsafePackageVersion [-2]"
--   Left "Prelude.read: no parse"
--
-- -- 
--   >>> TR.readEither @PackageVersion "UnsafePackageVersion []"
--   Left "Prelude.read: no parse"
--
newtype PackageVersion UnsafePackageVersion :: [Int] -> PackageVersion pattern MkPackageVersion :: [Int] -> 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 -- | Smart constructor for PackageVersion. The length of the list -- must be > 1 to match PVP's minimal A.B. Furthermore, all digits -- must be non-negative. -- --

Examples

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

Examples

-- -- 
--   >>> toText (UnsafePackageVersion [2,7,10,0])
--   "2.7.10.0"
--
toText :: PackageVersion -> Text -- | Renders a string via Pretty's smart option + default layout. prettyString :: Pretty a => a -> String instance Control.DeepSeq.NFData Data.Version.Package.Internal.PackageVersion instance GHC.Show.Show Data.Version.Package.Internal.PackageVersion instance Language.Haskell.TH.Syntax.Lift Data.Version.Package.Internal.PackageVersion instance GHC.Generics.Generic Data.Version.Package.Internal.PackageVersion instance Control.DeepSeq.NFData Data.Version.Package.Internal.ValidationError instance GHC.Show.Show Data.Version.Package.Internal.ValidationError instance GHC.Generics.Generic Data.Version.Package.Internal.ValidationError instance GHC.Classes.Eq Data.Version.Package.Internal.ValidationError instance Control.DeepSeq.NFData Data.Version.Package.Internal.ReadStringError instance GHC.Show.Show Data.Version.Package.Internal.ReadStringError instance GHC.Generics.Generic Data.Version.Package.Internal.ReadStringError instance GHC.Classes.Eq Data.Version.Package.Internal.ReadStringError instance Control.DeepSeq.NFData Data.Version.Package.Internal.ReadFileError instance GHC.Show.Show Data.Version.Package.Internal.ReadFileError instance GHC.Generics.Generic Data.Version.Package.Internal.ReadFileError instance GHC.Classes.Eq Data.Version.Package.Internal.ReadFileError instance Prettyprinter.Internal.Pretty Data.Version.Package.Internal.ReadFileError instance GHC.Exception.Type.Exception Data.Version.Package.Internal.ReadFileError instance Prettyprinter.Internal.Pretty Data.Version.Package.Internal.ReadStringError instance GHC.Exception.Type.Exception Data.Version.Package.Internal.ReadStringError instance Prettyprinter.Internal.Pretty Data.Version.Package.Internal.ValidationError instance GHC.Exception.Type.Exception Data.Version.Package.Internal.ValidationError instance GHC.Classes.Eq Data.Version.Package.Internal.PackageVersion instance GHC.Classes.Ord Data.Version.Package.Internal.PackageVersion instance GHC.Base.Semigroup Data.Version.Package.Internal.PackageVersion instance GHC.Base.Monoid Data.Version.Package.Internal.PackageVersion instance GHC.Read.Read Data.Version.Package.Internal.PackageVersion instance Prettyprinter.Internal.Pretty Data.Version.Package.Internal.PackageVersion -- | 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. module Data.Version.Package -- | PackageVersion represents PVP version numbers. It is -- similar to Data.Version's Version (i.e. wraps a -- [Int]) except: -- --
    --
  1. PackageVersion has no versionTags.
    2. --
  2. We enforce PVP's "tags must be at least A" invariant via the -- smart-constructor pattern.
    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 [Int] (or String) -- representation. -- --

Examples

-- -- 
--   >>> UnsafePackageVersion [0,0,0,0] == UnsafePackageVersion [0,0,0]
--   True
--
-- -- 
--   >>> UnsafePackageVersion [4,0,0] > UnsafePackageVersion [1,2,0,0]
--   True
--
-- -- 
--   >>> UnsafePackageVersion [5,6,0] <> UnsafePackageVersion [9,0,0]
--   UnsafePackageVersion [9,0,0]
--
-- -- 
--   >>> UnsafePackageVersion [0,9] <> UnsafePackageVersion [0,9,0,0]
--   UnsafePackageVersion [0,9]
--
-- -- 
--   >>> TR.readEither @PackageVersion "UnsafePackageVersion [3,2,1]"
--   Right (UnsafePackageVersion [3,2,1])
--
-- -- 
--   >>> TR.readEither @PackageVersion "UnsafePackageVersion [-2]"
--   Left "Prelude.read: no parse"
--
-- -- 
--   >>> TR.readEither @PackageVersion "UnsafePackageVersion []"
--   Left "Prelude.read: no parse"
--
data PackageVersion pattern MkPackageVersion :: [Int] -> PackageVersion -- | Smart constructor for PackageVersion. The length of the list -- must be > 1 to match PVP's minimal A.B. Furthermore, all digits -- must be non-negative. -- --

Examples

-- -- 
--   >>> mkPackageVersion [1,2]
--   Right (UnsafePackageVersion [1,2])
--
-- -- 
--   >>> mkPackageVersion [2,87,7,1]
--   Right (UnsafePackageVersion [2,87,7,1])
--
-- -- 
--   >>> mkPackageVersion [1,2,-3,-4,5]
--   Left (ValidationErrorNegative (-3))
--
-- -- 
--   >>> mkPackageVersion [3]
--   Right (UnsafePackageVersion [3])
--
-- -- 
--   >>> mkPackageVersion []
--   Left ValidationErrorEmpty
--
mkPackageVersion :: [Int] -> Either ValidationError PackageVersion -- | Safely constructs a PackageVersion at compile-time. -- --

Examples

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

Examples

-- -- 
--   >>> unsafePackageVersion [1,2,3]
--   UnsafePackageVersion [1,2,3]
--
unsafePackageVersion :: [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 (UnsafePackageVersion [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 (UnsafePackageVersion [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 (UnsafePackageVersion [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 unPackageVersion :: PackageVersion -> [Int] -- | Creates a Version with empty versionTags from -- PackageVersion. -- --

Examples

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

Examples

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

Examples

-- -- 
--   >>> toText (UnsafePackageVersion [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")
--   UnsafePackageVersion [0,3]
--
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.3"
--
-- -- 
--   >>> $$(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.3"
--
-- -- 
--   >>> $$(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"
--   UnsafePackageVersion [0,3]
--
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.3"
--
-- -- 
--   >>> 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.3"
--
-- -- 
--   >>> packageVersionTextIO "not-found.cabal"
--   "UNKNOWN"
--
packageVersionTextIO :: FilePath -> IO Text -- | Reads the cabal-file's version. -- --

Examples

-- -- 
--   >>> packageVersionEitherIO "package-version.cabal"
--   Right (UnsafePackageVersion [0,3])
--
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