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

-- | An either-or-both data type & a generalized 'zip with padding' typeclass
--   
--   This package provides a data type These a b which can hold a
--   value of either type or values of each type. This is usually thought
--   of as an "inclusive or" type (contrasting Either a b as
--   "exclusive or") or as an "outer join" type (contrasting (a,
--   b) as "inner join").
--   
--   The major use case of this is provided by the Align class,
--   representing a generalized notion of "zipping with padding" that
--   combines structures without truncating to the size of the smaller
--   input.
--   
--   Also included is ChronicleT, a monad transformer based on the
--   Monad instance for These a, along with the usual monad
--   transformer bells and whistles.
@package these
@version 0.7.3

-- | The These type and associated operations. Now enhanced with
--   Control.Lens magic!
module Data.These

-- | The These type represents values with two non-exclusive
--   possibilities.
--   
--   This can be useful to represent combinations of two values, where the
--   combination is defined if either input is. Algebraically, the type
--   These A B represents (A + B + AB), which doesn't
--   factor easily into sums and products--a type like Either A (B,
--   Maybe A) is unclear and awkward to use.
--   
--   These has straightforward instances of Functor,
--   Monad, &c., and behaves like a hybrid error/writer monad,
--   as would be expected.
data These a b
This :: a -> These a b
That :: b -> These a b
These :: a -> b -> These a b

-- | Case analysis for the These type.
these :: (a -> c) -> (b -> c) -> (a -> b -> c) -> These a b -> c

-- | Takes two default values and produces a tuple.
fromThese :: a -> b -> These a b -> (a, b)

-- | Coalesce with the provided operation.
mergeThese :: (a -> a -> a) -> These a a -> a

-- | BiMap and coalesce results with the provided operation.
mergeTheseWith :: (a -> c) -> (b -> c) -> (c -> c -> c) -> These a b -> c

-- | A Traversal of the first half of a These, suitable for
--   use with Control.Lens.
here :: (Applicative f) => (a -> f b) -> These a t -> f (These b t)

-- | A Traversal of the second half of a These, suitable
--   for use with Control.Lens.
there :: (Applicative f) => (a -> f b) -> These t a -> f (These t b)

-- | A Prism selecting the This constructor.
_This :: (Choice p, Applicative f) => p a (f a) -> p (These a b) (f (These a b))

-- | A Prism selecting the That constructor.
_That :: (Choice p, Applicative f) => p b (f b) -> p (These a b) (f (These a b))

-- | A Prism selecting the These constructor. These
--   names are ridiculous!
_These :: (Choice p, Applicative f) => p (a, b) (f (a, b)) -> p (These a b) (f (These a b))

-- | 
--   justThis = preview _This
--   
justThis :: These a b -> Maybe a

-- | 
--   justThat = preview _That
--   
justThat :: These a b -> Maybe b

-- | 
--   justThese = preview _These
--   
justThese :: These a b -> Maybe (a, b)

-- | Select all This constructors from a list.
catThis :: [These a b] -> [a]

-- | Select all That constructors from a list.
catThat :: [These a b] -> [b]

-- | Select all These constructors from a list.
catThese :: [These a b] -> [(a, b)]

-- | Select each constructor and partition them into separate lists.
partitionThese :: [These a b] -> ([(a, b)], ([a], [b]))

-- | 
--   isThis = isJust . justThis
--   
isThis :: These a b -> Bool

-- | 
--   isThat = isJust . justThat
--   
isThat :: These a b -> Bool

-- | 
--   isThese = isJust . justThese
--   
isThese :: These a b -> Bool

-- | Bifunctor map.
mapThese :: (a -> c) -> (b -> d) -> These a b -> These c d

-- | 
--   mapThis = over here
--   
mapThis :: (a -> c) -> These a b -> These c b

