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


-- | These as a transformer, ChronicleT
--   
--   This packages provides <tt>ChronicleT</tt>, a monad transformer based
--   on the <tt>Monad</tt> instance for <tt>These a</tt>, along with the
--   usual monad transformer bells and whistles.
@package monad-chronicle
@version 1.0.1


-- | Hybrid error/writer monad class that allows both accumulating outputs
--   and aborting computation with a final output.
--   
--   The expected use case is for computations with a notion of fatal vs.
--   non-fatal errors.
module Control.Monad.Trans.Chronicle

-- | A chronicle monad parameterized by the output type <tt>c</tt>.
--   
--   The <a>return</a> function produces a computation with no output, and
--   <a>&gt;&gt;=</a> combines multiple outputs with <a>&lt;&gt;</a>.
type Chronicle c = ChronicleT c Identity
chronicle :: Monad m => These c a -> ChronicleT c m a
runChronicle :: Chronicle c a -> These c a

-- | The <a>ChronicleT</a> monad transformer.
--   
--   The <a>return</a> function produces a computation with no output, and
--   <a>&gt;&gt;=</a> combines multiple outputs with <a>&lt;&gt;</a>.
newtype ChronicleT c m a
ChronicleT :: m (These c a) -> ChronicleT c m a
[runChronicleT] :: ChronicleT c m a -> m (These c a)

-- | <tt><a>dictate</a> c</tt> is an action that records the output
--   <tt>c</tt>.
--   
--   Equivalent to <a>tell</a> for the <tt>Writer</tt> monad.
dictate :: (Semigroup c, Monad m) => c -> ChronicleT c m ()

-- | <tt><a>disclose</a> c</tt> is an action that records the output
--   <tt>c</tt> and returns a <tt><a>Default</a></tt> value.
--   
--   This is a convenience function for reporting non-fatal errors in one
--   branch a <tt>case</tt>, or similar scenarios when there is no
--   meaningful result but a placeholder of sorts is needed in order to
--   continue.
disclose :: (Default a, Semigroup c, Monad m) => c -> ChronicleT c m a

-- | <tt><a>confess</a> c</tt> is an action that ends with a final output
--   <tt>c</tt>.
--   
--   Equivalent to <a>throwError</a> for the <a>Error</a> monad.
confess :: (Semigroup c, Monad m) => c -> ChronicleT c m a

-- | <tt><a>memento</a> m</tt> is an action that executes the action
--   <tt>m</tt>, returning either its record if it ended with
--   <a>confess</a>, or its final value otherwise, with any record added to
--   the current record.
--   
--   Similar to <a>catchError</a> in the <a>Error</a> monad, but with a
--   notion of non-fatal errors (which are accumulated) vs. fatal errors
--   (which are caught without accumulating).
memento :: (Semigroup c, Monad m) => ChronicleT c m a -> ChronicleT c m (Either c a)

-- | <tt><a>absolve</a> x m</tt> is an action that executes the action
--   <tt>m</tt> and discards any record it had. The default value
--   <tt>x</tt> will be used if <tt>m</tt> ended via <a>confess</a>.
absolve :: (Semigroup c, Monad m) => a -> ChronicleT c m a -> ChronicleT c m a

-- | <tt><a>condemn</a> m</tt> is an action that executes the action
--   <tt>m</tt> and keeps its value only if it had no record. Otherwise,
--   the value (if any) will be discarded and only the record kept.
--   
--   This can be seen as converting non-fatal errors into fatal ones.
condemn :: (Semigroup c, Monad m) => ChronicleT c m a -> ChronicleT c m a

