Because in Bluefin everything happens at the value level, creating your own effects is equivalent to creating your own data types. We just use the techniques we know and love from Haskell! For example, if I want to make a "counter" effect that allows me to increment a counter then I can wrap a Modify capability in a newtype:

newtype Counter1 e = MkCounter1 (Modify Int e)

incCounter1 :: (e <: es) => Counter1 e -> Eff es ()
incCounter1 (MkCounter1 st) = modify st (+ 1)

runCounter1 ::
  (forall e. Counter1 e -> Eff (e :& es) r) ->
  Eff es Int
runCounter1 k =
  evalModify 0 $ \st -> do
    _ <- k (MkCounter1 st)
    get st

Running the handler tells me the number of times I incremented the counter.

exampleCounter1 :: Int
exampleCounter1 = runPureEff $ runCounter1 $ \c -> do
  incCounter1 c
  incCounter1 c
  incCounter1 c

>>> exampleCounter1
3

If we want to wrap multiple effects then we can use the normal approach we use to wrap multiple values into a single value: define a new data type with multiple fields. There's a caveat to this approach, but before we address the caveat let's see the approach in action. Here we define a new capability, Counter2, that contains a Modify and Throw capability within it. That allows us to increment the counter and throw an exception when we hit a limit.

data Counter2 e1 e2 = MkCounter2 (Modify Int e1) (Throw () e2)

incCounter2 :: (e1 <: es, e2 <: es) => Counter2 e1 e2 -> Eff es ()
incCounter2 (MkCounter2 st ex) = do
  count <- get st
  when (count >= 10) $
    throw ex ()
  put st (count + 1)

runCounter2 ::
  (forall e1 e2. Counter2 e1 e2 -> Eff (e2 :& e1 :& es) r) ->
  Eff es Int
runCounter2 k =
  evalModify 0 $ \st -> do
    _ <- try $ \ex -> do
      k (MkCounter2 st ex)
    get st

We can see that attempting to increment the counter forever bails out when we reach the limit.

exampleCounter2 :: Int
exampleCounter2 = runPureEff $ runCounter2 $ \c ->
  forever $
    incCounter2 c

>>> exampleCounter2
10

The flaw of this approach is that you expose one effect parameter for each capability in the data type. That's rather cumbersome! We can do better.

We can avoid exposing multiple effect parameters and just expose a single one. To make this work we have to define our handler in a slightly different way. Firstly we apply useImplIn to the effectful operation k and secondly we apply mapHandle to each of the capabilities out of which we create our compound capability. Everything else remains the same.

data Counter3 e = MkCounter3 (Modify Int e) (Throw () e)

incCounter3 :: (e <: es) => Counter3 e -> Eff es ()
incCounter3 (MkCounter3 st ex) = do
  count <- get st
  when (count >= 10) $
    throw ex ()
  put st (count + 1)

runCounter3 ::
  (forall e. Counter3 e -> Eff (e :& es) r) ->
  Eff es Int
runCounter3 k =
  evalModify 0 $ \st -> do
    _ <- try $ \ex -> do
      useImplIn k (MkCounter3 (mapHandle st) (mapHandle ex))
    get st

The example works as before:

exampleCounter3 :: Int
exampleCounter3 = runPureEff $ runCounter3 $ \c ->
  forever $
    incCounter3 c

>>> exampleCounter3
10

So far our handlers have handled all the effects that are found within our compound effect. We don't have to do that though: we can leave an effect unhandled to be handled by a different handler at a higher level. This must always be the case for IOE, which can only be handled at the top level by runEff. Let's see what it looks like to wrap IOE and provide an API which allows a subset of IO operations.

newtype Counter3B e = MkCounter3B (IOE e)

incCounter3B :: (e <: es) => Counter3B e -> Eff es ()
incCounter3B (MkCounter3B io) =
  effIO io (putStrLn "You tried to increment the counter")

runCounter3B ::
  (e1 <: es) =>
  IOE e1 ->
  (forall e. Counter3B e -> Eff (e :& es) r) ->
  Eff es r
runCounter3B io k = useImplIn k (MkCounter3B (mapHandle io))

exampleCounter3B :: IO ()
exampleCounter3B = runEff $ \io -> runCounter3B io $ \c -> do
  incCounter3B c
  incCounter3B c
  incCounter3B c

This isn't a terribly useful counter! It doesn't actually increment anything, it just prints a message when we try, but the example does demonstrate how to wrap IOE.

-- ghci> exampleCounter3B
-- You tried to increment the counter
-- You tried to increment the counter
-- You tried to increment the counter

