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.

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"

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

Used to define dynamic effects.

Used to define handlers of compound effects.

Handle to a capability to create strict mutable state handles

Handle to an exception of type e

A handle to a strict mutable state of type a

A handle to a coroutine that expects values of type a and then yields 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 expects values of type () and then yields values of type a.

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 :: String -> Int -> Eff 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 themeselevs handles and apply useImpl to all the fields that are dynamic effects:

instance Handle Application where
  mapHandle
    MkApplication
      { queryDatabase = q,
        applicationState = a,
        logger = l
      } =
      MkApplication
        { queryDatabase = (fmap . fmap) useImpl q,
          applicationState = mapHandle a,
          logger = mapHandle l
        }

Note that preceding useImpl on the dynamic effect there is one fmap per -> that appears in type of the dynamic effect. That is, queryDatabase has type String -> Int -> Eff e [String], which has two ->, so there are two fmaps before useImpl.

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"

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.

>>> 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)

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

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

>>> 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")], ())

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)

>>> 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!

>>> 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