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


-- | Haskell 98 comonads
--   
--   Haskell 98 comonads
@package comonad
@version 0.3.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

-- | 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 'default' 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

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

-- | A generalized comonadic list anamorphism
unfoldW :: Comonad w => (w b -> (a, b)) -> w b -> [a]

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

-- | As a symmetric semi-monoidal comonad, an instance of ComonadZip is
--   required to satisfy:
--   
--   <pre>
--   extract (a &lt;.&gt; b) = extract a (extract b)
--   </pre>
--   
--   Minimal definition: <a>&lt;.&gt;</a>
--   
--   Based on the ComonadZip from "The Essence of Dataflow Programming" by
--   Tarmo Uustalu and Varmo Vene, but adapted to fit the programming style
--   of Control.Applicative.
class Comonad w => ComonadZip w
(<.>) :: ComonadZip w => w (a -> b) -> w a -> w b
(.>) :: ComonadZip w => w a -> w b -> w b
(<.) :: ComonadZip w => w a -> w b -> w a

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

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

-- | Lift a ternary function into a comonad with zipping
liftW3 :: ComonadZip 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
instance Monad (Cokleisli w a)
instance Functor (Cokleisli w a)
instance ComonadZip d => ArrowLoop (Cokleisli d)
instance Comonad w => ArrowChoice (Cokleisli w)
instance Comonad w => ArrowApply (Cokleisli w)
instance Comonad w => Category (Cokleisli w)
instance Comonad w => Arrow (Cokleisli w)
instance ComonadZip w => ComonadZip (IdentityT w)
instance ComonadZip Identity
instance Monoid m => ComonadZip ((->) m)
instance Monoid m => ComonadZip ((,) m)
instance Comonad w => Comonad (IdentityT w)
instance Comonad Identity
instance Monoid m => Comonad ((->) m)
instance Comonad ((,) e)