mirror of
https://github.com/haskell-effectful/effectful.git
synced 2024-11-22 22:14:21 +03:00
Release 1.0.0.0 (#67)
Fixes https://github.com/haskell-effectful/effectful/issues/20.
This commit is contained in:
Andrzej Rybczak
GitHub
parent
66c71d78d2
commit
1ebe7e1658
@ -1,2 +0,0 @@
|
||||
# effectful-0.0.0.0 (2021-06-13)
|
||||
* Initial alpha release.
|
||||
30
LICENSE
30
LICENSE
@ -1,30 +0,0 @@
|
||||
Copyright (c) 2021-2022, Andrzej Rybczak
|
||||
|
||||
All rights reserved.
|
||||
|
||||
Redistribution and use in source and binary forms, with or without
|
||||
modification, are permitted provided that the following conditions are met:
|
||||
|
||||
* Redistributions of source code must retain the above copyright
|
||||
notice, this list of conditions and the following disclaimer.
|
||||
|
||||
* Redistributions in binary form must reproduce the above
|
||||
copyright notice, this list of conditions and the following
|
||||
disclaimer in the documentation and/or other materials provided
|
||||
with the distribution.
|
||||
|
||||
* Neither the name of Andrzej Rybczak nor the names of other
|
||||
contributors may be used to endorse or promote products derived
|
||||
from this software without specific prior written permission.
|
||||
|
||||
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
||||
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
||||
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
|
||||
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
||||
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
||||
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
||||
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
||||
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
||||
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
||||
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
68
README.md
68
README.md
@ -1,16 +1,14 @@
|
||||
# effectful
|
||||
|
||||
[](https://github.com/haskell-effectful/effectful/actions?query=branch%3Amaster)
|
||||
[](https://rybczak.net/files/effectful/effectful-core-0.1-docs)
|
||||
[](https://rybczak.net/files/effectful/effectful-th-0.1-docs)
|
||||
[](https://rybczak.net/files/effectful/effectful-0.1-docs)
|
||||
[](https://hackage.haskell.org/package/effectful)
|
||||
[](https://packdeps.haskellers.com/feed?needle=andrzej@rybczak.net)
|
||||
[](https://www.stackage.org/lts/package/effectful)
|
||||
[](https://www.stackage.org/nightly/package/effectful)
|
||||
|
||||
|
||||
<img src="https://user-images.githubusercontent.com/387658/127747903-f728437f-2ee4-47b8-9f0c-5102fd44c8e4.png" width="128">
|
||||
|
||||
*Note:* this is a pre-release of the 0.1 version. Please disregard the 0.0.0.0
|
||||
version available on Hackage as the API has been completely redesigned since
|
||||
then.
|
||||
|
||||
An easy to use, fast extensible effects library with seamless integration with
|
||||
the existing Haskell ecosystem.
|
||||
|
||||
@ -19,9 +17,7 @@ Main features:
|
||||
1. Very fast
|
||||
([benchmarks](https://github.com/haskell-effectful/effectful/tree/master/benchmarks/README.md)).
|
||||
|
||||
2. Easy to use API (if you know how to use the
|
||||
[MonadUnliftIO](https://hackage.haskell.org/package/unliftio-core/docs/Control-Monad-IO-Unlift.html#t:MonadUnliftIO)
|
||||
class, you know how to write effects).
|
||||
2. Easy to use API (comparable with usage of the [MonadUnliftIO](https://hackage.haskell.org/package/unliftio-core/docs/Control-Monad-IO-Unlift.html#t:MonadUnliftIO) class).
|
||||
|
||||
3. Correct semantics in presence of runtime exceptions (no more discarded state
|
||||
updates).
|
||||
@ -76,17 +72,17 @@ However:
|
||||
- `mtl` style effects are
|
||||
[slow](https://github.com/haskell-effectful/effectful/tree/master/benchmarks/README.md).
|
||||
|
||||
- All of most often used monad transformers (except `ReaderT`) used for effect
|
||||
- The majority of popular monad transformers (except `ReaderT`) used for effect
|
||||
implementations are rife with [subtle
|
||||
issues](https://github.com/haskell-effectful/effectful/tree/master/transformers.md).
|
||||
|
||||
These issues are problematic enough that the [ReaderT design
|
||||
These are problematic enough that the [ReaderT design
|
||||
pattern](https://www.fpcomplete.com/blog/2017/06/readert-design-pattern/) was
|
||||
invented. Its fundamentals are solid, but it's not an effect system.
|
||||
|
||||
The solution? Use the `ReaderT` pattern as a base and build around it to make it
|
||||
an effect system! This is where `effectful` comes in. The `Eff` monad it uses is
|
||||
essentially a `ReaderT` over `IO` on steroids, allowing us to dynamically extend
|
||||
A solution? Use the `ReaderT` pattern as a base and build around it to make an
|
||||
extensible effects library! This is where `effectful` comes in. The `Eff` monad
|
||||
it uses is essentially a `ReaderT` over `IO` on steroids, allowing us to extend
|
||||
its environment with data types representing effects.
|
||||
|
||||
This concept is quite simple, so:
|
||||
@ -105,8 +101,8 @@ optimization passes, it just works.
|
||||
|
||||
### Any downsides?
|
||||
|
||||
As always, there's no free lunch. `Eff` doesn't support `NonDet` nor `Coroutine`
|
||||
effects. However, the `NonDet` effect in existing libraries is
|
||||
As always, there's no free lunch. The `Eff` monad doesn't support `NonDet` nor
|
||||
`Coroutine` effects. However, the `NonDet` effect in existing libraries is
|
||||
[broken](https://github.com/lexi-lambda/eff/blob/8c4df4bf54faf22456354be18095b14825be5e85/notes/semantics-zoo.md)
|
||||
and none of the ones with support for higher order effects provide the
|
||||
`Coroutine` effect, so arguably it's not a big loss.
|
||||
@ -118,32 +114,36 @@ libraries such as [conduit](https://hackage.haskell.org/package/conduit) or
|
||||
|
||||
### Summary
|
||||
|
||||
`effectful` aims to replace "boring" transformer stacks (which consist of a
|
||||
dozen of newtype'd `ExceptT`, `ReaderT`, `StateT` and `WriterT` transformers) by
|
||||
providing equivalent effects with improved semantics, performance and usability
|
||||
(it also makes it easy to reuse them for your own effects). It doesn't try to
|
||||
make monad transformers obsolete, so you're free to use it with `ConduitT`,
|
||||
`ContT`, `ListT` etc. when necessary.
|
||||
`effectful` is an extensible effects library that aims to replace "boring"
|
||||
transformer stacks (which consist of a dozen of newtype'd `ExceptT`, `ReaderT`,
|
||||
`StateT` and `WriterT` transformers) and their derivatives by providing
|
||||
equivalent effects with improved semantics, performance and usability (it also
|
||||
makes it easy to reuse them for your own effects). It doesn't try to make monad
|
||||
transformers obsolete, so you're free to use it with `ConduitT`, `ContT`,
|
||||
`ListT` etc. when necessary.
|
||||
|
||||
## Ecosystem
|
||||
## Package structure
|
||||
|
||||
The effect system is split among several libraries:
|
||||
|
||||
- The `effectful-core` library contains the main machinery of the effect system
|
||||
itself and basic effects. It aims for a small dependency footprint and
|
||||
provides building blocks for more advanced effects.
|
||||
- The [`effectful-core`](https://hackage.haskell.org/package/effectful-core)
|
||||
library contains the core of the effect system along with the basic
|
||||
effects. It aims for a small dependency footprint and provides building blocks
|
||||
for more advanced effects.
|
||||
|
||||
- The `effectful-plugin` library provides an optional GHC plugin for improving
|
||||
disambiguation of effects (see
|
||||
- The [`effectful-plugin`](https://hackage.haskell.org/package/effectful-plugin)
|
||||
library provides an optional GHC plugin for improving disambiguation of
|
||||
effects (see
|
||||
[here](https://github.com/haskell-effectful/effectful/blob/master/effectful-plugin/README.md)
|
||||
for more information).
|
||||
|
||||
- The `effectful-th` library provides utilities for generating bits of
|
||||
effect-related boilerplate via Template Haskell.
|
||||
- The [`effectful-th`](https://hackage.haskell.org/package/effectful-th) library
|
||||
provides utilities for generating bits of effect-related boilerplate via
|
||||
Template Haskell.
|
||||
|
||||
- The `effectful` library re-exports public modules of `effectful-core` and
|
||||
additionally provides most features of the `unliftio` library divided into
|
||||
appropriate effects.
|
||||
- The [`effectful`](https://hackage.haskell.org/package/effectful) library
|
||||
re-exports public modules of `effectful-core` and additionally provides most
|
||||
features of the `unliftio` library divided into appropriate effects.
|
||||
|
||||
## Example
|
||||
|
||||
|
||||
@ -1,2 +1,2 @@
|
||||
# effectful-core-0.0.0.0 (2021-06-13)
|
||||
* Initial alpha release.
|
||||
# effectful-core-1.0.0.0 (2022-07-13)
|
||||
* Initial release.
|
||||
|
||||
1
effectful-core/README.md
Symbolic link
1
effectful-core/README.md
Symbolic link
@ -0,0 +1 @@
|
||||
../README.md
|
||||
@ -1,7 +1,7 @@
|
||||
cabal-version: 2.4
|
||||
build-type: Simple
|
||||
name: effectful-core
|
||||
version: 0.1
|
||||
version: 1.0.0.0
|
||||
license: BSD-3-Clause
|
||||
license-file: LICENSE
|
||||
category: Control
|
||||
@ -16,7 +16,9 @@ description: An easy to use, performant extensible effects library with seamless
|
||||
footprint. See the @<https://hackage.haskell.org/package/effectful effectful>@
|
||||
package for the "batteries-included" variant.
|
||||
|
||||
extra-source-files: CHANGELOG.md
|
||||
extra-source-files:
|
||||
CHANGELOG.md
|
||||
README.md
|
||||
|
||||
tested-with: GHC ==8.8.4 || ==8.10.7 || ==9.0.2 || ==9.2.3 || ==9.4.1
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@ module Effectful
|
||||
( -- * Introduction
|
||||
-- $intro
|
||||
|
||||
-- ** Integration of existing libraries
|
||||
-- ** Integration with existing libraries
|
||||
-- $integration
|
||||
|
||||
-- *** Transformed monads
|
||||
@ -120,7 +120,7 @@ import Effectful.Internal.Monad
|
||||
--
|
||||
-- There are three main groups a library might fall into. It either operates:
|
||||
--
|
||||
-- 1) In a monad of your application transformed by a specific monad
|
||||
-- 1) In a monad of your application transformed by a library specific monad
|
||||
-- transformer.
|
||||
--
|
||||
-- 2) In its own, concrete monad, which is usually 'IO' or a couple of monad
|
||||
@ -183,10 +183,11 @@ import Effectful.Internal.Monad
|
||||
--
|
||||
-- Some libraries operate in a transformer stack over 'IO' or have its own
|
||||
-- concrete monad that's a newtype over 'IO', e.g. @Handler@ from the
|
||||
-- @servant-server@ package.
|
||||
-- [servant-server](https://hackage.haskell.org/package/servant-server) package.
|
||||
--
|
||||
-- In such case it's best to mimic the monad in question by the 'Eff' monad with
|
||||
-- appropriate effects (as standard monad transformers have [subtle
|
||||
-- In such case it's best to mirror the monad in question by the 'Eff' monad
|
||||
-- with appropriate effects (as tha majority of popular monad transformers have
|
||||
-- [subtle
|
||||
-- issues](https://github.com/haskell-effectful/effectful/blob/master/transformers.md)),
|
||||
-- use it as soon as possible, then at the end feed the final state to the monad
|
||||
-- of the library so it proceeds as if nothing unusual happened.
|
||||
|
||||
@ -9,7 +9,7 @@ module Effectful.Dispatch.Dynamic
|
||||
-- ** First order and higher order effects
|
||||
-- $order
|
||||
|
||||
-- ** Integration of @mtl@ style effects #integration#
|
||||
-- ** Integration with @mtl@ style effects #integration#
|
||||
-- $integration
|
||||
|
||||
-- * Sending operations to the handler
|
||||
@ -299,7 +299,7 @@ import Effectful.Internal.Monad
|
||||
-- :}
|
||||
--
|
||||
-- To make it possible to use it with the 'Eff' monad, the first step is to
|
||||
-- create an effect with operations that mimic the ones of a type class:
|
||||
-- create an effect with operations that mirror the ones of a type class:
|
||||
--
|
||||
-- >>> :{
|
||||
-- data RNG :: Effect where
|
||||
|
||||
@ -1,2 +1,2 @@
|
||||
# effectful-plugin-0.1 (2022-??-??)
|
||||
# effectful-plugin-1.0.0.0 (2022-07-13)
|
||||
* Initial release.
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
cabal-version: 2.4
|
||||
build-type: Simple
|
||||
name: effectful-plugin
|
||||
version: 0.1
|
||||
version: 1.0.0.0
|
||||
license: BSD-3-Clause
|
||||
license-file: LICENSE
|
||||
category: Control
|
||||
@ -58,7 +58,7 @@ library
|
||||
import: language
|
||||
|
||||
build-depends: base >= 4.13 && < 5
|
||||
, effectful-core >= 0.1 && < 0.1.1
|
||||
, effectful-core >= 1.0.0.0 && < 1.0.1.0
|
||||
, containers >= 0.5
|
||||
, ghc >= 8.6 && < 9.3
|
||||
, ghc-tcplugins-extra >= 0.3 && < 0.5
|
||||
|
||||
@ -1,2 +1,2 @@
|
||||
# effectful-th-0.1 (2022-??-??)
|
||||
# effectful-th-1.0.0.0 (2022-07-13)
|
||||
* Initial release.
|
||||
|
||||
1
effectful-th/README.md
Symbolic link
1
effectful-th/README.md
Symbolic link
@ -0,0 +1 @@
|
||||
../README.md
|
||||
@ -1,7 +1,7 @@
|
||||
cabal-version: 2.4
|
||||
build-type: Simple
|
||||
name: effectful-th
|
||||
version: 0.1
|
||||
version: 1.0.0.0
|
||||
license: BSD-3-Clause
|
||||
license-file: LICENSE
|
||||
category: Control
|
||||
@ -12,7 +12,9 @@ synopsis: Template Haskell utilities for the effectful library.
|
||||
description: Generate functions for performing operations of dynamically
|
||||
dispatched effects via Template Haskell.
|
||||
|
||||
extra-source-files: CHANGELOG.md
|
||||
extra-source-files:
|
||||
CHANGELOG.md
|
||||
README.md
|
||||
|
||||
tested-with: GHC ==8.8.4 || ==8.10.7 || ==9.0.2 || ==9.2.3 || ==9.4.1
|
||||
|
||||
@ -53,7 +55,7 @@ library
|
||||
|
||||
build-depends: base >= 4.13 && < 5
|
||||
, containers >= 0.6
|
||||
, effectful >= 0.1 && < 0.1.1
|
||||
, effectful >= 1.0.0.0 && < 1.0.1.0
|
||||
, exceptions >= 0.10.4
|
||||
, template-haskell >= 2.15 && < 2.20
|
||||
, th-abstraction >= 0.4 && < 0.5
|
||||
|
||||
@ -1,2 +1,2 @@
|
||||
# effectful-0.0.0.0 (2021-06-13)
|
||||
* Initial alpha release.
|
||||
# effectful-1.0.0.0 (2021-07-13)
|
||||
* Initial release.
|
||||
|
||||
1
effectful/README.md
Symbolic link
1
effectful/README.md
Symbolic link
@ -0,0 +1 @@
|
||||
../README.md
|
||||
@ -1,7 +1,7 @@
|
||||
cabal-version: 2.4
|
||||
build-type: Simple
|
||||
name: effectful
|
||||
version: 0.1
|
||||
version: 1.0.0.0
|
||||
license: BSD-3-Clause
|
||||
license-file: LICENSE
|
||||
category: Control
|
||||
@ -16,7 +16,9 @@ description: An easy to use, performant extensible effects library with seamless
|
||||
@<https://hackage.haskell.org/package/effectful-core effectful-core>@
|
||||
package if you need a more limited dependency footprint.
|
||||
|
||||
extra-source-files: CHANGELOG.md
|
||||
extra-source-files:
|
||||
CHANGELOG.md
|
||||
README.md
|
||||
|
||||
tested-with: GHC ==8.8.4 || ==8.10.7 || ==9.0.2 || ==9.2.3 || ==9.4.1
|
||||
|
||||
@ -63,7 +65,7 @@ library
|
||||
, async >= 2.2.2
|
||||
, bytestring >= 0.10
|
||||
, directory >= 1.3.2
|
||||
, effectful-core >= 0.1 && < 0.1.1
|
||||
, effectful-core >= 1.0.0.0 && < 1.0.1.0
|
||||
, process >= 1.6.9
|
||||
|
||||
, time >= 1.9.2
|
||||
|
||||
Loading…
Reference in New Issue
Block a user