Copyright | (C) Koz Ross 2022 Manuel Bärenz 2021 |
---|---|
License | BSD-3-Clause (see the LICENSE file) |
Maintainer | koz.ross@retro-freedom.nz |
Stability | Experimental |
Portability | GHC only |
Safe Haskell | Trustworthy |
Language | Haskell2010 |
- Computation type:
- Accumulation (either append-only state, or writer with the ability to read all previous input).
- Binding strategy:
- Binding a function to a monadic value monoidally
accumulates the subcomputations (that is, using
<>
). - Useful for:
- Logging, patch-style tracking.
- Zero and plus:
- None.
- Example type:
Accum
w a
A note on commutativity
Some effects are commutative: it doesn't matter which you resolve first, as
all possible orderings of commutative effects are isomorphic. Consider, for
example, the reader and state effects, as exemplified by ReaderT
and
StateT
respectively. If we have
, this is
effectively ReaderT
r (State
s) ar ->
; if we instead have
State
s a ~ r -> s -> (a, s)
, this is effectively
StateT
s (Reader
r) as ->
. Since we
can always reorder function arguments (for example, using Reader
r (a, s) ~ s -> r -> (a, s)flip
, as in
this case) without changing the result, these are
isomorphic, showing that reader and state are commutative, or, more
precisely, commute with each other.
However, this isn't generally the case. Consider instead the error and state
effects, as exemplified by MaybeT
and StateT
respectively.
If we have
, this
is effectively MaybeT
(State
s) a
: put simply,
the error can occur only in the result, but
not the state, which always 'survives'. On the other hand, if we have
State
s (Maybe
a) ~ s -> (Maybe
a, s)
, this is instead StateT
s Maybe
as ->
: here,
if we error, we lose both the state and the result! Thus, error and state effects
do not commute with each other.Maybe
(a, s)
As the MTL is capability-based, we support any ordering of non-commutative
effects on an equal footing. Indeed, if you wish to use
MonadState
, for
example, whether your final monadic stack ends up being
, MaybeT
(State
s)
a
, or anything else, you will be able to write your
desired code without having to consider such differences. However, the way we
implement these capabilities for any given transformer (or rather, any
given transformed stack) is affected by this ordering unless the effects in
question are commutative.StateT
s Maybe
a
We note in this module which effects the accumulation effect does and doesn't commute with; we also note on implementations with non-commutative transformers what the outcome will be. Note that, depending on how the 'inner monad' is structured, this may be more complex than we note: we describe only what impact the 'outer effect' has, not what else might be in the stack.
Commutativity of accumulation
The accumulation effect commutes with the identity effect (IdentityT
),
reader, writer or state effects (ReaderT
, WriterT
, StateT
and any
combination, including RWST
for example) and with itself. It does not
commute with anything else.
Synopsis
- class (Monoid w, Monad m) => MonadAccum w m | m -> w where
- newtype LiftingAccum (t :: (Type -> Type) -> Type -> Type) (m :: Type -> Type) (a :: Type) = LiftingAccum (t m a)
- looks :: forall (a :: Type) (m :: Type -> Type) (w :: Type). MonadAccum w m => (w -> a) -> m a
Type class
class (Monoid w, Monad m) => MonadAccum w m | m -> w where Source #
The capability to accumulate. This can be seen in one of two ways:
- A
MonadState
which can only append (using<>
); or - A
MonadWriter
(limited totell
) with the ability to view the result of all previoustell
s.
Laws
accum
should obey the following:
accum
(const
(x,mempty
))=
pure
xaccum
f*>
accum
g=
accum
$
acc -> let (_, v) = f acc (res, w) = g (acc<>
v) in (res, v<>
w)
If you choose to define look
and add
instead, their definitions must obey
the following:
look
*>
look
=
look
add
mempty
=
pure
()add
x*>
add
y=
add
(x<>
y)add
x*>
look
=
look
>>=
w ->add
x$>
w<>
x
If you want to define both, the relationship between them is as follows. These are also the default definitions.
look
=
accum
$
acc -> (acc, mempty)add
x=
accum
$
acc -> (()
, x)accum
f=
look
>>= acc -> let (res, v) = f acc inadd
v$>
res
Since: mtl-2.3
Retrieve the accumulated result so far.
Append a value to the result.
accum :: (w -> (a, w)) -> m a Source #
Embed a simple accumulation action into the monad.
Instances
MonadAccum w m => MonadAccum w (MaybeT m) Source # | The accumulated value 'survives' an error: even if the computation fails to deliver a result, we still have an accumulated value. Since: mtl-2.3 |
(MonadTrans t, Monad (t m), MonadAccum w m) => MonadAccum w (LiftingAccum t m) Source # | Since: mtl-2.3 |
Defined in Control.Monad.Accum look :: LiftingAccum t m w Source # add :: w -> LiftingAccum t m () Source # accum :: (w -> (a, w)) -> LiftingAccum t m a Source # | |
Monoid w => MonadAccum w (AccumT w Identity) Source # | Since: mtl-2.3 |
MonadAccum w m => MonadAccum w (ExceptT e m) Source # | The accumulated value 'survives' an exception: even if the computation fails to deliver a result, we still have an accumulated value. Since: mtl-2.3 |
MonadAccum w m => MonadAccum w (IdentityT m) Source # | Since: mtl-2.3 |
MonadAccum w m => MonadAccum w (ReaderT r m) Source # | Since: mtl-2.3 |
MonadAccum w m => MonadAccum w (SelectT r m) Source # | The 'ranking' function gains the ability to accumulate Since: mtl-2.3 |
MonadAccum w m => MonadAccum w (StateT s m) Source # | Since: mtl-2.3 |
MonadAccum w m => MonadAccum w (StateT s m) Source # | Since: mtl-2.3 |
MonadAccum w' m => MonadAccum w' (WriterT w m) Source # | Since: mtl-2.3 |
(MonadAccum w' m, Monoid w) => MonadAccum w' (WriterT w m) Source # | Since: mtl-2.3 |
(MonadAccum w' m, Monoid w) => MonadAccum w' (WriterT w m) Source # | Since: mtl-2.3 |
MonadAccum w m => MonadAccum w (ContT r m) Source # | The continuation can see, and interact with, the accumulated value. Since: mtl-2.3 |
MonadAccum w' m => MonadAccum w' (RWST r w s m) Source # | Since: mtl-2.3 |
(MonadAccum w' m, Monoid w) => MonadAccum w' (RWST r w s m) Source # | Since: mtl-2.3 |
(MonadAccum w' m, Monoid w) => MonadAccum w' (RWST r w s m) Source # | Since: mtl-2.3 |
Lifting helper type
newtype LiftingAccum (t :: (Type -> Type) -> Type -> Type) (m :: Type -> Type) (a :: Type) Source #
A helper type to decrease boilerplate when defining new transformer
instances of MonadAccum
.
Most of the instances in this module are derived using this method; for
example, our instance of ExceptT
is derived as follows:
deriving via (LiftingAccum (ExceptT e) m) instance (MonadAccum w m) => MonadAccum w (ExceptT e m)
Since: mtl-2.3
LiftingAccum (t m a) |