diff --git a/LICENSE b/LICENSE index 35fe72e..1f2e413 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright (c) 2016, Allele Dev +Copyright (c) 2016, Allele Dev; 2017 Ixperta Solutions s.r.o. All rights reserved. diff --git a/README.md b/README.md index 0b08809..119b693 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Freer: Extensible Effects with Freer Monads +# Freer Effects: Extensible Effects with Freer Monads [![Haskell Programming Language](https://img.shields.io/badge/language-Haskell-blue.svg)](http://www.haskell.org) [![BSD3 License](http://img.shields.io/badge/license-BSD3-brightgreen.svg)](https://tldrlegal.com/license/bsd-3-clause-license-%28revised%29) @@ -7,25 +7,33 @@ [![Hackage Dependencies](https://img.shields.io/hackage-deps/v/freer.svg)](http://packdeps.haskellers.com/reverse/freer) [![Build](https://travis-ci.org/IxpertaSolutions/freer.svg)](https://travis-ci.org/IxpertaSolutions/freer) -Freer is an implementation of -["Freer Monads, More Extensible Effects"](http://okmij.org/ftp/Haskell/extensible/more.pdf). Much -of the implementation is a repackaging and cleaning up of the -reference materials provided -[here](http://okmij.org/ftp/Haskell/extensible/). + +# Description + +Library `freer-effects` is an implementation of 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) +* [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 are: -* An efficient effect system for Haskell as a library -* Implementations for several common Haskell monad instances: - * Reader - * Writer - * State - * StateRW: State in terms of Reader/Writer - * Trace - * Exception -* Core components for defining your own Effects +* An efficient effect system for Haskell as a library. +* Implementations for several common Haskell monads as effects: + * `Reader` + * `Writer` + * `State` + * `StateRW`: State in terms of Reader/Writer. + * `Trace` + * `Exception` +* Core components for defining your own Effects. + # Example: Teletype DSL @@ -86,10 +94,12 @@ runTeletypePure inputs req = go (_, os) ExitSuccess _ = pure ([], os) ``` + # Contributing -Contributions are welcome! Documentation, examples, code, and -feedback - they all help. +Contributions are welcome! Documentation, examples, code, and feedback - they +all help. + ## Developer Setup @@ -99,26 +109,34 @@ GHC/Haskell for you, and automates common developer tasks. The key commands are: -* stack setup : install GHC -* stack build -* stack clean -* stack haddock : builds documentation -* stack test -* stack bench -* stack ghci : start a REPL instance +* `stack setup`: install GHC +* `stack build` +* `stack clean` +* `stack haddock`: builds documentation +* `stack test` +* `stack bench` +* `stack ghci`: start a REPL instance + # Licensing This project is distrubted under a BSD3 license. See the included LICENSE file for more details. + # Acknowledgements +Package `freer-effects` started as a fork of +[freer](http://hackage.haskell.org/package/freer) authored by Allele Dev. + This package would not be possible without the paper and the reference implementation. In particular: -* Data.Open.Union maps to [OpenUnion41.hs](http://okmij.org/ftp/Haskell/extensible/OpenUnion41.hs) -* Data.FTCQueue maps to [FTCQueue1](http://okmij.org/ftp/Haskell/extensible/FTCQueue1.hs) -* Control.Monad.Freer* maps to [Union1.hs](http://okmij.org/ftp/Haskell/extensible/Eff1.hs) +* `Data.Open.Union` maps to + [OpenUnion41.hs](http://okmij.org/ftp/Haskell/extensible/OpenUnion41.hs) +* `Data.FTCQueue` maps to + [FTCQueue1](http://okmij.org/ftp/Haskell/extensible/FTCQueue1.hs) +* `Control.Monad.Freer*` maps to + [Union1.hs](http://okmij.org/ftp/Haskell/extensible/Eff1.hs) There will be deviations from the source. diff --git a/freer-effects.cabal b/freer-effects.cabal new file mode 100644 index 0000000..5d51652 --- /dev/null +++ b/freer-effects.cabal @@ -0,0 +1,139 @@ +name: freer-effects +version: 0.2.4.1 +synopsis: Implementation of effect system for Haskell. +description: + Implementation of effect system for Haskell, which is based on the work of + Oleg Kiselyov et al.: + . + * + * + . + The key features are: + . + * An efficient effect system for Haskell - as a library! + . + * Reimplementations of several common Haskell monad transformers as effects. + . + * Core components for defining your own Effects. + +license: BSD3 +license-file: LICENSE +author: Allele Dev, Ixcom Core Team, and other contributors +maintainer: ixcom-core@ixperta.com +copyright: (c) 2016 Allele Dev; 2017 Ixperta Solutions s.r.o. +homepage: https://github.com/IxpertaSolutions/freer +bug-reports: https://github.com/IxpertaSolutions/freer/issues +category: Control + +build-type: Simple +cabal-version: >=1.10 +tested-with: GHC==7.10.3, GHC==8.0.1, GHC==7.8.4 + +extra-source-files: + README.md + changelog.md + +source-repository head + type: git + location: git clone https://github.com/IxpertaSolutions/freer.git + +flag pedantic + description: Pass additional warning flags and -Werror to GHC. + default: False + manual: True + +library + hs-source-dirs: src + exposed-modules: + Control.Monad.Freer + , Control.Monad.Freer.Coroutine + , Control.Monad.Freer.Cut + , Control.Monad.Freer.Exception + , Control.Monad.Freer.Fresh + , Control.Monad.Freer.Internal + , Control.Monad.Freer.Reader + , Control.Monad.Freer.State + , Control.Monad.Freer.StateRW + , Control.Monad.Freer.Trace + , Control.Monad.Freer.Writer + , Data.FTCQueue + , Data.Open.Union + , Data.Open.Union.Internal + + default-language: Haskell2010 + + build-depends: base >=4.7 && <5 + + ghc-options: -Wall + + if flag(pedantic) + ghc-options: -Werror + +executable freer-examples + hs-source-dirs: examples/src + main-is: Main.hs + other-modules: + Common + , Coroutine + , Cut + , Fresh + , NonDetEff + , Teletype + , Trace + + default-language: Haskell2010 + + build-depends: base, freer-effects + + ghc-options: -Wall + + if flag(pedantic) + ghc-options: -Werror + +test-suite test + type: exitcode-stdio-1.0 + hs-source-dirs: tests + main-is: Tests.hs + other-modules: + Tests.Common + , Tests.Coroutine + , Tests.Exception + , Tests.Fresh + , Tests.NonDetEff + , Tests.Reader + , Tests.State + , Tests.StateRW + + default-language: Haskell2010 + + build-depends: + base + , freer-effects + , tasty + , tasty-hunit + , tasty-quickcheck + , QuickCheck + + ghc-options: -Wall + + if flag(pedantic) + ghc-options: -Werror + +benchmark core + type: exitcode-stdio-1.0 + hs-source-dirs: bench + main-is: Core.hs + + default-language: Haskell2010 + + build-depends: + base + , criterion + , free + , freer-effects + , mtl + + ghc-options: -Wall -O2 + + if flag(pedantic) + ghc-options: -Werror diff --git a/freer.cabal b/freer.cabal deleted file mode 100644 index 92bd09d..0000000 --- a/freer.cabal +++ /dev/null @@ -1,105 +0,0 @@ -name: freer -version: 0.2.4.1 -synopsis: Implementation of the Freer Monad -license: BSD3 -license-file: LICENSE -author: TBA -maintainer: TBA -copyright: Allele Dev 2016 -homepage: https://github.com/IxpertaSolutions/freer -bug-reports: https://github.com/IxpertaSolutions/freer/issues -category: Control -build-type: Simple -cabal-version: >=1.10 -tested-with: GHC==7.10.3, GHC==8.0.1, GHC==7.8.4 -description: - - Freer is an implementation of "Freer Monads, More Extensible - Effects" - . - The key features of Freer are: - . - * An efficient effect system for Haskell - as a library! - . - * Implementations for several common Haskell monad instances: - . - * Core components for defining your own Effects - -extra-source-files: - README.md - changelog.md - -source-repository head - type: git - location: git clone https://github.com/IxpertaSolutions/freer.git - -library - exposed-modules: Control.Monad.Freer - , Control.Monad.Freer.Coroutine - , Control.Monad.Freer.Cut - , Control.Monad.Freer.Exception - , Control.Monad.Freer.Fresh - , Control.Monad.Freer.Internal - , Control.Monad.Freer.Reader - , Control.Monad.Freer.State - , Control.Monad.Freer.StateRW - , Control.Monad.Freer.Trace - , Control.Monad.Freer.Writer - , Data.FTCQueue - , Data.Open.Union - , Data.Open.Union.Internal - - build-depends: base >=4.7 && <5 - hs-source-dirs: src - ghc-options: -Wall - default-language: Haskell2010 - -executable freer-examples - main-is: Main.hs - other-modules: Common - , Coroutine - , Cut - , Fresh - , NonDetEff - , Teletype - , Trace - build-depends: base - , freer - hs-source-dirs: examples/src - ghc-options: -Wall - default-language: Haskell2010 - -test-suite test - default-language: Haskell2010 - type: exitcode-stdio-1.0 - hs-source-dirs: tests - main-is: Tests.hs - other-modules: Tests.Common - , Tests.Coroutine - , Tests.Exception - , Tests.Fresh - , Tests.NonDetEff - , Tests.Reader - , Tests.State - , Tests.StateRW - build-depends: base - , freer - , tasty - , tasty-hunit - , tasty-quickcheck - , QuickCheck - - ghc-options: -Wall - -benchmark core - default-language: Haskell2010 - type: exitcode-stdio-1.0 - hs-source-dirs: bench - main-is: Core.hs - build-depends: base - , freer - , criterion - , mtl - , free - - ghc-options: -Wall -O2 diff --git a/src/Control/Monad/Freer.hs b/src/Control/Monad/Freer.hs index f6c4ff4..86ee881 100644 --- a/src/Control/Monad/Freer.hs +++ b/src/Control/Monad/Freer.hs @@ -2,16 +2,14 @@ {-# LANGUAGE TypeOperators #-} {-# LANGUAGE RankNTypes #-} {-# LANGUAGE CPP #-} -{-| -Module : Control.Monad.Freer -Description : Freer - an extensible effects library -Copyright : Allele Dev 2016 -License : BSD-3 -Maintainer : allele.dev@gmail.com -Stability : experimental -Portability : POSIX - --} +-- | +-- Module: Control.Monad.Freer +-- Description: Freer - an extensible effects library +-- Copyright: (c) 2016 Allele Dev; 2017 Ixperta Solutions s.r.o. +-- License: BSD3 +-- Maintainer: ixcom-core@ixperta.com +-- Stability: experimental +-- Portability: POSIX module Control.Monad.Freer ( Member, Members, diff --git a/src/Control/Monad/Freer/Coroutine.hs b/src/Control/Monad/Freer/Coroutine.hs index bd890ee..bd70db3 100644 --- a/src/Control/Monad/Freer/Coroutine.hs +++ b/src/Control/Monad/Freer/Coroutine.hs @@ -2,22 +2,18 @@ {-# LANGUAGE FlexibleContexts #-} {-# LANGUAGE TypeOperators #-} {-# LANGUAGE DataKinds #-} - -{-| -Module : Control.Monad.Freer.Coroutine -Description : Composable coroutine effects layer. -Copyright : Allele Dev 2016 -License : BSD-3 -Maintainer : allele.dev@gmail.com -Stability : broken -Portability : POSIX - -An effect to compose functions with the ability to yield. - -Using as a -starting point. - --} +-- | +-- Module: Control.Monad.Freer.Coroutine +-- Description: Composable coroutine effects layer. +-- Copyright: (c) 2016 Allele Dev; 2017 Ixperta Solutions s.r.o. +-- License: BSD3 +-- Maintainer: ixcom-core@ixperta.com +-- Stability: broken +-- Portability: POSIX +-- +-- An effect to compose functions with the ability to yield. +-- +-- Using as a starting point. module Control.Monad.Freer.Coroutine ( Yield(..), yield, diff --git a/src/Control/Monad/Freer/Cut.hs b/src/Control/Monad/Freer/Cut.hs index 61499b2..30b1e67 100644 --- a/src/Control/Monad/Freer/Cut.hs +++ b/src/Control/Monad/Freer/Cut.hs @@ -1,23 +1,19 @@ {-# LANGUAGE FlexibleContexts #-} {-# LANGUAGE TypeOperators #-} {-# LANGUAGE DataKinds #-} - -{-| -Module : Control.Monad.Freer.Cut -Description : An implementation of logical Cut -Copyright : Allele Dev 2016 -License : BSD-3 -Maintainer : allele.dev@gmail.com -Stability : broken -Portability : POSIX - -Composable handler for logical Cut effects. Implemented in terms of -Exc effect. - -Using as a -starting point. - --} +-- | +-- Module: Control.Monad.Freer.Cut +-- Description: An implementation of logical Cut. +-- Copyright: (c) 2016 Allele Dev; 2017 Ixperta Solutions s.r.o. +-- License: BSD3 +-- Maintainer: ixcom-core@ixperta.com +-- Stability: broken +-- Portability: POSIX +-- +-- Composable handler for logical Cut effects. Implemented in terms of 'Exc' +-- effect. +-- +-- Using as a starting point. module Control.Monad.Freer.Cut ( CutFalse(..), cutFalse, diff --git a/src/Control/Monad/Freer/Exception.hs b/src/Control/Monad/Freer/Exception.hs index 7eedc57..c16c247 100644 --- a/src/Control/Monad/Freer/Exception.hs +++ b/src/Control/Monad/Freer/Exception.hs @@ -1,23 +1,19 @@ {-# LANGUAGE TypeOperators #-} {-# LANGUAGE DataKinds #-} {-# LANGUAGE FlexibleContexts #-} - -{-| -Module : Control.Monad.Freer.Exception -Description : An Exception effect and handler. -Copyright : Allele Dev 2016 -License : BSD-3 -Maintainer : allele.dev@gmail.com -Stability : experimental -Portability : POSIX - -Composable handler for Exception effects. Communicates success/failure -via an Either type. - -Using as a -starting point. - --} +-- | +-- Module: Control.Monad.Freer.Exception +-- Description: An Exception effect and handler. +-- Copyright: (c) 2016 Allele Dev; 2017 Ixperta Solutions s.r.o. +-- License: BSD3 +-- Maintainer: ixcom-core@ixperta.com +-- Stability: experimental +-- Portability: POSIX +-- +-- Composable handler for Exception effects. Communicates success\/failure +-- via an 'Either' type. +-- +-- Using as a starting point. module Control.Monad.Freer.Exception ( Exc(..), throwError, diff --git a/src/Control/Monad/Freer/Fresh.hs b/src/Control/Monad/Freer/Fresh.hs index 167c0a3..dd07fc0 100644 --- a/src/Control/Monad/Freer/Fresh.hs +++ b/src/Control/Monad/Freer/Fresh.hs @@ -2,23 +2,19 @@ {-# LANGUAGE DataKinds #-} {-# LANGUAGE FlexibleContexts #-} {-# LANGUAGE GADTs #-} - -{-| -Module : Control.Monad.Freer.Fresh -Description : Generation of fresh integers as an effect. -Copyright : Allele Dev 2016 -License : BSD-3 -Maintainer : allele.dev@gmail.com -Stability : broken -Portability : POSIX - -Composable handler for Fresh effects. This is likely to be of use when -implementing De Bruijn naming/scopes. - -Using as a -starting point. - --} +-- | +-- Module: Control.Monad.Freer.Fresh +-- Description: Generation of fresh integers as an effect. +-- Copyright: (c) 2016 Allele Dev; 2017 Ixperta Solutions s.r.o. +-- License: BSD3 +-- Maintainer: ixcom-core@ixperta.com +-- Stability: broken +-- Portability: POSIX +-- +-- Composable handler for 'Fresh' effects. This is likely to be of use when +-- implementing De Bruijn naming/scopes. +-- +-- Using as a starting point. module Control.Monad.Freer.Fresh ( Fresh(..), fresh, diff --git a/src/Control/Monad/Freer/Internal.hs b/src/Control/Monad/Freer/Internal.hs index 30f11ce..58549c1 100644 --- a/src/Control/Monad/Freer/Internal.hs +++ b/src/Control/Monad/Freer/Internal.hs @@ -11,25 +11,22 @@ -- TODO: remove once GHC can deduce the decidability of this instance {-# LANGUAGE UndecidableInstances #-} -{-| -Module : Control.Monad.Freer.Internal -Description : Mechanisms to make effects work -Copyright : Allele Dev 2016 -License : BSD-3 -Maintainer : allele.dev@gmail.com -Stability : experimental -Portability : POSIX - -Internal machinery for this effects library. This includes: - -* Eff data type, for expressing effects -* NonDetEff data type, for nondeterministic effects -* Functions for facilitating the construction of effects and their handlers - -Using as a -starting point. - --} +-- | +-- Module: Control.Monad.Freer.Internal +-- Description: Mechanisms to make effects work. +-- Copyright: (c) 2016 Allele Dev; 2017 Ixperta Solutions s.r.o. +-- License: BSD3 +-- Maintainer: ixcom-core@ixperta.com +-- Stability: experimental +-- Portability: POSIX +-- +-- Internal machinery for this effects library. This includes: +-- +-- * 'Eff' data type, for expressing effects. +-- * 'NonDetEff' data type, for nondeterministic effects. +-- * Functions for facilitating the construction of effects and their handlers. +-- +-- Using as a starting point. module Control.Monad.Freer.Internal ( Eff(..), Member(..), diff --git a/src/Control/Monad/Freer/Reader.hs b/src/Control/Monad/Freer/Reader.hs index 7028e91..708c983 100644 --- a/src/Control/Monad/Freer/Reader.hs +++ b/src/Control/Monad/Freer/Reader.hs @@ -3,23 +3,19 @@ {-# LANGUAGE FlexibleContexts #-} {-# LANGUAGE DataKinds #-} {-# LANGUAGE ScopedTypeVariables #-} - -{-| -Module : Control.Monad.Freer.Reader -Description : Reader effects, for encapsulating an environment -Copyright : Allele Dev 2016 -License : BSD-3 -Maintainer : allele.dev@gmail.com -Stability : experimental -Portability : POSIX - -Composable handler for Reader effects. Handy for encapsulating an -environment with immutable state for interpreters. - -Using as a -starting point. - --} +-- | +-- Module: Control.Monad.Freer.Reader +-- Description: Reader effects, for encapsulating an environment. +-- Copyright: (c) 2016 Allele Dev; 2017 Ixperta Solutions s.r.o. +-- License: BSD3 +-- Maintainer: ixcom-core@ixperta.com +-- Stability: experimental +-- Portability: POSIX +-- +-- Composable handler for 'Reader' effects. Handy for encapsulating an +-- environment with immutable state for interpreters. +-- +-- Using as a starting point. module Control.Monad.Freer.Reader ( Reader(..), diff --git a/src/Control/Monad/Freer/State.hs b/src/Control/Monad/Freer/State.hs index cde09d8..d1389f8 100644 --- a/src/Control/Monad/Freer/State.hs +++ b/src/Control/Monad/Freer/State.hs @@ -4,22 +4,18 @@ {-# LANGUAGE NoImplicitPrelude #-} {-# LANGUAGE ScopedTypeVariables #-} {-# LANGUAGE TypeOperators #-} - -{-| -Module : Control.Monad.Freer.State -Description : State effects, for state-carrying computations. -Copyright : Allele Dev 2016 -License : BSD-3 -Maintainer : allele.dev@gmail.com -Stability : experimental -Portability : POSIX - -Composable handler for State effects. - -Using as a -starting point. - --} +-- | +-- Module: Control.Monad.Freer.State +-- Description: State effects, for state-carrying computations. +-- Copyright: (c) 2016 Allele Dev; 2017 Ixperta Solutions s.r.o. +-- License: BSD3 +-- Maintainer: ixcom-core@ixperta.com +-- Stability: experimental +-- Portability: POSIX +-- +-- Composable handler for 'State' effects. +-- +-- Using as a starting point. module Control.Monad.Freer.State ( State(..), get, diff --git a/src/Control/Monad/Freer/StateRW.hs b/src/Control/Monad/Freer/StateRW.hs index 09683e5..f4b8092 100644 --- a/src/Control/Monad/Freer/StateRW.hs +++ b/src/Control/Monad/Freer/StateRW.hs @@ -2,24 +2,20 @@ {-# LANGUAGE DataKinds #-} {-# LANGUAGE FlexibleContexts #-} {-# LANGUAGE GADTs #-} - -{-| -Module : Control.Monad.Freer.StateRW -Description : State effects in terms of Reader/Writer -Copyright : Allele Dev 2016 -License : BSD-3 -Maintainer : allele.dev@gmail.com -Stability : experimental -Portability : POSIX - -Composable handler for State effects in terms of Reader/Writer -effects. This module is more a tutorial on how to compose handlers. It -is slightly slower than a dedicated State handler. - -Using as a -starting point. - --} +-- | +-- Module: Control.Monad.Freer.StateRW +-- Description: State effects in terms of Reader and Writer. +-- Copyright: (c) 2016 Allele Dev; 2017 Ixperta Solutions s.r.o. +-- License: BSD3 +-- Maintainer: ixcom-core@ixperta.com +-- Stability: experimental +-- Portability: POSIX +-- +-- Composable handler for 'State' effects in terms of 'Reader' and 'Writer' +-- effects. This module is more a tutorial on how to compose handlers. It is +-- slightly slower than a dedicated 'State' handler. +-- +-- Using as a starting point. module Control.Monad.Freer.StateRW ( runStateR, Reader, diff --git a/src/Control/Monad/Freer/Trace.hs b/src/Control/Monad/Freer/Trace.hs index 2f51e24..af4ca73 100644 --- a/src/Control/Monad/Freer/Trace.hs +++ b/src/Control/Monad/Freer/Trace.hs @@ -2,23 +2,19 @@ {-# LANGUAGE DataKinds #-} {-# LANGUAGE FlexibleContexts #-} {-# LANGUAGE GADTs #-} - -{-| -Module : Control.Monad.Freer.Trace -Description : Composable Trace effects -Copyright : Allele Dev 2016 -License : BSD-3 -Maintainer : allele.dev@gmail.com -Stability : experimental -Portability : POSIX - -Composable handler for Trace effects. Trace allows one to debug the -operation of sequences of effects by outputing to the console. - -Using as a -starting point. - --} +-- | +-- Module: Control.Monad.Freer.Trace +-- Description: Composable Trace effects. +-- Copyright: (c) 2016 Allele Dev; 2017 Ixperta Solutions s.r.o. +-- License: BSD3 +-- Maintainer: ixcom-core@ixperta.com +-- Stability: experimental +-- Portability: POSIX +-- +-- Composable handler for 'Trace' effects. Trace allows one to debug the +-- operation of sequences of effects by outputing to the console. +-- +-- Using as a starting point. module Control.Monad.Freer.Trace ( Trace(..), trace, diff --git a/src/Control/Monad/Freer/Writer.hs b/src/Control/Monad/Freer/Writer.hs index 555f8aa..b3144f9 100644 --- a/src/Control/Monad/Freer/Writer.hs +++ b/src/Control/Monad/Freer/Writer.hs @@ -3,21 +3,18 @@ {-# LANGUAGE FlexibleContexts #-} {-# LANGUAGE DataKinds #-} {-# LANGUAGE CPP #-} -{-| -Module : Control.Monad.Freer.Writer -Description : Composable Writer effects - -Copyright : Allele Dev 2016 -License : BSD-3 -Maintainer : allele.dev@gmail.com -Stability : experimental -Portability : POSIX - -Writer effects, for writing changes to an attached environment. - -Using as a -starting point. - --} +-- | +-- Module: Control.Monad.Freer.Writer +-- Description: Composable Writer effects. +-- Copyright: (c) 2016 Allele Dev; 2017 Ixperta Solutions s.r.o. +-- License: BSD3 +-- Maintainer: ixcom-core@ixperta.com +-- Stability: experimental +-- Portability: POSIX +-- +-- 'Writer' effects, for writing changes to an attached environment. +-- +-- Using as a starting point. module Control.Monad.Freer.Writer ( Writer(..), tell,