-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | An either-or-both data type, with corresponding hybrid error/writer monad transformer. -- -- An either-or-both data type, with corresponding hybrid error/writer -- monad transformer. @package these @version 0.2 -- | 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 -- | 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 (Eq a, Eq b) => Eq (These a b) instance (Ord a, Ord b) => Ord (These a b) instance (Read a, Read b) => Read (These a b) instance (Show a, Show b) => Show (These a b) instance Monoid a => Monad (These a) instance Monoid a => Bind (These a) instance Monoid a => Applicative (These a) instance Monoid a => Apply (These a) instance Bitraversable1 These instance Bitraversable These instance Bifoldable1 These instance Bifoldable These instance Bifunctor These instance Traversable (These a) instance Foldable (These a) instance Functor (These a) instance (Semigroup a, Semigroup b) => Semigroup (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 nil :: Align f => f a align :: Align f => f a -> f b -> f (These a b) alignWith :: Align f => (These a b -> c) -> f a -> f b -> f c -- | Align two structures and combine with mappend. malign :: (Align f, Monoid 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] -- | 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) alignVectorWith :: (Vector v a, Vector v b, Vector v c) => (These a b -> c) -> v a -> v b -> v c instance Bicrosswalk These instance Bicrosswalk Either instance Crosswalk (These a) instance Crosswalk [] instance Crosswalk Maybe instance Crosswalk Identity instance Monad m => Unalign (Stream m) instance (Unalign f, Unalign g) => Unalign (Product f g) instance Unalign ZipList instance Unalign [] instance Unalign Maybe instance Monad m => Align (Stream m) instance (Align f, Align g) => Align (Product f g) instance Align IntMap instance Ord k => Align (Map k) instance Align Seq instance Align ZipList instance Align [] instance Align Maybe -- | The ChronicleT monad, a hybrid error/writer monad that allows -- both accumulating outputs and aborting computation with a final -- output. 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 :: (Monoid c, Monad m) => c -> ChronicleT c m () -- | confess c is an action that ends with a final output -- c. -- -- Equivalent to throwError for the Error monad. confess :: (Monoid 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 :: (Monoid 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 :: (Monoid 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 :: (Monoid 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 :: (Monoid c, Monad m) => (c -> c) -> ChronicleT c m a -> ChronicleT c m a instance (Monoid c, MonadWriter w m) => MonadWriter w (ChronicleT c m) instance (Monoid c, MonadState s m) => MonadState s (ChronicleT c m) instance (Monoid c, MonadRWS r w s m) => MonadRWS r w s (ChronicleT c m) instance (Monoid c, MonadReader r m) => MonadReader r (ChronicleT c m) instance (Monoid c, MonadError e m) => MonadError e (ChronicleT c m) instance (Monoid c, Monad m) => MonadPlus (ChronicleT c m) instance (Monoid c, Applicative m, Monad m) => Alternative (ChronicleT c m) instance (Monoid c, MonadIO m) => MonadIO (ChronicleT c m) instance Monoid c => MonadTrans (ChronicleT c) instance (Monoid c, Monad m) => Monad (ChronicleT c m) instance (Monoid c, Apply m, Monad m) => Bind (ChronicleT c m) instance (Monoid c, Applicative m) => Applicative (ChronicleT c m) instance (Monoid c, Apply m) => Apply (ChronicleT c m) instance Functor m => Functor (ChronicleT c m) module Control.Monad.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 :: (Monoid c, Monad m) => c -> ChronicleT c m () -- | confess c is an action that ends with a final output -- c. -- -- Equivalent to throwError for the Error monad. confess :: (Monoid 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 :: (Monoid 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 :: (Monoid 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 :: (Monoid 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 :: (Monoid c, Monad m) => (c -> c) -> ChronicleT c m a -> ChronicleT c m a -- | 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 dictate :: MonadChronicle c m => c -> m () confess :: MonadChronicle c m => c -> m a memento :: MonadChronicle c m => m a -> m (Either c a) absolve :: MonadChronicle c m => a -> m a -> m a condemn :: MonadChronicle c m => m a -> m a retcon :: MonadChronicle c m => (c -> c) -> m a -> m a chronicle :: MonadChronicle c m => These c a -> m a instance (Monoid w, MonadChronicle c m) => MonadChronicle c (WriterT w m) instance (Monoid w, MonadChronicle c m) => MonadChronicle c (WriterT w m) instance (Monoid s, MonadChronicle c m) => MonadChronicle c (StateT s m) instance (Monoid s, MonadChronicle c m) => MonadChronicle c (StateT s m) instance MonadChronicle c m => MonadChronicle c (ReaderT r m) instance (Error e, MonadChronicle c m) => MonadChronicle c (ErrorT e m) instance MonadChronicle c m => MonadChronicle c (MaybeT m) instance MonadChronicle c m => MonadChronicle c (IdentityT m) instance (Monoid c, Monad m) => MonadChronicle c (ChronicleT c m) instance Monoid c => MonadChronicle c (These c)