The class of effect carriers, and the underlying mechanism with which effects are implemented.

Each carrier is able to implement a number of derived effects, and primitive effects. Users usually only interact with derived effects, as these determine the effects that users have access to.

The standard interpretation tools are typically powerful enough to let you avoid making instances of this class directly. If you need to make your own instance of Carrier, import Control.Effect.Carrier and consult the wiki.

The kind of effects.

Helpful for defining new effects:

data InOut i o :: Effect where
  Input  :: InOut i o m i
  Output :: o -> InOut i o m ()

RepresentationalEff is the constraint every effect is expected to satisfy: namely, that any effect e m a is representational in m, which -- in practice -- means that no constraints are ever placed upon m within the definion of e, and that m isn't present in the return type of any action of e.

You don't need to make instances of RepresentationalEff; the compiler will automatically infer if your effect satisfies it.

RepresentationalEff is not a very serious requirement, and even effects that don't satisfy it can typically be rewritten into equally powerful variants that do.

If you ever encounter that an effect you've written doesn't satisfy RepresentationalEff, please consult the wiki.

(Morally) a type synonym for (Member e (Derivs m), Carrier m). This and Effs are the typical methods to gain access to effects.

Unlike Member, Eff gives Bundle special treatment. As a side-effect, Eff will get stuck if e is a type variable.

If you need access to some completely polymorphic effect e, use (Member e (Derivs m), Carrier m) instead of Eff e m.

A variant of Eff that takes a list of effects, and expands them into multiple Member constraints on Derivs m. This and Eff are the typical methods to gain access to effects.

Like Eff, Effs gives Bundle special treatment. As a side-effect, Effs will get stuck if any element of the list is a type variable.

If you need access to some completetely polymorphic effect e, use a separate Member e (Derivs m) constraint.

A pseudo-effect given special treatment by Eff and Effs.

An Eff/s constraint on Bundle '[eff1, eff2, ... , effn] will expand it into membership constraints for eff1 through effn. For example:

Error e = Bundle '[Throw e, Catch e]

so

Eff (Error e) m = (Carrier m, Member (Throw e) (Derivs m), Member (Catch e) (Derivs m))

Bundle should never be used in any other contexts but within Eff and Effs, as it isn't an actual effect.

Not to be confused with Union, which is a proper effect that combines multiple effects into one.

A constraint that e is part of the effect row r.

r is typically Derivs m for some m. Member e (Derivs m) allows you to use actions of e with m.

If e occurs multiple times in r, then the first occurence will be used.

If possible, use Eff/s instead.

Perform an action of an effect.

send should be used to create actions of your own effects. For example:

data CheckString :: Effect where
  CheckString :: String -> CheckString m Bool

checkString :: Eff CheckString m => String -> m Bool
checkString str = send (CheckString str)

Extract the final result from a computation of which no effects remain to be handled.

Extract the final monad m from a computation of which no effects remain to be handled except for Embed m.

An effect for embedding actions of a base monad into the current one.

Interpret an effect in terms of other effects, without needing to define an explicit Handler instance. This is an alternative to interpretViaHandler.

See EffHandler for more information about the handler you pass to this function.

Derivs (InterpretSimpleC e m) = e ': Derivs m

Prims  (InterpretSimpleC e m) = Prims m

This is a significantly slower variant of interpret that doesn't have a higher-ranked type, making it much easier to use partially applied.

Note: this emits the threading constraint ReaderThreads (see Threaders). This makes interpretSimple significantly less attractive to use in application code, as it means propagating that constraint through your application.

Example usage:

data Teletype :: Effect where
  ReadTTY  :: Teletype m String
  WriteTTY :: String -> Teletype m ()

readTTY :: Eff Teletype m => m String
readTTY = send ReadTTY

writeTTY :: Eff Teletype m => String -> m ()
writeTTY = send . WriteTTY

echo :: Eff Teletype m => m ()
echo = readTTY >>= sendTTY

teletypeToIO :: Eff (Embed IO) m => SimpleInterpreterFor Teletype m
teletypeToIO = interpretSimple $ \case
  ReadTTY -> embed getLine
  WriteTTY str -> embed $ putStrLn str

main :: IO ()
main = runM $ teletypeToIO $ echo

A useful type synonym for the type of interpretSimple provided a handler

m is left polymorphic so that you may place Eff/s constraints on it.

Interpret an effect in terms of other effects by using an explicit Handler instance.

See Handler for more information.

Unlike interpret, this does not have a higher-rank type, making it easier to use partially applied, and unlike interpretSimple doesn't sacrifice performance.

Derivs (InterpretC h e m) = e ': Derivs m

