{-# LANGUAGE CPP #-}
{-# LANGUAGE UndecidableInstances #-}

-- |
-- Module: Data.Version.Package
-- Copyright: 2021 Thomas Bidne
-- License: BSD-3-Clause
-- Stability: experimental
--
-- 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.
--
-- @since 0.1.0.0
module Data.Version.Package
  ( -- * Type
    PackageVersion (MkPackageVersion),

    -- ** Creation
    Internal.mkPackageVersion,
    mkPackageVersionTH,
    unsafePackageVersion,
    fromVersion,
    fromString,
    fromText,

    -- ** Elimination
    unPackageVersion,
    toVersion,
    toString,
    Internal.toText,

    -- * Reading Cabal Files

    -- ** TemplateHaskell
    -- $retrieve-version-th
    packageVersionTH,
    packageVersionStringTH,
    packageVersionTextTH,

    -- ** IO
    packageVersionThrowIO,
    packageVersionStringIO,
    packageVersionTextIO,
    packageVersionEitherIO,

    -- * Errors
    ValidationError (..),
    ReadStringError (..),
    ReadFileError (..),
  )
where

import Control.Exception.Safe (Exception (..))
import Control.Exception.Safe qualified as SafeEx
import Control.Monad ((>=>))
import Data.Bifunctor (Bifunctor (..))
import Data.ByteString qualified as BS
import Data.List qualified as L
import Data.Text (Text)
import Data.Text qualified as T
import Data.Text.Encoding (decodeUtf8With)
import Data.Text.Encoding.Error (lenientDecode)
import Data.Version (Version (..))
#if MIN_VERSION_template_haskell(2, 17, 0)
import Language.Haskell.TH (Code, Q)
#else
import Language.Haskell.TH (Q, TExp)
#endif
import Data.Version.Package.Internal
  ( PackageVersion (..),
    ReadFileError (..),
    ReadStringError (..),
    ValidationError (..),
    unPackageVersion,
  )
import Data.Version.Package.Internal qualified as Internal
import Language.Haskell.TH qualified as TH
import Language.Haskell.TH.Syntax (Lift (..))
import Text.Read qualified as TR

-- $setup
-- >>> :set -XTemplateHaskell

-- | Safely constructs a 'PackageVersion' at compile-time.
--
-- ==== __Examples__
-- >>> $$(mkPackageVersionTH [2,4,0])
-- UnsafePackageVersion [2,4,0]
--
-- @since 0.1.0.0
#if MIN_VERSION_template_haskell(2,17,0)
mkPackageVersionTH :: [Int] -> Code Q PackageVersion
#else
mkPackageVersionTH :: [Int] -> Q (TExp PackageVersion)
#endif
mkPackageVersionTH :: [Int] -> Code Q PackageVersion
mkPackageVersionTH [Int]
v = case [Int] -> Either ValidationError PackageVersion
Internal.mkPackageVersion [Int]
v of
  Right PackageVersion
pv -> forall t (m :: * -> *). (Lift t, Quote m) => t -> Code m t
liftTyped PackageVersion
pv
  Left ValidationError
err -> forall a. HasCallStack => [Char] -> a
error forall a b. (a -> b) -> a -> b
$ forall a. Pretty a => a -> [Char]
Internal.prettyString ValidationError
err

-- | Unsafe version of 'Internal.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]
--
-- @since 0.1.0.0
unsafePackageVersion :: [Int] -> PackageVersion
unsafePackageVersion :: [Int] -> PackageVersion
unsafePackageVersion = forall a c b. (a -> c) -> (b -> c) -> Either a b -> c
either (forall a. HasCallStack => [Char] -> a
error forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall a. Pretty a => a -> [Char]
Internal.prettyString) forall a. a -> a
id forall b c a. (b -> c) -> (a -> b) -> a -> c
. [Int] -> Either ValidationError PackageVersion
Internal.mkPackageVersion

-- | Creates a 'PackageVersion' from 'Version'.
--
-- Note: Because 'PackageVersion' does not have a 'versionTags', 'fromVersion'
-- is not injective even on "well-formed" 'Version's (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
--
-- @since 0.1.0.0
fromVersion :: Version -> Either ValidationError PackageVersion
fromVersion :: Version -> Either ValidationError PackageVersion
fromVersion = [Int] -> Either ValidationError PackageVersion
Internal.mkPackageVersion forall b c a. (b -> c) -> (a -> b) -> a -> c
. Version -> [Int]
versionBranch

-- | 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)))
--
-- @since 0.1.0.0
fromString :: String -> Either ReadStringError PackageVersion
fromString :: [Char] -> Either ReadStringError PackageVersion
fromString = Text -> Either ReadStringError PackageVersion
fromText forall b c a. (b -> c) -> (a -> b) -> a -> c
. [Char] -> Text
T.pack

