-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | IoC Monad in Haskell
--
-- Monad used to encapsulate components, similiar to an IoC container.
@package boots
@version 0.2
module Control.Monad.Factory.Class
-- | Monads which allow to produce component under env,
-- and env can be changed by this procedure.
class (Monad m, Monad n) => MonadFactory env n m | m -> env n
-- | Return the environment of the monad.
getEnv :: MonadFactory env n m => m env
-- | Replace the environment inside the monad.
putEnv :: MonadFactory env n m => env -> m ()
-- | Produce a resource component, with open and close.
produce :: MonadFactory env n m => n component -> (component -> n ()) -> m component
-- | Defer to run side effect when closeing resource.
defer :: MonadFactory env n m => n () -> m ()
-- | Asks sub value of env.
asksEnv :: MonadFactory env n m => (env -> a) -> m a
-- | Change environment env.
withEnv :: MonadFactory env n m => (env -> m env) -> m ()
-- | Modify environment env.
modifyEnv :: MonadFactory env n m => (env -> env) -> m ()
-- | Run factory, return component c and updated environment
-- env.
runEnv :: MonadFactory env n m => m c -> m (env, c)
-- | IoC Monad in Haskell.
--
--
--
-- Simplify to create an application in Haskell.
--
-- When we decide to create an application using Haskell. We may need
-- using configurations, loggers as basic functions. If this application
-- needs storages, caches, etc., then we have to weaving the management
-- of connection of these facilities into the application. Connections
-- need to be created before and be destroyed after using them. There is
-- a common strategy to manage connections, that is using Cont.
-- Then we can encapsulate the management of connections separately. For
-- example, we can write a database plugin Factory m
-- cxt DBConnection, which can manage the database
-- connections in monad m with context cxt. Context
-- cxt may be requested for getting configurations or logging
-- functions. When all the components of application are encapsulated by
-- plugins, then running an application will be simplified.
--
--
--
-- Factory has an environment env, which provides
-- anything needs by the factory. component is the production of
-- the factory, it will be used by other Factory. Finally to build
-- a complete Factory m () (m ()), which can be boot.
module Control.Monad.Factory
-- | Monads which allow to produce component under env,
-- and env can be changed by this procedure.
class (Monad m, Monad n) => MonadFactory env n m | m -> env n
-- | Return the environment of the monad.
getEnv :: MonadFactory env n m => m env
-- | Replace the environment inside the monad.
putEnv :: MonadFactory env n m => env -> m ()
-- | Produce a resource component, with open and close.
produce :: MonadFactory env n m => n component -> (component -> n ()) -> m component
-- | Defer to run side effect when closeing resource.
defer :: MonadFactory env n m => n () -> m ()
-- | Asks sub value of env.
asksEnv :: MonadFactory env n m => (env -> a) -> m a
-- | Modify environment env.
modifyEnv :: MonadFactory env n m => (env -> env) -> m ()
-- | Change environment env.
withEnv :: MonadFactory env n m => (env -> m env) -> m ()
-- | Run factory, return component c and updated environment
-- env.
runEnv :: MonadFactory env n m => m c -> m (env, c)
-- | Factory defines how to generate a component under the
-- environment env in monad m. It is similar to IoC
-- container in oop, env will provide anything to be wanted to
-- generate component.
newtype Factory m env component
Factory :: StateT env (ContT () m) component -> Factory m env component
[unFactory] :: Factory m env component -> StateT env (ContT () m) component
-- | Running the factory.
running :: env -> Factory m env c -> (c -> m ()) -> m ()
-- | Run the application using a specified factory.
boot :: Monad m => Factory m () (m ()) -> m ()
-- | Construct factory under env, and adapt it to fit another
-- env'.
within :: env -> Factory m env component -> Factory m env' component
-- | Construct factory under env, and adapt it to fit another
-- env'.
withFactory :: (env' -> env) -> Factory m env component -> Factory m env' component
-- | Wrap raw procedure into a Factory.
wrap :: ((c -> m ()) -> m ()) -> Factory m env c
-- | Lift a monad m into a Factory.
liftFT :: Monad m => m a -> Factory m env a
-- | Nature transform of one Factory with monad n into
-- another with monad m.
natTrans :: (n () -> m ()) -> (m () -> n ()) -> Factory n env component -> Factory m env component
tryBuild :: Bool -> Factory n env () -> Factory n env ()
-- | Left-to-right composition
(>>>) :: Category cat => cat a b -> cat b c -> cat a c
infixr 1 >>>
-- | Right-to-left composition
(<<<) :: Category cat => cat b c -> cat a b -> cat a c
infixr 1 <<<
-- | An associative operation.
(<>) :: Semigroup a => a -> a -> a
infixr 6 <>
-- | A class for monads in which exceptions may be thrown.
--
-- Instances should obey the following law:
--
--
-- throwM e >> x = throwM e
--
--
-- In other words, throwing an exception short-circuits the rest of the
-- monadic computation.
class Monad m => MonadThrow (m :: Type -> Type)
-- | Throw an exception. Note that this throws when this action is run in
-- the monad m, not when it is applied. It is a generalization
-- of Control.Exception's throwIO.
--
-- Should satisfy the law:
--
--
-- throwM e >> f = throwM e
--
throwM :: (MonadThrow m, Exception e) => e -> m a
-- | A class for monads which allow exceptions to be caught, in particular
-- exceptions which were thrown by throwM.
--
-- Instances should obey the following law:
--
--
-- catch (throwM e) f = f e
--
--
-- Note that the ability to catch an exception does not guarantee
-- that we can deal with all possible exit points from a computation.
-- Some monads, such as continuation-based stacks, allow for more than
-- just a success/failure strategy, and therefore catch
-- cannot be used by those monads to properly implement a function
-- such as finally. For more information, see MonadMask.
class MonadThrow m => MonadCatch (m :: Type -> Type)
-- | A class for monads which provide for the ability to account for all
-- possible exit points from a computation, and to mask asynchronous
-- exceptions. Continuation-based monads are invalid instances of this
-- class.
--
-- Instances should ensure that, in the following code:
--
--
-- fg = f `finally` g
--
--
-- The action g is called regardless of what occurs within
-- f, including async exceptions. Some monads allow f
-- to abort the computation via other effects than throwing an exception.
-- For simplicity, we will consider aborting and throwing an exception to
-- be two forms of "throwing an error".
--
-- If f and g both throw an error, the error thrown by
-- fg depends on which errors we're talking about. In a monad
-- transformer stack, the deeper layers override the effects of the inner
-- layers; for example, ExceptT e1 (Except e2) a represents a
-- value of type Either e2 (Either e1 a), so throwing both an
-- e1 and an e2 will result in Left e2. If
-- f and g both throw an error from the same layer,
-- instances should ensure that the error from g wins.
--
-- Effects other than throwing an error are also overriden by the deeper
-- layers. For example, StateT s Maybe a represents a value of
-- type s -> Maybe (a, s), so if an error thrown from
-- f causes this function to return Nothing, any
-- changes to the state which f also performed will be erased.
-- As a result, g will see the state as it was before
-- f. Once g completes, f's error will be
-- rethrown, so g' state changes will be erased as well. This is
-- the normal interaction between effects in a monad transformer stack.
--
-- By contrast, lifted-base's version of finally always
-- discards all of g's non-IO effects, and g never sees
-- any of f's non-IO effects, regardless of the layer ordering
-- and regardless of whether f throws an error. This is not the
-- result of interacting effects, but a consequence of
-- MonadBaseControl's approach.
class MonadCatch m => MonadMask (m :: Type -> Type)
-- | Monads in which IO computations may be embedded. Any monad
-- built by applying a sequence of monad transformers to the IO
-- monad will be an instance of this class.
--
-- Instances should satisfy the following laws, which state that
-- liftIO is a transformer of monads:
--
--
class Monad m => MonadIO (m :: Type -> Type)
-- | Lift a computation from the IO monad.
liftIO :: MonadIO m => IO a -> m a
-- | Lift a computation from the argument monad to the constructed monad.
lift :: (MonadTrans t, Monad m) => m a -> t m a
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Control.Monad.Factory.Factory m env)
instance Control.Monad.State.Class.MonadState env (Control.Monad.Factory.Factory m env)
instance GHC.Base.Monad (Control.Monad.Factory.Factory m env)
instance GHC.Base.Applicative (Control.Monad.Factory.Factory m env)
instance GHC.Base.Functor (Control.Monad.Factory.Factory m env)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Control.Monad.Factory.Factory m env)
instance GHC.Base.Monad m => Control.Monad.Cont.Class.MonadCont (Control.Monad.Factory.Factory m env)
instance Control.Category.Category (Control.Monad.Factory.Factory m)
instance Control.Monad.Catch.MonadMask m => Control.Monad.Factory.Class.MonadFactory env m (Control.Monad.Factory.Factory m env)