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


-- | Programs with Environments and Managed Resources
--   
--   Please see the README on GitHub at
--   <a>https://github.com/typedbyte/program</a>
@package program
@version 0.1.0.0


-- | Types and functions for representing programs which run in a specific
--   environment and are able to integrate bracket-like operations.
module Control.Program

-- | Represents a program that produces a value of type <tt>a</tt> when
--   running in an environment <tt>e</tt>. The required content of the
--   environment is usually described by declaring <a>Has</a> constraints
--   on <tt>e</tt>.
--   
--   Turning an <a>IO</a> action into a <a>Program</a> is usually done by
--   using <a>liftIO</a>.
data Program e a

-- | Runs a program in a given environment <tt>e</tt>.
runProgram :: e -> Program e a -> IO a

-- | Acquire a resource, use it, and then release the resource
--   automatically after the program ends.
bracket :: IO a -> (a -> IO b) -> Program e a

-- | A version of <a>bracket</a> where the acquisition and release actions
--   may consult the environment <tt>e</tt>.
bracketE :: (e -> IO a) -> (e -> a -> IO b) -> Program e a

-- | Integrates a continuation into a <a>Program</a>, which is useful for
--   integrating existing bracket-like continuations (often named
--   <tt>with...</tt>).
manage :: (forall b. (a -> IO b) -> IO b) -> Program e a

-- | Runs a sub-program within a program, which is useful for fine-grained
--   resource handling (i.e., resources acquired by the sub-program are
--   released after the sub-program ends, not at the end of the whole
--   program).
local :: Program e a -> Program e a

-- | Demands that a specific value of type <tt>t</tt> must be present in
--   the environment <tt>e</tt>.
class e `Has` t

-- | Extracts a value of type <tt>t</tt> from the environment <tt>e</tt>.
from :: Has e t => e -> t

-- | Gets the environment.
ask :: Program e e

-- | Extracts a specific value of type <tt>t</tt> from the environment.
pull :: e `Has` t => Program e t

-- | Extracts a specific value of type <tt>t</tt> from the environment and
--   extracts some <a>IO</a> action from it. This is useful if the
--   environment contains a record of <a>IO</a> functions (e.g., a function
--   which returns a handle).
pullWith :: e `Has` t => (t -> IO a) -> Program e a
instance Control.Program.Has e e
instance GHC.Base.Functor (Control.Program.Program e)
instance GHC.Base.Applicative (Control.Program.Program e)
instance GHC.Base.Monad (Control.Program.Program e)
instance Control.Monad.Fail.MonadFail (Control.Program.Program e)
instance Control.Monad.IO.Class.MonadIO (Control.Program.Program e)


-- | Types and functions for handling mutable state in the environment of a
--   <a>Program</a>.
module Control.Program.State

-- | A record of functions which represents the operations on a mutable
--   value.
data State s
State :: IO s -> (s -> IO ()) -> State s

-- | Gets the current state.
[readState] :: State s -> IO s

-- | Replaces the state with a new value.
[writeState] :: State s -> s -> IO ()

-- | Gets the current state.
get :: e `Has` State s => Program e s

-- | Replaces the state with a new value.
put :: e `Has` State s => s -> Program e ()

-- | Modifies the state, using the provided function.
modify :: e `Has` State s => (s -> s) -> Program e ()

-- | A strict version of <a>modify</a>.
modify' :: e `Has` State s => (s -> s) -> Program e ()

-- | Creates a new record of functions for mutable state, backed by an
--   <a>IORef</a>.
newState :: s -> IO (State s)

-- | Modifies the state, using the provided function.
modifyState :: State s -> (s -> s) -> IO ()

-- | A strict version of <a>modifyState</a>.
modifyState' :: State s -> (s -> s) -> IO ()


-- | Types and functions for handling appendable output in the environment
--   of a <a>Program</a>.
module Control.Program.Writer

-- | A record of functions which represents the operations on an appendable
--   output.
newtype Writer w
Writer :: (w -> IO ()) -> Writer w
[writeValue] :: Writer w -> w -> IO ()

-- | Creates a new record of functions for appendable output, backed by an
--   <a>IORef</a>.
--   
--   Returns the record of functions and an action which reads the
--   accumulated output, usually used after running a corresponding
--   <a>Program</a> with the <a>Writer</a> in its environment.
newWriter :: Monoid w => IO (Writer w, IO w)

-- | Produces the output <tt>w</tt>. In other words, <tt>w</tt> is appended
--   to the accumulated output.
tell :: e `Has` Writer w => w -> Program e ()