-- | 
--   mapThat = over there
--   
mapThat :: (b -> d) -> These a b -> These a d
instance GHC.Generics.Generic (Data.These.These a b)
instance (Data.Data.Data b, Data.Data.Data a) => Data.Data.Data (Data.These.These a b)
instance (GHC.Show.Show b, GHC.Show.Show a) => GHC.Show.Show (Data.These.These a b)
instance (GHC.Read.Read b, GHC.Read.Read a) => GHC.Read.Read (Data.These.These a b)
instance (GHC.Classes.Ord b, GHC.Classes.Ord a) => GHC.Classes.Ord (Data.These.These a b)
instance (GHC.Classes.Eq b, GHC.Classes.Eq a) => GHC.Classes.Eq (Data.These.These a b)
instance (Data.Semigroup.Semigroup a, Data.Semigroup.Semigroup b) => Data.Semigroup.Semigroup (Data.These.These a b)
instance GHC.Base.Functor (Data.These.These a)
instance Data.Foldable.Foldable (Data.These.These a)
instance Data.Traversable.Traversable (Data.These.These a)
instance Data.Bifunctor.Bifunctor Data.These.These
instance Data.Bifoldable.Bifoldable Data.These.These
instance Data.Semigroup.Foldable.Class.Bifoldable1 Data.These.These
instance Data.Bitraversable.Bitraversable Data.These.These
instance Data.Semigroup.Traversable.Class.Bitraversable1 Data.These.These
instance Data.Semigroup.Semigroup a => Data.Functor.Bind.Class.Apply (Data.These.These a)
instance Data.Semigroup.Semigroup a => GHC.Base.Applicative (Data.These.These a)
instance Data.Semigroup.Semigroup a => Data.Functor.Bind.Class.Bind (Data.These.These a)
instance Data.Semigroup.Semigroup a => GHC.Base.Monad (Data.These.These a)
instance (Data.Hashable.Class.Hashable a, Data.Hashable.Class.Hashable b) => Data.Hashable.Class.Hashable (Data.These.These a b)
instance (Control.DeepSeq.NFData a, Control.DeepSeq.NFData b) => Control.DeepSeq.NFData (Data.These.These a b)
instance (Data.Binary.Class.Binary a, Data.Binary.Class.Binary b) => Data.Binary.Class.Binary (Data.These.These a b)
instance (Data.Aeson.Types.ToJSON.ToJSON a, Data.Aeson.Types.ToJSON.ToJSON b) => Data.Aeson.Types.ToJSON.ToJSON (Data.These.These a b)
instance (Data.Aeson.Types.FromJSON.FromJSON a, Data.Aeson.Types.FromJSON.FromJSON b) => Data.Aeson.Types.FromJSON.FromJSON (Data.These.These a b)
instance Data.Aeson.Types.ToJSON.ToJSON2 Data.These.These
instance Data.Aeson.Types.ToJSON.ToJSON a => Data.Aeson.Types.ToJSON.ToJSON1 (Data.These.These a)
instance Data.Aeson.Types.FromJSON.FromJSON2 Data.These.These
instance Data.Aeson.Types.FromJSON.FromJSON a => Data.Aeson.Types.FromJSON.FromJSON1 (Data.These.These a)
instance (Test.QuickCheck.Arbitrary.Arbitrary a, Test.QuickCheck.Arbitrary.Arbitrary b) => Test.QuickCheck.Arbitrary.Arbitrary (Data.These.These a b)
instance (Test.QuickCheck.Function.Function a, Test.QuickCheck.Function.Function b) => Test.QuickCheck.Function.Function (Data.These.These a b)
instance (Test.QuickCheck.Arbitrary.CoArbitrary a, Test.QuickCheck.Arbitrary.CoArbitrary b) => Test.QuickCheck.Arbitrary.CoArbitrary (Data.These.These a b)

-- | These-based zipping and unzipping of functors with non-uniform
--   shapes, plus traversal of (bi)foldable (bi)functors through said
--   functors.
module Data.Align

