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


-- | Explicit Sharing of Monadic Effects
--   
--   This package implements a monad transformer for sharing monadic
--   effects.
@package explicit-sharing
@version 0.4.0.1


-- | This library provides type classes for explicit sharing of monadic
--   effects. Usually you don't need to import this library as it is
--   reexported by the module <tt>Control.Monad.Sharing</tt>. You may want
--   to do so, however, when writing your own implementation of explicit
--   sharing.
module Control.Monad.Sharing.Classes

-- | Interface of monads that support explicit sharing.
class Sharing m
share :: (Sharing m, Trans m a a) => m a -> m (m a)

-- | Interface to transform nested monadic data types. The provided
--   function <a>trans</a> is supposed to map the given function on every
--   monadic argument. The result of <a>trans</a> may be of the same type
--   as the argument but can also be of a different type, e.g. to convert a
--   value with nested monadic arguments to a corresponding value without.
--   
--   We provide instances of the <a>Trans</a> class for some predefined
--   Haskell types. For flat types the function <a>trans</a> just returns
--   its argument which has no arguments to which the given function could
--   be applied.
class Trans m a b
trans :: (Trans m a b) => (forall c d. (Trans m c d) => m c -> m (m d)) -> a -> m b

-- | Lifts all monadic effects in nested monadic values to the top level.
--   If <tt>m</tt> is a monad for non-determinism and the argument a data
--   structure with nested non-determinism then the result corresponds to
--   the normal form of the argument.
eval :: (Monad m, Trans m a b) => a -> m b
instance (Monad m, Trans m a a) => Trans m [m a] [a]
instance (Monad m, Trans m a a) => Trans m [m a] [m a]
instance (Monad m) => Trans m [Double] [Double]
instance (Monad m) => Trans m [Float] [Float]
instance (Monad m) => Trans m [Char] [Char]
instance (Monad m) => Trans m [Int] [Int]
instance (Monad m) => Trans m [Bool] [Bool]
instance (Monad m) => Trans m Double Double
instance (Monad m) => Trans m Float Float
instance (Monad m) => Trans m Char Char
instance (Monad m) => Trans m Int Int
instance (Monad m) => Trans m Bool Bool


-- | This library provides lists with monadic head and tail as an example
--   for nested monadic data that can be used with the combinator
--   <tt>share</tt> for explicit sharing.
module Data.Monadic.List

-- | Data type for lists where both the head and tail are monadic.
data List m a
Nil :: List m a
Cons :: (m a) -> (m (List m a)) -> List m a

-- | The empty monadic list.
nil :: (Monad m) => m (List m a)

-- | Constructs a non-empty monadic list.
cons :: (Monad m) => m a -> m (List m a) -> m (List m a)

-- | Checks if monadic list is empty.
isEmpty :: (Monad m) => m (List m a) -> m Bool

-- | Yields the head of a monadic list. Relies on <a>MonadPlus</a> instance
--   to provide a failing implementation of <a>fail</a>.
first :: (MonadPlus m) => m (List m a) -> m a

-- | Yields the tail of a monadic list. Relies on <a>MonadPlus</a> instance
--   to provide a failing implementation of <a>fail</a>.
rest :: (MonadPlus m) => m (List m a) -> m (List m a)
instance (Monad m, Trans m a b) => Trans m [a] (List m b)
instance (Monad m, Trans m a b) => Trans m (List m a) [b]
instance (Monad m, Trans m a b) => Trans m (List m a) (List m b)


-- | This library provides an interface to monads that support explicit
--   sharing. A project website with tutorials can be found at
--   <a>http://sebfisch.github.com/explicit-sharing</a>.
module Control.Monad.Sharing

-- | Interface of monads that support explicit sharing.
class Sharing m
share :: (Sharing m, Trans m a a) => m a -> m (m a)

-- | Interface to transform nested monadic data types. The provided
--   function <a>trans</a> is supposed to map the given function on every
--   monadic argument. The result of <a>trans</a> may be of the same type
--   as the argument but can also be of a different type, e.g. to convert a
--   value with nested monadic arguments to a corresponding value without.
--   
--   We provide instances of the <a>Trans</a> class for some predefined
--   Haskell types. For flat types the function <a>trans</a> just returns
--   its argument which has no arguments to which the given function could
--   be applied.
class Trans m a b
trans :: (Trans m a b) => (forall c d. (Trans m c d) => m c -> m (m d)) -> a -> m b

-- | Lifts all monadic effects in nested monadic values to the top level.
--   If <tt>m</tt> is a monad for non-determinism and the argument a data
--   structure with nested non-determinism then the result corresponds to
--   the normal form of the argument.
eval :: (Monad m, Trans m a b) => a -> m b

-- | Continuation-based, store-passing implementation of explicit sharing.
--   It is an inlined version of <tt>ContT (ReaderT Store m)</tt> where the
--   result type of continuations is polymorphic.
data Lazy m a

-- | Lifts all monadic effects to the top-level and unwraps the monad
--   transformer for explicit sharing.
evalLazy :: (Monad m, Trans (Lazy m) a b) => Lazy m a -> m b