@@ -7,12 +7,16 @@
7{-# LANGUAGE TypeOperators #-}
7{-# LANGUAGE TypeOperators #-}
8{-# LANGUAGE GeneralizedNewtypeDeriving #-}
8{-# LANGUAGE GeneralizedNewtypeDeriving #-}
9module Control.Monad.Trans.Ether.Reader
9module Control.Monad.Trans.Ether.Reader
11− , Reader
11+ -- * The Reader monad
12− , runReaderT
12+ Reader
13 , runReader
13 , runReader
14− , etherReaderT
14+ -- * The ReaderT monad transformer
15 , mapReaderT
18 , mapReaderT
19+ -- * Lifting other operations
16 , liftCatch
20 , liftCatch
17 , liftCallCC
21 , liftCallCC
@@ -25,7 +29,7 @@ import Control.Monad (MonadPlus)
25import Control.Monad.Fix (MonadFix)
29import Control.Monad.Fix (MonadFix)
26import Control.Monad.Trans.Class (MonadTrans, lift)
30import Control.Monad.Trans.Class (MonadTrans, lift)
27import Control.Monad.IO.Class (MonadIO)
31import Control.Monad.IO.Class (MonadIO)
28−import Control.Ether.Core
32+import Control.Ether.Tags (Tags)
30import qualified Control.Monad.Signatures as Sig
34import qualified Control.Monad.Signatures as Sig
31import qualified Control.Monad.Trans.Reader as Trans
35import qualified Control.Monad.Trans.Reader as Trans
@@ -36,29 +40,48 @@ import qualified Control.Monad.State.Class as Class
36import qualified Control.Monad.Writer.Class as Class
40import qualified Control.Monad.Writer.Class as Class
37import qualified Control.Monad.Error.Class as Class
41import qualified Control.Monad.Error.Class as Class
43+-- | The parameterizable reader monad.
45+-- Computations are functions of a shared environment.
47+-- The 'return' function ignores the environment, while '>>=' passes
48+-- the inherited environment to both subcomputations.
49+type Reader tag r = ReaderT tag r Identity
51+-- | The reader monad transformer,
52+-- which adds a read-only environment to the given monad.
54+-- The 'return' function ignores the environment, while '>>=' passes
55+-- the inherited environment to both subcomputations.
39newtype ReaderT tag r m a = ReaderT (Trans.ReaderT r m a)
56newtype ReaderT tag r m a = ReaderT (Trans.ReaderT r m a)
40 deriving ( Functor, Applicative, Alternative, Monad, MonadPlus
57 deriving ( Functor, Applicative, Alternative, Monad, MonadPlus
41 , MonadFix, MonadTrans, MonadIO )
58 , MonadFix, MonadTrans, MonadIO )
43type instance Tags (ReaderT tag r m) = tag ': Tags m
60type instance Tags (ReaderT tag r m) = tag ': Tags m
45−type Reader tag r = ReaderT tag r Identity
62+-- | Constructor for computations in the reader monad transformer.
47−etherReaderT :: proxy tag -> (r -> m a) -> ReaderT tag r m a
63+readerT :: proxy tag -> (r -> m a) -> ReaderT tag r m a
48−etherReaderT _proxy = ReaderT . Trans.ReaderT
64+readerT _proxy = ReaderT . Trans.ReaderT
66+-- | Runs a 'Reader' and extracts the final value from it.
50runReaderT :: proxy tag -> ReaderT tag r m a -> r -> m a
67runReaderT :: proxy tag -> ReaderT tag r m a -> r -> m a
51runReaderT _proxy (ReaderT (Trans.ReaderT f)) = f
68runReaderT _proxy (ReaderT (Trans.ReaderT f)) = f
70+-- | Runs a 'Reader' and extracts the final value from it.
53runReader :: proxy tag -> Reader tag r a -> r -> a
71runReader :: proxy tag -> Reader tag r a -> r -> a
54runReader proxy m r = runIdentity (runReaderT proxy m r)
72runReader proxy m r = runIdentity (runReaderT proxy m r)
74+-- | Transform the computation inside a @ReaderT@.
76+-- * @'runReaderT' tag ('mapReaderT' tag f m) = f . 'runReaderT' tag m@
56mapReaderT :: proxy tag -> (m a -> n b) -> ReaderT tag r m a -> ReaderT tag r n b
77mapReaderT :: proxy tag -> (m a -> n b) -> ReaderT tag r m a -> ReaderT tag r n b
57mapReaderT _proxy f m = ReaderT $ Trans.mapReaderT f (coerce m)
78mapReaderT _proxy f m = ReaderT $ Trans.mapReaderT f (coerce m)
80+-- | Lift a @catchE@ operation to the new monad.
59liftCatch :: proxy tag -> Sig.Catch e m a -> Sig.Catch e (ReaderT tag r m) a
81liftCatch :: proxy tag -> Sig.Catch e m a -> Sig.Catch e (ReaderT tag r m) a
60liftCatch _proxy f m h = ReaderT $ Trans.liftCatch f (coerce m) (coerce h)
82liftCatch _proxy f m h = ReaderT $ Trans.liftCatch f (coerce m) (coerce h)
84+-- | Lift a @callCC@ operation to the new monad.
62liftCallCC :: proxy tag -> Sig.CallCC m a b -> Sig.CallCC (ReaderT tag r m) a b
85liftCallCC :: proxy tag -> Sig.CallCC m a b -> Sig.CallCC (ReaderT tag r m) a b
63liftCallCC _proxy callCC f = ReaderT $ Trans.liftCallCC callCC (coerce f)
86liftCallCC _proxy callCC f = ReaderT $ Trans.liftCallCC callCC (coerce f)