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

Control.Monad.Accum

Contents

Type class
The Accum monad
The AccumT monad transformer
Lifting helper type
Other functions

Description

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 ReaderT r (State s) a, this is effectively r -> State s a ~ r -> s -> (a, s); if we instead have StateT s (Reader r) a, this is effectively s -> Reader r (a, s) ~ s -> r -> (a, s). Since we can always reorder function arguments (for example, using 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 MaybeT (State s) a, this is effectively State s (Maybe a) ~ s -> (Maybe a, s): put simply, the error can occur only in the result, but not the state, which always 'survives'. On the other hand, if we have StateT s Maybe a, this is instead s -> Maybe (a, s): here, if we error, we lose both the state and the result! Thus, error and state effects do not commute with each other.

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, StateT s Maybe 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.

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 :: Type -> Type) | m -> w where
- look :: m w
- add :: w -> m ()
- accum :: (w -> (a, w)) -> m a
type Accum w = AccumT w Identity
runAccum :: Accum w a -> w -> (a, w)
execAccum :: Accum w a -> w -> w
evalAccum :: Monoid w => Accum w a -> w -> a
mapAccum :: ((a, w) -> (b, w)) -> Accum w a -> Accum w b
newtype AccumT w (m :: Type -> Type) a = AccumT (w -> m (a, w))
execAccumT :: Monad m => AccumT w m a -> w -> m w
evalAccumT :: (Monad m, Monoid w) => AccumT w m a -> w -> m a
mapAccumT :: (m (a, w) -> n (b, w)) -> AccumT w m a -> AccumT w n b
readerToAccumT :: forall (m :: Type -> Type) w a. (Functor m, Monoid w) => ReaderT w m a -> AccumT w m a
writerToAccumT :: forall w (m :: Type -> Type) a. WriterT w m a -> AccumT w m a
accumToStateT :: forall (m :: Type -> Type) s a. (Functor m, Monoid s) => AccumT s m a -> StateT s m a
newtype LiftingAccum (t :: (Type -> Type) -> Type -> Type) (m :: Type -> Type) a = LiftingAccum (t m a)
looks :: forall a m w. MonadAccum w m => (w -> a) -> m a

Type class

class (Monoid w, Monad m) => MonadAccum w (m :: Type -> Type) | 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 to tell) with the ability to view the result of all previous tells.

Laws

accum should obey the following:

accum (const (x, mempty)) = pure x
accum 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 in add v $> res

Since: 2.3

Minimal complete definition

accum | look, add

Methods

look :: m w Source #

Retrieve the accumulated result so far.

add :: w -> m () Source #

Append a value to the result.

accum :: (w -> (a, w)) -> m a Source #

Embed a simple accumulation action into the monad.

Instances

