diff --git a/Control/Monad/Trans/Accum.hs b/Control/Monad/Trans/Accum.hs --- a/Control/Monad/Trans/Accum.hs +++ b/Control/Monad/Trans/Accum.hs @@ -18,10 +18,12 @@ -- -- The lazy 'AccumT' monad transformer, which adds accumulation -- capabilities (such as declarations or document patches) to a given monad. +-- Each computation has access to the combination of the input environment +-- and outputs added so far, and returns the outputs added. -- --- This monad transformer provides append-only accumulation --- during the computation. For more general access, use --- "Control.Monad.Trans.State" instead. +-- In applications requiring only the ability to accumulate an output and +-- to inspect the output so far, it would be considerably more efficient +-- to use "Control.Monad.Trans.State" instead. ----------------------------------------------------------------------------- module Control.Monad.Trans.Accum ( @@ -78,8 +80,16 @@ -- --------------------------------------------------------------------------- -- | 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'. +-- This monad is a more complex extension of both the reader and writer +-- monads. The 'return' function produces the output 'mempty', while @m +-- '>>=' k@ uses the output of @m@ both to extend the initial environment +-- of @k@ and to combine with the output of @k@: +-- +-- <> +-- +-- In applications requiring only the ability to accumulate an output and +-- to inspect the output so far, it would be considerably more efficient +-- to use a state monad. type Accum w = AccumT w Identity -- | Construct an accumulation computation from a (result, output) pair. @@ -124,21 +134,28 @@ -- -- * @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 +-- This monad transformer is a more complex extension of both the reader +-- and writer monad transformers. The 'return' function produces the +-- output 'mempty', while @m '>>=' k@ uses the output of @m@ both to +-- extend the initial environment of @k@ and to combine with the output +-- of @k@: -- --- * a restricted append-only version of a state monad transformer or +-- <> -- --- * a writer monad transformer with the extra ability to read all previous output. +-- In applications requiring only the ability to accumulate an output and +-- to inspect the output so far, it would be considerably more efficient +-- to use a state monad transformer. newtype AccumT w m a = AccumT (w -> m (a, w)) #if __GLASGOW_HASKELL__ >= 704 deriving (Generic) #endif --- | Unwrap an accumulation computation. +-- | Unwrap an accumulation computation. For example, in the call +-- +-- @ (value, locals) <- runAccumT action globals@ +-- +-- the action is fed an initial environment @globals@, and @locals@ is +-- the sum of all arguments to calls of 'add' executed by the action. runAccumT :: AccumT w m a -> w -> m (a, w) runAccumT (AccumT f) = f {-# INLINE runAccumT #-} @@ -152,8 +169,8 @@ return w' {-# INLINE execAccumT #-} --- | Evaluate an accumulation computation with the given initial output history --- and return the final value, discarding the final output. +-- | 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)@ evalAccumT :: (Monad m, Monoid w) => AccumT w m a -> w -> m a @@ -162,8 +179,8 @@ return a {-# INLINE evalAccumT #-} --- | Map both the return value and output of a computation using --- the given function. +-- | Map both the return value and output of a computation using the +-- given function. -- -- * @'runAccumT' ('mapAccumT' f m) = f . 'runAccumT' m@ mapAccumT :: (m (a, w) -> n (b, w)) -> AccumT w m a -> AccumT w n b diff --git a/Control/Monad/Trans/Class.hs b/Control/Monad/Trans/Class.hs --- a/Control/Monad/Trans/Class.hs +++ b/Control/Monad/Trans/Class.hs @@ -87,15 +87,18 @@ lift :: (Monad m) => m a -> t m a {- $conventions -Most monad transformer modules include the special case of applying -the transformer to 'Data.Functor.Identity.Identity'. For example, +All monad transformer modules except 'Control.Monad.Trans.Maybe' +include the special case of applying the transformer +to 'Data.Functor.Identity.Identity'. For example, @'Control.Monad.Trans.State.Lazy.State' s@ is an abbreviation for @'Control.Monad.Trans.State.Lazy.StateT' s 'Data.Functor.Identity.Identity'@. +As a consequence, operations defined on the monad transformer can also +be used on this special case. Each monad transformer also comes with an operation @run@/XXX/@T@ to unwrap the transformer, exposing a computation of the inner monad. -(Currently these functions are defined as field labels, but in the next -major release they will be separate functions.) +(Currently these functions are defined as field labels, but in a future +major release they may be separate functions.) All of the monad transformers except 'Control.Monad.Trans.Cont.ContT' and 'Control.Monad.Trans.Cont.SelectT' are functors on the category @@ -134,7 +137,7 @@ >>> undefined >> print 2 *** Exception: Prelude.undefined -However the monads 'Data.Functor.Identity.Identity' and @(->) a@ are not: +However, the monads 'Data.Functor.Identity.Identity' and @(->) a@ are not: >>> undefined >> Identity 2 Identity 2 @@ -143,7 +146,7 @@ In a strict monad you know when each action is executed, but the monad is not necessarily strict in the return value, or in other components -of the monad, such as a state. However you can use 'seq' to create +of the monad, such as a state. However, you can use 'seq' to create an action that is strict in the component you want evaluated. -} diff --git a/Control/Monad/Trans/Reader.hs b/Control/Monad/Trans/Reader.hs --- a/Control/Monad/Trans/Reader.hs +++ b/Control/Monad/Trans/Reader.hs @@ -75,8 +75,11 @@ -- -- Computations are functions of a shared environment. -- --- The 'return' function ignores the environment, while @>>=@ passes --- the inherited environment to both subcomputations. +-- The 'return' function ignores the environment, while @m '>>=' k@ +-- passes the inherited environment to both subcomputations: +-- +-- <> +-- type Reader r = ReaderT r Identity -- | Constructor for computations in the reader monad (equivalent to 'asks'). @@ -114,8 +117,11 @@ -- | The reader monad transformer, -- which adds a read-only environment to the given monad. -- --- The 'return' function ignores the environment, while @>>=@ passes --- the inherited environment to both subcomputations. +-- The 'return' function ignores the environment, while @m '>>=' k@ +-- passes the inherited environment to both subcomputations: +-- +-- <> +-- newtype ReaderT r m a = ReaderT { runReaderT :: r -> m a } #if __GLASGOW_HASKELL__ >= 710 deriving (Generic, Generic1) diff --git a/Control/Monad/Trans/Writer/CPS.hs b/Control/Monad/Trans/Writer/CPS.hs --- a/Control/Monad/Trans/Writer/CPS.hs +++ b/Control/Monad/Trans/Writer/CPS.hs @@ -76,8 +76,12 @@ -- --------------------------------------------------------------------------- -- | A writer 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'. +-- The 'return' function produces the output 'mempty', while @m '>>=' k@ +-- combines the outputs of the subcomputations using 'mappend' (also +-- known as @<>@): +-- +-- <> +-- type Writer w = WriterT w Identity -- | Construct a writer computation from a (result, output) pair. @@ -116,9 +120,12 @@ -- -- * @m@ - The inner monad. -- --- The 'return' function produces the output 'mempty', while '>>=' --- combines the outputs of the subcomputations using 'mappend'. - +-- The 'return' function produces the output 'mempty', while @m '>>=' k@ +-- combines the outputs of the subcomputations using 'mappend' (also +-- known as @<>@): +-- +-- <> +-- newtype WriterT w m a = WriterT { unWriterT :: w -> m (a, w) } #if __GLASGOW_HASKELL__ >= 704 deriving (Generic) diff --git a/Control/Monad/Trans/Writer/Lazy.hs b/Control/Monad/Trans/Writer/Lazy.hs --- a/Control/Monad/Trans/Writer/Lazy.hs +++ b/Control/Monad/Trans/Writer/Lazy.hs @@ -81,8 +81,12 @@ -- --------------------------------------------------------------------------- -- | A writer 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'. +-- The 'return' function produces the output 'mempty', while @m '>>=' k@ +-- combines the outputs of the subcomputations using 'mappend' (also +-- known as @<>@): +-- +-- <> +-- type Writer w = WriterT w Identity -- | Construct a writer computation from a (result, output) pair. @@ -119,8 +123,12 @@ -- -- * @m@ - The inner monad. -- --- The 'return' function produces the output 'mempty', while @>>=@ --- combines the outputs of the subcomputations using 'mappend'. +-- The 'return' function produces the output 'mempty', while @m '>>=' k@ +-- combines the outputs of the subcomputations using 'mappend' (also +-- known as @<>@): +-- +-- <> +-- newtype WriterT w m a = WriterT { runWriterT :: m (a, w) } #if __GLASGOW_HASKELL__ >= 704 deriving (Generic) diff --git a/Control/Monad/Trans/Writer/Strict.hs b/Control/Monad/Trans/Writer/Strict.hs --- a/Control/Monad/Trans/Writer/Strict.hs +++ b/Control/Monad/Trans/Writer/Strict.hs @@ -84,8 +84,12 @@ -- --------------------------------------------------------------------------- -- | A writer 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'. +-- The 'return' function produces the output 'mempty', while @m '>>=' k@ +-- combines the outputs of the subcomputations using 'mappend' (also +-- known as @<>@): +-- +-- <> +-- type Writer w = WriterT w Identity -- | Construct a writer computation from a (result, output) pair. @@ -122,8 +126,12 @@ -- -- * @m@ - The inner monad. -- --- The 'return' function produces the output 'mempty', while @>>=@ --- combines the outputs of the subcomputations using 'mappend'. +-- The 'return' function produces the output 'mempty', while @m '>>=' k@ +-- combines the outputs of the subcomputations using 'mappend' (also +-- known as @<>@): +-- +-- <> +-- newtype WriterT w m a = WriterT { runWriterT :: m (a, w) } #if __GLASGOW_HASKELL__ >= 704 deriving (Generic) diff --git a/changelog b/changelog --- a/changelog +++ b/changelog @@ -1,5 +1,8 @@ -*-change-log-*- +0.6.1.1 Ross Paterson Aug 2023 + * Additions to documentation, especially of AccumT. + 0.6.1.0 Ross Paterson Feb 2023 * Add instances of Foldable1 (class added to base-4.18) * Add modifyM to StateT transformers diff --git a/images/bind-AccumT.svg b/images/bind-AccumT.svg new file mode 100644 --- /dev/null +++ b/images/bind-AccumT.svg @@ -0,0 +1,66 @@ + + + + + + + + + + + + + + + + + + <> + + + + + <> + + + w + + + + + m + + k + + diff --git a/images/bind-ReaderT.svg b/images/bind-ReaderT.svg new file mode 100644 --- /dev/null +++ b/images/bind-ReaderT.svg @@ -0,0 +1,57 @@ + + + + + + + + + + + + + + + + + r + + + + + m + + k + + diff --git a/images/bind-WriterT.svg b/images/bind-WriterT.svg new file mode 100644 --- /dev/null +++ b/images/bind-WriterT.svg @@ -0,0 +1,60 @@ + + + + + + + + + + + + + + + + + <> + + + w + + + + + m + + k + + diff --git a/transformers.cabal b/transformers.cabal --- a/transformers.cabal +++ b/transformers.cabal @@ -1,5 +1,5 @@ name: transformers -version: 0.6.1.0 +version: 0.6.1.1 license: BSD3 license-file: LICENSE author: Andy Gill, Ross Paterson @@ -31,9 +31,13 @@ the @mtl@ or @monads-tf@ packages, which automatically lift operations introduced by monad transformers through other transformers. build-type: Simple +extra-doc-files: + images/bind-AccumT.svg + images/bind-ReaderT.svg + images/bind-WriterT.svg extra-source-files: changelog -cabal-version: >= 1.10 +cabal-version: 1.18 source-repository head type: darcs