content: -- |
  -- Module:       Control.Monad.Freer.Reader
  -- Description:  Reader effects, for encapsulating an environment.
  -- Copyright:    (c) 2016 Allele Dev; 2017 Ixperta Solutions s.r.o.; 2017 Alexis King
  -- License:      BSD3
  -- Maintainer:   Alexis King <lexi.lambda@gmail.com>
  -- Stability:    experimental
  -- Portability:  GHC specific language extensions.
  --
  -- Composable handler for 'Reader' effects. Handy for encapsulating an
  -- environment with immutable state for interpreters.
  --
  -- Using <http://okmij.org/ftp/Haskell/extensible/Eff1.hs> as a starting point.
  module Control.Monad.Freer.Reader
    ( -- * Reader Effect
      Reader(..)
  
      -- * Reader Operations
    , ask
    , asks
    , local
  
      -- * Reader Handlers
    , runReader
  
      -- * Example 1: Simple Reader Usage
      -- $simpleReaderExample
  
      -- * Example 2: Modifying Reader Content With @local@
      -- $localExample
    ) where
  
  import Control.Monad.Freer (Eff, Member, interpose, interpret, send)
  
  -- | Represents shared immutable environment of type @(e :: *)@ which is made
  -- available to effectful computation.
  data Reader r a where
    Ask :: Reader r r
  
  -- | Request a value of the environment.
  ask :: forall r effs. Member (Reader r) effs => Eff effs r
  ask = send Ask
  
  -- | Request a value of the environment, and apply as selector\/projection
  -- function to it.
  asks
    :: forall r effs a
     . Member (Reader r) effs
    => (r -> a)
    -- ^ The selector\/projection function to be applied to the environment.
    -> Eff effs a
  asks f = f <$> ask
  
  -- | Handler for 'Reader' effects.
  runReader :: forall r effs a. r -> Eff (Reader r ': effs) a -> Eff effs a
  runReader r = interpret (\Ask -> pure r)
  
  -- | 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 r effs a. Member (Reader r) effs
    => (r -> r)
    -> Eff effs a
    -> Eff effs a
  local f m = do
    r <- asks f
    interpose @(Reader r) (\Ask -> pure r) 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 bindings calc_isCountCorrect
  -- >
  -- > -- 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)
  
  -- $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 s calculateModifiedContentLen
  -- >   let len = run $ runReader s calculateContentLen
  -- >   putStrLn $ "Modified 's' length: " ++ (show modifiedLen)
  -- >   putStrLn $ "Original 's' length: " ++ (show len)
  