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


-- | A library for writing extensible algebraic effects and handlers. Similar to extensible-effects but with deep handlers.
--   
--   This is an extensible effects library for Haskell taking inspiration
--   from the Eff language <a>http://www.eff-lang.org/</a>.
--   
--   See these papers for the ideas and theory behind the library:
--   
--   <ul>
--   <li>O. Kammar et al: Handlers in Action!
--   <a>http://homepages.inf.ed.ac.uk/slindley/papers/handlers.pdf</a></li>
--   <li>A. Bauer, M. Pretnar: Programming with Algebraic Effects and
--   Handlers <a>http://arxiv.org/abs/1203.1539</a></li>
--   <li>O Kiselyov, A Sabry, C Swords: Extensible Effects
--   <a>http://dl.acm.org/citation.cfm?id=2503791</a></li>
--   </ul>
--   
--   Implementation wise it's most close to <tt>extensible-effects</tt>
--   <a>http://hackage.haskell.org/package/extensible-effects</a> (also see
--   the Extensible Effects paper) but it implements deep handlers instead
--   of shallow.
--   
--   <pre>
--   import Control.Effects.Cont.Eff
--   import Control.Effects.Cont.Reader
--   import Control.Effects.Cont.Exception
--   
--   program = do
--     v &lt;- ask
--     if v &lt; 15
--     then throw $ show v
--     else return (v+1)
--   
--   run n = runPure . handle exceptionHandler . handle (readerHandler n)
--   
--   res :: Integer -&gt; Either String Integer
--   res n = run n program
--   </pre>
@package effect-handlers
@version 0.1.0.8


-- | This module provides an open union of functors.
module Data.Union

-- | <a>Union</a> is an open sum of functors A value of type <a>Union</a> r
--   a is a value f a for some f that is a member of the r list Since
--   direct construction is not safe you have to use <a>inj</a> to create a
--   value.
data Union (r :: [* -> *]) (a :: *)

-- | The <a>Member</a> type clas denotes that f is a member of type list r
class Member (f :: * -> *) (r :: [* -> *])

-- | Smart constructor for <a>Union</a>. Injects the functor into any union
--   of which the said functor is a member. Please note that only the type
--   constructor need be a <a>Typeable</a>.
inj :: (Typeable f, Functor f, Member f r) => f a -> Union r a

-- | Project a <a>Union</a> into a specific functor.
prj :: (Typeable f, Member f r) => Union r a -> Maybe (f a)

-- | Decompose a <a>Union</a>. Similar to <a>prj</a> but gives you a
--   <a>Union</a> instance without the functor f in type if projection
--   fails.
decomp :: (Typeable f) => Union (f : r) a -> Either (f a) (Union r a)

-- | A <a>Union</a> of one functor can only be that. Safe cast.
trivial :: (Typeable f) => Union '[f] a -> f a
instance GHC.Base.Functor (Data.Union.Union r)
instance Data.Union.Member h (h : t)
instance Data.Union.Member x t => Data.Union.Member x (h : t)


-- | This implementation of the effect monad uses <a>Free</a> over a
--   <a>Union</a> of functors and then applies <a>Codensity</a> over it for
--   asymptotic improvements of ill-associated binds.
module Control.Effects.Eff
data Eff r a

-- | Handler is a function that takes a result or an effect and a
--   continuation |and handles it.
--   
--   <tt>e</tt> is the effect functor you are handling
--   
--   <tt>r</tt> represents the type of the type list of the remaining
--   effects. Usually you want to be polymorphic in this.
--   
--   <tt>a</tt> is the result type of the program you will handle
--   
--   <tt>b</tt> is the result of handled computation.
type Handler e r a b = Comp e r a b -> Res r b

-- | Comp represents a computation. It is either a pure value or a
--   computation that needs further evaluation and effect handling.
data Comp e r a b
Value :: a -> Comp e r a b
Comp :: (e (Res r b)) -> Comp e r a b

-- | Result structure of the program is directly <a>Free</a> over
--   <a>Union</a> indexed by the list of effect functors.
type Res r = Free (Union r)

-- | <a>effect</a> is meant to be used as a helper function for defining
--   new effects. See predefined effects for examples. Good way to use it
--   is to pass in a lambda expression with explicit <tt>k</tt> for
--   continuation. You will need to manually <a>inj</a> into the
--   <a>Union</a> because of some GHC limitations.
effect :: (forall b. (a -> Res r b) -> Union r (Res r b)) -> Eff r a

-- | A program without effects is guaranteed to be pure so you can safely
--   convert it into a value.
runPure :: Eff '[] a -> a

-- | Like <a>runPure</a> but for program results. You only need this for
--   implementing some handlers.
runPureRes :: Res '[] a -> a

-- | Use a <a>Handler</a> on an <a>Eff</a> program to stripe away the first
--   layer of effects. There are some issues if you are using a handler
--   that is somewhat polymorphic in <tt>e</tt> As the compiler cannot
--   figure out which effect are you handling. Currently the best solution
--   seems to be to manually specify type of the handler such that it is
--   monomorphic in <tt>e</tt>. Sorry.
handle :: (Functor e, Typeable e) => Handler e r a b -> Eff (e : r) a -> Eff r b

