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


-- | Composable, hierarchical errors.
--   
--   An Applicative Functor with error accumulation. Built in tree like
--   error type meant for gathering and reporting errors to users.
@package error-or
@version 0.2.0.0


-- | Provides composable and hierarchical errors, with pretty printing. The
--   errors are accumulated in a tree like structure, <a>ErrorAcc</a>.
--   <a>ErrorAcc</a> is disigned to be read by humans, via
--   <a>prettyErrAcc</a>, not dispatched on by code. Using <a>toE</a> to
--   convert an <a>ErrorOr</a> to IO throws (in case it holds an error) a
--   <a>PrettyErrAcc</a> that uses <tt>pretty</tt> in the show instance.
module Data.ErrorOr

-- | Use <a>Applicative</a>'s <a>sequenceA</a> and <tt>sequenceA_</tt> to
--   compose <a>ErrorOr</a>s as opposed to <a>Monad</a> derived functions
--   like <a>sequence</a>.
newtype ErrorOr a
ErrorOr :: Either ErrorAcc a -> ErrorOr a
[errorOrToEither] :: ErrorOr a -> Either ErrorAcc a

-- | Annotate the error with context information.
tag :: Text -> ErrorOr a -> ErrorOr a
pattern Error :: ErrorAcc -> ErrorOr a
pattern OK :: a -> ErrorOr a
isOK :: ErrorOr a -> Bool
isError :: ErrorOr a -> Bool

-- | A partial function, like <tt>fromRight</tt>.
fromOK :: ErrorOr a -> a

-- | Produce an error from <tt>Text</tt>. You can also use <a>fail</a>,
--   which takes a <a>String</a>.
failText :: Text -> ErrorOr a

-- | Convert between functors that hold error info.
class ErrorConv t s
toE :: ErrorConv t s => t a -> s a
data ErrorAcc
ErrMessage :: Text -> ErrorAcc
ErrList :: Seq ErrorAcc -> ErrorAcc
ErrTag :: Text -> ErrorAcc -> ErrorAcc

-- | Pretty print the error.
prettyErrAcc :: Int -> ErrorAcc -> Text

-- | A wrapper over <a>ErrorAcc</a> to provide human readable exceptions.
--   (Exception class' displayException does not seem to be used by GHC)
--   <a>https://stackoverflow.com/questions/55490766/why-doesn-t-ghc-use-my-displayexception-method</a>
newtype PrettyErrAcc
PrettyErrAcc :: ErrorAcc -> PrettyErrAcc
[unPrettyErrAcc] :: PrettyErrAcc -> ErrorAcc

-- | Tag an exception with an annotation.
--   
--   It acts on two types of exceptions: <a>IOException</a> and
--   <a>PrettyErrAcc</a>. For <a>PrettyErrAcc</a> it is streightforward
--   tagging. For <a>IOException</a>, otoh, it converts the error message
--   into Text via String and turns it into <a>PrettyErrAcc</a> tagged with
--   provided adnotation.
--   
--   This is rather a convenience function. Sometimes it is convenient to
--   <tt>fail "msg"</tt> in IO, and tag it higher up with some context. The
--   need for <a>tagIO</a> often comes with <a>lookup</a> (from
--   error-or-utils package) when used from IO, which is overloaded for
--   MonadFail.
--   
--   Since ver 0.1.1.0
tagIO :: Text -> IO a -> IO a
instance GHC.Classes.Ord Data.ErrorOr.ErrorAcc
instance GHC.Classes.Eq Data.ErrorOr.ErrorAcc
instance GHC.Read.Read Data.ErrorOr.ErrorAcc
instance GHC.Show.Show Data.ErrorOr.ErrorAcc
instance Data.Traversable.Traversable Data.ErrorOr.ErrorOr
instance Data.Foldable.Foldable Data.ErrorOr.ErrorOr
instance GHC.Base.Functor Data.ErrorOr.ErrorOr
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.ErrorOr.ErrorOr a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.ErrorOr.ErrorOr a)
instance GHC.Read.Read a => GHC.Read.Read (Data.ErrorOr.ErrorOr a)
instance GHC.Show.Show a => GHC.Show.Show (Data.ErrorOr.ErrorOr a)
instance Data.ErrorOr.ErrorConv Data.ErrorOr.ErrorOr GHC.Types.IO
instance Data.ErrorOr.ErrorConv GHC.Maybe.Maybe Data.ErrorOr.ErrorOr
instance GHC.Show.Show e => Data.ErrorOr.ErrorConv (Data.Either.Either e) Data.ErrorOr.ErrorOr
instance GHC.Show.Show Data.ErrorOr.PrettyErrAcc
instance GHC.Exception.Type.Exception Data.ErrorOr.PrettyErrAcc
instance GHC.Base.Applicative Data.ErrorOr.ErrorOr
instance GHC.Base.Semigroup a => GHC.Base.Semigroup (Data.ErrorOr.ErrorOr a)
instance (GHC.Base.Semigroup (Data.ErrorOr.ErrorOr a), GHC.Base.Monoid a) => GHC.Base.Monoid (Data.ErrorOr.ErrorOr a)
instance GHC.Base.Monad Data.ErrorOr.ErrorOr
instance Control.Monad.Fail.MonadFail Data.ErrorOr.ErrorOr
instance Control.Monad.Error.Class.MonadError Data.ErrorOr.ErrorAcc Data.ErrorOr.ErrorOr
instance Data.String.IsString Data.ErrorOr.ErrorAcc
instance GHC.Base.Semigroup Data.ErrorOr.ErrorAcc