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


-- | Haskell 98 comonads
--   
--   Haskell 98 comonads
@package comonad
@version 0.4.0


-- | A <a>Comonad</a> is the categorical dual of a <a>Monad</a>.
module Control.Comonad

-- | The <a>Functor</a> class is used for types that can be mapped over.
--   Instances of <a>Functor</a> should satisfy the following laws:
--   
--   <pre>
--   fmap id  ==  id
--   fmap (f . g)  ==  fmap f . fmap g
--   </pre>
--   
--   The instances of <a>Functor</a> for lists, <tt>Data.Maybe.Maybe</tt>
--   and <tt>System.IO.IO</tt> satisfy these laws.
class Functor f :: (* -> *)
fmap :: Functor f => (a -> b) -> f a -> f b
(<$) :: Functor f => a -> f b -> f a

-- | An infix synonym for <a>fmap</a>.
(<$>) :: Functor f => (a -> b) -> f a -> f b
($>) :: Functor f => f a -> b -> f b

-- | There are two ways to define a comonad:
--   
--   I. Provide definitions for <a>extract</a> and <a>extend</a> satisfying
--   these laws:
--   
--   <pre>
--   extend extract      = id
--   extract . extend f  = f
--   extend f . extend g = extend (f . extend g)
--   </pre>
--   
--   In this case, you may simply set <a>fmap</a> = <a>liftW</a>.
--   
--   These laws are directly analogous to the laws for monads and perhaps
--   can be made clearer by viewing them as laws stating that Cokleisli
--   composition must be associative, and has extract for a unit:
--   
--   <pre>
--   f =&gt;= extract   = f
--   extract =&gt;= f   = f
--   (f =&gt;= g) =&gt;= h = f =&gt;= (g =&gt;= h)
--   </pre>
--   
--   II. Alternately, you may choose to provide definitions for
--   <a>fmap</a>, <a>extract</a>, and <a>duplicate</a> satisfying these
--   laws:
--   
--   <pre>
--   extract . duplicate      = id
--   fmap extract . duplicate = id
--   duplicate . duplicate    = fmap duplicate . duplicate
--   </pre>
--   
--   In this case you may not rely on the ability to define <a>fmap</a> in
--   terms of <a>liftW</a>.
--   
--   You may of course, choose to define both <a>duplicate</a> <i>and</i>
--   <a>extend</a>. In that case you must also satisfy these laws:
--   
--   <pre>
--   extend f  = fmap f . duplicate
--   duplicate = extend id
--   fmap f    = extend (f . extract)
--   </pre>
--   
--   These are the default definitions of <a>extend</a> and<a>duplicate</a>
--   and the definition of <a>liftW</a> respectively.
class Functor w => Comonad w
extract :: Comonad w => w a -> a
duplicate :: Comonad w => w a -> w (w a)
extend :: Comonad w => (w a -> b) -> w a -> w b

-- | Left-to-right Cokleisli composition
(=>=) :: Comonad w => (w a -> b) -> (w b -> c) -> w a -> c

-- | Right-to-left Cokleisli composition
(=<=) :: Comonad w => (w b -> c) -> (w a -> b) -> w a -> c

-- | <a>extend</a> with the arguments swapped. Dual to <a>&gt;&gt;=</a> for
--   a <a>Monad</a>.
(=>>) :: Comonad w => w a -> (w a -> b) -> w b

-- | <a>extend</a> in operator form
(<<=) :: Comonad w => (w a -> b) -> w a -> w b

-- | A suitable default definition for <a>fmap</a> for a <a>Comonad</a>.
--   Promotes a function to a comonad.
--   
--   <pre>
--   fmap f    = extend (f . extract)
--   </pre>
liftW :: Comonad w => (a -> b) -> w a -> w b

-- | Comonadic fixed point
wfix :: Comonad w => w (w a -> a) -> a

-- | A strong lax symmetric semi-monoidal functor.
class Functor f => FunctorApply f
(<.>) :: FunctorApply f => f (a -> b) -> f a -> f b
(.>) :: FunctorApply f => f a -> f b -> f b
(<.) :: FunctorApply f => f a -> f b -> f a