-- | Functors supporting a zip operation that takes the union of
--   non-uniform shapes.
--   
--   If your functor is actually a functor from Kleisli Maybe to
--   Hask (so it supports maybeMap :: (a -> Maybe b) ->
--   f a -> f b), then an Align instance is making your
--   functor lax monoidal w.r.t. the cartesian monoidal structure on
--   Kleisli Maybe, because These is the cartesian
--   product in that category (a -> Maybe (These b c) ~ (a ->
--   Maybe b, a -> Maybe c)). This insight is due to rwbarton.
--   
--   Minimal definition: nil and either align or
--   alignWith.
--   
--   Laws:
--   
--   
--   (`align` nil) = fmap This
--   (nil `align`) = fmap That
--   join align = fmap (join These)
--   align (f <$> x) (g <$> y) = bimap f g <$> align x y
--   alignWith f a b = f <$> align a b
--   
class (Functor f) => Align f where align = alignWith id alignWith f a b = f <$> align a b

-- | An empty strucutre. aligning with nil
--   will produce a structure with the same shape and elements as the other
--   input, modulo This or That.
nil :: Align f => f a

-- | Analogous to zip, combines two structures by taking
--   the union of their shapes and using These to hold the
--   elements.
align :: Align f => f a -> f b -> f (These a b)

-- | Analogous to zipWith, combines two structures by
--   taking the union of their shapes and combining the elements with the
--   given function.
alignWith :: Align f => (These a b -> c) -> f a -> f b -> f c

-- | Align two structures and combine with mappend.
--   
--   See salign. malign will be deprecated after
--   Semigroup becomes a super class of Monoid
malign :: (Align f, Monoid a) => f a -> f a -> f a

-- | Align two structures and combine with <>.
salign :: (Align f, Semigroup a) => f a -> f a -> f a

-- | Align two structures as in zip, but filling in blanks with
--   Nothing.
padZip :: (Align f) => f a -> f b -> f (Maybe a, Maybe b)

-- | Align two structures as in zipWith, but filling in blanks with
--   Nothing.
padZipWith :: (Align f) => (Maybe a -> Maybe b -> c) -> f a -> f b -> f c

-- | Left-padded zip.
lpadZip :: [a] -> [b] -> [(Maybe a, b)]

-- | Left-padded zipWith.
lpadZipWith :: (Maybe a -> b -> c) -> [a] -> [b] -> [c]

-- | Right-padded zip.
rpadZip :: [a] -> [b] -> [(a, Maybe b)]

-- | Right-padded zipWith.
rpadZipWith :: (a -> Maybe b -> c) -> [a] -> [b] -> [c]
alignVectorWith :: (Vector v a, Vector v b, Vector v c) => (These a b -> c) -> v a -> v b -> v c

-- | Alignable functors supporting an "inverse" to align: splitting
--   a union shape into its component parts.
--   
--   Minimal definition: nothing; a default definition is provided, but it
--   may not have the desired definition for all functors. See the source
--   for more information.
--   
--   Laws:
--   
--   
--   unalign nil                 = (nil,           nil)
--   unalign (This        <$> x) = (Just    <$> x, Nothing <$  x)
--   unalign (That        <$> y) = (Nothing <$  y, Just    <$> y)
--   unalign (join These  <$> x) = (Just    <$> x, Just    <$> x)
--   unalign ((x `These`) <$> y) = (Just x  <$  y, Just    <$> y)
--   unalign ((`These` y) <$> x) = (Just    <$> x, Just y  <$  x)
--   
class (Align f) => Unalign f where unalign x = (fmap left x, fmap right x) where left = these Just (const Nothing) (\ a _ -> Just a) right = these (const Nothing) Just (\ _ b -> Just b)
unalign :: Unalign f => f (These a b) -> (f (Maybe a), f (Maybe b))

-- | Foldable functors supporting traversal through an alignable functor.
--   
--   Minimal definition: crosswalk or sequenceL.
--   
--   Laws:
--   
--   
--   crosswalk (const nil) = const nil
--   crosswalk f = sequenceL . fmap f
--   
class (Functor t, Foldable t) => Crosswalk t where crosswalk f = sequenceL . fmap f sequenceL = crosswalk id
crosswalk :: (Crosswalk t, Align f) => (a -> f b) -> t a -> f (t b)
sequenceL :: (Crosswalk t, Align f) => t (f a) -> f (t a)