-- | 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)))
--
-- @since 0.1.0.0
fromText :: Text -> Either ReadStringError PackageVersion
fromText :: Text -> Either ReadStringError PackageVersion
fromText = [Text] -> Either ReadStringError [Int]
readInts forall b c a. (b -> c) -> (a -> b) -> a -> c
. Text -> [Text]
splitDots forall (m :: * -> *) a b c.
Monad m =>
(a -> m b) -> (b -> m c) -> a -> m c
>=> forall (p :: * -> * -> *) a b c.
Bifunctor p =>
(a -> b) -> p a c -> p b c
first ValidationError -> ReadStringError
ReadStringErrorValidate forall b c a. (b -> c) -> (a -> b) -> a -> c
. [Int] -> Either ValidationError PackageVersion
Internal.mkPackageVersion
  where
    splitDots :: Text -> [Text]
splitDots = (Char -> Bool) -> Text -> [Text]
T.split (forall a. Eq a => a -> a -> Bool
== Char
'.')
    readInts :: [Text] -> Either ReadStringError [Int]
readInts = forall (p :: * -> * -> *) a b c.
Bifunctor p =>
(a -> b) -> p a c -> p b c
first [Char] -> ReadStringError
ReadStringErrorParse forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall (t :: * -> *) (f :: * -> *) a b.
(Traversable t, Applicative f) =>
(a -> f b) -> t a -> f (t b)
traverse (forall a. Read a => [Char] -> Either [Char] a
TR.readEither forall b c a. (b -> c) -> (a -> b) -> a -> c
. Text -> [Char]
T.unpack)

-- | Creates a 'Version' with empty 'versionTags' from 'PackageVersion'.
--
-- ==== __Examples__
-- >>> toVersion (UnsafePackageVersion [3,2,0])
-- Version {versionBranch = [3,2,0], versionTags = []}
--
-- @since 0.1.0.0
toVersion :: PackageVersion -> Version
toVersion :: PackageVersion -> Version
toVersion (UnsafePackageVersion [Int]
v) = [Int] -> [[Char]] -> Version
Version [Int]
v []

-- | Displays 'PackageVersion' in 'String' format.
--
-- ==== __Examples__
-- >>> toString (UnsafePackageVersion [2,7,10,0])
-- "2.7.10.0"
--
-- @since 0.1.0.0
toString :: PackageVersion -> String
toString :: PackageVersion -> [Char]
toString = forall a. [a] -> [[a]] -> [a]
L.intercalate [Char]
"." forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap forall a. Show a => a -> [Char]
show forall b c a. (b -> c) -> (a -> b) -> a -> c
. PackageVersion -> [Int]
unPackageVersion

