@@ -9,6 +9,18 @@ import Control.Monad.Trans
99import Data.Functor.Identity
1010import Data.Monoid
1111
12+-- | A declare monad transformer parametrized by:
13+--
14+-- * @d@ — the output to accumulate (declarations);
15+--
16+-- * @m@ — the inner monad.
17+--
18+-- This monad transformer is similar to both state and writer monad transformers.
19+-- Thus it can be seen as
20+--
21+-- * a restricted append-only version of a state monad transformer or
22+--
23+-- * a writer monad transformer with the extra ability to read all previous output.
1224newtype DeclareT d m a = DeclareT { runDeclareT :: d -> m (d, a) }
1325 deriving (Functor)
1426
@@ -29,14 +41,28 @@ instance (Monad m, Monoid d) => Monad (DeclareT d m) where
2941instance Monoid d => MonadTrans (DeclareT d) where
3042 lift m = DeclareT (\_ -> (,) mempty <$> m)
3143
44+-- |
45+-- Laws:
46+--
47+-- @
48+-- declare mempty == return ()
49+-- declare x >> declare y == declare (x <> y)
50+--
51+-- declare x >> look == fmap (<> x) look
52+--
53+-- look >> f == f
54+-- @
3255class Monad m => MonadDeclare d m | m -> d where
56+ -- | @'declare' x@ is an action that produces the output @x@.
3357 declare :: d -> m ()
58+ -- | @'look'@ is an action that returns all the output so far.
3459 look :: m d
3560
3661instance (Monad m, Monoid d) => MonadDeclare d (DeclareT d m) where
3762 declare d = DeclareT (\_ -> return (d, ()))
3863 look = DeclareT (\d -> return (mempty, d))
3964
65+-- | Retrieve a function of all the output so far.
4066looks :: MonadDeclare d m => (d -> a) -> m a
4167looks f = f <$> look
4268
@@ -49,6 +75,14 @@ execDeclareT (DeclareT f) d = fst `liftM` f d
4975undeclareT :: (Monad m, Monoid d) => DeclareT d m a -> m a
5076undeclareT = flip evalDeclareT mempty
5177
78+-- | A declare monad parametrized by @d@ — the output to accumulate (declarations).
79+--
80+-- This monad is similar to both state and writer monads.
81+-- Thus it can be seen as
82+--
83+-- * a restricted append-only version of a state monad or
84+--
85+-- * a writer monad with the extra ability to read all previous output.
5286type Declare d = DeclareT d Identity
5387
5488runDeclare :: Declare d a -> d -> (d, a)