-- | Bifoldable bifunctors supporting traversal through an alignable
--   functor.
--   
--   Minimal definition: bicrosswalk or bisequenceL.
--   
--   Laws:
--   
--   
--   bicrosswalk (const empty) (const empty) = const empty
--   bicrosswalk f g = bisequenceL . bimap f g
--   
class (Bifunctor t, Bifoldable t) => Bicrosswalk t where bicrosswalk f g = bisequenceL . bimap f g bisequenceL = bicrosswalk id id
bicrosswalk :: (Bicrosswalk t, Align f) => (a -> f c) -> (b -> f d) -> t a b -> f (t c d)
bisequenceL :: (Bicrosswalk t, Align f) => t (f a) (f b) -> f (t a b)
instance Data.Align.Align GHC.Base.Maybe
instance Data.Align.Align []
instance Data.Align.Align Control.Applicative.ZipList
instance Data.Align.Align Data.Sequence.Seq
instance GHC.Classes.Ord k => Data.Align.Align (Data.Map.Base.Map k)
instance Data.Align.Align Data.IntMap.Base.IntMap
instance (Data.Align.Align f, Data.Align.Align g) => Data.Align.Align (Data.Functor.Product.Product f g)
instance GHC.Base.Monad m => Data.Align.Align (Data.Vector.Fusion.Stream.Monadic.Stream m)
instance GHC.Base.Monad m => Data.Align.Align (Data.Vector.Fusion.Bundle.Monadic.Bundle m v)
instance Data.Align.Align Data.Vector.Vector
instance (GHC.Classes.Eq k, Data.Hashable.Class.Hashable k) => Data.Align.Align (Data.HashMap.Base.HashMap k)
instance Data.Align.Unalign GHC.Base.Maybe
instance Data.Align.Unalign []
instance Data.Align.Unalign Control.Applicative.ZipList
instance (Data.Align.Unalign f, Data.Align.Unalign g) => Data.Align.Unalign (Data.Functor.Product.Product f g)
instance GHC.Base.Monad m => Data.Align.Unalign (Data.Vector.Fusion.Stream.Monadic.Stream m)
instance Data.Align.Crosswalk Data.Functor.Identity.Identity
instance Data.Align.Crosswalk GHC.Base.Maybe
instance Data.Align.Crosswalk []
instance Data.Align.Crosswalk Data.Sequence.Seq
instance Data.Align.Crosswalk (Data.These.These a)
instance Data.Align.Crosswalk Data.Vector.Vector
instance Data.Align.Bicrosswalk Data.Either.Either
instance Data.Align.Bicrosswalk Data.These.These

-- | These-based zipping and unzipping of indexed functors.
module Data.Align.Key

-- | Keyed version of Align.
class (Keyed f, Align f) => AlignWithKey f where alignWithKey f a b = mapWithKey f (align a b)

-- | Analogous to alignWith, but also provides an index.
alignWithKey :: AlignWithKey f => (Key f -> These a b -> c) -> f a -> f b -> f c
instance Data.Align.Key.AlignWithKey GHC.Base.Maybe
instance Data.Align.Key.AlignWithKey []
instance Data.Align.Key.AlignWithKey Data.Sequence.Seq
instance Data.Align.Key.AlignWithKey Data.IntMap.Base.IntMap
instance GHC.Classes.Ord k => Data.Align.Key.AlignWithKey (Data.Map.Base.Map k)
instance (GHC.Classes.Eq k, Data.Hashable.Class.Hashable k) => Data.Align.Key.AlignWithKey (Data.HashMap.Base.HashMap k)
instance Data.Align.Key.AlignWithKey Data.Vector.Vector

-- | 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 c.
--   
--   The return function produces a computation with no output, and
--   >>= combines multiple outputs with mappend.
type Chronicle c = ChronicleT c Identity
chronicle :: These c a -> Chronicle c a
runChronicle :: Chronicle c a -> These c a

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

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

-- | disclose c is an action that records the output
--   c and returns a Default value.
--   
--   This is a convenience function for reporting non-fatal errors in one
--   branch a case, 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

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