-- $retrieve-version-th
-- These functions allow for reading a cabal's version at compile-time. If
-- the intention is to simply read the value so it can be printed during
-- runtime (e.g. for an executable's @--version@ flag), then
-- 'packageVersionStringTH' (or 'packageVersionTextTH') is the best choice,
-- as any errors encountered will not prevent compilation.

-- | 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]
--
-- @since 0.1.0.0
#if MIN_VERSION_template_haskell(2, 17, 0)
packageVersionTH :: FilePath -> Code Q PackageVersion
#else
packageVersionTH :: FilePath -> Q (TExp PackageVersion)
#endif
packageVersionTH :: [Char] -> Code Q PackageVersion
packageVersionTH = forall b a. Lift b => (a -> IO b) -> a -> Code Q b
ioToTH [Char] -> IO PackageVersion
unsafePackageVersionIO
  where
    unsafePackageVersionIO :: [Char] -> IO PackageVersion
unsafePackageVersionIO = forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap (forall a c b. (a -> c) -> (b -> c) -> Either a b -> c
either (forall a. HasCallStack => [Char] -> a
error forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall a. Pretty a => a -> [Char]
Internal.prettyString) forall a. a -> a
id) forall b c a. (b -> c) -> (a -> b) -> a -> c
. [Char] -> IO (Either ReadFileError PackageVersion)
packageVersionEitherIO

-- | 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"
--
-- @since 0.1.0.0
#if MIN_VERSION_template_haskell(2, 17, 0)
packageVersionStringTH :: FilePath -> Code Q String
#else
packageVersionStringTH :: FilePath -> Q (TExp String)
#endif
packageVersionStringTH :: [Char] -> Code Q [Char]
packageVersionStringTH = forall b a. Lift b => (a -> IO b) -> a -> Code Q b
ioToTH [Char] -> IO [Char]
packageVersionStringIO

-- | 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"
--
-- @since 0.1.0.0
#if MIN_VERSION_template_haskell(2, 17, 0)
packageVersionTextTH :: FilePath -> Code Q Text
#else
packageVersionTextTH :: FilePath -> Q (TExp Text)
#endif
packageVersionTextTH :: [Char] -> Code Q Text
packageVersionTextTH = forall b a. Lift b => (a -> IO b) -> a -> Code Q b
ioToTH [Char] -> IO Text
packageVersionTextIO

-- | Version of 'packageVersionEitherIO' that throws an
-- 'Control.Exception.Safe.Exception' if any errors are encountered.
--
-- ==== __Examples__
-- >>> packageVersionThrowIO "package-version.cabal"
-- UnsafePackageVersion [0,3]
--
-- @since 0.1.0.0
packageVersionThrowIO :: FilePath -> IO PackageVersion
packageVersionThrowIO :: [Char] -> IO PackageVersion
packageVersionThrowIO = [Char] -> IO (Either ReadFileError PackageVersion)
packageVersionEitherIO forall (m :: * -> *) a b c.
Monad m =>
(a -> m b) -> (b -> m c) -> a -> m c
>=> forall a c b. (a -> c) -> (b -> c) -> Either a b -> c
either forall (m :: * -> *) e a. (MonadThrow m, Exception e) => e -> m a
SafeEx.throw forall (f :: * -> *) a. Applicative f => a -> f a
pure

-- | 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"
--
-- @since 0.1.0.0
packageVersionStringIO :: FilePath -> IO String
packageVersionStringIO :: [Char] -> IO [Char]
packageVersionStringIO [Char]
fp = do
  Either ReadFileError PackageVersion
eVersion <- [Char] -> IO (Either ReadFileError PackageVersion)
packageVersionEitherIO [Char]
fp
  forall (f :: * -> *) a. Applicative f => a -> f a
pure forall a b. (a -> b) -> a -> b
$ case Either ReadFileError PackageVersion
eVersion of
    Left ReadFileError
_ -> [Char]
"UNKNOWN"
    Right PackageVersion
v -> PackageVersion -> [Char]
toString PackageVersion
v

-- | 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"
--
-- @since 0.1.0.0
packageVersionTextIO :: FilePath -> IO Text
packageVersionTextIO :: [Char] -> IO Text
packageVersionTextIO [Char]
fp = do
  Either ReadFileError PackageVersion
eVersion <- [Char] -> IO (Either ReadFileError PackageVersion)
packageVersionEitherIO [Char]
fp
  forall (f :: * -> *) a. Applicative f => a -> f a
