The extensible effects monad. The 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.

The best practice is to always use a polymorphic type variable for the effect stack es, and then use the type operators (:>) and (:>>) in constraints to indicate what effects are available in the stack. For example,

(Reader String :> es, State Bool :> es) => Eff es Integer

means you can perform operations of the Reader String effect and the State Bool effect in a computation returning an Integer. The reason why you should always use a polymorphic effect stack as opposed to a concrete list of effects are that

• it can contain other effects that are used by computations other than the current one, and
• it does not require you to run the effects in any particular order.

e :> es means the effect e is present in the effect stack es, and therefore can be sended 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 capable of 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 directly in application code, as it is too liberal and allows arbitrary IO, therefore making it harder to do proper effect management. Ideally, this is only used in interpreting more fine-grained effects.

Technical details

Note that this is not a real effect and cannot be interpreted in any way besides thisIsPureTrustMe and runIOE. 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 largely generalized version of send; only use this if you are sure about what you're doing.

send = sendVia id

Since: 0.2.0.0

For a datatype T representing an effect, makeEffect T generates function defintions for performing the operations of T via send. For example,

makeEffect ''Filesystem

generates the following definitions:

readFile      :: Filesystem :> es => FilePath -> Eff es String
readFile  x   =  send (ReadFile x)
writeFile     :: Filesystem :> es => FilePath -> String -> Eff es ()
writeFile x y =  send (WriteFile x y)

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.

Technical details

This function is also "weaker" than polysemy's makeSem, because this function cannot properly handle some cases involving ambiguous types. Those cases are rare, though. See the ThSpec test spec 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.

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

es is a subset of es', i.e. all elements of es are in 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' to the stack 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, but does not eliminate it from the stack. This means you can re-send the operations in the effect handler; it is often useful when you need to "intercept" operations so you can add extra behaviors like logging.

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.

Since: 0.2.0.0

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

Since: 0.2.0.0

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

Since: 0.2.0.0

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.

Since: 0.2.0.0

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. For example, if you want to interpret a bracketing effects in terms of IO:

data Resource m a where
  Bracket :: m a -> (a -> m ()) -> (a -> m b) -> Resource m b

You will not be able to simply write this for the effect:

runBracket :: IOE :> es => Eff (Resource : es) a -> Eff es a
runBracket = interpret \case
  Bracket alloc dealloc use -> UnliftIO.bracket alloc dealloc use

This is because effects are sended from all kinds of stacks that has Resource in it, so effect handlers received the effect as Resource esSend a, where esSend is an arbitrary stack with Resource, instead of Resource es a. This means alloc, dealloc and use are of type Eff esSend a, while bracket can only take and return Eff es a. So we need to use toEff, which converts an Eff esSend a into an Eff es a:

runBracket :: IOE :> es => Eff (Resource : es) a -> Eff es a
runBracket = interpret \case
  Bracket alloc dealloc use -> UnliftIO.bracket
    (toEff alloc)
    (toEff . dealloc)
    (toEff . use)

Run a computation in the current effect stack, just like toEff, but takes a Handler of the current effect being interpreted, so that inside the computation being ran, the effect is interpreted differently. 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 only 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 analogous to withRunInIO, and is useful in dealing with higher-order effects that involves IO. For example, the Resource effect that supports bracketing:

data Resource m a where
  Bracket :: m a -> (a -> m ()) -> (a -> m b) -> Resource m b

can be interpreted into bracket actions in IO, by converting all effect computations into IO computations via withToIO:

runResource :: IOE :> es => Eff (Resource : es) a -> Eff es a
runResource = interpret \case
  Bracket alloc dealloc use -> withToIO $ \toIO ->
    bracket (toIO alloc) (toIO . dealloc) (toIO . use)

Lift an IO computation into Eff esSend. This is analogous to liftIO, and is only useful in dealing with effect operations with the monad type in the negative position, for example masking:

data Mask :: Effect where
  Mask :: ((m ~> m) -> m a) -> Mask m a
                 ^ this "m" is in negative position

See how the restore :: IO a -> IO a from mask is "wrapped" into Eff esSend a -> Eff esSend a:

runMask :: IOE :> es => Eff (Mask : es) a -> Eff es a
runMask = interpret \case
  Mask f -> withToIO $ \toIO -> mask $
    \restore -> f (fromIO . restore . toIO)

Here, toIO from withToIO takes an Eff esSend to IO, where it can be passed into the restore function, and the returned IO computation is recovered into Eff with fromIO.

A natural transformation from f to g. With this, instead of writing

runSomeEffect :: Eff (SomeEffect : es) a -> Eff es a

you can write:

runSomeEffect :: Eff (SomeEffect : es) ~> Eff es

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