-- | <tt><a>retcon</a> f m</tt> is an action that executes the action
--   <tt>m</tt> and applies the function <tt>f</tt> to its output, leaving
--   the return value unchanged.
--   
--   Equivalent to <a>censor</a> for the <tt>Writer</tt> monad.
retcon :: (Semigroup c, Monad m) => (c -> c) -> ChronicleT c m a -> ChronicleT c m a
instance GHC.Base.Functor m => GHC.Base.Functor (Control.Monad.Trans.Chronicle.ChronicleT c m)
instance (GHC.Base.Semigroup c, Data.Functor.Bind.Class.Apply m) => Data.Functor.Bind.Class.Apply (Control.Monad.Trans.Chronicle.ChronicleT c m)
instance (GHC.Base.Semigroup c, Data.Functor.Bind.Class.Apply m, GHC.Base.Monad m) => Data.Functor.Bind.Class.Bind (Control.Monad.Trans.Chronicle.ChronicleT c m)
instance (GHC.Base.Semigroup c, GHC.Base.Applicative m) => GHC.Base.Applicative (Control.Monad.Trans.Chronicle.ChronicleT c m)
instance (GHC.Base.Semigroup c, GHC.Base.Monad m) => GHC.Base.Monad (Control.Monad.Trans.Chronicle.ChronicleT c m)
instance GHC.Base.Semigroup c => Control.Monad.Trans.Class.MonadTrans (Control.Monad.Trans.Chronicle.ChronicleT c)
instance (GHC.Base.Semigroup c, Control.Monad.IO.Class.MonadIO m) => Control.Monad.IO.Class.MonadIO (Control.Monad.Trans.Chronicle.ChronicleT c m)
instance (GHC.Base.Semigroup c, GHC.Base.Monoid c, GHC.Base.Applicative m, GHC.Base.Monad m) => GHC.Base.Alternative (Control.Monad.Trans.Chronicle.ChronicleT c m)
instance (GHC.Base.Semigroup c, GHC.Base.Monoid c, GHC.Base.Monad m) => GHC.Base.MonadPlus (Control.Monad.Trans.Chronicle.ChronicleT c m)
instance (GHC.Base.Semigroup c, Control.Monad.Error.Class.MonadError e m) => Control.Monad.Error.Class.MonadError e (Control.Monad.Trans.Chronicle.ChronicleT c m)
instance (GHC.Base.Semigroup c, Control.Monad.Reader.Class.MonadReader r m) => Control.Monad.Reader.Class.MonadReader r (Control.Monad.Trans.Chronicle.ChronicleT c m)
instance (GHC.Base.Semigroup c, Control.Monad.RWS.Class.MonadRWS r w s m) => Control.Monad.RWS.Class.MonadRWS r w s (Control.Monad.Trans.Chronicle.ChronicleT c m)
instance (GHC.Base.Semigroup c, Control.Monad.State.Class.MonadState s m) => Control.Monad.State.Class.MonadState s (Control.Monad.Trans.Chronicle.ChronicleT c m)
instance (GHC.Base.Semigroup c, Control.Monad.Writer.Class.MonadWriter w m) => Control.Monad.Writer.Class.MonadWriter w (Control.Monad.Trans.Chronicle.ChronicleT c m)
instance (GHC.Base.Semigroup c, Control.Monad.Fix.MonadFix m) => Control.Monad.Fix.MonadFix (Control.Monad.Trans.Chronicle.ChronicleT c m)


-- | Hybrid error/writer monad class that allows both accumulating outputs
--   and aborting computation with a final output.
--   
--   The expected use case is for computations with a notion of fatal vs.
--   non-fatal errors.
module Control.Monad.Chronicle.Class
class (Monad m) => MonadChronicle c m | m -> c

-- | <tt><a>dictate</a> c</tt> is an action that records the output
--   <tt>c</tt>.
--   
--   Equivalent to <a>tell</a> for the <a>Writer</a> monad.
dictate :: MonadChronicle c m => c -> m ()

-- | <tt><a>disclose</a> c</tt> is an action that records the output
--   <tt>c</tt> and returns a <tt><a>Default</a></tt> value.
--   
--   This is a convenience function for reporting non-fatal errors in one
--   branch a <tt>case</tt>, or similar scenarios when there is no
--   meaningful result but a placeholder of sorts is needed in order to
--   continue.
disclose :: (MonadChronicle c m, Default a) => c -> m a