Prims  (InterpretC h e m) = Prims m

Example usage:

data Teletype :: Effect where
  ReadTTY  :: Teletype m String
  WriteTTY :: String -> Teletype m ()

readTTY :: Eff Teletype m => m String
readTTY = send ReadTTY

writeTTY :: Eff Teletype m => String -> m ()
writeTTY = send . WriteTTY

echo :: Eff Teletype m => m ()
echo = readTTY >>= sendTTY

data TeletypeToIOH

instance Eff (Embed IO) m
      => Handler TeletypeToIOH Teletype m where
  effHandler = \case
    ReadTTY -> embed getLine
    WriteTTY str -> embed $ putStrLn str

type TeletypeToIOC = InterpretC TeletypeToIOH Teletype

teletypeToIO :: Eff (Embed IO) m => TeletypeToIOC m a -> m a
teletypeToIO = interpretViaHandler

main :: IO ()
main = runM $ teletypeToIO $ echo

The class of effect handlers for derived effects. Instances of this class can be used together interpretViaHandler in order to interpret effects.

h is the tag for the handler, e is the effect to interpret, and m is the Carrier on which the handler operates.

To define your own interpreter using this method, create a new datatype without any constructors to serve as the tag for the handler, and then define a Handler instance for it. Then, you can use your handler to interpret effects with interpretViaHandler.

Alternatively, you can use interpret or interpretSimple, which lets you avoid the need to define instances of Handler, but come at other costs.

Interpret an effect in terms of other effects, without needing to define an explicit Handler instance. This is an alternative to interpretViaHandler, and is more performant than interpretSimple.

See EffHandler for more information about the handler you pass to this function.

Derivs (InterpretReifiedC e m) = e ': Derivs m

Prims  (InterpretReifiedC e m) = Prims m

This has a higher-rank type, as it makes use of InterpretReifiedC. This makes interpret very difficult to use partially applied. In particular, it can't be composed using .. You must use paranthesis or $.

Consider using interpretSimple instead if performance is secondary.

Example usage:

data Teletype :: Effect where
  ReadTTY  :: Teletype m String
  WriteTTY :: String -> Teletype m ()

readTTY :: Eff Teletype m => m String
readTTY = send ReadTTY

writeTTY :: Eff Teletype m => String -> m ()
writeTTY = send . WriteTTY

echo :: Eff Teletype m => m ()
echo = readTTY >>= sendTTY

teletypeToIO :: Eff (Embed IO) m => InterpreterFor Teletype m
teletypeToIO = interpret $ \case
  ReadTTY -> embed getLine
  WriteTTY str -> embed $ putStrLn str

main :: IO ()
main = runM $ teletypeToIO $ echo

A useful type synonym for the type of interpret provided a handler

m is left polymorphic so that you may place Eff/s constraints on it.

The type of effect handlers for a derived effect e with current carrier m.

Don't let the type overwhelm you; in most cases, you can treat this as e m x -> m x.

Any EffHandler is required to work with any carrier monad z that lifts m, and has the same derived and primitive effects as m does. The only constraints that are propagated to z are membership constraints: MonadIO m doesn't imply MonadIO z, but Eff (Embed IO) m does imply Eff (Embed IO) z.

In addition, since z lifts m, you can lift values of m to z through liftBase. This is most useful when using interpret or interpretSimple, as it allows you to bring monadic values of m from outside of the handler (like arguments to the interpreter) into the handler.

The z provided to the handler has Effly wrapped around it, so the handler may make use of the various instances of Effly. For example, you have access to MonadFix inside the handler if you have Eff Fix m.

Any effect to be handled needs to be representational in the monad parameter. See RepresentationalEff for more information.

Reinterpret an effect in terms of newly introduced effects.

This combines interpretSimple and introUnder in order to introduce the effects new under e, which you then may make use of inside the handler for e.

Derivs (ReinterpretSimpleC e new m) = e ': StripPrefix new (Derivs m)

Prims  (ReinterpretSimpleC e new m) = Prims m

This is a significantly slower variant of reinterpret that doesn't have a higher-ranked type, making it much easier to use partially applied.

Reinterpret an effect in terms of newly introduced effects by using an explicit Handler instance.

See Handler for more information.

This combines interpretViaHandler and introUnder in order to introduce the effects new under e, which you then may make use of inside the handler for e.

Derivs (ReinterpretC h e new m) = e ': StripPrefix new (Derivs m)

Prims  (ReinterpretC h e new m) = Prims m

Unlike reinterpret, this does not have a higher-rank type, making it easier to use partially applied, and unlike reinterpretSimple doesn't sacrifice performance.

Reinterpret an effect in terms of newly introduced effects.

