-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Fast and concise extensible effects
--
-- Please see the README on GitHub at
-- https://github.com/re-xyr/cleff#readme
@package cleff
@version 0.2.1.0
-- | This module contains utility functions for Any.
--
-- This is an internal module and its API may change even
-- between minor versions. Therefore you should be extra careful if
-- you're to depend on this module.
module Cleff.Internal.Any
-- | The type constructor Any is type to which you can unsafely
-- coerce any lifted type, and back. More concretely, for a lifted type
-- t and value x :: t, -- unsafeCoerce
-- (unsafeCoerce x :: Any) :: t is equivalent to x.
type family Any :: k
-- | Coerce Any to a boxed value. This is generally unsafe
-- and it is your responsibility to ensure that the type you're coercing
-- into is the original type that the Any is coerced from.
fromAny :: Any -> a
-- | Coerce any boxed value into Any.
toAny :: a -> Any
-- | This module contains definitions of some basic types related to
-- effects. You won't need this module directly; these functionalities
-- are reexported in the Cleff module.
--
-- This is an internal module and its API may change even
-- between minor versions. Therefore you should be extra careful if
-- you're to depend on this module.
module Cleff.Internal.Effect
-- | The type of effects. An effect e m a takes an effect monad
-- type m :: Type -> Type and a result type
-- a :: Type.
type Effect = (Type -> Type) -> Type -> Type
-- | e :> es means the effect e is present in
-- the effect stack es, and therefore can be used in an
-- Eff es computation.
type (:>) = Elem
infix 0 :>
-- | xs :>> es means the list of effects xs
-- are all present in the effect stack es. This is a convenient
-- type alias for (e1 :> es, ..., en :> es).
type family xs :>> es :: Constraint
infix 0 :>>
-- | Type level list concatenation.
type family (xs :: [a]) ++ (ys :: [a]) :: [a]
infixr 5 ++
-- | The type of natural transformations from functor f to
-- g.
type (f :: k -> Type) ~> (g :: k -> Type) = forall (a :: k). () => f a -> g a
infixr 0 ~>
-- | This module contains the definition of the Eff monad. Most of
-- the times, you won't need to use this module directly; user-facing
-- functionalities are all exported via the Cleff module.
--
-- This is an internal module and its API may change even
-- between minor versions. Therefore you should be extra careful if
-- you're to depend on this module.
module Cleff.Internal.Monad
-- | The internal representation of effect handlers. This is just a natural
-- transformation from the effect type e (Eff es) to the
-- effect monad Eff es for any effect stack es.
--
-- In interpreting functions (see Cleff.Internal.Interpret), the
-- user-facing Handler type is transformed into this type.
newtype InternalHandler e
InternalHandler :: (forall es. e (Eff es) ~> Eff es) -> InternalHandler e
[runHandler] :: InternalHandler e -> forall es. e (Eff es) ~> Eff es
-- | The extensible effect monad. A monad Eff es is capable
-- of performing any effect in the effect stack es, which
-- is a type-level list that holds all effects available. However, most
-- of the times, for flexibility, es should be a polymorphic
-- type variable, and you should use the (:>) and
-- (:>>) operators in constraints to indicate what effects
-- are in the stack. For example,
--
--
-- Reader String :> es, State Bool :> es => Eff es Integer
--
--
-- allows you to perform operations of the Reader
-- String effect and the State Bool
-- effect in a computation returning an Integer.
newtype Eff es a
-- | The effect monad receives an effect environment Env that
-- contains all effect handlers and produces an IO action.
Eff :: (Env es -> IO a) -> Eff es a
[unEff] :: Eff es a -> Env es -> IO a
-- | The effect environment that corresponds effects in the stack to
-- their respective InternalHandlers. This structure simulates
-- memory: handlers are retrieved via pointers (HandlerPtrs), and
-- for each effect in the stack we can either change what pointer it uses
-- or change the handler the pointer points to. The former is used for
-- global effect interpretation (reinterpretN) and the latter for
-- local interpretation (toEffWith) in order to retain correct HO
-- semantics. For more details on this see
-- https://github.com/re-xyr/cleff/issues/5.
data Env (es :: [Effect])
-- | A pointer to InternalHandler in an Env.
data HandlerPtr (e :: Effect)
-- | Create an empty Env with no address allocated.
emptyEnv :: Env '[]
-- | Adjust the effect stack via an function over Rec.
adjustEnv :: forall es' es. (Rec HandlerPtr es -> Rec HandlerPtr es') -> Env es -> Env es'
-- | Allocate a new, empty address for a handler. <math>.
allocaEnv :: forall e es. Env es -> (# HandlerPtr e, Env es #)
-- | Read the handler a pointer points to. <math>.
readEnv :: forall e es. Elem e es => Env es -> InternalHandler e
-- | Overwrite the handler a pointer points to. <math>.
writeEnv :: forall e es. HandlerPtr e -> InternalHandler e -> Env es -> Env es
-- | Replace the handler pointer of an effect in the stack. <math>.
replaceEnv :: forall e es. Elem e es => HandlerPtr e -> InternalHandler e -> Env es -> Env es
-- | Add a new effect to the stack with its corresponding handler pointer.
-- <math>.
appendEnv :: forall e es. HandlerPtr e -> InternalHandler e -> Env es -> Env (e : es)
-- | Use the state of LHS as a newer version for RHS. <math>.
updateEnv :: forall es es'. Env es' -> Env es -> Env es
-- | The list es list is concrete, i.e. is of the form '[a1,
-- a2, ..., an], i.e. is not a type variable.
class KnownList (es :: [k])
-- | es is a subset of es'.
class KnownList es => Subset (es :: [k]) (es' :: [k])
-- | Perform an effect operation, i.e. a value of an effect type
-- e :: Effect. This requires e to be in the
-- effect stack.
send :: e :> es => e (Eff es) ~> Eff es
-- | Perform an action in another effect stack via a transformation to that
-- stack; in other words, this function "maps" the effect operation from
-- effect stack es to es'. This is a generalization of
-- send; end users most likely won't need to use this.
--
--
-- send = sendVia id
--
sendVia :: e :> es' => (Eff es ~> Eff es') -> e (Eff es) ~> Eff es'
instance GHC.Base.Functor (Cleff.Internal.Monad.Eff es)
instance GHC.Base.Applicative (Cleff.Internal.Monad.Eff es)
instance GHC.Base.Monad (Cleff.Internal.Monad.Eff es)
instance Control.Monad.Fix.MonadFix (Cleff.Internal.Monad.Eff es)
-- | This module contains functions for interpreting effects. Most of the
-- times you won't need to import this directly; the module Cleff
-- reexports most of the functionalities.
--
-- This is an internal module and its API may change even
-- between minor versions. Therefore you should be extra careful if
-- you're to depend on this module.
module Cleff.Internal.Interpret
-- | Adjust the effect stack by a contravariant transformation function
-- over the stack. This function reveals the profunctorial nature of
-- Eff; in particular, Eff is a profunctor
-- [Effect] -> Type, lmap is
-- adjust, and rmap is fmap.
adjust :: forall es es'. (forall f. Rec f es' -> Rec f es) -> Eff es ~> Eff es'
-- | Lift a computation into a bigger effect stack with one more effect.
-- For a more general version see raiseN.
raise :: forall e es. Eff es ~> Eff (e : es)
-- | Lift a computation into a bigger effect stack with arbitrarily more
-- effects. This function requires TypeApplications.
raiseN :: forall es' es. KnownList es' => Eff es ~> Eff (es' ++ es)
-- | Lift a computation with a fixed, known effect stack into some superset
-- of the stack.
inject :: forall es' es. Subset es' es => Eff es' ~> Eff es
-- | Eliminate a duplicate effect from the top of the effect stack. For a
-- more general version see subsumeN.
subsume :: forall e es. e :> es => Eff (e : es) ~> Eff es
-- | Eliminate several duplicate effects from the top of the effect stack.
-- This function requires TypeApplications.
subsumeN :: forall es' es. Subset es' es => Eff (es' ++ es) ~> Eff es
-- | Like raise, but adds the new effect under the top effect. This
-- is useful for transforming an interpreter e' :> es =>
-- Eff (e ': es) ~> Eff es into a
-- reinterpreter Eff (e ': es) ~> Eff (e' ':
-- es):
--
--
-- myInterpreter :: Bar :> es => Eff (Foo ': es) ~> Eff es
-- myInterpreter = ...
--
-- myReinterpreter :: Eff (Foo ': es) ~> Eff (Bar ': es)
-- myReinterpreter = myInterpreter . raiseUnder
--
--
-- In other words,
--
--
-- reinterpret h == interpret h . raiseUnder
--
--
-- However, note that this function is suited for transforming an
-- existing interpreter into a reinterpreter; if you want to define a
-- reinterpreter from scratch, you should still prefer
-- reinterpret, which is both easier to use and more efficient.
raiseUnder :: forall e' e es. Eff (e : es) ~> Eff (e : (e' : es))
-- | Like raiseUnder, but allows introducing multiple effects. This
-- function requires TypeApplications.
raiseNUnder :: forall es' e es. KnownList es' => Eff (e : es) ~> Eff (e : (es' ++ es))
-- | Like raiseUnder, but allows introducing the effect under
-- multiple effects. This function requires TypeApplications.
raiseUnderN :: forall e es' es. KnownList es' => Eff (es' ++ es) ~> Eff (es' ++ (e : es))
-- | A generalization of both raiseUnderN and raiseNUnder,
-- allowing introducing multiple effects under multiple effects. This
-- function requires TypeApplications and is subject to serious
-- type ambiguity; you most likely will need to supply all three type
-- variables explicitly.
raiseNUnderN :: forall es'' es' es. (KnownList es', KnownList es'') => Eff (es' ++ es) ~> Eff (es' ++ (es'' ++ es))
-- | The typeclass that denotes a handler scope, handling effect e
-- sent from the effect stack esSend in the effect stack
-- es.
--
-- You should not define instances for this typeclass whatsoever.
class Handling esSend e es | esSend -> e es
-- | Get the send-site Env.
esSend :: Handling esSend e es => Env esSend
-- | The type of an effect handler, which is a function that
-- transforms an effect e from an arbitrary effect stack into
-- computations in the effect stack es.
type Handler e es = forall esSend. Handling esSend e es => e (Eff esSend) ~> Eff es
-- | The type of a simple transformation function from effect e to
-- e'.
type Translator e e' = forall esSend. e (Eff esSend) ~> e' (Eff esSend)
-- | Interpret an effect e in terms of effects in the effect stack
-- es with an effect handler.
interpret :: forall e es. Handler e es -> Eff (e : es) ~> Eff es
-- | Like interpret, but adds a new effect e' that can be
-- used in the handler.
reinterpret :: forall e' e es. Handler e (e' : es) -> Eff (e : es) ~> Eff (e' : es)
-- | Like reinterpret, but adds two new effects.
reinterpret2 :: forall e' e'' e es. Handler e (e' : (e'' : es)) -> Eff (e : es) ~> Eff (e' : (e'' : es))
-- | Like reinterpret, but adds three new effects.
reinterpret3 :: forall e' e'' e''' e es. Handler e (e' : (e'' : (e''' : es))) -> Eff (e : es) ~> Eff (e' : (e'' : (e''' : es)))
-- | Like reinterpret, but adds arbitrarily many new effects. This
-- function requires TypeApplications.
reinterpretN :: forall es' e es. KnownList es' => Handler e (es' ++ es) -> Eff (e : es) ~> Eff (es' ++ es)
-- | Respond to an effect while being able to leave it unhandled (i.e. you
-- can resend the effects in the handler).
interpose :: forall e es. e :> es => Handler e es -> Eff es ~> Eff es
-- | Like interpose, but allows to introduce one new effect to use
-- in the handler.
impose :: forall e' e es. e :> es => Handler e (e' : es) -> Eff es ~> Eff (e' : es)
-- | Like impose, but allows introducing arbitrarily many effects.
-- This requires TypeApplications.
imposeN :: forall es' e es. (KnownList es', e :> es) => Handler e (es' ++ es) -> Eff es ~> Eff (es' ++ es)
-- | Interpret an effect in terms of another effect in the stack via a
-- simple Translator.
--
--
-- transform trans = interpret (sendVia toEff . trans)
--
transform :: forall e e' es. e' :> es => Translator e e' -> Eff (e : es) ~> Eff es
-- | Like transform, but instead of using an effect in stack, add a
-- new one to the top of it.
--
--
-- translate trans = reinterpret (sendVia toEff . trans)
--
translate :: forall e e' es. Translator e e' -> Eff (e : es) ~> Eff (e' : es)
-- | Run a computation in the current effect stack. This is useful for
-- interpreting higher-order effects, like a bracketing effect:
--
--
-- data Resource m a where
-- Bracket :: m a -> (a -> m ()) -> (a -> m b) -> Resource m b
--
--
--
-- Bracket alloc dealloc use ->
-- bracket
-- (toEff alloc)
-- (toEff . dealloc)
-- (toEff . use)
--
toEff :: Handling esSend e es => Eff esSend ~> Eff es
-- | Run a computation in the current effect stack, but handles the current
-- effect inside the computation differently by providing a new
-- Handler. This is useful for interpreting effects with local
-- contexts, like Local:
--
--
-- runReader :: r -> Eff (Reader r ': es) ~> Eff es
-- runReader x = interpret (handle x)
-- where
-- handle :: r -> Handler (Reader r) es
-- handle r = \case
-- Ask -> pure r
-- Local f m -> toEffWith (handle $ f r) m
--
toEffWith :: forall esSend e es. Handling esSend e es => Handler e es -> Eff esSend ~> Eff es
-- | Temporarily gain the ability to lift some Eff es
-- actions into Eff esSend. This is useful for dealing
-- with effect operations with the monad type in the negative position,
-- which means it's unlikely that you need to use this function in
-- implementing your effects.
withFromEff :: Handling esSend e es => ((Eff es ~> Eff esSend) -> Eff esSend a) -> Eff es a
-- | This module contains lifted instances of some typeclasses for
-- Eff for convenience. They are all exported in the Cleff
-- module so you shouldn't need to import this module.
--
-- This is an internal module and its API may change even
-- between minor versions. Therefore you should be extra careful if
-- you're to depend on this module.
module Cleff.Internal.Instances
instance GHC.Enum.Bounded a => GHC.Enum.Bounded (Cleff.Internal.Monad.Eff es a)
instance GHC.Num.Num a => GHC.Num.Num (Cleff.Internal.Monad.Eff es a)
instance GHC.Real.Fractional a => GHC.Real.Fractional (Cleff.Internal.Monad.Eff es a)
instance GHC.Float.Floating a => GHC.Float.Floating (Cleff.Internal.Monad.Eff es a)
instance GHC.Base.Semigroup a => GHC.Base.Semigroup (Cleff.Internal.Monad.Eff es a)
instance GHC.Base.Monoid a => GHC.Base.Monoid (Cleff.Internal.Monad.Eff es a)
instance Data.String.IsString a => Data.String.IsString (Cleff.Internal.Monad.Eff es a)
instance Control.Monad.Zip.MonadZip (Cleff.Internal.Monad.Eff es)
-- | This module contains the IOE effect together with a few
-- primitives for using it, as well as interpretation combinators for
-- IO-related effects. It is not usually needed because safe
-- functionalities are re-exported in the Cleff module.
--
-- This is an internal module and its API may change even
-- between minor versions. Therefore you should be extra careful if
-- you're to depend on this module.
module Cleff.Internal.Base
-- | The effect for lifting and unlifting the IO monad, allowing you
-- to use MonadIO, MonadUnliftIO, PrimMonad,
-- MonadCatch, MonadThrow and MonadMask
-- functionalities. This is the "final" effect that most effects
-- eventually are interpreted into. For example, you can do:
--
--
-- log :: IOE :> es => Eff es ()
-- log = liftIO (putStrLn "Test logging")
--
--
-- It is not recommended to use this effect in application code, as it is
-- too liberal and allows arbitrary IO. Ideally, this is only used in
-- interpreting more fine-grained effects.
--
-- Note that this is not a real effect and cannot be interpreted
-- in any way besides thisIsPureTrustMe and runIOE. It is
-- similar to Polysemy's Final effect which also cannot be
-- interpreted. This is mainly for performance concern, but also that
-- there doesn't really exist reasonable interpretations other than the
-- current one, given the underlying implementation of the Eff
-- monad.
--
-- IOE can be a real effect though, and you can enable the
-- dynamic-ioe build flag to have that. However it is only for
-- reference purposes and should not be used in production code.
data IOE :: Effect
-- | Lift an IO computation into Eff. This function is
-- highly unsafe and should not be used directly; use
-- liftIO instead, or if you're interpreting higher-order effects,
-- use fromIO.
primLiftIO :: IO a -> Eff es a
-- | Give a runner function a way to run Eff actions as an IO
-- computation. This function is highly unsafe and should not be
-- used directly; use withRunInIO instead, or if you're
-- interpreting higher-order effects, use withToIO.
primUnliftIO :: ((Eff es ~> IO) -> IO a) -> Eff es a
-- | Unsafely eliminate an IOE effect from the top of the effect
-- stack. This is mainly for implementing effects that uses IO but
-- does not do anything really impure (i.e. can be safely used
-- unsafeDupablePerformIO on), such as a State effect.
thisIsPureTrustMe :: Eff (IOE : es) ~> Eff es
-- | Unwrap an Eff computation with side effects into an IO
-- computation, given that all effects other than IOE are
-- interpreted.
runIOE :: Eff '[IOE] ~> IO
-- | Unwrap a pure Eff computation into a pure value, given that all
-- effects are interpreted.
runPure :: Eff '[] a -> a
-- | The type of an IO effect handler, which is a function
-- that transforms an effect e into IO computations. This
-- is used for interpretIO.
type HandlerIO e es = forall esSend. Handling esSend e es => e (Eff esSend) ~> IO
-- | Interpret an effect in terms of IO, by transforming an effect
-- into IO computations.
--
--
-- interpretIO f = interpret (liftIO . f)
--
interpretIO :: IOE :> es => HandlerIO e es -> Eff (e : es) ~> Eff es
-- | Temporarily gain the ability to unlift an Eff esSend
-- computation into IO. This is useful for dealing with
-- higher-order effects that involves IO.
withToIO :: (Handling esSend e es, IOE :> es) => ((Eff esSend ~> IO) -> IO a) -> Eff es a
-- | Lift an IO computation into Eff esSend. This is
-- useful for dealing with effect operations with the monad type in the
-- negative position within IOE, like masking.
fromIO :: (Handling esSend e es, IOE :> es) => IO ~> Eff esSend
instance (Cleff.Internal.Base.IOE Cleff.Internal.Effect.:> es) => Control.Monad.IO.Class.MonadIO (Cleff.Internal.Monad.Eff es)
instance (Cleff.Internal.Base.IOE Cleff.Internal.Effect.:> es) => Control.Monad.IO.Unlift.MonadUnliftIO (Cleff.Internal.Monad.Eff es)
instance (Cleff.Internal.Base.IOE Cleff.Internal.Effect.:> es) => Control.Monad.Catch.MonadThrow (Cleff.Internal.Monad.Eff es)
instance (Cleff.Internal.Base.IOE Cleff.Internal.Effect.:> es) => Control.Monad.Catch.MonadCatch (Cleff.Internal.Monad.Eff es)
instance (Cleff.Internal.Base.IOE Cleff.Internal.Effect.:> es) => Control.Monad.Catch.MonadMask (Cleff.Internal.Monad.Eff es)
instance (Cleff.Internal.Base.IOE Cleff.Internal.Effect.:> es) => Control.Monad.Base.MonadBase GHC.Types.IO (Cleff.Internal.Monad.Eff es)
instance (Cleff.Internal.Base.IOE Cleff.Internal.Effect.:> es) => Control.Monad.Trans.Control.MonadBaseControl GHC.Types.IO (Cleff.Internal.Monad.Eff es)
instance (Cleff.Internal.Base.IOE Cleff.Internal.Effect.:> es) => Control.Monad.Primitive.PrimMonad (Cleff.Internal.Monad.Eff es)
-- | This module contains Template Haskell functions for generating
-- definitions of functions that send effect operations. You mostly won't
-- want to import this module directly; The Cleff module reexports
-- the main functionalities of this module.
--
-- This is an internal module and its API may change even
-- between minor versions. Therefore you should be extra careful if
-- you're to depend on this module.
module Cleff.Internal.TH
-- | For a datatype T representing an effect,
-- makeEffect T generates functions defintions for
-- performing the operations of T via send. The naming
-- rule is changing the first uppercase letter in the constructor name to
-- lowercase or removing the : symbol in the case of operator
-- constructors. Also, this function will preserve any fixity
-- declarations defined on the constructors.
--
-- Because of the limitations of Template Haskell, all constructors of
-- T should be polymorphic in the monad type, if they are
-- to be used by makeEffect. For example, this is not OK:
--
--
-- data Limited :: Effect where
-- Noop :: Limited (Eff es) ()
--
--
-- because the monad type Eff es is not a fully
-- polymorphic type variable.
--
-- This function is also "weaker" than polysemy's
-- makeSem, because this function cannot properly handle some
-- cases involving complex higher order effects. Those cases are rare,
-- though. See the tests for more details.
makeEffect :: Name -> Q [Dec]
-- | Like makeEffect, but doesn't generate type signatures. This is
-- useful when you want to attach Haddock documentation to the function
-- signature, e.g.:
--
--
-- data Identity :: Effect where
-- Noop :: Identity m ()
-- makeEffect_ ''Identity
--
-- -- | Perform nothing at all.
-- noop :: Identity :> es => Eff es ()
--
--
-- Be careful that the function signatures must be added after the
-- makeEffect_ call.
makeEffect_ :: Name -> Q [Dec]
-- | This library implements an extensible effects system, where
-- sets of monadic actions ("effects") are encoded as datatypes, tracked
-- at the type level and can have multiple different implementations.
-- This means you can swap out implementations of certain monadic actions
-- in mock tests or in different environments. The notion of "effect" is
-- general here: it can be an IO-performing side effect, or just
-- obtaining the value of a static global environment.
--
-- In particular, this library consists of
--
--
-- - The Eff monad, which is the core of an extensible effects
-- system. All effects are performed within it and it will be the "main"
-- monad of your application. This monad tracks effects at the type
-- level.
-- - A set of predefined general effects, like Reader and
-- State that can be used out of the box.
-- - Combinators for defining new effects and interpreting them on
-- your own. These effects can be translated in terms of other
-- already existing effects, or into operations in the IO
-- monad.
--
--
-- So, this library allows you to do two things:
--
--
-- - Effect management: The Eff monad tracks what effects
-- are used explicitly at the type level, therefore you are able to be
-- certain about what effects are involved in each function.
-- - Effect decoupling: You can decouple the implementation of
-- the effects from your application and swap them easily.
--
module Cleff
-- | The extensible effect monad. A monad Eff es is capable
-- of performing any effect in the effect stack es, which
-- is a type-level list that holds all effects available. However, most
-- of the times, for flexibility, es should be a polymorphic
-- type variable, and you should use the (:>) and
-- (:>>) operators in constraints to indicate what effects
-- are in the stack. For example,
--
--
-- Reader String :> es, State Bool :> es => Eff es Integer
--
--
-- allows you to perform operations of the Reader
-- String effect and the State Bool
-- effect in a computation returning an Integer.
data Eff es a
-- | e :> es means the effect e is present in
-- the effect stack es, and therefore can be used in an
-- Eff es computation.
type (:>) = Elem
infix 0 :>
-- | xs :>> es means the list of effects xs
-- are all present in the effect stack es. This is a convenient
-- type alias for (e1 :> es, ..., en :> es).
type family xs :>> es :: Constraint
infix 0 :>>
-- | The type of effects. An effect e m a takes an effect monad
-- type m :: Type -> Type and a result type
-- a :: Type.
type Effect = (Type -> Type) -> Type -> Type
-- | The effect for lifting and unlifting the IO monad, allowing you
-- to use MonadIO, MonadUnliftIO, PrimMonad,
-- MonadCatch, MonadThrow and MonadMask
-- functionalities. This is the "final" effect that most effects
-- eventually are interpreted into. For example, you can do:
--
--
-- log :: IOE :> es => Eff es ()
-- log = liftIO (putStrLn "Test logging")
--
--
-- It is not recommended to use this effect in application code, as it is
-- too liberal and allows arbitrary IO. Ideally, this is only used in
-- interpreting more fine-grained effects.
--
-- Note that this is not a real effect and cannot be interpreted
-- in any way besides thisIsPureTrustMe and runIOE. It is
-- similar to Polysemy's Final effect which also cannot be
-- interpreted. This is mainly for performance concern, but also that
-- there doesn't really exist reasonable interpretations other than the
-- current one, given the underlying implementation of the Eff
-- monad.
--
-- IOE can be a real effect though, and you can enable the
-- dynamic-ioe build flag to have that. However it is only for
-- reference purposes and should not be used in production code.
data IOE :: Effect
-- | Unwrap a pure Eff computation into a pure value, given that all
-- effects are interpreted.
runPure :: Eff '[] a -> a
-- | Unwrap an Eff computation with side effects into an IO
-- computation, given that all effects other than IOE are
-- interpreted.
runIOE :: Eff '[IOE] ~> IO
-- | Perform an effect operation, i.e. a value of an effect type
-- e :: Effect. This requires e to be in the
-- effect stack.
send :: e :> es => e (Eff es) ~> Eff es
-- | Perform an action in another effect stack via a transformation to that
-- stack; in other words, this function "maps" the effect operation from
-- effect stack es to es'. This is a generalization of
-- send; end users most likely won't need to use this.
--
--
-- send = sendVia id
--
sendVia :: e :> es' => (Eff es ~> Eff es') -> e (Eff es) ~> Eff es'
-- | For a datatype T representing an effect,
-- makeEffect T generates functions defintions for
-- performing the operations of T via send. The naming
-- rule is changing the first uppercase letter in the constructor name to
-- lowercase or removing the : symbol in the case of operator
-- constructors. Also, this function will preserve any fixity
-- declarations defined on the constructors.
--
-- Because of the limitations of Template Haskell, all constructors of
-- T should be polymorphic in the monad type, if they are
-- to be used by makeEffect. For example, this is not OK:
--
--
-- data Limited :: Effect where
-- Noop :: Limited (Eff es) ()
--
--
-- because the monad type Eff es is not a fully
-- polymorphic type variable.
--
-- This function is also "weaker" than polysemy's
-- makeSem, because this function cannot properly handle some
-- cases involving complex higher order effects. Those cases are rare,
-- though. See the tests for more details.
makeEffect :: Name -> Q [Dec]
-- | Like makeEffect, but doesn't generate type signatures. This is
-- useful when you want to attach Haddock documentation to the function
-- signature, e.g.:
--
--
-- data Identity :: Effect where
-- Noop :: Identity m ()
-- makeEffect_ ''Identity
--
-- -- | Perform nothing at all.
-- noop :: Identity :> es => Eff es ()
--
--
-- Be careful that the function signatures must be added after the
-- makeEffect_ call.
makeEffect_ :: Name -> Q [Dec]
-- | Lift a computation into a bigger effect stack with one more effect.
-- For a more general version see raiseN.
raise :: forall e es. Eff es ~> Eff (e : es)
-- | Lift a computation into a bigger effect stack with arbitrarily more
-- effects. This function requires TypeApplications.
raiseN :: forall es' es. KnownList es' => Eff es ~> Eff (es' ++ es)
-- | Lift a computation with a fixed, known effect stack into some superset
-- of the stack.
inject :: forall es' es. Subset es' es => Eff es' ~> Eff es
-- | Eliminate a duplicate effect from the top of the effect stack. For a
-- more general version see subsumeN.
subsume :: forall e es. e :> es => Eff (e : es) ~> Eff es
-- | Eliminate several duplicate effects from the top of the effect stack.
-- This function requires TypeApplications.
subsumeN :: forall es' es. Subset es' es => Eff (es' ++ es) ~> Eff es
-- | The list es list is concrete, i.e. is of the form '[a1,
-- a2, ..., an], i.e. is not a type variable.
class KnownList (es :: [k])
-- | es is a subset of es'.
class KnownList es => Subset (es :: [k]) (es' :: [k])
-- | The type of an effect handler, which is a function that
-- transforms an effect e from an arbitrary effect stack into
-- computations in the effect stack es.
type Handler e es = forall esSend. Handling esSend e es => e (Eff esSend) ~> Eff es
-- | Interpret an effect e in terms of effects in the effect stack
-- es with an effect handler.
interpret :: forall e es. Handler e es -> Eff (e : es) ~> Eff es
-- | Like interpret, but adds a new effect e' that can be
-- used in the handler.
reinterpret :: forall e' e es. Handler e (e' : es) -> Eff (e : es) ~> Eff (e' : es)
-- | Like reinterpret, but adds two new effects.
reinterpret2 :: forall e' e'' e es. Handler e (e' : (e'' : es)) -> Eff (e : es) ~> Eff (e' : (e'' : es))
-- | Like reinterpret, but adds three new effects.
reinterpret3 :: forall e' e'' e''' e es. Handler e (e' : (e'' : (e''' : es))) -> Eff (e : es) ~> Eff (e' : (e'' : (e''' : es)))
-- | Like reinterpret, but adds arbitrarily many new effects. This
-- function requires TypeApplications.
reinterpretN :: forall es' e es. KnownList es' => Handler e (es' ++ es) -> Eff (e : es) ~> Eff (es' ++ es)
-- | Respond to an effect while being able to leave it unhandled (i.e. you
-- can resend the effects in the handler).
interpose :: forall e es. e :> es => Handler e es -> Eff es ~> Eff es
-- | Like interpose, but allows to introduce one new effect to use
-- in the handler.
impose :: forall e' e es. e :> es => Handler e (e' : es) -> Eff es ~> Eff (e' : es)
-- | Like impose, but allows introducing arbitrarily many effects.
-- This requires TypeApplications.
imposeN :: forall es' e es. (KnownList es', e :> es) => Handler e (es' ++ es) -> Eff es ~> Eff (es' ++ es)
-- | The type of an IO effect handler, which is a function
-- that transforms an effect e into IO computations. This
-- is used for interpretIO.
type HandlerIO e es = forall esSend. Handling esSend e es => e (Eff esSend) ~> IO
-- | Interpret an effect in terms of IO, by transforming an effect
-- into IO computations.
--
--
-- interpretIO f = interpret (liftIO . f)
--
interpretIO :: IOE :> es => HandlerIO e es -> Eff (e : es) ~> Eff es
-- | The type of a simple transformation function from effect e to
-- e'.
type Translator e e' = forall esSend. e (Eff esSend) ~> e' (Eff esSend)
-- | Interpret an effect in terms of another effect in the stack via a
-- simple Translator.
--
--
-- transform trans = interpret (sendVia toEff . trans)
--
transform :: forall e e' es. e' :> es => Translator e e' -> Eff (e : es) ~> Eff es
-- | Like transform, but instead of using an effect in stack, add a
-- new one to the top of it.
--
--
-- translate trans = reinterpret (sendVia toEff . trans)
--
translate :: forall e e' es. Translator e e' -> Eff (e : es) ~> Eff (e' : es)
-- | Like raise, but adds the new effect under the top effect. This
-- is useful for transforming an interpreter e' :> es =>
-- Eff (e ': es) ~> Eff es into a
-- reinterpreter Eff (e ': es) ~> Eff (e' ':
-- es):
--
--
-- myInterpreter :: Bar :> es => Eff (Foo ': es) ~> Eff es
-- myInterpreter = ...
--
-- myReinterpreter :: Eff (Foo ': es) ~> Eff (Bar ': es)
-- myReinterpreter = myInterpreter . raiseUnder
--
--
-- In other words,
--
--
-- reinterpret h == interpret h . raiseUnder
--
--
-- However, note that this function is suited for transforming an
-- existing interpreter into a reinterpreter; if you want to define a
-- reinterpreter from scratch, you should still prefer
-- reinterpret, which is both easier to use and more efficient.
raiseUnder :: forall e' e es. Eff (e : es) ~> Eff (e : (e' : es))
-- | Like raiseUnder, but allows introducing multiple effects. This
-- function requires TypeApplications.
raiseNUnder :: forall es' e es. KnownList es' => Eff (e : es) ~> Eff (e : (es' ++ es))
-- | Like raiseUnder, but allows introducing the effect under
-- multiple effects. This function requires TypeApplications.
raiseUnderN :: forall e es' es. KnownList es' => Eff (es' ++ es) ~> Eff (es' ++ (e : es))
-- | A generalization of both raiseUnderN and raiseNUnder,
-- allowing introducing multiple effects under multiple effects. This
-- function requires TypeApplications and is subject to serious
-- type ambiguity; you most likely will need to supply all three type
-- variables explicitly.
raiseNUnderN :: forall es'' es' es. (KnownList es', KnownList es'') => Eff (es' ++ es) ~> Eff (es' ++ (es'' ++ es))
-- | The typeclass that denotes a handler scope, handling effect e
-- sent from the effect stack esSend in the effect stack
-- es.
--
-- You should not define instances for this typeclass whatsoever.
class Handling esSend e es | esSend -> e es
-- | Run a computation in the current effect stack. This is useful for
-- interpreting higher-order effects, like a bracketing effect:
--
--
-- data Resource m a where
-- Bracket :: m a -> (a -> m ()) -> (a -> m b) -> Resource m b
--
--
--
-- Bracket alloc dealloc use ->
-- bracket
-- (toEff alloc)
-- (toEff . dealloc)
-- (toEff . use)
--
toEff :: Handling esSend e es => Eff esSend ~> Eff es
-- | Run a computation in the current effect stack, but handles the current
-- effect inside the computation differently by providing a new
-- Handler. This is useful for interpreting effects with local
-- contexts, like Local:
--
--
-- runReader :: r -> Eff (Reader r ': es) ~> Eff es
-- runReader x = interpret (handle x)
-- where
-- handle :: r -> Handler (Reader r) es
-- handle r = \case
-- Ask -> pure r
-- Local f m -> toEffWith (handle $ f r) m
--
toEffWith :: forall esSend e es. Handling esSend e es => Handler e es -> Eff esSend ~> Eff es
-- | Temporarily gain the ability to lift some Eff es
-- actions into Eff esSend. This is useful for dealing
-- with effect operations with the monad type in the negative position,
-- which means it's unlikely that you need to use this function in
-- implementing your effects.
withFromEff :: Handling esSend e es => ((Eff es ~> Eff esSend) -> Eff esSend a) -> Eff es a
-- | Temporarily gain the ability to unlift an Eff esSend
-- computation into IO. This is useful for dealing with
-- higher-order effects that involves IO.
withToIO :: (Handling esSend e es, IOE :> es) => ((Eff esSend ~> IO) -> IO a) -> Eff es a
-- | Lift an IO computation into Eff esSend. This is
-- useful for dealing with effect operations with the monad type in the
-- negative position within IOE, like masking.
fromIO :: (Handling esSend e es, IOE :> es) => IO ~> Eff esSend
-- | The type of natural transformations from functor f to
-- g.
type (f :: k -> Type) ~> (g :: k -> Type) = forall (a :: k). () => f a -> g a
infixr 0 ~>
-- | Type level list concatenation.
type family (xs :: [a]) ++ (ys :: [a]) :: [a]
infixr 5 ++
-- | 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
-- | Monads which allow their actions to be run in IO.
--
-- While MonadIO allows an IO action to be lifted into
-- another monad, this class captures the opposite concept: allowing you
-- to capture the monadic context. Note that, in order to meet the laws
-- given below, the intuition is that a monad must have no monadic state,
-- but may have monadic context. This essentially limits
-- MonadUnliftIO to ReaderT and IdentityT
-- transformers on top of IO.
--
-- Laws. For any value u returned by askUnliftIO, it must
-- meet the monad transformer laws as reformulated for
-- MonadUnliftIO:
--
--
--
-- Instances of MonadUnliftIO must also satisfy the idempotency
-- law:
--
--
--
-- This law showcases two properties. First, askUnliftIO doesn't
-- change the monadic context, and second, liftIO . unliftIO u
-- is equivalent to id IF called in the same monadic context as
-- askUnliftIO.
class MonadIO m => MonadUnliftIO (m :: Type -> Type)
-- | Convenience function for capturing the monadic context and running an
-- IO action with a runner function. The runner function is used
-- to run a monadic action m in IO.
withRunInIO :: MonadUnliftIO m => ((forall a. () => m a -> IO a) -> IO b) -> m b
module Cleff.Error
-- | An effect capable of breaking out of current control flow by raising
-- an exceptional value e. This effect roughly corresponds to
-- the MonadError typeclass and ExceptT monad
-- transformer in mtl.
data Error e :: Effect
[ThrowError] :: e -> Error e m a
[CatchError] :: m a -> (e -> m a) -> Error e m a
throwError :: Error e_afOw :> es_afTC => e_afOw -> Eff es_afTC a_afOy
catchError :: Error e_afOB :> es_afTz => Eff es_afTz a_afOA -> (e_afOB -> Eff es_afTz a_afOA) -> Eff es_afTz a_afOA
-- | Lift an Either value into the Error effect.
fromEither :: Error e :> es => Either e a -> Eff es a
-- | Lift exceptions generated by an IO computation into the
-- Error effect.
fromException :: forall e es a. (Exception e, '[Error e, IOE] :>> es) => IO a -> Eff es a
-- | Like fromException, but allows to transform the exception into
-- another error type.
fromExceptionVia :: (Exception ex, '[Error er, IOE] :>> es) => (ex -> er) -> IO a -> Eff es a
-- | Lift exceptions generated by an Eff computation into the
-- Error effect.
fromExceptionEff :: forall e es a. (Exception e, '[Error e, IOE] :>> es) => Eff es a -> Eff es a
-- | Like fromExceptionEff, but allows to transform the exception
-- into another error type.
fromExceptionEffVia :: (Exception ex, '[Error er, IOE] :>> es) => (ex -> er) -> Eff es a -> Eff es a
-- | Try to extract a value from Maybe, throw an error otherwise.
note :: Error e :> es => e -> Maybe a -> Eff es a
-- | A variant of catchError that allows a predicate to choose
-- whether to catch (Just) or rethrow (Nothing) the error.
catchErrorJust :: Error e :> es => (e -> Maybe b) -> Eff es a -> (b -> Eff es a) -> Eff es a
-- | A variant of catchError that allows a predicate to choose
-- whether to catch (True) or rethrow (False) the error.
catchErrorIf :: Error e :> es => (e -> Bool) -> Eff es a -> (e -> Eff es a) -> Eff es a
-- | Flipped version of catchError.
handleError :: Error e :> es => (e -> Eff es a) -> Eff es a -> Eff es a
-- | Flipped version of catchErrorJust.
handleErrorJust :: Error e :> es => (e -> Maybe b) -> (b -> Eff es a) -> Eff es a -> Eff es a
-- | Flipped version of catchErrorIf.
handleErrorIf :: Error e :> es => (e -> Bool) -> (e -> Eff es a) -> Eff es a -> Eff es a
-- | Runs a computation, returning a Left value if an error was
-- thrown.
tryError :: Error e :> es => Eff es a -> Eff es (Either e a)
-- | A variant of tryError that allows a predicate to choose whether
-- to catch (True) or rethrow (False) the error.
tryErrorJust :: Error e :> es => (e -> Maybe b) -> Eff es a -> Eff es (Either b a)
-- | Run an Error effect.
--
-- Caveat: runError is implemented with Exceptions
-- therefore inherits some of its unexpected behaviors. Errors thrown in
-- forked threads will not be directly caught by
-- catchErrors in the parent thread. Instead it will incur an
-- exception, and we won't be quite able to display the details of that
-- exception properly at that point. Therefore please properly handle the
-- errors in the forked threads separately.
--
-- However if you use async and wait for the action in
-- the same effect scope (i.e. they get to be interpreted by the same
-- runError handler), the error will be caught in the
-- parent thread even if you don't deal with it in the forked thread. But
-- if you passed the Async value out of the effect scope and
-- waited for it elsewhere, the error will again not be caught.
-- The best choice is not to pass Async values around
-- randomly.
runError :: forall e es a. Eff (Error e : es) a -> Eff es (Either e a)
-- | Transform an Error into another. This is useful for aggregating
-- multiple errors into one type.
mapError :: forall e e' es. Error e' :> es => (e -> e') -> Eff (Error e : es) ~> Eff es
instance GHC.Exception.Type.Exception Cleff.Error.ErrorExc
instance GHC.Show.Show Cleff.Error.ErrorExc
module Cleff.Fail
-- | An effect that expresses failure with a message. This effect allows
-- the use of the MonadFail class.
data Fail :: Effect
[Fail] :: String -> Fail m a
-- | Run a Fail effect in terms of Error.
runFail :: Eff (Fail : es) a -> Eff es (Either String a)
-- | Run a Fail effect in terms of throwing exceptions in IO.
runFailIO :: IOE :> es => Eff (Fail : es) ~> Eff es
instance (Cleff.Fail.Fail Cleff.Internal.Effect.:> es) => Control.Monad.Fail.MonadFail (Cleff.Internal.Monad.Eff es)
module Cleff.Mask
-- | An effect capable of masking and specifically,
-- bracketing operations, i.e. allowing cleanup after
-- operations that my raise exceptions.
data Mask :: Effect
[Mask] :: ((m ~> m) -> m a) -> Mask m a
[UninterruptibleMask] :: ((m ~> m) -> m a) -> Mask m a
[Bracket] :: m a -> (a -> m c) -> (a -> m b) -> Mask m b
[BracketOnError] :: m a -> (a -> m c) -> (a -> m b) -> Mask m b
mask :: Mask :> es_ahLi => ((~>) (Eff es_ahLi) (Eff es_ahLi) -> Eff es_ahLi a_ahI8) -> Eff es_ahLi a_ahI8
uninterruptibleMask :: Mask :> es_ahLg => ((~>) (Eff es_ahLg) (Eff es_ahLg) -> Eff es_ahLg a_ahIa) -> Eff es_ahLg a_ahIa
bracket :: Mask :> es_ahLc => Eff es_ahLc a_XhId -> (a_XhId -> Eff es_ahLc c_XhIf) -> (a_XhId -> Eff es_ahLc b_ahIe) -> Eff es_ahLc b_ahIe
bracketOnError :: Mask :> es_ahL8 => Eff es_ahL8 a_XhIh -> (a_XhIh -> Eff es_ahL8 c_XhIj) -> (a_XhIh -> Eff es_ahL8 b_ahIi) -> Eff es_ahL8 b_ahIi
-- | Variant of mask that does not provide a restoring function.
mask_ :: Mask :> es => Eff es a -> Eff es a
-- | Variant of uninterruptibleMask that does not provide a
-- restoring function.
uninterruptibleMask_ :: Mask :> es => Eff es a -> Eff es a
-- | Variant of bracket that does not pass the allocated resource to
-- the cleanup action.
bracket_ :: Mask :> es => Eff es a -> Eff es c -> (a -> Eff es b) -> Eff es b
-- | Attach a cleanup action that will always run to a potentially throwing
-- computation.
finally :: Mask :> es => Eff es a -> Eff es b -> Eff es a
-- | Attach an action that runs if the main computation throws an
-- exception.
onError :: Mask :> es => Eff es a -> Eff es b -> Eff es a
-- | Interpret the Mask effect in terms of primitive IO
-- actions.
runMask :: Eff (Mask : es) ~> Eff es
module Cleff.Reader
-- | An effect capable of providing an immutable environment r
-- that can be read. This roughly corresponds to the MonadReader
-- typeclass and ReaderT monad transformer in the mtl
-- approach.
data Reader r :: Effect
[Ask] :: Reader r m r
[Local] :: (r -> r) -> m a -> Reader r m a
ask :: Reader r_ainM :> es_aipp => Eff es_aipp r_ainM
local :: Reader r_ainO :> es_aipm => (r_ainO -> r_ainO) -> Eff es_aipm a_ainQ -> Eff es_aipm a_ainQ
-- | Apply a function on the result of ask.
asks :: Reader r :> es => (r -> s) -> Eff es s
-- | Run a Reader effect with a given environment value.
runReader :: r -> Eff (Reader r : es) ~> Eff es
-- | Run a Reader effect in terms of a larger Reader via a
-- Lens'.
magnify :: Reader t :> es => Lens' t r -> Eff (Reader r : es) ~> Eff es
module Cleff.State
-- | An effect capable of providing a mutable state s that can be
-- read and written. This roughly corresponds to the MonadState
-- typeclass and StateT monad transformer in the mtl
-- approach.
data State s :: Effect
[Get] :: State s m s
[Put] :: s -> State s m ()
[State] :: (s -> (a, s)) -> State s m a
get :: State s_aiUI :> es_aiWU => Eff es_aiWU s_aiUI
put :: State s_aiUK :> es_aiWS => s_aiUK -> Eff es_aiWS ()
state :: State s_aiUM :> es_aiWQ => (s_aiUM -> (a_aiUN, s_aiUM)) -> Eff es_aiWQ a_aiUN
-- | Apply a function to the result of get.
gets :: State s :> es => (s -> t) -> Eff es t
-- | Modify the value of the state via a function.
modify :: State s :> es => (s -> s) -> Eff es ()
-- | Run the State effect.
--
-- Caveat: The runState interpreter is implemented with
-- IORefs and there is no way to do arbitrary atomic transactions.
-- The state operation is atomic though and it is implemented with
-- atomicModifyIORefCAS, which can be faster than
-- atomicModifyIORef in contention. For any more complicated
-- cases of atomicity, please build your own effect that uses either
-- MVars or TVars based on your need.
--
-- Unlike mtl, in cleff the state will not
-- revert when an error is thrown.
--
-- runState will stop taking care of state operations done on
-- forked threads as soon as the main thread finishes its computation.
-- Any state operation done before main thread finishes is still
-- taken into account.
runState :: s -> Eff (State s : es) a -> Eff es (a, s)
-- | Run the State effect in terms of operations on a supplied
-- IORef. The state operation is atomic.
runStateIORef :: IOE :> es => IORef s -> Eff (State s : es) a -> Eff es a
-- | Run the State effect in terms of operations on a supplied
-- MVar.
runStateMVar :: IOE :> es => MVar s -> Eff (State s : es) a -> Eff es a
-- | Run the State effect in terms of operations on a supplied
-- TVar.
runStateTVar :: IOE :> es => TVar s -> Eff (State s : es) a -> Eff es a
-- | Run a State effect in terms of a larger State via a
-- Lens'.
zoom :: State t :> es => Lens' t s -> Eff (State s : es) ~> Eff es
module Cleff.Input
-- | An effect that is capable of reading from some input source, such as
-- an input stream.
data Input i :: Effect
[Input] :: Input i m i
input :: Input i_ajZM :> es_ak0v => Eff es_ak0v i_ajZM
-- | Apply a function to the result of input.
inputs :: Input i :> es => (i -> i') -> Eff es i'
-- | Run an Input effect by giving a constant input value.
runInputConst :: i -> Eff (Input i : es) ~> Eff es
-- | Run an Input effect by going through a list of values.
inputToListState :: Eff (Input (Maybe i) : es) ~> Eff (State [i] : es)
-- | Run an Input in terms of a Reader.
inputToReader :: Eff (Input i : es) ~> Eff (Reader i : es)
-- | Run an Input effect by performing a computation for each input
-- request.
runInputEff :: Eff es i -> Eff (Input i : es) ~> Eff es
-- | Transform an Input effect into another one already in the
-- effect stack, by a pure function.
mapInput :: Input i' :> es => (i' -> i) -> Eff (Input i : es) ~> Eff es
-- | Transform an Input effect into another one already in the
-- effect stack, by an effectful computation.
bindInput :: Input i' :> es => (i' -> Eff es i) -> Eff (Input i : es) ~> Eff es
module Cleff.Fresh
-- | An effect capable of generating unique values. This effect can be
-- useful in generating variable indices.
data Fresh u :: Effect
[Fresh] :: Fresh u m u
fresh :: Fresh u_akl5 :> es_aklO => Eff es_aklO u_akl5
-- | Interpret a Fresh Int effect in terms of
-- State Int. This is a specialized version of
-- freshEnumToState.
freshIntToState :: Eff (Fresh Int : es) ~> Eff (State Int : es)
-- | Interpret a Fresh Int effect in terms of a
-- AtomicCounter. This is usually faster than
-- runFreshUnique.
runFreshAtomicCounter :: Eff (Fresh Int : es) ~> Eff es
-- | Interpret a Fresh Unique effect in terms of IO
-- actions. This is slower than runFreshAtomicCounter, but it
-- won't overflow on maxBound :: Int.
runFreshUnique :: IOE :> es => Eff (Fresh Unique : es) ~> Eff es
module Cleff.Writer
-- | An effect capable of accumulating outputs. This roughly corresponds to
-- the MonadWriter typeclass and WriterT monad
-- transformer in the mtl approach.
--
-- However, note that this does not have a pass operation as we
-- are not sure what its semantics should be. In fact, the pass
-- semantics in mtl is also unclear and will change when
-- handlers are put in different orders. To avoid any confusion we
-- decided it is best that we don't include it because no one seems to be
-- relying on it anyway.
data Writer w :: Effect
[Tell] :: w -> Writer w m ()
[Listen] :: m a -> Writer w m (a, w)
tell :: Writer w_akDu :> es_akF1 => w_akDu -> Eff es_akF1 ()
listen :: Writer w_akDy :> es_akEZ => Eff es_akEZ a_XkDy -> Eff es_akEZ (a_XkDy, w_akDy)
-- | Apply a function to the accumulated output of listen.
listens :: Writer w :> es => (w -> x) -> Eff es a -> Eff es (a, x)
-- | Run a monoidal Writer effect.
--
-- Caveat: Both runWriter and listens under
-- runWriter will stop taking care of writer operations done on
-- forked threads as soon as the main thread finishes its computation.
-- Any writer operation done before main thread finishes is still
-- taken into account.
runWriter :: forall w es a. Monoid w => Eff (Writer w : es) a -> Eff es (a, w)
-- | Run a monoidal Writer effect, but appends the listened output
-- to the parent value only when the listen operation finishes. This
-- means that when you run two listens on two threads, the values
-- telled inside will not be appended to the parent value in real
-- time, but only after the thread finishes listening. For
-- example, this code
--
--
-- concurrently_
-- (listen $ tell "1" >> tell "2" >> tell "3")
-- (listen $ tell "4" >> tell "5" >> tell "6")
--
--
-- will produce either "123456" or "456123" with
-- runWriterBatch, but may produce these digits in any order with
-- runWriter.
--
-- This version of interpreter can be faster than runWriter in
-- listen-intense code. It is subject to all caveats of
-- runWriter.
runWriterBatch :: forall w es a. Monoid w => Eff (Writer w : es) a -> Eff es (a, w)
module Cleff.Output
-- | An effect that is capable of sending outputs, for example to a log
-- file or an output stream.
data Output o :: Effect
[Output] :: o -> Output o m ()
output :: Output o_alnz :> es_alol => o_alnz -> Eff es_alol ()
-- | Run an Output effect by accumulating a list. Note that outputs
-- are being prepended to the head of the list, so in many cases you
-- would want to reverse the result.
outputToListState :: Eff (Output o : es) ~> Eff (State [o] : es)
-- | Run an Output effect by translating it into a Writer.
outputToWriter :: (o -> o') -> Eff (Output o : es) ~> Eff (Writer o' : es)
-- | Ignore outputs of an Output effect altogether.
ignoreOutput :: Eff (Output o : es) ~> Eff es
-- | Run an Output effect by performing a computation for each
-- output.
runOutputEff :: (o -> Eff es ()) -> Eff (Output o : es) ~> Eff es
-- | Transform an Output effect into another one already in the
-- effect stack, by a pure function.
mapOutput :: Output o' :> es => (o -> o') -> Eff (Output o : es) ~> Eff es
-- | Transform an Input effect into another one already in the
-- effect stack, by an effectful computation.
bindOutput :: Output o' :> es => (o -> Eff es o') -> Eff (Output o : es) ~> Eff es
module Cleff.Trace
-- | An effect capable of logging messages, mostly for debugging purposes.
data Trace :: Effect
[Trace] :: String -> Trace m ()
trace :: Trace :> es_alKz => String -> Eff es_alKz ()
-- | Run the Trace effect by writing to a Handle.
runTraceHandle :: IOE :> es => Handle -> Eff (Trace : es) a -> Eff es a
-- | Run the Trace effect by writing to stdout.
runTraceStdout :: IOE :> es => Eff (Trace : es) ~> Eff es
-- | Run the Trace effect by writing to stderr.
runTraceStderr :: IOE :> es => Eff (Trace : es) ~> Eff es
-- | Run the Trace effect by ignoring all outputs altogether.
ignoreTrace :: Eff (Trace : es) ~> Eff es
-- | Transform the Trace effect into an Output
-- String effect.
traceToOutput :: Eff (Trace : es) ~> Eff (Output String : es)