-- | <tt><a>confess</a> c</tt> is an action that ends with a final record
--   <tt>c</tt>.
--   
--   Equivalent to <a>throwError</a> for the <a>Error</a> monad.
confess :: MonadChronicle c m => c -> m a

-- | <tt><a>memento</a> m</tt> is an action that executes the action
--   <tt>m</tt>, returning either its record if it ended with
--   <a>confess</a>, or its final value otherwise, with any record added to
--   the current record.
--   
--   Similar to <a>catchError</a> in the <a>Error</a> monad, but with a
--   notion of non-fatal errors (which are accumulated) vs. fatal errors
--   (which are caught without accumulating).
memento :: MonadChronicle c m => m a -> m (Either c a)

-- | <tt><a>absolve</a> x m</tt> is an action that executes the action
--   <tt>m</tt> and discards any record it had. The default value
--   <tt>x</tt> will be used if <tt>m</tt> ended via <a>confess</a>.
absolve :: MonadChronicle c m => a -> m a -> m a

-- | <tt><a>condemn</a> m</tt> is an action that executes the action
--   <tt>m</tt> and keeps its value only if it had no record. Otherwise,
--   the value (if any) will be discarded and only the record kept.
--   
--   This can be seen as converting non-fatal errors into fatal ones.
condemn :: MonadChronicle c m => m a -> m a

-- | <tt><a>retcon</a> f m</tt> is an action that executes the action
--   <tt>m</tt> and applies the function <tt>f</tt> to its output, leaving
--   the return value unchanged.
--   
--   Equivalent to <a>censor</a> for the <a>Writer</a> monad.
retcon :: MonadChronicle c m => (c -> c) -> m a -> m a

