BSD-3-Clause licensed by Allele Dev, Ixcom Core Team, Alexis King, and other contributors
Maintained by Alexis King
This version can be pinned in stack with:freer-simple-1.2.1.2@sha256:39417ebbb47e96a40097aaeb8185fbf0b8887f7a93596a7a2c0e06e30e5209e2,3206

freer-simple — a friendly effect system for Haskell Build Status Hackage

The freer-simple library is an implementation of an extensible effect system for Haskell, a general-purpose way of tracking effects at the type level and handling them in different ways. The concept of an “effect” is very general: it encompasses the things most people consider side-effects, like generating random values, interacting with the file system, and mutating state, but it also includes things like access to an immutable global environment and exception handling.

The key features of freer-simple are:

  • An efficient effect system for Haskell as a library.

  • Implementations for several common Haskell monads as effects, including Reader, Writer, State, Error, and others.

  • A combinator language for defining your own effects, designed to make simple, common use cases easy to read and write.

For more details, see the package documentation on Hackage.

Code example

{-# LANGUAGE DataKinds #-}
{-# LANGUAGE FlexibleContexts #-}
{-# LANGUAGE GADTs #-}
{-# LANGUAGE LambdaCase #-}
{-# LANGUAGE TemplateHaskell #-}
{-# LANGUAGE TypeOperators #-}

import qualified Prelude
import qualified System.Exit

import Prelude hiding (putStrLn, getLine)

import Control.Monad.Freer
import Control.Monad.Freer.TH
import Control.Monad.Freer.Error
import Control.Monad.Freer.State
import Control.Monad.Freer.Writer

--------------------------------------------------------------------------------
                               -- Effect Model --
--------------------------------------------------------------------------------
data Console r where
  PutStrLn    :: String -> Console ()
  GetLine     :: Console String
  ExitSuccess :: Console ()
makeEffect ''Console

--------------------------------------------------------------------------------
                          -- Effectful Interpreter --
--------------------------------------------------------------------------------
runConsole :: Eff '[Console, IO] a -> IO a
runConsole = runM . interpretM (\case
  PutStrLn msg -> Prelude.putStrLn msg
  GetLine -> Prelude.getLine
  ExitSuccess -> System.Exit.exitSuccess)

--------------------------------------------------------------------------------
                             -- Pure Interpreter --
--------------------------------------------------------------------------------
runConsolePure :: [String] -> Eff '[Console] w -> [String]
runConsolePure inputs req = snd . fst $
    run (runWriter (runState inputs (runError (reinterpret3 go req))))
  where
    go :: Console v -> Eff '[Error (), State [String], Writer [String]] v
    go (PutStrLn msg) = tell [msg]
    go GetLine = get >>= \case
      [] -> error "not enough lines"
      (x:xs) -> put xs >> pure x
    go ExitSuccess = throwError ()

Acknowledgements

The freer-simple package began as a fork of freer-effects by Ixperta Solutions, which in turn is a fork of freer by Allele Dev. All implementations are based on the paper and reference implementation by Oleg Kiselyov.

Changes

1.2.1.2 (January 7th, 2022)

  • Compatibility with template-haskell versions through 2.18 (which is distributed with GHC 9.2) (#34).

1.2.1.1 (October 4th, 2019)

  • Loosened bounds on template-haskell (#29).
  • Made some minor internal changes to better support GHC 8.8.

1.2.1.0 (November 15th, 2018)

  • Improved makeEffect from Control.Monad.Freer.TH to support more datatypes (#17).

1.2.0.0 (October 23rd, 2018)

  • Added Control.Monad.Freer.TH, which provides a makeEffect function that automatically generates boilerplate operations using send for an effect (#15).

1.1.0.0 (February 20th, 2018)

  • Changed the implementation of LastMember to avoid an issue similar to the one with Member fixed in 1.0.1.1 that could cause the constraint to unnecessarily fail to solve (#6).
  • Changed the order of the type variables in interpretM to be more consistent with other functions (only relevant in combination with TypeApplications).
  • Re-exported (~>) from Control.Natural through Control.Monad.Freer.

1.0.1.1 (January 31st, 2018)

  • Fixed a bug that could cause Member constraints to erroneously fail to solve (#3).

1.0.1.0 (January 27th, 2018)

  • Added subsume to Control.Monad.Freer for deduplicating effects.
  • Added gets to Control.Monad.Freer.State (#1).

1.0.0.0 (December 7th, 2017)

  • Initial release.