Documentation

type (:&) :: Effects -> Effects -> Effects

Union of effects

Because doing IO operations inside Eff requires a value-level argument we can't give IO-related instances to Eff directly. Instead we wrap it in EffReader.

Deprecated. Use withEffToIO_ instead.

This is equivalent to the withRunInIO method of MonadUnliftIO, but written in Bluefin-style.

Connect two coroutines. Their execution is interleaved by exchanging as and bs. When the first yields its first a it starts the second (which is awaiting an a).

Old name for consumeStream. receiveStream will be deprecated in a future version.

Run MonadIO operations in Eff.

>>> runEff_ $ \io -> withMonadIO io $ liftIO $ do
      putStrLn "Hello world!"
Hello, world!

Run MonadFail operations in Eff.

>>> runPureEff $ try $ \e ->
      when (2 > 1) $
        withMonadFail e (fail "2 was bigger than 1")
Left "2 was bigger than 1"

This function is really very unsafe and for internal use only. Unlike the similarly-named unsafeEff_ function from effectful, which is provided for use in user code, this function must never be used in user code.

Run an Eff that doesn't contain any unhandled effects.

Used to define dynamic effects.

Used to define dynamic effects.

Like useImpl

Used to define handlers of compound effects.

Deprecated. Use useImplUnder instead.

Handle to a capability to create strict mutable state handles

Handle to an exception of type exn

A handle to a strict mutable state of type s

A handle to a coroutine that yields values of type a and then expects values of type b.

A handle to a stream that yields values of type a. It is implemented as a handle to a coroutine that yields values of type a and then expects values of type ().

You can define a Handle instance for your compound handles. As an example, an "application" handle with a dynamic effect for database queries, a concrete effect for application state and a concrete effect for a logging effect might look like this:

data Application e = MkApplication
  { queryDatabase :: forall e'. String -> Int -> Eff (e' :& e) [String],
    applicationState :: State (Int, Bool) e,
    logger :: Stream String e
  }

To define mapHandle for Application you should apply mapHandle to all the fields that are themeselves handles and apply useImplUnder to all the fields that are dynamic effects:

instance Handle Application where
  mapHandle
    MkApplication
      { queryDatabase = q,
        applicationState = a,
        logger = l
      } =
      MkApplication
        { queryDatabase = s i -> useImplUnder (q s i),
          applicationState = mapHandle a,
          logger = mapHandle l
        }

Effect subset constraint

>>> runPureEff $ try $ \e -> do
      throw e 42
      pure "No exception thrown"
Left 42

>>> runPureEff $ try $ \e -> do
      pure "No exception thrown"
Right "No exception thrown"

>>> runPureEff $ try $ \e -> do
      throw e 42
      pure "No exception thrown"
Left 42

handle, but with the argument order swapped

>>> runPureEff $ handle (pure . show) $ \e -> do
      throw e 42
      pure "No exception thrown"
"42"

Rethrow an exception raised by an IO action as a Bluefin exception.

runEff $ \io -> do
  r <- try $ \ex -> do
    rethrowIO @IOException io ex $ do
      effIO io (readFile "/tmp/doesnt-exist")

  effIO io $ putStrLn $ case r of
    Left e -> "Caught IOException:\n" ++ show e
    Right contents -> contents

Caught IOException:
/tmp/doesnt-exist: openFile: does not exist (No such file or directory)

bracket acquire release body: acquire a resource, perform the body with it, and release the resource even if body threw an exception. This is essentially the same as Control.Exception.bracket, whose documentation you can inspect for further details.

bracket has a very general type that does not require es to contain an exception or IO effect. The reason that this is safe is:

• While bracket does catch exceptions, this is unobservable, since the exception is re-thrown; the cleanup action happens unconditionally; and no part of it gets access to the thrown exception.
• Eff itself is able to guarantee that any exceptions thrown in the body will be actually thrown before bracket exits. This is inherited from the fact that Eff is a wrapper around IO.

While it is usually the case that the cleanup action will in fact want to use IO effects, this is not universally true, see the polymorphicBracket example for an example.

>>> runPureEff $ runState 10 $ \st -> do
      n <- get st
      pure (2 * n)
(20,10)

Set the value of the state

>>> runPureEff $ runState 10 $ \st -> do
      put st 30
((), 30)

>>> runPureEff $ runState 10 $ \st -> do
      modify st (* 2)
((), 20)