-- | memento m is an action that executes the action
--   m, returning either its record if it ended with
--   confess, or its final value otherwise, with any record added to
--   the current record.
--   
--   Similar to catchError in the Error 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)

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

-- | condemn m is an action that executes the action
--   m 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

-- | retcon f m is an action that executes the action
--   m and applies the function f to its output, leaving
--   the return value unchanged.
--   
--   Equivalent to censor for the Writer 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 (Data.Semigroup.Semigroup c, Data.Functor.Bind.Class.Apply m) => Data.Functor.Bind.Class.Apply (Control.Monad.Trans.Chronicle.ChronicleT c m)
instance (Data.Semigroup.Semigroup c, GHC.Base.Applicative m) => GHC.Base.Applicative (Control.Monad.Trans.Chronicle.ChronicleT c m)
instance (Data.Semigroup.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 (Data.Semigroup.Semigroup c, GHC.Base.Monad m) => GHC.Base.Monad (Control.Monad.Trans.Chronicle.ChronicleT c m)
instance Data.Semigroup.Semigroup c => Control.Monad.Trans.Class.MonadTrans (Control.Monad.Trans.Chronicle.ChronicleT c)
instance (Data.Semigroup.Semigroup c, Control.Monad.IO.Class.MonadIO m) => Control.Monad.IO.Class.MonadIO (Control.Monad.Trans.Chronicle.ChronicleT c m)
instance (Data.Semigroup.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 (Data.Semigroup.Semigroup c, GHC.Base.Monoid c, GHC.Base.Monad m) => GHC.Base.MonadPlus (Control.Monad.Trans.Chronicle.ChronicleT c m)
instance (Data.Semigroup.Semigroup c, Control.Monad.Error.Class.MonadError e m) => Control.Monad.Error.Class.MonadError e (Control.Monad.Trans.Chronicle.ChronicleT c m)
instance (Data.Semigroup.Semigroup c, Control.Monad.Reader.Class.MonadReader r m) => Control.Monad.Reader.Class.MonadReader r (Control.Monad.Trans.Chronicle.ChronicleT c m)
instance (Data.Semigroup.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 (Data.Semigroup.Semigroup c, Control.Monad.State.Class.MonadState s m) => Control.Monad.State.Class.MonadState s (Control.Monad.Trans.Chronicle.ChronicleT c m)
instance (Data.Semigroup.Semigroup c, Control.Monad.Writer.Class.MonadWriter w m) => Control.Monad.Writer.Class.MonadWriter w (Control.Monad.Trans.Chronicle.ChronicleT c m)
instance (Data.Semigroup.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 where disclose c = dictate c >> return def

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

-- | disclose c is an action that records the output
--   c and returns a Default value.
--   
--   This is a convenience function for reporting non-fatal errors in one
--   branch a case, 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

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

-- | memento m is an action that executes the action
--   m, returning either its record if it ended with
--   confess, or its final value otherwise, with any record added to
--   the current record.
--   
--   Similar to catchError in the Error 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)

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

-- | condemn m is an action that executes the action
--   m 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

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

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

-- | The ChronicleT monad transformer.
--   
--   The return function produces a computation with no output, and
--   >>= combines multiple outputs with mappend.
newtype ChronicleT c m a
ChronicleT :: m (These c a) -> ChronicleT c m a
[runChronicleT] :: ChronicleT c m a -> m (These c a)
runChronicle :: Chronicle c a -> These c a
instance Data.Semigroup.Semigroup c => Control.Monad.Chronicle.Class.MonadChronicle c (Data.These.These c)
instance (Data.Semigroup.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 ChronicleT 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 where disclose c = dictate c >> return def

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

-- | disclose c is an action that records the output
--   c and returns a Default value.
--   
--   This is a convenience function for reporting non-fatal errors in one
--   branch a case, 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

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

-- | memento m is an action that executes the action
--   m, returning either its record if it ended with
--   confess, or its final value otherwise, with any record added to
--   the current record.
--   
--   Similar to catchError in the Error 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)

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

-- | condemn m is an action that executes the action
--   m 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

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

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

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

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