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


-- | Comonad transformers
--   
--   Comonad transformers
@package comonad-transformers
@version 3.1

module Data.Functor.Composition

-- | We often need to distinguish between various forms of Functor-like
--   composition in Haskell in order to please the type system. This lets
--   us work with these representations uniformly.
class Composition o
decompose :: Composition o => o f g x -> f (g x)
compose :: Composition o => f (g x) -> o f g x
instance Composition Compose


module Data.Functor.Coproduct
newtype Coproduct f g a
Coproduct :: Either (f a) (g a) -> Coproduct f g a
getCoproduct :: Coproduct f g a -> Either (f a) (g a)
left :: f a -> Coproduct f g a
right :: g a -> Coproduct f g a
coproduct :: (f a -> b) -> (g a -> b) -> Coproduct f g a -> b
instance (Eq (f a), Eq (g a)) => Eq (Coproduct f g a)
instance (Ord (f a), Ord (g a)) => Ord (Coproduct f g a)
instance (Read (f a), Read (g a)) => Read (Coproduct f g a)
instance (Show (f a), Show (g a)) => Show (Coproduct f g a)
instance (Contravariant f, Contravariant g) => Contravariant (Coproduct f g)
instance (Comonad f, Comonad g) => Comonad (Coproduct f g)
instance (Extend f, Extend g) => Extend (Coproduct f g)
instance (Traversable1 f, Traversable1 g) => Traversable1 (Coproduct f g)
instance (Traversable f, Traversable g) => Traversable (Coproduct f g)
instance (Foldable1 f, Foldable1 g) => Foldable1 (Coproduct f g)
instance (Foldable f, Foldable g) => Foldable (Coproduct f g)
instance (Functor f, Functor g) => Functor (Coproduct f g)


module Control.Comonad.Trans.Identity

-- | The trivial monad transformer, which maps a monad to an equivalent
--   monad.
newtype IdentityT (m :: * -> *) a :: (* -> *) -> * -> *
IdentityT :: m a -> IdentityT a
runIdentityT :: IdentityT a -> m a


module Control.Comonad.Trans.Class
class ComonadTrans t
lower :: (ComonadTrans t, Comonad w) => t w a -> w a
instance ComonadTrans IdentityT


module Control.Comonad.Hoist.Class
class ComonadHoist t
cohoist :: (ComonadHoist t, Comonad w) => t w a -> t Identity a
instance ComonadHoist IdentityT


-- | The environment comonad holds a value along with some retrievable
--   context.
--   
--   This module specifies the environment comonad transformer (aka
--   coreader), which is left adjoint to the reader comonad.
--   
--   The following sets up an experiment that retains its initial value in
--   the background:
--   
--   <pre>
--   &gt;&gt;&gt; let initial = env 0 0
--   </pre>
--   
--   Extract simply retrieves the value:
--   
--   <pre>
--   &gt;&gt;&gt; extract initial
--   0
--   </pre>
--   
--   Play around with the value, in our case producing a negative value:
--   
--   <pre>
--   &gt;&gt;&gt; let experiment = fmap (+ 10) initial
--   
--   &gt;&gt;&gt; extract experiment
--   10
--   </pre>
--   
--   Oh noes, something went wrong, 10 isn't very negative! Better restore
--   the initial value using the default:
--   
--   <pre>
--   &gt;&gt;&gt; let initialRestored = experiment =&gt;&gt; ask
--   
--   &gt;&gt;&gt; extract initialRestored
--   0
--   </pre>
module Control.Comonad.Trans.Env
type Env e = EnvT e Identity

-- | Create an Env using an environment and a value
env :: e -> a -> Env e a
runEnv :: Env e a -> (e, a)
data EnvT e w a
EnvT :: e -> (w a) -> EnvT e w a
runEnvT :: EnvT e w a -> (e, w a)

-- | Gets rid of the environment. This differs from <a>extract</a> in that
--   it will not continue extracting the value from the contained comonad.
lowerEnvT :: EnvT e w a -> w a

-- | Retrieves the environment.
ask :: EnvT e w a -> e

-- | Like <a>ask</a>, but modifies the resulting value with a function.
--   
--   <pre>
--   asks = f . ask
--   </pre>
asks :: (e -> f) -> EnvT e w a -> f

