mtl-2.3.1: Monad classes for transformers, using functional dependencies
Copyright(c) Andy Gill 2001
(c) Oregon Graduate Institute of Science and Technology 2001
(c) Jeff Newbern 2003-2007
(c) Andriy Palamarchuk 2007
LicenseBSD-style (see the file LICENSE)
Maintainerlibraries@haskell.org
Stabilityexperimental
Portabilitynon-portable (multi-param classes, functional dependencies)
Safe HaskellSafe
LanguageHaskell2010

Control.Monad.Reader

Description

Computation type:
Computations which read values from a shared environment.
Binding strategy:
Monad values are functions from the environment to a value. The bound function is applied to the bound value, and both have access to the shared environment.
Useful for:
Maintaining variable bindings, or other shared environment.
Zero and plus:
None.
Example type:
Reader [(String,Value)] a

The Reader monad (also called the Environment monad). Represents a computation, which can read values from a shared environment, pass values from function to function, and execute sub-computations in a modified environment. Using Reader monad for such computations is often clearer and easier than using the State monad.

Inspired by the paper Functional Programming with Overloading and Higher-Order Polymorphism, Mark P Jones (http://web.cecs.pdx.edu/~mpj/) Advanced School of Functional Programming, 1995.

Synopsis

MonadReader class

class Monad m => MonadReader r (m :: Type -> Type) | m -> r where Source #

See examples in Control.Monad.Reader. Note, the partially applied function type (->) r is a simple reader monad. See the instance declaration below.

Minimal complete definition

(ask | reader), local

Methods

ask :: m r Source #

Retrieves the monad environment.

local Source #

Arguments

:: (r -> r)

The function to modify the environment.

-> m a

Reader to run in the modified environment.

-> m a 

Executes a computation in a modified environment.

reader Source #

Arguments

:: (r -> a)

The selector function to apply to the environment.

-> m a 

Retrieves a function of the current environment.

Instances

Instances details
MonadReader r m => MonadReader r (MaybeT m) Source # 
Instance details

Defined in Control.Monad.Reader.Class

Methods

ask :: MaybeT m r Source #

local :: (r -> r) -> MaybeT m a -> MaybeT m a Source #

reader :: (r -> a) -> MaybeT m a Source #

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

Since: mtl-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 #

MonadReader r m => MonadReader r (ExceptT e m) Source #

Since: mtl-2.2

Instance details

Defined in Control.Monad.Reader.Class

Methods

ask :: ExceptT e m r Source #

local :: (r -> r) -> ExceptT e m a -> ExceptT e m a Source #

reader :: (r -> a) -> ExceptT e m a Source #

MonadReader r m => MonadReader r (IdentityT m) Source # 
Instance details

Defined in Control.Monad.Reader.Class

Methods

ask :: IdentityT m r Source #

local :: (r -> r) -> IdentityT m a -> IdentityT m a Source #

reader :: (r -> a) -> IdentityT m a Source #

Monad m => MonadReader r (ReaderT r m) Source # 
Instance details

Defined in Control.Monad.Reader.Class

Methods

ask :: ReaderT r m r Source #

local :: (r -> r) -> ReaderT r m a -> ReaderT r m a Source #

reader :: (r -> a) -> ReaderT r m a Source #

MonadReader r m => MonadReader r (StateT s m) Source # 
Instance details

Defined in Control.Monad.Reader.Class

Methods

ask :: StateT s m r Source #

local :: (r -> r) -> StateT s m a -> StateT s m a Source #

reader :: (r -> a) -> StateT s m a Source #

MonadReader r m => MonadReader r (StateT s m) Source # 
Instance details

Defined in Control.Monad.Reader.Class

Methods

ask :: StateT s m r Source #

local :: (r -> r) -> StateT s m a -> StateT s m a Source #

reader :: (r -> a) -> StateT s m a Source #

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

Since: mtl-2.3

Instance details

Defined in Control.Monad.Reader.Class

Methods

ask :: WriterT w m r Source #

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

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

(Monoid w, MonadReader r m) => MonadReader r (WriterT w m) Source # 
Instance details

Defined in Control.Monad.Reader.Class

Methods

ask :: WriterT w m r Source #

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

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

(Monoid w, MonadReader r m) => MonadReader r (WriterT w m) Source # 
Instance details

Defined in Control.Monad.Reader.Class

Methods

ask :: WriterT w m r Source #

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

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

MonadReader r' m => MonadReader r' (SelectT r m) Source #

Since: mtl-2.3

Instance details

Defined in Control.Monad.Reader.Class

Methods

ask :: SelectT r m r' Source #

local :: (r' -> r') -> SelectT r m a -> SelectT r m a Source #

reader :: (r' -> a) -> SelectT r m a Source #

MonadReader r ((->) r) Source # 
Instance details

Defined in Control.Monad.Reader.Class

Methods

ask :: r -> r Source #

local :: (r -> r) -> (r -> a) -> r -> a Source #

reader :: (r -> a) -> r -> a Source #

MonadReader r' m => MonadReader r' (ContT r m) Source # 
Instance details

Defined in Control.Monad.Reader.Class

Methods

ask :: ContT r m r' Source #

local :: (r' -> r') -> ContT r m a -> ContT r m a Source #

reader :: (r' -> a) -> ContT r m a Source #

(Monad m, Monoid w) => MonadReader r (RWST r w s m) Source #

Since: mtl-2.3

Instance details

Defined in Control.Monad.Reader.Class

Methods

ask :: RWST r w s m r Source #

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

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

(Monad m, Monoid w) => MonadReader r (RWST r w s m) Source # 
Instance details

Defined in Control.Monad.Reader.Class

Methods

ask :: RWST r w s m r Source #

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

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

(Monad m, Monoid w) => MonadReader r (RWST r w s m) Source # 
Instance details

Defined in Control.Monad.Reader.Class

Methods

ask :: RWST r w s m r Source #

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

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

asks Source #

Arguments

:: MonadReader r m 
=> (r -> a)

The selector function to apply to the environment.

-> m a 

Retrieves a function of the current environment.

The Reader monad

type Reader r = ReaderT r Identity Source #

The parameterizable reader monad.

Computations are functions of a shared environment.

The return function ignores the environment, while m >>= k passes the inherited environment to both subcomputations:

runReader Source #

Arguments

:: Reader r a

A Reader to run.

-> r

An initial environment.

-> a 

Runs a Reader and extracts the final value from it. (The inverse of reader.)

mapReader :: (a -> b) -> Reader r a -> Reader r b Source #

Transform the value returned by a Reader.

withReader Source #

Arguments

:: (r' -> r)

The function to modify the environment.

-> Reader r a

Computation to run in the modified environment.

-> Reader r' a 

Execute a computation in a modified environment (a specialization of withReaderT).

The ReaderT monad transformer

newtype ReaderT r (m :: Type -> Type) a Source #

The reader monad transformer, which adds a read-only environment to the given monad.

The return function ignores the environment, while m >>= k passes the inherited environment to both subcomputations:

Constructors

ReaderT (r -> m a) 

Instances

Instances details
Generic1 (ReaderT r m :: Type -> Type) 
Instance details

Defined in Control.Monad.Trans.Reader

Associated Types

type Rep1 (ReaderT r m :: Type -> Type) 
Instance details

Defined in Control.Monad.Trans.Reader

type Rep1 (ReaderT r m :: Type -> Type) = D1 ('MetaData "ReaderT" "Control.Monad.Trans.Reader" "transformers-0.6.1.1-3dcc" 'True) (C1 ('MetaCons "ReaderT" 'PrefixI 'True) (S1 ('MetaSel ('Just "runReaderT") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) ((FUN 'Many r :: Type -> Type) :.: Rec1 m)))

Methods

from1 :: ReaderT r m a -> Rep1 (ReaderT r m) a #

to1 :: Rep1 (ReaderT r m) a -> ReaderT r m a #

MonadAccum w m => MonadAccum w (ReaderT r m) Source #

Since: mtl-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 #

MonadError e m => MonadError e (ReaderT r m) Source # 
Instance details

Defined in Control.Monad.Error.Class

Methods

throwError :: e -> ReaderT r m a Source #

catchError :: ReaderT r m a -> (e -> ReaderT r m a) -> ReaderT r m a Source #

Monad m => MonadReader r (ReaderT r m) Source # 
Instance details

Defined in Control.Monad.Reader.Class

Methods

ask :: ReaderT r m r Source #

local :: (r -> r) -> ReaderT r m a -> ReaderT r m a Source #

reader :: (r -> a) -> ReaderT r m a Source #

MonadSelect r' m => MonadSelect r' (ReaderT r m) Source #

Provides a read-only environment of type r to the 'strategy' function. However, the 'ranking' function (or more accurately, representation) has no access to r. Put another way, you can influence what values get chosen by changing r, but not how solutions are ranked.

Since: mtl-2.3

Instance details

Defined in Control.Monad.Select

Methods

select :: ((a -> r') -> a) -> ReaderT r m a Source #

MonadState s m => MonadState s (ReaderT r m) Source # 
Instance details

Defined in Control.Monad.State.Class

Methods

get :: ReaderT r m s Source #

put :: s -> ReaderT r m () Source #

state :: (s -> (a, s)) -> ReaderT r m a Source #

MonadWriter w m => MonadWriter w (ReaderT r m) Source # 
Instance details

Defined in Control.Monad.Writer.Class

Methods

writer :: (a, w) -> ReaderT r m a Source #

tell :: w -> ReaderT r m () Source #

listen :: ReaderT r m a -> ReaderT r m (a, w) Source #

pass :: ReaderT r m (a, w -> w) -> ReaderT r m a Source #

MonadTrans (ReaderT r) 
Instance details

Defined in Control.Monad.Trans.Reader

Methods

lift :: Monad m => m a -> ReaderT r m a Source #

MonadIO m => MonadIO (ReaderT r m) 
Instance details

Defined in Control.Monad.Trans.Reader

Methods

liftIO :: IO a -> ReaderT r m a Source #

MonadZip m => MonadZip (ReaderT r m) 
Instance details

Defined in Control.Monad.Trans.Reader

Methods

mzip :: ReaderT r m a -> ReaderT r m b -> ReaderT r m (a, b) Source #

mzipWith :: (a -> b -> c) -> ReaderT r m a -> ReaderT r m b -> ReaderT r m c Source #

munzip :: ReaderT r m (a, b) -> (ReaderT r m a, ReaderT r m b) Source #

Contravariant m => Contravariant (ReaderT r m) 
Instance details

Defined in Control.Monad.Trans.Reader

Methods

contramap :: (a' -> a) -> ReaderT r m a -> ReaderT r m a' Source #

(>$) :: b -> ReaderT r m b -> ReaderT r m a Source #

Alternative m => Alternative (ReaderT r m) 
Instance details

Defined in Control.Monad.Trans.Reader

Methods

empty :: ReaderT r m a #

(<|>) :: ReaderT r m a -> ReaderT r m a -> ReaderT r m a #

some :: ReaderT r m a -> ReaderT r m [a] #

many :: ReaderT r m a -> ReaderT r m [a] #

Applicative m => Applicative (ReaderT r m) 
Instance details

Defined in Control.Monad.Trans.Reader

Methods

pure :: a -> ReaderT r m a #

(<*>) :: ReaderT r m (a -> b) -> ReaderT r m a -> ReaderT r m b #

liftA2 :: (a -> b -> c) -> ReaderT r m a -> ReaderT r m b -> ReaderT r m c #

(*>) :: ReaderT r m a -> ReaderT r m b -> ReaderT r m b #

(<*) :: ReaderT r m a -> ReaderT r m b -> ReaderT r m a #

Functor m => Functor (ReaderT r m) 
Instance details

Defined in Control.Monad.Trans.Reader

Methods

fmap :: (a -> b) -> ReaderT r m a -> ReaderT r m b #

(<$) :: a -> ReaderT r m b -> ReaderT r m a #

Monad m => Monad (ReaderT r m) 
Instance details

Defined in Control.Monad.Trans.Reader

Methods

(>>=) :: ReaderT r m a -> (a -> ReaderT r m b) -> ReaderT r m b #

(>>) :: ReaderT r m a -> ReaderT r m b -> ReaderT r m b #

return :: a -> ReaderT r m a #

MonadPlus m => MonadPlus (ReaderT r m) 
Instance details

Defined in Control.Monad.Trans.Reader

Methods

mzero :: ReaderT r m a #

mplus :: ReaderT r m a -> ReaderT r m a -> ReaderT r m a #

MonadFail m => MonadFail (ReaderT r m) 
Instance details

Defined in Control.Monad.Trans.Reader

Methods

fail :: String -> ReaderT r m a #

MonadFix m => MonadFix (ReaderT r m) 
Instance details

Defined in Control.Monad.Trans.Reader

Methods

mfix :: (a -> ReaderT r m a) -> ReaderT r m a #

MonadCont m => MonadCont (ReaderT r m) Source # 
Instance details

Defined in Control.Monad.Cont.Class

Methods

callCC :: ((a -> ReaderT r m b) -> ReaderT r m a) -> ReaderT r m a Source #

Generic (ReaderT r m a) 
Instance details

Defined in Control.Monad.Trans.Reader

Associated Types

type Rep (ReaderT r m a) 
Instance details

Defined in Control.Monad.Trans.Reader

type Rep (ReaderT r m a) = D1 ('MetaData "ReaderT" "Control.Monad.Trans.Reader" "transformers-0.6.1.1-3dcc" 'True) (C1 ('MetaCons "ReaderT" 'PrefixI 'True) (S1 ('MetaSel ('Just "runReaderT") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (r -> m a))))

Methods

from :: ReaderT r m a -> Rep (ReaderT r m a) x #

to :: Rep (ReaderT r m a) x -> ReaderT r m a #

type Rep1 (ReaderT r m :: Type -> Type) 
Instance details

Defined in Control.Monad.Trans.Reader

type Rep1 (ReaderT r m :: Type -> Type) = D1 ('MetaData "ReaderT" "Control.Monad.Trans.Reader" "transformers-0.6.1.1-3dcc" 'True) (C1 ('MetaCons "ReaderT" 'PrefixI 'True) (S1 ('MetaSel ('Just "runReaderT") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) ((FUN 'Many r :: Type -> Type) :.: Rec1 m)))
type Rep (ReaderT r m a) 
Instance details

Defined in Control.Monad.Trans.Reader

type Rep (ReaderT r m a) = D1 ('MetaData "ReaderT" "Control.Monad.Trans.Reader" "transformers-0.6.1.1-3dcc" 'True) (C1 ('MetaCons "ReaderT" 'PrefixI 'True) (S1 ('MetaSel ('Just "runReaderT") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (r -> m a))))

runReaderT :: ReaderT r m a -> r -> m a Source #

mapReaderT :: (m a -> n b) -> ReaderT r m a -> ReaderT r n b Source #

Transform the computation inside a ReaderT.

withReaderT Source #

Arguments

:: forall r' r (m :: Type -> Type) a. (r' -> r)

The function to modify the environment.

-> ReaderT r m a

Computation to run in the modified environment.

-> ReaderT r' m a 

Execute a computation in a modified environment (a more general version of local).

Example 1: Simple Reader Usage

In this example the Reader monad provides access to variable bindings. Bindings are a Map of integer variables. The variable count contains number of variables in the bindings. You can see how to run a Reader monad and retrieve data from it with runReader, how to access the Reader data with ask and asks.

import           Control.Monad.Reader
import           Data.Map (Map)
import qualified Data.Map as Map

type Bindings = Map String Int

-- Returns True if the "count" variable contains correct bindings size.
isCountCorrect :: Bindings -> Bool
isCountCorrect bindings = runReader calc_isCountCorrect bindings

-- The Reader monad, which implements this complicated check.
calc_isCountCorrect :: Reader Bindings Bool
calc_isCountCorrect = do
    count <- asks (lookupVar "count")
    bindings <- ask
    return (count == (Map.size bindings))

-- The selector function to use with 'asks'.
-- Returns value of the variable with specified name.
lookupVar :: String -> Bindings -> Int
lookupVar name bindings = maybe 0 id (Map.lookup name bindings)

sampleBindings :: Bindings
sampleBindings = Map.fromList [("count", 3), ("1", 1), ("b", 2)]

main :: IO ()
main = do
    putStr $ "Count is correct for bindings " ++ (show sampleBindings) ++ ": "
    putStrLn $ show (isCountCorrect sampleBindings)

Example 2: Modifying Reader Content With local

Shows how to modify Reader content with local.

import Control.Monad.Reader

calculateContentLen :: Reader String Int
calculateContentLen = do
    content <- ask
    return (length content);

-- Calls calculateContentLen after adding a prefix to the Reader content.
calculateModifiedContentLen :: Reader String Int
calculateModifiedContentLen = local ("Prefix " ++) calculateContentLen

main :: IO ()
main = do
    let s = "12345";
    let modifiedLen = runReader calculateModifiedContentLen s
    let len = runReader calculateContentLen s
    putStrLn $ "Modified 's' length: " ++ (show modifiedLen)
    putStrLn $ "Original 's' length: " ++ (show len)

Example 3: ReaderT Monad Transformer

Now you are thinking: 'Wow, what a great monad! I wish I could use Reader functionality in MyFavoriteComplexMonad!'. Don't worry. This can be easily done with the ReaderT monad transformer. This example shows how to combine ReaderT with the IO monad.

import Control.Monad.Reader

-- The Reader/IO combined monad, where Reader stores a string.
printReaderContent :: ReaderT String IO ()
printReaderContent = do
    content <- ask
    liftIO $ putStrLn ("The Reader Content: " ++ content)

main :: IO ()
main = runReaderT printReaderContent "Some Content"