We can wrap multiple effects, handle some of them and leave the others to be handled later. Let's extend Counter3 with a Yield effect. Whenever we ask to increment the counter, and it is currently an even number, then we yield a message about that. Additionally, there's a new operation getCounter4 which allows us to yield a message whilst returning the value of the counter.

data Counter4 e
  = MkCounter4 (Modify Int e) (Throw () e) (Yield String e)

incCounter4 :: (e <: es) => Counter4 e -> Eff es ()
incCounter4 (MkCounter4 st ex y) = do
  count <- get st

  when (even count) $
    yield y "Count was even"

  when (count >= 10) $
    throw ex ()

  put st (count + 1)

getCounter4 :: (e <: es) => Counter4 e -> String -> Eff es Int
getCounter4 (MkCounter4 st _ y) msg = do
  yield y msg
  get st

runCounter4 ::
  (e1 <: es) =>
  Yield String e1 ->
  (forall e. Counter4 e -> Eff (e :& es) r) ->
  Eff es Int
runCounter4 y k =
  evalModify 0 $ \st -> do
    _ <- try $ \ex -> do
      useImplIn k (MkCounter4 (mapHandle st) (mapHandle ex) (mapHandle y))
    get st

exampleCounter4 :: ([String], Int)
exampleCounter4 = runPureEff $ yieldToList $ \y -> do
  runCounter4 y $ \c -> do
    incCounter4 c
    incCounter4 c
    n <- getCounter4 c "I'm getting the counter"
    when (n == 2) $
      yield y "n was 2, as expected"

>>> exampleCounter4
(["Count was even","I'm getting the counter","n was 2, as expected"],2)

So far we've looked at "concrete" compound effects, that is, new effects implemented in terms of specific other effects. We can also define dynamic effects, whose implementation is left abstract, to be defined in the handler. To do that we create a capability that is a record of functions. To run an effectful operation we call one of the functions from the record. We define the record in the handler. Here incCounter5Impl and getCounter5Impl are exactly the same as incCounter4 and getCounter4 were, they're just defined in the handler. In order to be used polymorphically, the actual effectful functions we call, incCounter5 and getCounter5 are derived from the record fields.

data Counter5 e = MkCounter5
  { incCounter5Impl :: Eff e (),
    getCounter5Impl :: String -> Eff e Int
  }
  deriving (Generic)
  deriving (Handle) via OneWayCoercibleHandle Counter5

instance (e <: es) => OneWayCoercible (Counter5 e) (Counter5 es) where
  oneWayCoercibleImpl = gOneWayCoercible

incCounter5 :: (e <: es) => Counter5 e -> Eff es ()
incCounter5 e = incCounter5Impl (mapHandle e)

getCounter5 :: (e <: es) => Counter5 e -> String -> Eff es Int
getCounter5 e msg = getCounter5Impl (mapHandle e) msg

runCounter5 ::
  (e1 <: es) =>
  Yield String e1 ->
  (forall e. Counter5 e -> Eff (e :& es) r) ->
  Eff es Int
runCounter5 y k =
  evalModify 0 $ \st -> do
    _ <- try $ \ex -> do
      useImplIn
        k
        ( MkCounter5
            { incCounter5Impl = do
                count <- get st

                when (even count) $
                  yield y "Count was even"

                when (count >= 10) $
                  throw ex ()

                put st (count + 1),
              getCounter5Impl = \msg -> do
                yield y msg
                get st
            }
        )
    get st

The result is exactly the same as before

exampleCounter5 :: ([String], Int)
exampleCounter5 = runPureEff $ yieldToList $ \y -> do
  runCounter5 y $ \c -> do
    incCounter5 c
    incCounter5 c
    n <- getCounter5 c "I'm getting the counter"
    when (n == 2) $
      yield y "n was 2, as expected"

>>> exampleCounter5
(["Count was even","I'm getting the counter","n was 2, as expected"],2)

We can also freely combine concrete and dynamic effects. In the following example, the incCounter6 effect is left dynamic, and defined in the handler, whilst getCounter6 is implemented in terms of concrete Modify and Yield effects.

data Counter6 e = MkCounter6
  { incCounter6Impl :: Eff e (),
    counter6Modify :: Modify Int e,
    counter6Yield :: Yield String e
  }
  deriving (Generic)
  deriving (Handle) via OneWayCoercibleHandle Counter6

instance (e <: es) => OneWayCoercible (Counter6 e) (Counter6 es) where
  oneWayCoercibleImpl = gOneWayCoercible

incCounter6 :: (e <: es) => Counter6 e -> Eff es ()
incCounter6 e = incCounter6Impl (mapHandle e)

getCounter6 :: (e <: es) => Counter6 e -> String -> Eff es Int
getCounter6 (MkCounter6 _ st y) msg = do
  yield y msg
  get st

