All eff computations operate in the Eff monad. Eff computations are parameterized by a type-level list that specifies which effects they are allowed to perform. For example, a computation of type Eff '[Error e, Reader r, State s] a can raise exceptions of type e, can access a global environment of type r, and can read and modify a single cell of mutable state of type s.

To run an Eff computation that performs effects, the effects must be explicitly handled. Functions that handle effects are called effect handlers, and they usually have types like the following:

runX :: Eff (X ': effs) a -> Eff effs a

Note that the argument to runX can perform the X effect, but the result cannot! Any X operations have been handled by runX, which interprets their meaning. Examples of effect handlers include runError, runReader, and runState.

After all effects have been handled, the resulting computation will have type Eff '[] a, a computation that performs no effects. A computation with this type is pure, so it can be converted to an ordinary value using run.

Some effects cannot be handled locally, but instead require performing I/O. These effects will delegate to the IOE effect, which provides low-level interop with Haskell’s built-in IO monad. After all other effects have been handled, a computation of type Eff '[IOE] a can be converted to an ordinary IO a computation using runIO.

Runs a pure Eff computation to produce a value.

>>> run $ pure 42
42
>>> run $ runError $ throw "bang"
Left "bang"

Lifts an Eff computation into one that performs all the same effects, and possibly more. For example, if you have a computation

m :: Eff '[Foo, Bar] ()

then lift will transform it into a polymorphic computation with the following type:

lift m :: (Foo :< effs, Bar :< effs) => Eff effs ()

This type is much more general, and effs can now be instantiated at many different types. Generally, lift can manipulate the list of effects in any of the following ways:

• Effects can be reordered.
• New effects can be inserted anywhere in the list.
• Duplicate effects can be collapsed.

More generally, the list of effects doesn’t need to be entirely concrete in order for lift to work. For example, if you have a computation

n :: Eff (Foo ': Bar ': effs1) ()

then lift n will have the following type:

lift n :: (Foo :< effs2, Bar :< effs2, effs1 :<< effs2) => Eff effs2 ()

This type is extremely general, and it allows lift to manipulate the head of the effects list even if the entire list is not completely known.

The Lift typeclass provides some type-level programming machinery to implement lift, but it should be treated as an implementation detail. In most situations, the machinery should “just work,” but if it doesn’t, the type errors can be somewhat inscrutable. In those situations, adding some explicit type annotations (or using TypeApplications) can improve the type errors significantly.

Like lift, but restricted to introducing a single additional effect in the result. This is behaviorally identical to just using lift, but the restricted type can produce better type inference.

The kind of effects.

The simplest way to handle an effect. Each use of send for the handled effect dispatches to the handler function, which provides an interpretation for the operation. The handler function may handle the operation directly, or it may defer to other effects currently in scope.

Most effect handlers should be implemented using interpret, possibly with the help of additional Error or State effects. Especially complex handlers can be defined via the more general handle, which interpret is defined in terms of:

interpret f = handle (liftH . f)

The monad that effect handlers run in.

• The eff parameter is the effect being handled, and the effs parameter includes the other effects in scope at the point of the handle call (used by liftH).
• The i parameter is the return type of the handled computation before the exit handler has been applied (used by control0).
• The r parameter is the final return type of the handled computation (used by abort, control, and control0).
• The effs' parameter is the list of effects in scope at the point of the originating send call (used by locally).

See handle for more details.

Handles the topmost effect in an Eff computation. The given handler function must provide an interpretation for each effectful operation. The handler runs in the restrictive Handle monad, which generally uses one of the following core Handle operations:

• liftH — Runs an action in the context of the original handle call. This is the most common way to handle an effect.
• abort — Aborts the computation to the handle call and returns a value directly. This is usually used to implement exception-like operations.
• control — Captures the current continuation up to and including the handle call and aborts, passing the captured continuation to the handler. This can be used to implement complex control operators such as coroutines or resumable exceptions.
• control0 — Like control, but does not include the handle call itself in the captured continuation, so a different handler may be installed before resuming the computation.
• locally — Runs an action directly in the context of the originating send call. This can be used to implement “scoped” operations like local and catch.

See the documentation for each of the above functions for examples and more details.

An effect used to run IO operations via liftIO. Handled by the special runIO handler.

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)

Converts an Eff computation to IO. Unlike most handlers, IOE must be the final effect handled, and runIO completely replaces the call to run.