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.

e :> es means the effect e is present in the effect stack es, and therefore can be used in an Eff es computation.

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

The type of effects. An effect e m a takes an effect monad type m :: Type -> Type and a result type a :: 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.

Unwrap a pure Eff computation into a pure value, given that all effects are interpreted.

Unwrap an Eff computation with side effects into an IO computation, given that all effects other than IOE are interpreted.

Perform an effect operation, i.e. a value of an effect type e :: Effect. This requires e to be in the effect stack.

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

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.

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.

Lift a computation into a bigger effect stack with one more effect. For a more general version see raiseN.

Lift a computation into a bigger effect stack with arbitrarily more effects. This function requires TypeApplications.

Lift a computation with a fixed, known effect stack into some superset of the stack.

Eliminate a duplicate effect from the top of the effect stack. For a more general version see subsumeN.

Eliminate several duplicate effects from the top of the effect stack. This function requires TypeApplications.

The list es list is concrete, i.e. is of the form '[a1, a2, ..., an], i.e. is not a type variable.

es is a subset of es'.

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.

Interpret an effect e in terms of effects in the effect stack es with an effect handler.

Like interpret, but adds a new effect e' that can be used in the handler.

Like reinterpret, but adds two new effects.

Like reinterpret, but adds three new effects.

Like reinterpret, but adds arbitrarily many new effects. This function requires TypeApplications.

Respond to an effect while being able to leave it unhandled (i.e. you can resend the effects in the handler).

Like interpose, but allows to introduce one new effect to use in the handler.

Like impose, but allows introducing arbitrarily many effects. This requires TypeApplications.

The type of an IO effect handler, which is a function that transforms an effect e into IO computations. This is used for interpretIO.

Interpret an effect in terms of IO, by transforming an effect into IO computations.

interpretIO f = interpret (liftIO . f)

The type of a simple transformation function from effect e to e'.

Interpret an effect in terms of another effect in the stack via a simple Translator.

transform trans = interpret (sendVia toEff . trans)

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)

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.

Like raiseUnder, but allows introducing multiple effects. This function requires TypeApplications.

Like raiseUnder, but allows introducing the effect under multiple effects. This function requires TypeApplications.

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.

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.

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)

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

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.

Temporarily gain the ability to unlift an Eff esSend computation into IO. This is useful for dealing with higher-order effects that involves IO.

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.

The type of natural transformations from functor f to g.

Type level list concatenation.

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:

• liftIO . return = return

• liftIO (m >>= f) = liftIO m >>= (liftIO . f)

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:

• unliftIO u . return = return

• unliftIO u (m >>= f) = unliftIO u m >>= unliftIO u . f

Instances of MonadUnliftIO must also satisfy the idempotency law:

• askUnliftIO >>= \u -> (liftIO . unliftIO u) m = m

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.

Since: unliftio-core-0.1.0.0