runCounter6 ::
  (e1 <: es) =>
  Yield String e1 ->
  (forall e. Counter6 e -> Eff (e :& es) r) ->
  Eff es Int
runCounter6 y k =
  evalModify 0 $ \st -> do
    _ <- try $ \ex -> do
      useImplIn
        k
        ( MkCounter6
            { incCounter6Impl = do
                count <- get st

                when (even count) $
                  yield y "Count was even"

                when (count >= 10) $
                  throw ex ()

                put st (count + 1),
              counter6Modify = mapHandle st,
              counter6Yield = mapHandle y
            }
        )
    get st

Naturally, the result is the same.

exampleCounter6 :: ([String], Int)
exampleCounter6 = runPureEff $ yieldToList $ \y -> do
  runCounter6 y $ \c -> do
    incCounter6 c
    incCounter6 c
    n <- getCounter6 c "I'm getting the counter"
    when (n == 2) $
      yield y "n was 2, as expected"

>>> exampleCounter6
(["Count was even","I'm getting the counter","n was 2, as expected"],2)

We can implement dynamic effects that themselves take capabilities as arguments, by giving all the capability arguments the effect tag e'.

data Counter7 e = MkCounter7
  { incCounter7Impl :: forall e'. Throw () e' -> Eff (e' :& e) (),
    counter7Modify :: Modify Int e,
    counter7Yield :: Yield String e
  }
  deriving (Handle) via OneWayCoercibleHandle Counter7

-- | The "forall" in the type of incCounter7 means that we
-- can't derive the OneWayCoercible instance with
-- gOneWayCoercible so instead we use oneWayCoercibleTrustMe.

instance (e <: es) => OneWayCoercible (Counter7 e) (Counter7 es) where
  oneWayCoercibleImpl = oneWayCoercibleTrustMe $ \c ->
    MkCounter7
      { incCounter7Impl = \ex -> useImplUnder (incCounter7Impl c ex),
        counter7Modify = mapHandle (counter7Modify c),
        counter7Yield = mapHandle (counter7Yield c)
      }

incCounter7 ::
  (e <: es, e1 <: es) => Counter7 e -> Throw () e1 -> Eff es ()
incCounter7 e ex = makeOp (incCounter7Impl (mapHandle e) (mapHandle ex))

getCounter7 :: (e <: es) => Counter7 e -> String -> Eff es Int
getCounter7 (MkCounter7 _ st y) msg = do
  yield y msg
  get st

runCounter7 ::
  (e1 <: es) =>
  Yield String e1 ->
  (forall e. Counter7 e -> Eff (e :& es) r) ->
  Eff es Int
runCounter7 y k =
  evalModify 0 $ \st -> do
    _ <-
      useImplIn
        k
        ( MkCounter7
            { incCounter7Impl = \ex -> do
                count <- get st

                when (even count) $
                  yield y "Count was even"

                when (count >= 10) $
                  throw ex ()

                put st (count + 1),
              counter7Modify = mapHandle st,
              counter7Yield = mapHandle y
            }
        )
    get st

The result is the same as before ...

exampleCounter7A :: ([String], Int)
exampleCounter7A = runPureEff $ yieldToList $ \y -> do
  handle (\() -> pure (-42)) $ \ex ->
    runCounter7 y $ \c -> do
      incCounter7 c ex
      incCounter7 c ex
      n <- getCounter7 c "I'm getting the counter"
      when (n == 2) $
        yield y "n was 2, as expected"

-- > exampleCounter7A
-- (["Count was even","I'm getting the counter","n was 2, as expected"],2)

... unless we run incCounter too many times, in which case it throws an exception.

exampleCounter7B :: ([String], Int)
exampleCounter7B = runPureEff $ yieldToList $ \y -> do
  handle (\() -> pure (-42)) $ \ex ->
    runCounter7 y $ \c -> do
      forever (incCounter7 c ex)

-- > exampleCounter7B
-- (["Count was even","Count was even","Count was even","Count was even","Count was even","Count was even"],-42)

We can also implement dynamic effects that themselves take effectful operations as arguments, by giving the effectful operation the effect tag e'. Here's an example of a dynamic reader effect, and one handler for the effect, which runs it in terms of the existing Reader effect.

data DynamicReader r e = DynamicReader
  { askLRImpl :: Eff e r,
    localLRImpl :: forall e' a. (r -> r) -> Eff e' a -> Eff (e' :& e) a
  }
  deriving (Handle) via OneWayCoercibleHandle (DynamicReader r)

-- | The "forall" in the type of localRImpl means that we
-- can't derive the OneWayCoercible instance with
-- gOneWayCoercible instead we use oneWayCoercibleTrustMe.

instance
  (e <: es) =>
  OneWayCoercible (DynamicReader r e) (DynamicReader r es)
  where
  oneWayCoercibleImpl = oneWayCoercibleTrustMe $ \h ->
    DynamicReader
      { askLRImpl = useImpl (askLRImpl h),
        localLRImpl = \f k -> useImplUnder (localLRImpl h f k)
      }

askLR ::
  (e <: es) =>
  DynamicReader r e ->
  Eff es r
askLR c = askLRImpl (mapHandle c)

localLR ::
  (e <: es) =>
  DynamicReader r e ->
  (r -> r) ->
  Eff es a ->
  Eff es a
localLR c f m = makeOp (localLRImpl (mapHandle c) f m)

runDynamicReader ::
  r ->
  (forall e. DynamicReader r e -> Eff (e :& es) a) ->
  Eff es a
runDynamicReader r k =
  runReader r $ \h -> do
    useImplIn
      k
      DynamicReader
        { askLRImpl = ask h,
          localLRImpl = \f k' -> local h f (useImpl k')
        }

The effectful library has an example of a dynamic effect for basic file system access. This is what it looks like in Bluefin. We start by defining a record of effectful operations.

data FileSystem es = MkFileSystem
  { readFileImpl :: FilePath -> Eff es String,
    writeFileImpl :: FilePath -> String -> Eff es ()
  }
  deriving (Generic)
  deriving (Handle) via OneWayCoercibleHandle FileSystem

instance (e <: es) => OneWayCoercible (FileSystem e) (FileSystem es) where
  oneWayCoercibleImpl = gOneWayCoercible

readFile :: (e <: es) => FileSystem e -> FilePath -> Eff es String
readFile fs filepath = readFileImpl (mapHandle fs) filepath

writeFile :: (e <: es) => FileSystem e -> FilePath -> String -> Eff es ()
writeFile fs filepath contents =
  writeFileImpl (mapHandle fs) filepath contents

We can make a pure handler that simulates reading and writing to a file system by storing file contents in an association list.

runFileSystemPure ::
  (e1 <: es) =>
  Throw String e1 ->
  [(FilePath, String)] ->
  (forall e2. FileSystem e2 -> Eff (e2 :& es) r) ->
  Eff es r
runFileSystemPure ex fs0 k =
  evalModify fs0 $ \fs ->
    useImplIn
      k
      MkFileSystem
        { readFileImpl = \filepath -> do
            fs' <- get fs
            case lookup filepath fs' of
              Nothing ->
                throw ex ("File not found: " <> filepath)
              Just s -> pure s,
          writeFileImpl = \filepath contents ->
            modify fs ((filepath, contents) :)
        }

Or we can make a handler that actually performs IO operations against a real file system.

runFileSystemIO ::
  forall e1 e2 es r.
  (e1 <: es, e2 <: es) =>
  Throw String e1 ->
  IOE e2 ->
  (forall e. FileSystem e -> Eff (e :& es) r) ->
  Eff es r
runFileSystemIO ex io k =
  useImplIn
    k
    MkFileSystem
      { readFileImpl =
          adapt . Prelude.readFile,
        writeFileImpl =
          \filepath -> adapt . Prelude.writeFile filepath
      }
  where
    adapt :: (e1 <: ess, e2 <: ess) => IO a -> Eff ess a
    adapt m =
      effIO io (Control.Exception.try @IOException m) >>= \case
        Left e -> throw ex (show e)
        Right r -> pure r

We can use the FileSystem effect to define an action which does some file system operations.

action :: (e <: es) => FileSystem e -> Eff es String
action fs = do
  file <- readFile fs "/dev/null"
  when (length file == 0) $ do
    writeFile fs "/tmp/bluefin" "Hello!"
  readFile fs "/tmp/doesn't exist"

and we can run it purely, against a simulated file system

exampleRunFileSystemPure :: Either String String
exampleRunFileSystemPure = runPureEff $ try $ \ex ->
  runFileSystemPure ex [("/dev/null", "")] action

>>> exampleRunFileSystemPure
Left "File not found: /tmp/doesn't exist"

or against the real file system.

exampleRunFileSystemIO :: IO (Either String String)
exampleRunFileSystemIO = runEff $ \io -> try $ \ex ->
  runFileSystemIO ex io action

>>> exampleRunFileSystemIO
Left "/tmp/doesn't exist: openFile: does not exist (No such file or directory)"
$ cat /tmp/bluefin
Hello!

The documentation for Handle shows how to use OneWayCoercible to define Handle instances.

Bluefin re-exports Generic for convenience.

Do not use. Will be removed in a future version.