-- | <tt><a>chronicle</a> m</tt> lifts a plain <tt><a>These</a> c a</tt>
--   value into a <a>MonadChronicle</a> instance.
chronicle :: MonadChronicle c m => These c a -> m a
instance GHC.Base.Semigroup c => Control.Monad.Chronicle.Class.MonadChronicle c (Data.These.These c)
instance (GHC.Base.Semigroup c, GHC.Base.Monad m) => Control.Monad.Chronicle.Class.MonadChronicle c (Control.Monad.Trans.Chronicle.ChronicleT c m)
instance Control.Monad.Chronicle.Class.MonadChronicle c m => Control.Monad.Chronicle.Class.MonadChronicle c (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.Chronicle.Class.MonadChronicle c m => Control.Monad.Chronicle.Class.MonadChronicle c (Control.Monad.Trans.Maybe.MaybeT m)
instance (Control.Monad.Trans.Error.Error e, Control.Monad.Chronicle.Class.MonadChronicle c m) => Control.Monad.Chronicle.Class.MonadChronicle c (Control.Monad.Trans.Error.ErrorT e m)
instance Control.Monad.Chronicle.Class.MonadChronicle c m => Control.Monad.Chronicle.Class.MonadChronicle c (Control.Monad.Trans.Except.ExceptT e m)
instance Control.Monad.Chronicle.Class.MonadChronicle c m => Control.Monad.Chronicle.Class.MonadChronicle c (Control.Monad.Trans.Reader.ReaderT r m)
instance Control.Monad.Chronicle.Class.MonadChronicle c m => Control.Monad.Chronicle.Class.MonadChronicle c (Control.Monad.Trans.State.Lazy.StateT s m)
instance Control.Monad.Chronicle.Class.MonadChronicle c m => Control.Monad.Chronicle.Class.MonadChronicle c (Control.Monad.Trans.State.Strict.StateT s m)
instance (GHC.Base.Monoid w, Control.Monad.Chronicle.Class.MonadChronicle c m) => Control.Monad.Chronicle.Class.MonadChronicle c (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (GHC.Base.Monoid w, Control.Monad.Chronicle.Class.MonadChronicle c m) => Control.Monad.Chronicle.Class.MonadChronicle c (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance (GHC.Base.Monoid w, Control.Monad.Chronicle.Class.MonadChronicle c m) => Control.Monad.Chronicle.Class.MonadChronicle c (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance (GHC.Base.Monoid w, Control.Monad.Chronicle.Class.MonadChronicle c m) => Control.Monad.Chronicle.Class.MonadChronicle c (Control.Monad.Trans.RWS.Strict.RWST r w s m)


-- | The <a>ChronicleT</a> monad, a hybrid error/writer monad that allows
--   both accumulating outputs and aborting computation with a final
--   output.
module Control.Monad.Chronicle
class (Monad m) => MonadChronicle c m | m -> c

-- | <tt><a>dictate</a> c</tt> is an action that records the output
--   <tt>c</tt>.
--   
--   Equivalent to <a>tell</a> for the <a>Writer</a> monad.
dictate :: MonadChronicle c m => c -> m ()

-- | <tt><a>disclose</a> c</tt> is an action that records the output
--   <tt>c</tt> and returns a <tt><a>Default</a></tt> value.
--   
--   This is a convenience function for reporting non-fatal errors in one
--   branch a <tt>case</tt>, or similar scenarios when there is no
--   meaningful result but a placeholder of sorts is needed in order to
--   continue.
disclose :: (MonadChronicle c m, Default a) => c -> m a

-- | <tt><a>confess</a> c</tt> is an action that ends with a final record
--   <tt>c</tt>.
--   
--   Equivalent to <a>throwError</a> for the <a>Error</a> monad.
confess :: MonadChronicle c m => c -> m a

-- | <tt><a>memento</a> m</tt> is an action that executes the action
--   <tt>m</tt>, returning either its record if it ended with
--   <a>confess</a>, or its final value otherwise, with any record added to
--   the current record.
--   
--   Similar to <a>catchError</a> in the <a>Error</a> monad, but with a
--   notion of non-fatal errors (which are accumulated) vs. fatal errors
--   (which are caught without accumulating).
memento :: MonadChronicle c m => m a -> m (Either c a)

-- | <tt><a>absolve</a> x m</tt> is an action that executes the action
--   <tt>m</tt> and discards any record it had. The default value
--   <tt>x</tt> will be used if <tt>m</tt> ended via <a>confess</a>.
absolve :: MonadChronicle c m => a -> m a -> m a

-- | <tt><a>condemn</a> m</tt> is an action that executes the action
--   <tt>m</tt> and keeps its value only if it had no record. Otherwise,
--   the value (if any) will be discarded and only the record kept.
--   
--   This can be seen as converting non-fatal errors into fatal ones.
condemn :: MonadChronicle c m => m a -> m a

-- | <tt><a>retcon</a> f m</tt> is an action that executes the action
--   <tt>m</tt> and applies the function <tt>f</tt> to its output, leaving
--   the return value unchanged.
--   
--   Equivalent to <a>censor</a> for the <a>Writer</a> monad.
retcon :: MonadChronicle c m => (c -> c) -> m a -> m a

-- | <tt><a>chronicle</a> m</tt> lifts a plain <tt><a>These</a> c a</tt>
--   value into a <a>MonadChronicle</a> instance.
chronicle :: MonadChronicle c m => These c a -> m a

-- | A chronicle monad parameterized by the output type <tt>c</tt>.
--   
--   The <a>return</a> function produces a computation with no output, and
--   <a>&gt;&gt;=</a> combines multiple outputs with <a>&lt;&gt;</a>.
type Chronicle c = ChronicleT c Identity
runChronicle :: Chronicle c a -> These c a

-- | The <a>ChronicleT</a> monad transformer.
--   
--   The <a>return</a> function produces a computation with no output, and
--   <a>&gt;&gt;=</a> combines multiple outputs with <a>&lt;&gt;</a>.
newtype ChronicleT c m a
ChronicleT :: m (These c a) -> ChronicleT c m a
[runChronicleT] :: ChronicleT c m a -> m (These c a)
