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


-- | Automatic deriving of monadic data types and corresponding instances.
module Data.Monadic.Derive

-- | Derives monadic datatypes and instances for explicit sharing as well
--   as conversion. Combines the other three derivations which provide the
--   same functionality split into different parts.
--   
--   You usually need the following preamble when deriving monadic code:
--   
--   <pre>
--   {-# LANGUAGE TemplateHaskell
--     , KindSignatures
--     , MultiParamTypeClasses
--     , FlexibleInstances
--     #-}
--   import Control.Monad.Sharing
--   import Data.Monadic.Derive
--   import Data.DeriveTH
--   </pre>
--   
--   If your types contain lists, you also need to
--   
--   <pre>
--   import Data.Monadic.List
--   </pre>
--   
--   With this prerequisites, you can derive a monadic <a>Maybe</a> type by
--   
--   <pre>
--   $(derive monadic ''Maybe)
--   </pre>
monadic :: Derivation

-- | Generates a monadic datatype and corresponding con- and destructor
--   functions from a Haskell datatype.
--   
--   For example, the datatype
--   
--   <pre>
--   data Maybe a = Nothing | Just a
--   </pre>
--   
--   can be translated into its monadic counterpart by typing
--   
--   <pre>
--   $(derive makeMData ''Maybe)
--   </pre>
--   
--   This call generates the following datatype
--   
--   <pre>
--   data MMaybe m a = MNothing | MJust (m a)
--   </pre>
--   
--   and the following auxiliary functions for constructing and matching
--   monadic values:
--   
--   <pre>
--   mNothing :: Monad m =&gt; m (MMaybe m a)
--   mNothing = return MNothing
--   </pre>
--   
--   <pre>
--   mJust :: Monad m =&gt; m a -&gt; m (MMaybe m a)
--   mJust a = return (MJust a)
--   </pre>
--   
--   <pre>
--   matchMMaybe :: Monad m =&gt; m (MMaybe m a) -&gt; m b -&gt; (m a -&gt; m b) -&gt; m b
--   matchMMaybe x n j = x &gt;&gt;= \x -&gt; case x of { MNothing -&gt; n; MJust a -&gt; j a }
--   </pre>
makeMData :: Derivation

-- | Generates a <tt>Shareable</tt> instance for a monadic datatype.
--   
--   For example the call
--   
--   <pre>
--   $(derive makeShareable ''Maybe)
--   </pre>
--   
--   generates the following instance:
--   
--   <pre>
--   instance (Monad m, Shareable m a) =&gt; Shareable (Maybe m a) where
--     shareArgs fun MNothing  = return MNothing
--     shareArgs fun (MJust a) = fun a &gt;&gt;= \a -&gt; mJust a
--   </pre>
makeShareable :: Derivation

-- | Generates <tt>Convertible</tt> instances to convert between monadic
--   and non-monadic datatypes.
--   
--   For example, the call
--   
--   <pre>
--   $(derive makeConvertible ''Maybe)
--   </pre>
--   
--   generates the following instances:
--   
--   <pre>
--   instance (Monad m, Convertible m a a')
--         =&gt; Convertible m (Maybe a) (MMaybe m a') where
--     convArgs fun Nothing  = mNothing
--     convArgs fun (Just a) = mJust (fun a)
--   
--   instance (Monad m, Convertible m a' a)
--         =&gt; Convertible m (MMaybe m a') (Maybe a) where
--     convArgs fun MNothing  = return Nothing
--     convArgs fun (MJust a) = (a &gt;&gt;= fun) &gt;&gt;= \a -&gt; return (Just a)
--   </pre>
makeConvertible :: Derivation


-- | 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, Shareable m a) => m a -> m (m a)

-- | Interface of shareable nested monadic data types. The provided
--   function <a>shareArgs</a> is supposed to map the given function on
--   every monadic argument.
--   
--   We provide instances of the <a>Shareable</a> class for some predefined
--   Haskell types. For flat types the function <a>shareArgs</a> just
--   returns its argument which has no arguments to which the given
--   function could be applied.
class Shareable m a
shareArgs :: (Shareable m a, Monad n) => (forall b. (Shareable m b) => m b -> n (m b)) -> a -> n a

-- | Interface for convertible datatypes. The provided function
--   <a>convArgs</a> is supposed to map the given function on every
--   argument of the given value and combine the results to give the
--   converted value.
--   
--   We provide instances of the <a>Convertible</a> class for some
--   predefined Haskell types. For flat types the function <a>convArgs</a>
--   just returns its argument which has no arguments to which the given
--   function could be applied.
class Convertible m a b
convArgs :: (Convertible m a b) => (forall c d. (Convertible m c d) => c -> m d) -> a -> m b

-- | Converts a convertible value recursively.
convert :: (Convertible m a b) => a -> m b
type MInt m = Int
type MChar m = Char
type MBool m = Bool
instance (Monad m, Convertible m a b) => Convertible m [m a] [b]
instance (Monad m, Convertible m a b) => Convertible m [a] [m b]
instance (Monad m) => Convertible m [Char] [Char]
instance (Monad m) => Convertible m [Int] [Int]
instance (Monad m) => Convertible m [Bool] [Bool]
instance (Monad m) => Convertible m Char Char
instance (Monad m) => Convertible m Int Int
instance (Monad m) => Convertible m Bool Bool
instance (Monad m, Shareable m a) => Shareable m [m a]
instance (Monad m) => Shareable m (a -> b)
instance (Monad m) => Shareable m [Char]
instance (Monad m) => Shareable m [Int]
instance (Monad m) => Shareable m [Bool]
instance (Monad m) => Shareable m Char
instance (Monad m) => Shareable m Int
instance (Monad m) => Shareable m Bool


-- | This library provides an interface to monads that support explicit
--   sharing based on two-level types. This implementation is not as
--   efficient as the default implementation but supports a restricted form
--   of sharing across non-determinism if a first-order data type is used
--   as underlying monad.
module Control.Monad.Sharing.FirstOrder

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

-- | Interface of shareable nested monadic data types. The provided
--   function <a>shareArgs</a> is supposed to map the given function on
--   every monadic argument.
--   
--   We provide instances of the <a>Shareable</a> class for some predefined
--   Haskell types. For flat types the function <a>shareArgs</a> just
--   returns its argument which has no arguments to which the given
--   function could be applied.
class Shareable m a
shareArgs :: (Shareable m a, Monad n) => (forall b. (Shareable m b) => m b -> n (m b)) -> a -> n a

-- | Interface for convertible datatypes. The provided function
--   <a>convArgs</a> is supposed to map the given function on every
--   argument of the given value and combine the results to give the
--   converted value.
--   
--   We provide instances of the <a>Convertible</a> class for some
--   predefined Haskell types. For flat types the function <a>convArgs</a>
--   just returns its argument which has no arguments to which the given
--   function could be applied.
class Convertible m a b
convArgs :: (Convertible m a b) => (forall c d. (Convertible m c d) => c -> m d) -> a -> m b

-- | Converts a convertible value recursively.
convert :: (Convertible m a b) => a -> m b

-- | Monad transformer that adds explicit sharing capability to every
--   monad.
data Lazy m a

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


-- | 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, Convertible m a b) => Convertible m (List m a) [b]
instance (Monad m, Convertible m a b) => Convertible m [a] (List m b)
instance (Monad m, Shareable m a) => Shareable m (List m a)


-- | 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, Shareable m a) => m a -> m (m a)

-- | Interface of shareable nested monadic data types. The provided
--   function <a>shareArgs</a> is supposed to map the given function on
--   every monadic argument.
--   
--   We provide instances of the <a>Shareable</a> class for some predefined
--   Haskell types. For flat types the function <a>shareArgs</a> just
--   returns its argument which has no arguments to which the given
--   function could be applied.
class Shareable m a
shareArgs :: (Shareable m a, Monad n) => (forall b. (Shareable m b) => m b -> n (m b)) -> a -> n a

-- | Interface for convertible datatypes. The provided function
--   <a>convArgs</a> is supposed to map the given function on every
--   argument of the given value and combine the results to give the
--   converted value.
--   
--   We provide instances of the <a>Convertible</a> class for some
--   predefined Haskell types. For flat types the function <a>convArgs</a>
--   just returns its argument which has no arguments to which the given
--   function could be applied.
class Convertible m a b
convArgs :: (Convertible m a b) => (forall c d. (Convertible m c d) => c -> m d) -> a -> m b

-- | Converts a convertible value recursively.
convert :: (Convertible 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, Convertible (Lazy m) a b) => Lazy m a -> m b