-- | A variant of <a>&lt;.&gt;</a> with the arguments reversed.
(<..>) :: FunctorApply w => w a -> w (a -> b) -> w b

-- | Lift a binary function into a comonad with zipping
liftF2 :: FunctorApply w => (a -> b -> c) -> w a -> w b -> w c

-- | Lift a ternary function into a comonad with zipping
liftF3 :: FunctorApply w => (a -> b -> c -> d) -> w a -> w b -> w c -> w d

-- | A strong lax symmetric semi-monoidal comonad. As such an instance of
--   <a>ComonadApply</a> is required to satisfy:
--   
--   <pre>
--   extract (a &lt;.&gt; b) = extract a (extract b)
--   </pre>
--   
--   This class is based on ComonadZip from "The Essence of Dataflow
--   Programming" by Tarmo Uustalu and Varmo Vene, but adapted to fit the
--   programming style of Control.Applicative. <a>Applicative</a> can be
--   seen as a similar law over and above FunctorApply that:
--   
--   <pre>
--   pure (a b) = pure a &lt;.&gt; pure b
--   </pre>
class (Comonad w, FunctorApply w) => ComonadApply w

-- | Lift a binary function into a comonad with zipping
liftW2 :: ComonadApply w => (a -> b -> c) -> w a -> w b -> w c

-- | Lift a ternary function into a comonad with zipping
liftW3 :: ComonadApply w => (a -> b -> c -> d) -> w a -> w b -> w c -> w d

-- | The <a>Cokleisli</a> <a>Arrow</a>s of a given <a>Comonad</a>
newtype Cokleisli w a b
Cokleisli :: (w a -> b) -> Cokleisli w a b
runCokleisli :: Cokleisli w a b -> w a -> b

-- | Wrap Applicatives to be used as a member of FunctorApply
newtype WrappedApplicative f a
WrappedApplicative :: f a -> WrappedApplicative f a
unwrapApplicative :: WrappedApplicative f a -> f a

-- | Transform a strong lax symmetric semi-monoidal endofunctor into a
--   strong lax symmetric monoidal endofunctor by adding a unit.
newtype WrappedApply f a
WrapApply :: Either (f a) a -> WrappedApply f a
unwrapApply :: WrappedApply f a -> Either (f a) a
instance Monad (Cokleisli w a)
instance Applicative (Cokleisli w a)
instance FunctorApply (Cokleisli w a)
instance Functor (Cokleisli w a)
instance ComonadApply w => ArrowLoop (Cokleisli w)
instance Comonad w => ArrowChoice (Cokleisli w)
instance Comonad w => ArrowApply (Cokleisli w)
instance Comonad w => Arrow (Cokleisli w)
instance Comonad w => Category (Cokleisli w)
instance ComonadApply w => ComonadApply (IdentityT w)
instance ComonadApply Identity
instance Monoid m => ComonadApply ((->) m)
instance Monoid m => ComonadApply ((,) m)
instance ComonadApply f => ComonadApply (WrappedApply f)
instance Comonad f => Comonad (WrappedApply f)
instance FunctorApply f => Applicative (WrappedApply f)
instance FunctorApply f => FunctorApply (WrappedApply f)
instance Functor f => Functor (WrappedApply f)
instance Applicative f => Applicative (WrappedApplicative f)
instance Applicative f => FunctorApply (WrappedApplicative f)
instance Functor f => Functor (WrappedApplicative f)
instance Arrow a => FunctorApply (WrappedArrow a b)
instance Monoid m => FunctorApply (Const m)
instance Monad m => FunctorApply (WrappedMonad m)
instance FunctorApply w => FunctorApply (IdentityT w)
instance FunctorApply Identity
instance FunctorApply Maybe
instance FunctorApply IO
instance FunctorApply []
instance FunctorApply ZipList
instance Monoid m => FunctorApply ((->) m)
instance Monoid m => FunctorApply ((,) m)
instance Comonad w => Comonad (IdentityT w)
instance Comonad Identity
instance Monoid m => Comonad ((->) m)
instance Comonad ((,) e)