Polysemy.Final.MTL

An effect for embedding higher-order actions in the final target monad of the effect stack.

This is very useful for writing interpreters that interpret higher-order effects in terms of the final monad.

Final is more powerful than Embed, but is also less flexible to interpret (compare runEmbedded with finalToFinal). If you only need the power of embed, then you should use Embed instead.

Beware: Final actions are interpreted as actions of the final monad, and the effectful state visible to withWeavingToFinal / withStrategicToFinal / interpretFinal is that of all interpreters run in order to produce the final monad.

This means that any interpreter built using Final will not respect local/global state semantics based on the order of interpreters run. You should signal interpreters that make use of Final by adding a -Final suffix to the names of these.

State semantics of effects that are not interpreted in terms of the final monad will always appear local to effects that are interpreted in terms of the final monad.

State semantics between effects that are interpreted in terms of the final monad depend on the final monad. For example, if the final monad is a monad transformer stack, then state semantics will depend on the order monad transformers are stacked.

Strategic is an environment in which you're capable of explicitly threading higher-order effect states to the final monad. This is a variant of Tactics (see Tactical), and usage is extremely similar.

Allows for embedding higher-order actions of the final monad by providing the means of explicitly threading effects through Sem r to the final monad.

Consider using withStrategicToFinal instead, which provides a more user-friendly interface, but is also slightly weaker.

You are discouraged from using withWeavingToFinal directly in application code, as it ties your application code directly to the final monad.

Given natural transformations between m1 and m2, run a Final m1 effect by transforming it into a Final m2 effect.

Like interpretH, but may be used to interpret higher-order effects in terms of the final monad.

interpretFinal requires less boilerplate than using interpretH together with withStrategicToFinal / withWeavingToFinal, but is also less powerful. interpretFinal does not provide any means of executing actions of Sem r as you interpret each action, and the provided interpreter is automatically recursively used to process higher-order occurences of Sem (e ': r) to Sem r.

If you need greater control of how the effect is interpreted, use interpretH together with withStrategicToFinal / withWeavingToFinal instead.

Beware: Effects that aren't interpreted in terms of the final monad will have local state semantics in regards to effects interpreted using interpretFinal. See Final.

Lifts a monadic action into the stateful environment, in terms of the final monad. The stateful environment will be the same as the one that the Strategy is initially run in.

Use bindS if you'd prefer to explicitly manage your stateful environment.

Embed a kleisli action into the stateful environment, in terms of the final monad. You can use bindS to get an effect parameter of the form a -> n b into something that can be used after calling runS on an effect parameter n a.

Get the stateful environment of the world at the moment the Strategy is to be run.

Prefer pureS, liftS, runS, or bindS instead of using this function directly.

Lifts an action of the final monad into Strategic.

Note: you don't need to use this function if you already have a monadic action with the functorial state threaded into it, by the use of runS or bindS. In these cases, you need only use pure to embed the action into the Strategic environment.

Get a natural transformation capable of potentially inspecting values inside of f. Binding the result of getInspectorS produces a function that can sometimes peek inside values returned by bindS.

This is often useful for running callback functions that are not managed by polysemy code.

See also getInspectorT

Allows for embedding higher-order actions of the final monad by providing the means of explicitly threading effects through Sem r to the final monad. This is done through the use of the Strategic environment, which provides runS and bindS.

You are discouraged from using withStrategicToFinal in application code, as it ties your application code directly to the final monad.

withWeavingToFinal admits an implementation of embed.

Just like embed, you are discouraged from using this in application code.

Transform an Embed m effect into a Final m effect

Lower a Sem containing only a single lifted, final Monad into that monad.

If you also need to process an Embed m effect, use this together with embedToFinal.

Embed a value into Strategic.

This represents a function which produces an action of the final monad m given:

• The initial effectful state at the moment the action is to be executed.

• A way to convert z (which is typically Sem r) to m by threading the effectful state through.

• An inspector that is able to view some value within the effectful state if the effectful state contains any values.

A Weaving provides these components, hence the name ThroughWeavingToFinal.

Run an Error effect through a final MonadError

Beware: Effects that aren't interpreted in terms of the final monad will have local state semantics in regards to Error effects interpreted this way. See Final.

Run a Reader effect through a final MonadReader

Beware: Effects that aren't interpreted in terms of the final monad will have local state semantics in regards to Reader effects interpreted this way. See Final.

Run a State effect in terms of an underlying MonadState instance

Although this is not a Final interpreter, as the target monad need not actually be the final monad, stateToEmbed still possesses the unusual semantics of interpreters that runs effects by embedding them into another monad.

Beware: Effects that aren't interpreted in terms of the embedded monad will have local state semantics in regards to State effects interpreted this way. See Final.

Run a Writer effect through a final MonadWriter

Beware: Effects that aren't interpreted in terms of the final monad will have local state semantics in regards to Writer effects interpreted this way. See Final.