Instances details

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: 2.3
Instance details Defined in Control.Monad.Accum Methods look :: MaybeT m w Source # add :: w -> MaybeT m () Source # accum :: (w -> (a, w)) -> MaybeT m a Source #
(MonadTrans t, Monad (t m), MonadAccum w m) => MonadAccum w (LiftingAccum t m) Source #	Since: 2.3
Instance details Defined in Control.Monad.Accum Methods look :: LiftingAccum t m w Source # add :: w -> LiftingAccum t m () Source # accum :: (w -> (a, w)) -> LiftingAccum t m a Source #
(Monoid w, Monad m) => MonadAccum w (AccumT w m) Source #	Since: 2.3
Instance details Defined in Control.Monad.Accum Methods look :: AccumT w m w Source # add :: w -> AccumT w m () Source # accum :: (w -> (a, w)) -> AccumT w m a Source #
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: 2.3
Instance details Defined in Control.Monad.Accum Methods look :: ExceptT e m w Source # add :: w -> ExceptT e m () Source # accum :: (w -> (a, w)) -> ExceptT e m a Source #
MonadAccum w m => MonadAccum w (IdentityT m) Source #	Since: 2.3
Instance details Defined in Control.Monad.Accum Methods look :: IdentityT m w Source # add :: w -> IdentityT m () Source # accum :: (w -> (a, w)) -> IdentityT m a Source #
MonadAccum w m => MonadAccum w (ReaderT r m) Source #	Since: 2.3
Instance details Defined in Control.Monad.Accum Methods look :: ReaderT r m w Source # add :: w -> ReaderT r m () Source # accum :: (w -> (a, w)) -> ReaderT r m a Source #
MonadAccum w m => MonadAccum w (SelectT r m) Source #	The 'ranking' function gains the ability to accumulate `w`s each time it is called. The final result will include the entire log of all such calls. Since: 2.3
Instance details Defined in Control.Monad.Accum Methods look :: SelectT r m w Source # add :: w -> SelectT r m () Source # accum :: (w -> (a, w)) -> SelectT r m a Source #
MonadAccum w m => MonadAccum w (StateT s m) Source #	Since: 2.3
Instance details Defined in Control.Monad.Accum Methods look :: StateT s m w Source # add :: w -> StateT s m () Source # accum :: (w -> (a, w)) -> StateT s m a Source #
MonadAccum w m => MonadAccum w (StateT s m) Source #	Since: 2.3
Instance details Defined in Control.Monad.Accum Methods look :: StateT s m w Source # add :: w -> StateT s m () Source # accum :: (w -> (a, w)) -> StateT s m a Source #
MonadAccum w' m => MonadAccum w' (WriterT w m) Source #	Since: 2.3
Instance details Defined in Control.Monad.Accum Methods look :: WriterT w m w' Source # add :: w' -> WriterT w m () Source # accum :: (w' -> (a, w')) -> WriterT w m a Source #
(MonadAccum w' m, Monoid w) => MonadAccum w' (WriterT w m) Source #	Since: 2.3
Instance details Defined in Control.Monad.Accum Methods look :: WriterT w m w' Source # add :: w' -> WriterT w m () Source # accum :: (w' -> (a, w')) -> WriterT w m a Source #
(MonadAccum w' m, Monoid w) => MonadAccum w' (WriterT w m) Source #	Since: 2.3
Instance details Defined in Control.Monad.Accum Methods look :: WriterT w m w' Source # add :: w' -> WriterT w m () Source # accum :: (w' -> (a, w')) -> WriterT w m a Source #
MonadAccum w m => MonadAccum w (ContT r m) Source #	The continuation can see, and interact with, the accumulated value. Since: 2.3
Instance details Defined in Control.Monad.Accum Methods look :: ContT r m w Source # add :: w -> ContT r m () Source # accum :: (w -> (a, w)) -> ContT r m a Source #
MonadAccum w' m => MonadAccum w' (RWST r w s m) Source #	Since: 2.3
Instance details Defined in Control.Monad.Accum Methods look :: RWST r w s m w' Source # add :: w' -> RWST r w s m () Source # accum :: (w' -> (a, w')) -> RWST r w s m a Source #
(MonadAccum w' m, Monoid w) => MonadAccum w' (RWST r w s m) Source #	Since: 2.3
Instance details Defined in Control.Monad.Accum Methods look :: RWST r w s m w' Source # add :: w' -> RWST r w s m () Source # accum :: (w' -> (a, w')) -> RWST r w s m a Source #
(MonadAccum w' m, Monoid w) => MonadAccum w' (RWST r w s m) Source #	Since: 2.3
Instance details Defined in Control.Monad.Accum Methods look :: RWST r w s m w' Source # add :: w' -> RWST r w s m () Source # accum :: (w' -> (a, w')) -> RWST r w s m a Source #

The `Accum` monad

type Accum w = AccumT w Identity #

An accumulation monad parameterized by the type w of output to accumulate.

The return function produces the output mempty, while >>= combines the outputs of the subcomputations using mappend.

runAccum :: Accum w a -> w -> (a, w) #

Unwrap an accumulation computation as a (result, output) pair. (The inverse of accum.)

execAccum :: Accum w a -> w -> w #

Extract the output from an accumulation computation.

```
execAccum m w = snd (runAccum m w)
```

evalAccum :: Monoid w => Accum w a -> w -> a #

Evaluate an accumulation computation with the given initial output history and return the final value, discarding the final output.

```
evalAccum m w = fst (runAccum m w)
```

mapAccum :: ((a, w) -> (b, w)) -> Accum w a -> Accum w b #

Map both the return value and output of a computation using the given function.

runAccum (mapAccum f m) = f . runAccum m

The `AccumT` monad transformer

newtype AccumT w (m :: Type -> Type) a #

An accumulation monad parameterized by:

w - the output to accumulate.
m - The inner monad.

The return function produces the output mempty, while >>= combines the outputs of the subcomputations using mappend.

This monad transformer is similar to both state and writer monad transformers. Thus it can be seen as

a restricted append-only version of a state monad transformer or
a writer monad transformer with the extra ability to read all previous output.

Constructors

AccumT (w -> m (a, w))

Instances

Instances details

(Monoid w, Monad m) => MonadAccum w (AccumT w m) Source #

Since: 2.3

Instance details

Defined in Control.Monad.Accum

Methods

look :: AccumT w m w Source #

add :: w -> AccumT w m () Source #

accum :: (w -> (a, w)) -> AccumT w m a Source #

(Monoid w, MonadError e m) => MonadError e (AccumT w m) Source #

Since: 2.3

Instance details

Defined in Control.Monad.Error.Class

Methods

throwError :: e -> AccumT w m a Source #

catchError :: AccumT w m a -> (e -> AccumT w m a) -> AccumT w m a Source #

(Monoid w, MonadReader r m) => MonadReader r (AccumT w m) Source #

Since: 2.3

Instance details

Defined in Control.Monad.Reader.Class

Methods

ask :: AccumT w m r Source #

local :: (r -> r) -> AccumT w m a -> AccumT w m a Source #

reader :: (r -> a) -> AccumT w m a Source #

(MonadSelect r m, Monoid w) => MonadSelect r (AccumT w m) Source #

'Readerizes' the accumulator: the 'ranking' function can see the value that has been accumulated (of type w), but can't add anything to it. Effectively, can be thought of as 'extending' the 'ranking' by all values of w, but which w gets given to any rank calls is predetermined by the 'outer accumulation' (and cannot change).

Since: 2.3

Instance details

Defined in Control.Monad.Select

Methods

select :: ((a -> r) -> a) -> AccumT w m a Source #

(Monoid w, MonadState s m) => MonadState s (AccumT w m) Source #

Since: 2.3

Instance details

Defined in Control.Monad.State.Class

Methods

get :: AccumT w m s Source #

put :: s -> AccumT w m () Source #

state :: (s -> (a, s)) -> AccumT w m a Source #

(Monoid w', MonadWriter w m) => MonadWriter w (AccumT w' m) Source #

There are two valid instances for AccumT. It could either:

Lift the operations to the inner MonadWriter
Handle the operations itself, à la a WriterT.

This instance chooses (1), reflecting that the intent of AccumT as a type is different than that of WriterT.

Since: 2.3

Instance details

Defined in Control.Monad.Writer.Class

Methods

writer :: (a, w) -> AccumT w' m a Source #

tell :: w -> AccumT w' m () Source #

listen :: AccumT w' m a -> AccumT w' m (a, w) Source #

pass :: AccumT w' m (a, w -> w) -> AccumT w' m a Source #

Monoid w => MonadTrans (AccumT w)

Instance details

Defined in Control.Monad.Trans.Accum

Methods

lift :: Monad m => m a -> AccumT w m a #

(Monoid w, MonadFail m) => MonadFail (AccumT w m)

Instance details

Defined in Control.Monad.Trans.Accum

Methods

fail :: String -> AccumT w m a #

(Monoid w, Functor m, MonadFix m) => MonadFix (AccumT w m)

Instance details

Defined in Control.Monad.Trans.Accum

Methods

mfix :: (a -> AccumT w m a) -> AccumT w m a #

(Monoid w, Functor m, MonadIO m) => MonadIO (AccumT w m)

Instance details

Defined in Control.Monad.Trans.Accum

Methods

liftIO :: IO a -> AccumT w m a #

(Monoid w, Functor m, MonadPlus m) => Alternative (AccumT w m)

Instance details

Defined in Control.Monad.Trans.Accum

Methods

empty :: AccumT w m a #

(<|>) :: AccumT w m a -> AccumT w m a -> AccumT w m a #

some :: AccumT w m a -> AccumT w m [a] #

many :: AccumT w m a -> AccumT w m [a] #

(Monoid w, Functor m, Monad m) => Applicative (AccumT w m)

Instance details

Defined in Control.Monad.Trans.Accum

Methods

pure :: a -> AccumT w m a #

(<*>) :: AccumT w m (a -> b) -> AccumT w m a -> AccumT w m b #

liftA2 :: (a -> b -> c) -> AccumT w m a -> AccumT w m b -> AccumT w m c #

(*>) :: AccumT w m a -> AccumT w m b -> AccumT w m b #

(<*) :: AccumT w m a -> AccumT w m b -> AccumT w m a #

Functor m => Functor (AccumT w m)

Instance details

Defined in Control.Monad.Trans.Accum

Methods

fmap :: (a -> b) -> AccumT w m a -> AccumT w m b #

(<$) :: a -> AccumT w m b -> AccumT w m a #

(Monoid w, Functor m, Monad m) => Monad (AccumT w m)

Instance details

Defined in Control.Monad.Trans.Accum

Methods

(>>=) :: AccumT w m a -> (a -> AccumT w m b) -> AccumT w m b #

(>>) :: AccumT w m a -> AccumT w m b -> AccumT w m b #

return :: a -> AccumT w m a #

(Monoid w, Functor m, MonadPlus m) => MonadPlus (AccumT w m)

Instance details

Defined in Control.Monad.Trans.Accum

Methods

mzero :: AccumT w m a #

mplus :: AccumT w m a -> AccumT w m a -> AccumT w m a #

(Monoid w, MonadCont m) => MonadCont (AccumT w m) Source #

Since: 2.3

Instance details

Defined in Control.Monad.Cont.Class

Methods

callCC :: ((a -> AccumT w m b) -> AccumT w m a) -> AccumT w m a Source #

Generic (AccumT w m a)

Instance details

Defined in Control.Monad.Trans.Accum

Associated Types

type Rep (AccumT w m a)
Instance details Defined in Control.Monad.Trans.Accum type Rep (AccumT w m a) = D1 ('MetaData "AccumT" "Control.Monad.Trans.Accum" "transformers-0.6.1.0-inplace" 'True) (C1 ('MetaCons "AccumT" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (w -> m (a, w)))))

Methods

from :: AccumT w m a -> Rep (AccumT w m a) x #

to :: Rep (AccumT w m a) x -> AccumT w m a #

type Rep (AccumT w m a)

Instance details

Defined in Control.Monad.Trans.Accum

type Rep (AccumT w m a) = D1 ('MetaData "AccumT" "Control.Monad.Trans.Accum" "transformers-0.6.1.0-inplace" 'True) (C1 ('MetaCons "AccumT" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (w -> m (a, w)))))

execAccumT :: Monad m => AccumT w m a -> w -> m w #

Extract the output from an accumulation computation.

execAccumT m w = liftM snd (runAccumT m w)

evalAccumT :: (Monad m, Monoid w) => AccumT w m a -> w -> m a #

Evaluate an accumulation computation with the given initial output history and return the final value, discarding the final output.

evalAccumT m w = liftM fst (runAccumT m w)

mapAccumT :: (m (a, w) -> n (b, w)) -> AccumT w m a -> AccumT w n b #

Map both the return value and output of a computation using the given function.

runAccumT (mapAccumT f m) = f . runAccumT m

readerToAccumT :: forall (m :: Type -> Type) w a. (Functor m, Monoid w) => ReaderT w m a -> AccumT w m a #

Convert a read-only computation into an accumulation computation.

writerToAccumT :: forall w (m :: Type -> Type) a. WriterT w m a -> AccumT w m a #

Convert a writer computation into an accumulation computation.

accumToStateT :: forall (m :: Type -> Type) s a. (Functor m, Monoid s) => AccumT s m a -> StateT s m a #

Convert an accumulation (append-only) computation into a fully stateful computation.

Lifting helper type

newtype LiftingAccum (t :: (Type -> Type) -> Type -> Type) (m :: Type -> Type) a 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: 2.3

Constructors

LiftingAccum (t m a)

Instances

Instances details

(MonadTrans t, Monad (t m), MonadAccum w m) => MonadAccum w (LiftingAccum t m) Source #	Since: 2.3
Instance details Defined in Control.Monad.Accum Methods look :: LiftingAccum t m w Source # add :: w -> LiftingAccum t m () Source # accum :: (w -> (a, w)) -> LiftingAccum t m a Source #
Applicative (t m) => Applicative (LiftingAccum t m) Source #	Since: 2.3
Instance details Defined in Control.Monad.Accum Methods pure :: a -> LiftingAccum t m a # (<>) :: LiftingAccum t m (a -> b) -> LiftingAccum t m a -> LiftingAccum t m b # liftA2 :: (a -> b -> c) -> LiftingAccum t m a -> LiftingAccum t m b -> LiftingAccum t m c # (>) :: LiftingAccum t m a -> LiftingAccum t m b -> LiftingAccum t m b # (<*) :: LiftingAccum t m a -> LiftingAccum t m b -> LiftingAccum t m a #
Functor (t m) => Functor (LiftingAccum t m) Source #	Since: 2.3
Instance details Defined in Control.Monad.Accum Methods fmap :: (a -> b) -> LiftingAccum t m a -> LiftingAccum t m b # (<$) :: a -> LiftingAccum t m b -> LiftingAccum t m a #
Monad (t m) => Monad (LiftingAccum t m) Source #	Since: 2.3
Instance details Defined in Control.Monad.Accum Methods (>>=) :: LiftingAccum t m a -> (a -> LiftingAccum t m b) -> LiftingAccum t m b # (>>) :: LiftingAccum t m a -> LiftingAccum t m b -> LiftingAccum t m b # return :: a -> LiftingAccum t m a #

Other functions

looks :: forall a m w. MonadAccum w m => (w -> a) -> m a Source #

Retrieve a function of the accumulated value.

Since: 2.3

A note on commutativity

Commutativity of accumulation

Type class

Laws

Instances

The Accum monad

The AccumT monad transformer

Instances

Lifting helper type

Instances

Other functions

The `Accum` monad

The `AccumT` monad transformer