-- | Convert a result back into a program in order to compose it. This
--   function might not be needed and might introduce some performance
--   issues (it is used in <a>handle</a>) but we didn't find a way to drop
--   it.
continue :: Res r a -> Eff r a

-- | Finish a program and convert it into a result structure.
finish :: Eff r a -> Res r a

-- | Smart constructor for <a>Union</a>. Injects the functor into any union
--   of which the said functor is a member. Please note that only the type
--   constructor need be a <a>Typeable</a>.
inj :: (Typeable f, Functor f, Member f r) => f a -> Union r a

-- | The <a>Member</a> type clas denotes that f is a member of type list r
class Member (f :: * -> *) (r :: [* -> *])

-- | The class <a>Typeable</a> allows a concrete representation of a type
--   to be calculated.
class Typeable k (a :: k)
instance GHC.Base.Monad (Control.Effects.Eff.Eff r)
instance GHC.Base.Applicative (Control.Effects.Eff.Eff r)
instance GHC.Base.Functor (Control.Effects.Eff.Eff r)

module Control.Effects.Exception

-- | The functor representing the exception. You shouldn't need to create
--   this manually, just use <a>throw</a>.
newtype Exception m a
Exception :: m -> Exception m a

-- | Throw an exception. The only requirement is that exception be
--   typeable.
throw :: (Member (Exception a) r, Typeable a) => a -> Eff r b

-- | This handler converts an program that might throw an exception into a
--   program that returns either its result or the exception.
exceptionHandler :: Handler (Exception m) r a (Either m a)

-- | This function generates a handler that upon a <a>throw</a>
--   short-circuts the computation and returns the default value instead.
defValueExceptionHandler :: a -> Handler (Exception m) r a a
instance GHC.Base.Functor (Control.Effects.Exception.Exception m)

module Control.Effects.IO

-- | The functor representing the effect. You shouldn't need to create this
--   manually, just use <a>liftIO</a>.
data LiftIO a
LiftIO :: (IO r) -> (r -> a) -> LiftIO a

-- | Lift an existing <a>IO</a> action into the effect monad.
liftIO :: Member LiftIO r => IO a -> Eff r a

-- | Handle by converting back to <a>IO</a>. Note that it is required that
--   the effect stack is otherwise empty - this handler would not typecheck
--   otherwise.
ioHandler :: Handler LiftIO '[] a (IO a)
instance GHC.Base.Functor Control.Effects.IO.LiftIO

module Control.Effects.Reader

-- | The functor representing the effect. You shouldn't need to create this
--   manually, just use <a>ask</a> or <a>reader</a>
newtype Reader w a
Reader :: (w -> a) -> Reader w a

-- | Get the value from the reader
ask :: (Member (Reader a) r, Typeable a) => Eff r a

-- | Lift a function into a reader.
reader :: (Member (Reader a) r, Typeable a) => (a -> b) -> Eff r b

-- | The obvious handler that just embeds the value provided.
readerHandler :: w -> Handler (Reader w) r a a
instance GHC.Base.Functor (Control.Effects.Reader.Reader w)

module Control.Effects.Search

-- | A proxy for passing type to functions. Example &gt; foo
data T a
T :: T a
asT :: a -> T a -> a

-- | The functor representing the effect. You shouldn't need to create this
--   manually, just use <a>choose</a> or <a>searchFail</a>.
data Search w a
SChoose :: [w] -> (w -> a) -> Search w a

-- | Nondeterministicaly choose an element from a list
choose :: (Member (Search w) r, Typeable w) => [w] -> Eff r w

-- | Fail a search. Equal to choosing from an empty list.
searchFail :: (Member (Search w) r, Typeable w) => T w -> Eff r ()

-- | Use a strict depth first search. Equal to using <tt>ListT</tt>
handleDFS :: Handler (Search w) r a [a]

-- | Lazy depth first search with backtracking.
handleBacktrackMaybe :: Handler (Search w) r a (Maybe a)
instance GHC.Base.Functor (Control.Effects.Search.Search w)

module Control.Effects.State

-- | The functor representing the effect. You shouldn't need to create this
--   manually, just use <a>get</a>, <a>put</a> or <a>state</a>.
data State s a
SGet :: (s -> a) -> State s a
SPut :: s -> a -> State s a

-- | Read from state
get :: (Member (State a) r, Typeable a) => Eff r a

-- | Write to state
put :: (Member (State s) r, Typeable s) => s -> Eff r ()

-- | Lift a function into state
state :: (Member (State s) r, Typeable s) => (s -> (a, s)) -> Eff r a

-- | Handle state into a function. Note that applying the resulting
--   function you get out another program that you have to bind over.
stateHandler :: Handler (State s) r a (s -> Eff r a)
instance GHC.Base.Functor (Control.Effects.State.State s)

module Control.Effects.Writer

-- | The functor representing the effect. You shouldn't need to create this
--   manually, just use <a>tell</a>
data Writer m a
Writer :: m -> a -> Writer m a

-- | Send a value into the writer
tell :: (Member (Writer m) r, Typeable m) => m -> Eff r ()

-- | Handles writes by <a>mappend</a>ing them together.
writerHandler :: (Monoid m) => Handler (Writer m) r a (a, m)
instance GHC.Base.Functor (Control.Effects.Writer.Writer m)