This combines interpret and introUnder in order to introduce the effects new under e, which you then may make use of inside the handler for e.

Derivs (ReinterpretReifiedC e new m) = e ': StripPrefix new (Derivs m)

Prims  (ReinterpretReifiedC e new m) = Prims m

This has a higher-rank type, as it makes use of ReinterpretReifiedC. This makes reinterpret very difficult to use partially applied. In particular, it can't be composed using .. You must use paranthesis or $.

Consider using reinterpretSimple instead if performance is secondary.

A constraint that Prims m satisfies all the constraints in the list cs.

This is used for threading constraints.

Every interpreter that relies on an underlying non-trivial monad transformer -- such as runState, which uses StateT internally -- must be able to lift all primitive effect handlers of the monad it's transforming so that the resulting transformed monad can also handle the primitive effects.

The ability of a monad transformer to lift handlers of a particular primitive effect is called threading that effect. Threading constraints correspond to the requirement that the primitive effects of the monad that's being transformed can be thread by certain monad transformers.

For example, the runState places the threading constraint StateThreads on Prims m, so that StateC s m can carry all primitive effects that m does.

Threaders is used to handle threading constraints. Threaders '[StateThreads, ExceptThreads] m p allows you to use runState and runError with the carrier m.

Sometimes, you may want to have a local effect which you interpret inside of application code, such as a local State or Error effect. In such cases, try to use split interpretation instead of using interpreters with threading constraints inside of application code. If you can't, then using Threaders is necessary to propagate the threading constraints throughout the application.

The third argument p should always be a polymorphic type variable, which you can simply provide and ignore. It exists as a work-around to the fact that many threading constraints don't actually work if they operate on Prims m directly, since threading constraints often involve quantified constraints, which are fragile in combination with type families -- like Prims.

So Threaders '[StateThreads] m p doesn't expand to StateThreads (Prims m), but rather, (p ~ Prims m, StateThreads p)

The most common threading constraint of the library, as it is emitted by -Simple interpreters (interpreters that internally make use of interpretSimple or reinterpretSimple).

ReaderThreads accepts all the primitive effects (intended to be used as such) offered in this library.

Most notably, ReaderThreads accepts Unlift b.

Introduce an effect at the top of the stack -- or rather, reveal an effect previously hidden.

Derivs (IntroTopC '[e] m) = StripPrefix '[e] (Derivs m)

Prims  (IntroTopC '[e] m) = Prims m

Introduce multiple effects on the top of the effect stack -- or rather, reveal effects previously hidden.

Derivs (IntroTopC new m) = StripPrefix new (Derivs m)

Prims  (IntroTopC new m) = Prims m

Introduce an effect under the top effect of the effect stack -- or rather, reveal that effect which was previously hidden.

Derivs (IntroUnderC e '[new] m) = e ': StripPrefix [e, new] (Derivs m)

Prims  (IntroUnderC e '[new] m) = Prims m

Introduce multiple effects under the top effect of the effect stack -- or rather, reveal those effects which were previously hidden.

Derivs (IntroUnderC e new m) = e ': StripPrefix (e ': new) (Derivs m)

Prims  (IntroUnderC e new m) = Prims m

Introduce multiple effects under a number of top effects of the effect stack -- or rather, reveal those effects which were previously hidden.

Derivs (IntroUnderManyC top new m) = Append top (StripPrefix (Append top new) (Derivs m))

Prims  (IntroUnderManyC top new m) = Prims m

A constraint that the effect stack of m -- Derivs m -- begins with the effect e.

Note that unlike Eff, this does not give Bundle special treatment.

A constraint that the effect stack of m -- Derivs m -- begins with new.

Note that unlike Effs, this does not give Bundle special treatment.

Composition of a list of carrier transformers.

This is useful when you have multiple interpretations whose carriers you'd like to treat as one larger object, such that lift lifts past all those carriers.

For example:

data Counter m a where
  Probe :: Counter m Int

type CounterC = CompositionC
  '[ ReinterpretSimpleC Counter '[State Int]
   , StateC Int
   ]

runCounter :: (Carrier m, Threaders '[StateThreads] m p)
           => CounterC m a
           -> m a
runCounter =
   runState 0
 . reinterpretSimple (case
     Probe -> state' (s -> (s+1,s))
   )
 . runComposition

Then you have lift :: Monad m => m a -> CounterC m a

Transform CompositionC [t1, t2, ..., tn] m a to t1 (t2 (... (tn m) ...)) a

A newtype wrapper with instances based around the effects of m when possible; Effly as in "Effectfully."

This is often useful for making use of these instances inside of interpreter handlers, or within application code.