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


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


-- | 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>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>
--   
--   II. 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>
--   
--   (<a>fmap</a> cannot be defaulted, but a comonad which defines
--   <a>extend</a> may simply set <a>fmap</a> equal to <a>liftW</a>.)
--   
--   A comonad providing definitions for <a>extend</a> <i>and</i>
--   <a>duplicate</a>, must also satisfy these laws:
--   
--   <pre>
--   extend f  == fmap f . duplicate
--   duplicate == extend id
--   fmap f    == extend (f . extract)
--   </pre>
--   
--   (The first two are the defaults for <a>extend</a> and
--   <a>duplicate</a>, and the third is the definition of <a>liftW</a>.)
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

-- | As a symmetric semi-monoidal comonad, an instance of ComonadZip is
--   required to satisfy:
--   
--   <pre>
--   extract (wzip a b) = (extract a, extract b)
--   </pre>
--   
--   By extension, the following law must also hold:
--   
--   <pre>
--   extract (a &lt;.&gt; b) = extract a (extract b)
--   </pre>
--   
--   Minimum definition: <a>&lt;.&gt;</a>
--   
--   Based on the ComonadZip from <a>The Essence of Dataflow
--   Programming</a> by Tarmo Uustalu and Varmo Vene, but adapted to fit
--   the conventions of Control.Monad and to provide a similar programming
--   style to that 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

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

-- | 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
(<..>) :: ComonadZip w => w a -> w (a -> b) -> 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
liftW2 :: ComonadZip w => (a -> b -> c) -> w a -> w b -> w c
liftW3 :: ComonadZip w => (a -> b -> c -> d) -> w a -> w b -> w c -> w d

-- | <pre>
--   wzip wa wb = (,) &lt;$&gt; wa &lt;.&gt; wb
--   wzip = liftW2 (,) 
--   </pre>
--   
--   Called <tt>czip</tt> in <a>Essence of Dataflow Programming</a>
wzip :: ComonadZip w => w a -> w 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)