runPureEff $ withStateSource $ \source -> do
  n <- newState source 5
  total <- newState source 0

  withJump $ \done -> forever $ do
    n' <- get n
    modify total (+ n')
    when (n' == 0) $ jumpTo done
    modify n (subtract 1)

  get total
15

runPureEff $ withStateSource $ \source -> do
  n <- newState source 5
  total <- newState source 0

  withJump $ \done -> forever $ do
    n' <- get n
    modify total (+ n')
    when (n' == 0) $ jumpTo done
    modify n (subtract 1)

  get total
15

>>> runPureEff $ runState 10 $ \st -> do
      n <- get st
      pure (2 * n)
(20,10)

Yield an element to the stream.

>>> runPureEff $ yieldToList $ \y -> do
      yield y 1
      yield y 2
      yield y 100
([1,2,100], ())

Apply an effectful function to each element yielded to the stream.

>>> runPureEff $ yieldToList $ \y -> do
      for_ [0 .. 4] $ \i -> do
        yield y i
        yield y (i * 10)
([0, 0, 1, 10, 2, 20, 3, 30], ())

Ignore all elements yielded to the stream.

>>> runPureEff $ ignoreStream $ \y -> do
     for_ [0 .. 4] $ \i -> do
       yield y i
       yield y (i * 10)

     pure 42
42

>>> runPureEff $ yieldToList $ inFoldable [1, 2, 100]
([1, 2, 100], ())

Pair each element in the stream with an increasing index, starting from 0.

>>> runPureEff $ yieldToList $ enumerate (inFoldable ["A", "B", "C"])
([(0, "A"), (1, "B"), (2, "C")], ())

Pair each element in the stream with an increasing index, starting from an inital value.

>>> runPureEff $ yieldToList $ enumerateFrom1 (inFoldable ["A", "B", "C"])
([(1, "A"), (2, "B"), (3, "C")], ())

A version of forEach specialized to Consume. Every time the Consume is used to await a b, feed it the one created by the handler.

Run an Eff action with the ability to return early to this point. In the language of exceptions, withEarlyReturn installs an exception handler for an exception of type r.

>>> runPureEff $ withEarlyReturn $ \e -> do
      for_ [1 .. 10] $ \i -> do
        when (i >= 5) $
          returnEarly e ("Returned early with " ++ show i)
      pure "End of loop"
"Returned early with 5"

>>> runPureEff $ withEarlyReturn $ \e -> do
      for_ [1 .. 10] $ \i -> do
        when (i >= 5) $
          returnEarly e ("Returned early with " ++ show i)
      pure "End of loop"
"Returned early with 5"

>>> runPureEff $ evalState 10 $ \st -> do
      n <- get st
      pure (2 * n)
20

>>> runPureEff $ withState 10 $ \st -> do
      n <- get st
      pure (s -> (2 * n, s))
(20,10)

Gather all yielded elements into a list.

>>> runPureEff $ yieldToList $ \y -> do
      yield y 1
      yield y 2
      yield y 100
([1,2,100], ())

>>> runPureEff $ withYieldToList $ \y -> do
  yield y 1
  yield y 2
  yield y 100
  pure length
3

This is more efficient than yieldToList because it gathers the elements into a stack in reverse order. yieldToList then reverses that stack.

>>> runPureEff $ yieldToReverseList $ \y -> do
      yield y 1
      yield y 2
      yield y 100
([100,2,1], ())

Remove Nothing elements from a stream.

runPureEff $ withStateSource $ \source -> do
  n <- newState source 5
  total <- newState source 0

  withJump $ \done -> forever $ do
    n' <- get n
    modify total (+ n')
    when (n' == 0) $ jumpTo done
    modify n (subtract 1)

  get total
15

runPureEff $ withStateSource $ \source -> do
  n <- newState source 5
  total <- newState source 0

  withJump $ \done -> forever $ do
    n' <- get n
    modify total (+ n')
    when (n' == 0) $ jumpTo done
    modify n (subtract 1)

  get total
15

Handle that allows you to run IO operations

Run an IO operation in Eff

>>> runEff_ $ \io -> do
      effIO io (putStrLn "Hello world!")
Hello, world!

Run an Eff whose only unhandled effect is IO.

>>> runEff_ $ \io -> do
      effIO io (putStrLn "Hello world!")
Hello, world!

We suggest you use runEff_ instead, as it probably has better type inference properties.

Run an Eff whose only unhandled effect is IO.

>>> runEff_ $ \io -> do
      effIO io (putStrLn "Hello world!")
Hello, world!

This probably has better type inference properties than runEff and so will probably replace it in a later version.

>>> getAny $ snd $ runPureEff $ runWriter $ \w -> do
      -- Non-empty list (the tell event does happen)
      for_ [1 .. 10] $ \_ -> tell w (Any True)
True

>>> getAny $ runPureEff $ execWriter $ \w -> do
      -- Non-empty list (the tell event does happen)
      for_ [1 .. 10] $ \_ -> tell w (Any True)
True

>>> getAny $ runPureEff $ execWriter $ \w -> do
      -- Empty list (the tell event does not happen)
      for_ [] $ \_ -> tell w (Any True)
False

>>> getAny $ runPureEff $ execWriter $ \w -> do
      -- Non-empty list (the tell event does happen)
      for_ [1 .. 10] $ \_ -> tell w (Any True)
True

Read the value. Note that ask has the property that these two operations are always equivalent:

do
  r1 <- ask re
  r2 <- ask re
  pure (r1, r2)

do
  r <- ask re
  pure (r, r)

Read the value modified by a function