Enhanced docs, and applied coding style to Reader

This commit is contained in:
Peter Trsko 2017-01-30 16:18:35 +01:00 committed by Peter Trško
parent eb9ec89ec7
commit 766e4e03ab

View File

@ -18,11 +18,18 @@
--
-- Using <http://okmij.org/ftp/Haskell/extensible/Eff1.hs> as a starting point.
module Control.Monad.Freer.Reader
( Reader(..)
(
-- * Reader Effect
Reader(..)
-- * Reader Operations
, ask
, asks
, runReader
, local
-- * Reader Handlers
, runReader
-- * Example 1: Simple Reader Usage
-- $simpleReaderExample
@ -43,101 +50,108 @@ import Control.Monad.Freer.Internal
, send
)
-- |
-- | Represents shared immutable environment of type @(e :: *)@ which is made
-- available to effectful computation.
data Reader e v where
Reader :: Reader e e
-- | Request a value for the environment
ask :: (Member (Reader e) r) => Eff r e
-- | Request a value of the environment.
ask :: Member (Reader e) effs => Eff effs e
ask = send Reader
-- | Request a value from the environment and applys as function
asks :: (b -> a) -> Eff '[Reader b] a
-- | Request a value of the environment, and apply as selector\/projection
-- function to it.
asks
:: (e -> a)
-- ^ The selector\/projection function to be applied to the environment.
-> Eff '[Reader e] a
asks f = f <$> ask
-- | Handler for reader effects
runReader :: Eff (Reader e ': r) w -> e -> Eff r w
-- | Handler for 'Reader' effects.
runReader :: Eff (Reader e ': effs) a -> e -> Eff effs a
runReader m e = handleRelay pure (\Reader k -> k e) m
-- |
-- Locally rebind the value in the dynamic environment
-- This function is like a relay; it is both an admin for Reader requests,
-- and a requestor of them
local :: forall e a r. Member (Reader e) r =>
(e -> e) -> Eff r a -> Eff r a
-- | Locally rebind the value in the dynamic environment.
--
-- This function is like a relay; it is both an admin for 'Reader' requests,
-- and a requestor of them.
local
:: forall e a effs. Member (Reader e) effs
=> (e -> e)
-> Eff effs a
-> Eff effs a
local f m = do
e0 <- ask
let e = f e0
let h :: Reader e v -> Arr r v a -> Eff r a
h Reader g = g e
interpose pure h m
e <- f <$> ask
let h :: Reader e v -> Arr effs v a -> Eff effs a
h Reader k = k e
interpose pure h m
-- $simpleReaderExample
--
-- In this example the 'Reader' effect 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 effect
-- and retrieve data from it with 'runReader', how to access the Reader data
-- with 'ask' and 'asks'.
--
-- > import Control.Monad.Freer
-- > import Control.Monad.Freer.Reader
-- > import Data.Map as Map
-- > import Data.Maybe
-- >
-- > type Bindings = Map String Int
-- >
-- > -- Returns True if the "count" variable contains correct bindings size.
-- > isCountCorrect :: Bindings -> Bool
-- > isCountCorrect bindings = run $ runReader calc_isCountCorrect bindings
-- >
-- > -- The Reader effect, which implements this complicated check.
-- > calc_isCountCorrect :: Eff '[Reader Bindings] Bool
-- > calc_isCountCorrect = do
-- > count <- asks (lookupVar "count")
-- > bindings <- (ask :: Eff '[Reader Bindings] Bindings)
-- > 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 = fromJust (Map.lookup name bindings)
-- >
-- > sampleBindings :: Map.Map String Int
-- > sampleBindings = Map.fromList [("count",3), ("1",1), ("b",2)]
-- >
-- > main :: IO ()
-- > main = putStrLn
-- > $ "Count is correct for bindings " ++ show sampleBindings ++ ": "
-- > ++ show (isCountCorrect sampleBindings)
{- $simpleReaderExample
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 effect and retrieve data from it
with 'runReader', how to access the Reader data with 'ask' and 'asks'.
>import Control.Monad.Freer
>import Control.Monad.Freer.Reader
>import Data.Map as Map
>import Data.Maybe
>
>type Bindings = Map String Int
>
>-- Returns True if the "count" variable contains correct bindings size.
>isCountCorrect :: Bindings -> Bool
>isCountCorrect bindings = run $ runReader calc_isCountCorrect bindings
>
>-- The Reader effect, which implements this complicated check.
>calc_isCountCorrect :: Eff '[Reader Bindings] Bool
>calc_isCountCorrect = do
> count <- asks (lookupVar "count")
> bindings <- (ask :: Eff '[Reader Bindings] Bindings)
> 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 = fromJust (Map.lookup name bindings)
>
>sampleBindings :: Map.Map String Int
>sampleBindings = Map.fromList [("count",3), ("1",1), ("b",2)]
>
>main = do
> putStr $ "Count is correct for bindings " ++ (show sampleBindings) ++ ": "
> putStrLn $ show (isCountCorrect sampleBindings)
-}
{- $localExample
Shows how to modify Reader content with 'local'.
> import Control.Monad.Freer
> import Control.Monad.Freer.Reader
>
> import Data.Map as Map
> import Data.Maybe
>
> type Bindings = Map String Int
>
> calculateContentLen :: Eff '[Reader String] Int
> calculateContentLen = do
> content <- (ask :: Eff '[Reader String] String)
> return (length content)
>
> -- Calls calculateContentLen after adding a prefix to the Reader content.
> calculateModifiedContentLen :: Eff '[Reader String] Int
> calculateModifiedContentLen = local ("Prefix " ++) calculateContentLen
>
> main :: IO ()
> main = do
> let s = "12345";
> let modifiedLen = run $ runReader calculateModifiedContentLen s;
> let len = run $ runReader calculateContentLen s ;
> putStrLn $ "Modified 's' length: " ++ (show modifiedLen)
> putStrLn $ "Original 's' length: " ++ (show len)
-}
-- $localExample
--
-- Shows how to modify 'Reader' content with 'local'.
--
-- > import Control.Monad.Freer
-- > import Control.Monad.Freer.Reader
-- >
-- > import Data.Map as Map
-- > import Data.Maybe
-- >
-- > type Bindings = Map String Int
-- >
-- > calculateContentLen :: Eff '[Reader String] Int
-- > calculateContentLen = do
-- > content <- (ask :: Eff '[Reader String] String)
-- > return (length content)
-- >
-- > -- Calls calculateContentLen after adding a prefix to the Reader content.
-- > calculateModifiedContentLen :: Eff '[Reader String] Int
-- > calculateModifiedContentLen = local ("Prefix " ++) calculateContentLen
-- >
-- > main :: IO ()
-- > main = do
-- > let s = "12345";
-- > let modifiedLen = run $ runReader calculateModifiedContentLen s;
-- > let len = run $ runReader calculateContentLen s ;
-- > putStrLn $ "Modified 's' length: " ++ (show modifiedLen)
-- > putStrLn $ "Original 's' length: " ++ (show len)