-- | Modifies the environment using the specified function.
local :: (e -> e') -> EnvT e w a -> EnvT e' w a
instance Traversable w => Traversable (EnvT e w)
instance Foldable w => Foldable (EnvT e w)
instance (Semigroup e, ComonadApply w) => ComonadApply (EnvT e w)
instance (Semigroup e, Apply w) => Apply (EnvT e w)
instance ComonadHoist (EnvT e)
instance ComonadTrans (EnvT e)
instance Comonad w => Comonad (EnvT e w)
instance Extend w => Extend (EnvT e w)
instance Functor w => Functor (EnvT e w)
instance (Data e, Typeable1 w, Data (w a), Data a) => Data (EnvT e w a)
instance (Typeable s, Typeable1 w, Typeable a) => Typeable (EnvT s w a)
instance (Typeable s, Typeable1 w) => Typeable1 (EnvT s w)


-- | The store comonad holds a constant value along with a modifiable
--   <i>accessor</i> function, which maps the <i>stored value</i> to the
--   <i>focus</i>.
--   
--   This module defines the strict store (aka state-in-context/costate)
--   comonad transformer.
--   
--   <tt>stored value = (1, 5)</tt>, <tt>accessor = fst</tt>, <tt>resulting
--   focus = 1</tt>:
--   
--   <pre>
--   storeTuple :: Store (Int, Int) Int
--   storeTuple = store fst (1, 5)
--   </pre>
--   
--   Add something to the focus:
--   
--   <pre>
--   addToFocus :: Int -&gt; Store (Int, Int) Int -&gt; Int
--   addToFocus x wa = x + extract wa
--   
--   added3 :: Store (Int, Int) Int
--   added3 = extend (addToFocus 3) storeTuple
--   </pre>
--   
--   The focus of added3 is now <tt>1 + 3 = 4</tt>. However, this action
--   changed only the accessor function and therefore the focus but not the
--   stored value:
--   
--   <pre>
--   &gt;&gt;&gt; pos added3
--   (1, 5)
--   
--   &gt;&gt;&gt; extract added3
--   4
--   </pre>
--   
--   The strict store (state-in-context/costate) comonad transformer is
--   subject to the laws:
--   
--   <pre>
--   x = seek (pos x) x
--   y = pos (seek y x)
--   seek y x = seek y (seek z x)
--   </pre>
--   
--   Thanks go to Russell O'Connor and Daniel Peebles for their help
--   formulating and proving the laws for this comonad transformer.
module Control.Comonad.Trans.Store
type Store s = StoreT s Identity

-- | Create a Store using an accessor function and a stored value
store :: (s -> a) -> s -> Store s a
runStore :: Store s a -> (s -> a, s)
data StoreT s w a
StoreT :: (w (s -> a)) -> s -> StoreT s w a
runStoreT :: StoreT s w a -> (w (s -> a), s)

-- | Read the stored value
--   
--   <pre>
--   &gt;&gt;&gt; pos $ store fst (1,5)
--   (1,5)
--   </pre>
pos :: StoreT s w a -> s

-- | Set the stored value
--   
--   <pre>
--   &gt;&gt;&gt; pos . seek (3,7) $ store fst (1,5)
--   (3,7)
--   </pre>
--   
--   Seek satisfies the law
--   
--   <pre>
--   seek s = peek s . duplicate
--   </pre>
seek :: s -> StoreT s w a -> StoreT s w a

-- | Modify the stored value
--   
--   <pre>
--   &gt;&gt;&gt; pos . seeks swap $ store fst (1,5)
--   (5,1)
--   </pre>
--   
--   Seeks satisfies the law
--   
--   <pre>
--   seeks f = peeks f . duplicate
--   </pre>
seeks :: (s -> s) -> StoreT s w a -> StoreT s w a

-- | Peek at what the current focus would be for a different stored value
--   
--   Peek satisfies the law
--   
--   <pre>
--   peek x . extend (peek y) = peek y
--   </pre>
peek :: Comonad w => s -> StoreT s w a -> a

-- | Peek at what the current focus would be if the stored value was
--   modified by some function
peeks :: Comonad w => (s -> s) -> StoreT s w a -> a

-- | Applies a functor-valued function to the stored value, and then uses
--   the new accessor to read the resulting focus.
--   
--   <pre>
--   &gt;&gt;&gt; let f x = if x &gt; 0 then Just (x^2) else Nothing
--   
--   &gt;&gt;&gt; experiment f $ store (+1) 2
--   Just 5
--   
--   &gt;&gt;&gt; experiment f $ store (+1) (-2)
--   Nothing
--   </pre>
experiment :: (Comonad w, Functor f) => (s -> f s) -> StoreT s w a -> f a
instance ComonadHoist (StoreT s)
instance ComonadTrans (StoreT s)
instance Comonad w => Comonad (StoreT s w)
instance Extend w => Extend (StoreT s w)
instance (Applicative w, Monoid s) => Applicative (StoreT s w)
instance (ComonadApply w, Semigroup s) => ComonadApply (StoreT s w)
instance (Apply w, Semigroup s) => Apply (StoreT s w)
instance Functor w => Functor (StoreT s w)
instance (Typeable s, Typeable1 w, Typeable a) => Typeable (StoreT s w a)
instance (Typeable s, Typeable1 w) => Typeable1 (StoreT s w)


-- | The trace comonad builds up a result by prepending monoidal values to
--   each other.
--   
--   This module specifies the traced comonad transformer (aka the cowriter
--   or exponential comonad transformer).
module Control.Comonad.Trans.Traced
type Traced m = TracedT m Identity
traced :: (m -> a) -> Traced m a
runTraced :: Traced m a -> m -> a
newtype TracedT m w a
TracedT :: w (m -> a) -> TracedT m w a
runTracedT :: TracedT m w a -> w (m -> a)
trace :: Comonad w => m -> TracedT m w a -> a
listen :: Functor w => TracedT m w a -> TracedT m w (a, m)
listens :: Functor w => (m -> b) -> TracedT m w a -> TracedT m w (a, b)
censor :: Functor w => (m -> m) -> TracedT m w a -> TracedT m w a
instance (Typeable s, Typeable1 w) => Typeable1 (TracedT s w)
instance Distributive w => Distributive (TracedT m w)
instance Monoid m => ComonadHoist (TracedT m)
instance Monoid m => ComonadTrans (TracedT m)
instance (Comonad w, Monoid m) => Comonad (TracedT m w)
instance (Extend w, Semigroup m) => Extend (TracedT m w)
instance Applicative w => Applicative (TracedT m w)
instance (ComonadApply w, Monoid m) => ComonadApply (TracedT m w)
instance Apply w => Apply (TracedT m w)
instance Functor w => Functor (TracedT m w)