mirror of
https://github.com/lexi-lambda/freer-simple.git
synced 2024-12-23 05:51:58 +03:00
Restructure and simplify README
This commit is contained in:
parent
645809851e
commit
eb93c6b064
95
README.md
95
README.md
@ -1,45 +1,37 @@
|
|||||||
# Freer: Extensible Effects with Freer Monads [![Build Status](https://travis-ci.org/lexi-lambda/freer-simple.svg?branch=master)](https://travis-ci.org/lexi-lambda/freer-simple)
|
# freer-simple — a friendly effect system for Haskell [![Build Status](https://travis-ci.org/lexi-lambda/freer-simple.svg?branch=master)](https://travis-ci.org/lexi-lambda/freer-simple)
|
||||||
|
|
||||||
# Description
|
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 `freer-simple` library (a fork of [`freer-effects`](http://hackage.haskell.org/package/freer-effects)) is an implementation of an effect system for Haskell, which is based on the work of Oleg Kiselyov et al.:
|
|
||||||
|
|
||||||
- [Freer Monads, More Extensible Effects](http://okmij.org/ftp/Haskell/extensible/more.pdf)
|
|
||||||
- [Reflection without Remorse](http://okmij.org/ftp/Haskell/zseq.pdf)
|
|
||||||
- [Extensible Effects](http://okmij.org/ftp/Haskell/extensible/exteff.pdf)
|
|
||||||
|
|
||||||
Much of the implementation is a repackaging and cleaning up of the reference materials provided [here](http://okmij.org/ftp/Haskell/extensible/).
|
|
||||||
|
|
||||||
# Features
|
|
||||||
|
|
||||||
The key features of `freer-simple` are:
|
The key features of `freer-simple` are:
|
||||||
|
|
||||||
- An efficient effect system for Haskell as a library.
|
- An efficient effect system for Haskell as a library.
|
||||||
- Implementations for several common Haskell monads as effects:
|
|
||||||
- `Reader`
|
|
||||||
- `Writer`
|
|
||||||
- `State`
|
|
||||||
- `Trace`
|
|
||||||
- `Error`
|
|
||||||
- Core components for defining your own Effects.
|
|
||||||
|
|
||||||
# Example: Console DSL
|
- Implementations for several common Haskell monads as effects, including `Reader`, `Writer`, `State`, `Error`, and others.
|
||||||
|
|
||||||
Here's what using `freer-simple` looks like:
|
- 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.**](https://hackage.haskell.org/package/freer-simple)
|
||||||
|
|
||||||
|
## Code example
|
||||||
|
|
||||||
```haskell
|
```haskell
|
||||||
{-# LANGUAGE GADTs #-}
|
|
||||||
{-# LANGUAGE FlexibleContexts #-}
|
|
||||||
{-# LANGUAGE TypeOperators #-}
|
|
||||||
{-# LANGUAGE DataKinds #-}
|
{-# LANGUAGE DataKinds #-}
|
||||||
|
{-# LANGUAGE FlexibleContexts #-}
|
||||||
|
{-# LANGUAGE GADTs #-}
|
||||||
{-# LANGUAGE LambdaCase #-}
|
{-# LANGUAGE LambdaCase #-}
|
||||||
module Console where
|
{-# LANGUAGE TemplateHaskell #-}
|
||||||
|
{-# LANGUAGE TypeOperators #-}
|
||||||
|
|
||||||
|
import qualified Prelude
|
||||||
|
import qualified System.Exit
|
||||||
|
|
||||||
|
import Prelude hiding (putStrLn, getLine)
|
||||||
|
|
||||||
import Control.Monad.Freer
|
import Control.Monad.Freer
|
||||||
|
import Control.Monad.Freer.TH
|
||||||
import Control.Monad.Freer.Error
|
import Control.Monad.Freer.Error
|
||||||
import Control.Monad.Freer.State
|
import Control.Monad.Freer.State
|
||||||
import Control.Monad.Freer.Writer
|
import Control.Monad.Freer.Writer
|
||||||
import System.Exit hiding (ExitCode(ExitSuccess))
|
|
||||||
|
|
||||||
--------------------------------------------------------------------------------
|
--------------------------------------------------------------------------------
|
||||||
-- Effect Model --
|
-- Effect Model --
|
||||||
@ -48,24 +40,16 @@ data Console r where
|
|||||||
PutStrLn :: String -> Console ()
|
PutStrLn :: String -> Console ()
|
||||||
GetLine :: Console String
|
GetLine :: Console String
|
||||||
ExitSuccess :: Console ()
|
ExitSuccess :: Console ()
|
||||||
|
makeEffect ''Console
|
||||||
putStrLn' :: Member Console effs => String -> Eff effs ()
|
|
||||||
putStrLn' = send . PutStrLn
|
|
||||||
|
|
||||||
getLine' :: Member Console effs => Eff effs String
|
|
||||||
getLine' = send GetLine
|
|
||||||
|
|
||||||
exitSuccess' :: Member Console effs => Eff effs ()
|
|
||||||
exitSuccess' = send ExitSuccess
|
|
||||||
|
|
||||||
--------------------------------------------------------------------------------
|
--------------------------------------------------------------------------------
|
||||||
-- Effectful Interpreter --
|
-- Effectful Interpreter --
|
||||||
--------------------------------------------------------------------------------
|
--------------------------------------------------------------------------------
|
||||||
runConsole :: Eff '[Console, IO] a -> IO a
|
runConsole :: Eff '[Console, IO] a -> IO a
|
||||||
runConsole = runM . interpretM (\case
|
runConsole = runM . interpretM (\case
|
||||||
PutStrLn msg -> putStrLn msg
|
PutStrLn msg -> Prelude.putStrLn msg
|
||||||
GetLine -> getLine
|
GetLine -> Prelude.getLine
|
||||||
ExitSuccess -> exitSuccess)
|
ExitSuccess -> System.Exit.exitSuccess)
|
||||||
|
|
||||||
--------------------------------------------------------------------------------
|
--------------------------------------------------------------------------------
|
||||||
-- Pure Interpreter --
|
-- Pure Interpreter --
|
||||||
@ -82,37 +66,6 @@ runConsolePure inputs req = snd . fst $
|
|||||||
go ExitSuccess = throwError ()
|
go ExitSuccess = throwError ()
|
||||||
```
|
```
|
||||||
|
|
||||||
# Contributing
|
## Acknowledgements
|
||||||
|
|
||||||
Contributions are welcome! Documentation, examples, code, and feedback - they all help.
|
The `freer-simple` package began as a fork of [freer-effects](http://hackage.haskell.org/package/freer-effects) by Ixperta Solutions, which in turn is a fork of [freer](http://hackage.haskell.org/package/freer) by Allele Dev. All implementations are based on the [paper and reference implementation by Oleg Kiselyov](http://okmij.org/ftp/Haskell/extensible/more.pdf).
|
||||||
|
|
||||||
|
|
||||||
## Developer Setup
|
|
||||||
|
|
||||||
The easiest way to start contributing is to install [stack](https://haskellstack.org/). Stack can install GHC/Haskell for you, and automates common developer tasks.
|
|
||||||
|
|
||||||
The key commands are:
|
|
||||||
|
|
||||||
- `stack setup` — install required version of GHC compiler
|
|
||||||
- `stack build` — builds project, dependencies are automatically resolved
|
|
||||||
- `stack test` — builds project, its tests, and executes the tests
|
|
||||||
- `stack bench` — builds project, its benchmarks, and executes the benchamks
|
|
||||||
- `stack ghci` — start a REPL instance with a project modules loaded
|
|
||||||
- `stack clean`
|
|
||||||
- `stack haddock` — builds documentation
|
|
||||||
|
|
||||||
More information about `stack` can be found in its [documentation](https://haskellstack.org/).
|
|
||||||
|
|
||||||
# Licensing
|
|
||||||
|
|
||||||
This project is distributed under a BSD3 license. See the included LICENSE file for more details.
|
|
||||||
|
|
||||||
# Acknowledgements
|
|
||||||
|
|
||||||
The `freer-simple` package started as a fork of [freer-effects](http://hackage.haskell.org/package/freer-effects) by Ixperta Solutions, which in turn is a fork of [freer](http://hackage.haskell.org/package/freer) by Allele Dev. All implementations are based on the paper and reference implementation by Oleg Kiselyov. In particular:
|
|
||||||
|
|
||||||
- `Data.OpenUnion` maps to [OpenUnion51.hs](http://okmij.org/ftp/Haskell/extensible/OpenUnion51.hs)
|
|
||||||
- `Data.FTCQueue` maps to [FTCQueue1](http://okmij.org/ftp/Haskell/extensible/FTCQueue1.hs)
|
|
||||||
- `Control.Monad.Freer*` maps to [Eff1.hs](http://okmij.org/ftp/Haskell/extensible/Eff1.hs)
|
|
||||||
|
|
||||||
There will be deviations from the source.
|
|
||||||
|
Loading…
Reference in New Issue
Block a user