An ordered sequence of values, each with an associated emission wrapper (default: id).

An emission wrapper.

Map items.

mapItems == fmap

Example:

>>> evenEffect x = if even x then Just () else Nothing
>>> run evenEffect ((+1) <$> embed 3)
Just ()

Add an additional emission wrapper to each b.

The given function composes outside of any existing wrappers.

wrap id          ==  id
wrap (f . g)     ==  wrap f . wrap g

run' (wrap f x)  ==  f <$> (run' x)      where run' = runWith emit

Add an additional emission wrapper to each b.

The given function composes inside of any existing wrappers.

wrapInside id              ==  id
wrapInside (f . g)         ==  wrapInside g . wrapInside f

run emit (wrapInside f x)  ==  run (f . emit) x

Conditional inclusion.

Suppress the effects of emitting the value if an effectful predicate evaluates to False:

run emit (when' (pure False) x)  == pure ()
run emit (when' (pure True ) x)  == run emit x

when' has the distributive and commutation properties as those of wrap.

When emitted, the monadic action will be run once for each element of the internal representation.

Flipped when'.

Binary choice.

When emitted, the monadic action will be run twice for each element of the internal representation.

Constraining to types whose inhabitants can be enumerated with [minBound..maxBound].

Such types are types with a known and finite set of inhabitants, given that their Enum and Bounded instances behave within established social norms.

Evaluation of finite-domain function for the daring.

When emitted, the monadic action will be run once for each element, for each inhabitant of the Enumerable type that the action yields.

Comparing with >>=

The signature can be compared to that of monadic bind (>>=):

byAction :: (Enumerable a, e b ~ Effable m b) =>
            Monad m => m a -> (a -> e b) -> e b
(>>=)    :: Monad m => m a -> (a -> m b) -> m b

A possible interpretation of the two signatures is:

• >>= returns a value-yielding action that may depend on what value some other action yields
• byAction returns a pure Effable that may depend on what value some action yields

Warning: should only be used with types of a few inhabitants

All outcomes of the action are reified in the internal representation. With IO-like monads, there is no short-circuiting; neither will we be saved by laziness - the full internal representation is likely to be forced at emission time.

Bool has two inhabitants so reifying IO Bool is not expensive.

--- GHCi session ---

λ> effable = byAction (pure True) embed

λ> -- make GHCi report evaluation time and allocated bytes:

λ> :set +s

λ> run print effable
True
(ran for 0.01 secs, allocated 1,014,600 bytes)

An Int is Enumerable but has many inhabitants so reifying IO Int becomes costly in both time and allocations.

--- GHCi session ---

λ> ineffable = byAction (pure (1::Int)) embed

λ> :set +s

λ> run print ineffable
1
(ran for 1.02 million years, allocated 3.06e10 gigabytes)

Evaluation of finite-domain value for the daring.

When emitted, the monadic action will be run once for each value of the domain.

(The same warning as that for byAction applies.)

For each b of an Effable, emit it with the given function, then apply the composed emission wrapper associated with that b, and combine all results.

Laws

Monoid homomorphism

run emit mempty    ==  pure ()
run emit (x <> y)  ==  run emit x *> run emit y

Naturality

run emit (f <$> x)  ==  run (emit . f) x

Examples

These examples use Const [] whose emission effect is to accumulate emitted items into a list.

>>> import Data.Functor.Const (Const (..))
>>> emitConst b = Const [b]

>>> run emitConst (embed 'a' <> embed 'b')
Const "ab"

With emission wrapper:

>>> silence = wrap (\_ -> Const [])
>>> run emitConst (embed 'a' <> (silence $ embed 'b') <> embed 'c')
Const "ac"

Create a representation of the individual emission results of an Effable.

Methods of the Foldable and Traversable instances of the result type can be used e.g. to customize how the individual emission results are combined.

sequenceA_ (runWith emit x)  == run emit x

Example

The following uses the foldr method of RunWith's Foldable instance to create a run-like function with a foldr-style API:

>>> :{
  let
    run_foldr
      :: (b -> m ())
      -> (m () -> c -> c)
      -> c
      -> Effable m b
      -> c
    run_foldr emit comb z = foldr comb z . runWith emit
:}