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


-- | The <a>These</a> type and associated operations. Now enhanced with
--   <tt>Control.Lens</tt> magic!
module Data.These

-- | The <a>These</a> 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
--   <tt>These A B</tt> represents <tt>(A + B + AB)</tt>, which doesn't
--   factor easily into sums and products--a type like <tt>Either A (B,
--   Maybe A)</tt> is unclear and awkward to use.
--   
--   <a>These</a> has straightforward instances of <a>Functor</a>,
--   <a>Monad</a>, &amp;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 <a>These</a> 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 <tt>Traversal</tt> of the first half of a <a>These</a>, suitable for
--   use with <tt>Control.Lens</tt>.
here :: (Applicative f) => (a -> f b) -> These a t -> f (These b t)

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

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

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

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

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

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

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

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

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

-- | Select all <a>These</a> 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]))

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

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

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

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

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

-- | <pre>
--   <a>mapThat</a> = over <a>there</a>
--   </pre>
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)


-- | <a>These</a>-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 <tt>Kleisli Maybe</tt> to
--   <tt>Hask</tt> (so it supports <tt>maybeMap :: (a -&gt; Maybe b) -&gt;
--   f a -&gt; f b</tt>), then an <tt>Align</tt> instance is making your
--   functor lax monoidal w.r.t. the cartesian monoidal structure on
--   <tt>Kleisli Maybe</tt>, because <tt>These</tt> is the cartesian
--   product in that category <tt>(a -&gt; Maybe (These b c) ~ (a -&gt;
--   Maybe b, a -&gt; Maybe c))</tt>. This insight is due to rwbarton.
--   
--   Minimal definition: <tt>nil</tt> and either <tt>align</tt> or
--   <tt>alignWith</tt>.
--   
--   Laws:
--   
--   <pre>
--   (`align` nil) = fmap This
--   (nil `align`) = fmap That
--   join align = fmap (join These)
--   align (f &lt;$&gt; x) (g &lt;$&gt; y) = bimap f g &lt;$&gt; align x y
--   alignWith f a b = f &lt;$&gt; align a b
--   </pre>
class (Functor f) => Align f where align = alignWith id alignWith f a b = f <$> align a b

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

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

-- | Analogous to <tt><a>zipWith</a></tt>, 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 <a>mappend</a>.
malign :: (Align f, Monoid a) => f a -> f a -> f a

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

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

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

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

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

-- | Right-padded <a>zipWith</a>.
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 <a>align</a>: 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:
--   
--   <pre>
--   unalign nil                 = (nil,           nil)
--   unalign (This        &lt;$&gt; x) = (Just    &lt;$&gt; x, Nothing &lt;$  x)
--   unalign (That        &lt;$&gt; y) = (Nothing &lt;$  y, Just    &lt;$&gt; y)
--   unalign (join These  &lt;$&gt; x) = (Just    &lt;$&gt; x, Just    &lt;$&gt; x)
--   unalign ((x `These`) &lt;$&gt; y) = (Just x  &lt;$  y, Just    &lt;$&gt; y)
--   unalign ((`These` y) &lt;$&gt; x) = (Just    &lt;$&gt; x, Just y  &lt;$  x)
--   </pre>
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: <tt>crosswalk</tt> or <tt>sequenceL</tt>.
--   
--   Laws:
--   
--   <pre>
--   crosswalk (const nil) = const nil
--   crosswalk f = sequenceL . fmap f
--   </pre>
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: <tt>bicrosswalk</tt> or <tt>bisequenceL</tt>.
--   
--   Laws:
--   
--   <pre>
--   bicrosswalk (const empty) (const empty) = const empty
--   bicrosswalk f g = bisequenceL . bimap f g
--   </pre>
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


-- | <a>These</a>-based zipping and unzipping of indexed functors.
module Data.Align.Key

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

-- | Analogous to <tt><a>alignWith</a></tt>, 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 <tt>c</tt>.
--   
--   The <a>return</a> function produces a computation with no output, and
--   <a>&gt;&gt;=</a> combines multiple outputs with <a>mappend</a>.
type Chronicle c = ChronicleT c Identity
chronicle :: These c a -> Chronicle c 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>mappend</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 (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

-- | <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 'These c a' value into a
--   <a>MonadChronicle</a> instance.
chronicle :: MonadChronicle c m => These c a -> m 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>mappend</a>.
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 <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 where disclose c = dictate c >> return def

-- | <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 'These c a' 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>mappend</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>mappend</a>.
newtype ChronicleT c m a
ChronicleT :: m (These c a) -> ChronicleT c m a
[runChronicleT] :: ChronicleT c m a -> m (These c a)