pure forall a b. (a -> b) -> a -> b
$ case Either ReadFileError PackageVersion
eVersion of
    Left ReadFileError
_ -> Text
"UNKNOWN"
    Right PackageVersion
v -> PackageVersion -> Text
Internal.toText PackageVersion
v

-- | Reads the cabal-file's version.
--
-- ==== __Examples__
-- >>> packageVersionEitherIO "package-version.cabal"
-- Right (UnsafePackageVersion [0,3])
--
-- @since 0.1.0.0
packageVersionEitherIO :: FilePath -> IO (Either ReadFileError PackageVersion)
packageVersionEitherIO :: [Char] -> IO (Either ReadFileError PackageVersion)
packageVersionEitherIO [Char]
fp = do
  Either SomeException [Text]
eContents <- forall (p :: * -> * -> *) b c a.
Bifunctor p =>
(b -> c) -> p a b -> p a c
second Text -> [Text]
T.lines forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> forall (m :: * -> *) a.
MonadCatch m =>
m a -> m (Either SomeException a)
SafeEx.tryAny ([Char] -> IO Text
readFile' [Char]
fp)
  forall (f :: * -> *) a. Applicative f => a -> f a
pure forall a b. (a -> b) -> a -> b
$ case Either SomeException [Text]
eContents of
    Left SomeException
err -> forall a b. a -> Either a b
Left forall a b. (a -> b) -> a -> b
$ [Char] -> ReadFileError
ReadFileErrorGeneral forall a b. (a -> b) -> a -> b
$ forall e. Exception e => e -> [Char]
displayException SomeException
err
    Right [Text]
contents -> forall (t :: * -> *) a b.
Foldable t =>
(a -> b -> b) -> b -> t a -> b
foldr Text
-> Either ReadFileError PackageVersion
-> Either ReadFileError PackageVersion
findVers forall {b}. Either ReadFileError b
noVersErr [Text]
contents
  where
    noVersErr :: Either ReadFileError b
noVersErr = forall a b. a -> Either a b
Left forall a b. (a -> b) -> a -> b
$ [Char] -> ReadFileError
ReadFileErrorVersionNotFound [Char]
fp
    findVers :: Text
-> Either ReadFileError PackageVersion
-> Either ReadFileError PackageVersion
findVers Text
line Either ReadFileError PackageVersion
acc = case Text -> Text -> Maybe Text
T.stripPrefix Text
"version:" Text
line of
      Just Text
rest -> forall (p :: * -> * -> *) a b c.
Bifunctor p =>
(a -> b) -> p a c -> p b c
first ReadStringError -> ReadFileError
ReadFileErrorReadString forall a b. (a -> b) -> a -> b
$ Text -> Either ReadStringError PackageVersion
fromText (Text -> Text
T.strip Text
rest)
      Maybe Text
Nothing -> Either ReadFileError PackageVersion
acc
    readFile' :: [Char] -> IO Text
readFile' = forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap (OnDecodeError -> ByteString -> Text
decodeUtf8With OnDecodeError
lenientDecode) forall b c a. (b -> c) -> (a -> b) -> a -> c
. [Char] -> IO ByteString
BS.readFile

#if MIN_VERSION_template_haskell(2, 17, 0)
ioToTH :: Lift b => (a -> IO b) -> a -> Code Q b
ioToTH :: forall b a. Lift b => (a -> IO b) -> a -> Code Q b
ioToTH a -> IO b
f a
x = forall (m :: * -> *) a b.
Monad m =>
m a -> (a -> Code m b) -> Code m b
TH.bindCode (forall a. IO a -> Q a
TH.runIO (a -> IO b
f a
x)) forall t (m :: * -> *). (Lift t, Quote m) => t -> Code m t
liftTyped
#else
ioToTH :: Lift b => (a -> IO b) -> a -> Q (TExp b)
ioToTH f x = TH.runIO (f x) >>= liftTyped
#endif