Ticket #1410: ReaderMonad.patch

New patches:

[Reader Monad. Added Haddock documentation. Converted the existing module documentation to Haddock format. Created examples. Per Jeff Newberns permission included parts his tutorial "All About Monads" http://haskell.org/all_about_monads/.
Andriy Palamarchuk <apa3a@yahoo.com>**20070627180520] {
hunk ./Control/Monad/Reader/Class.hs 2
--- Search for -fallow-undecidable-instances to see why this is needed
------------------------------------------------------------------------------
--- |
--- Module      :  Control.Monad.Reader.Class
--- Copyright   :  (c) Andy Gill 2001,
---                (c) Oregon Graduate Institute of Science and Technology, 2001
--- License     :  BSD-style (see the file libraries/base/LICENSE)
---
--- Maintainer  :  libraries@haskell.org
--- Stability   :  experimental
--- Portability :  non-portable (multi-param classes, functional dependencies)
---
--- MonadReader class.
---
---      Inspired by the paper
---      /Functional Programming with Overloading and
---          Higher-Order Polymorphism/,
---        Mark P Jones (<http://www.cse.ogi.edu/~mpj/>)
---          Advanced School of Functional Programming, 1995.
------------------------------------------------------------------------------
+{- |
+Module      :  Control.Monad.Reader.Class
+Copyright   :  (c) Andy Gill 2001,
+               (c) Oregon Graduate Institute of Science and Technology 2001,
+               (c) Jeff Newbern 2003-2007,
+               (c) Andriy Palamarchuk 2007
+License     :  BSD-style (see the file libraries/base/LICENSE)
+
+Maintainer  :  libraries@haskell.org
+Stability   :  experimental
+Portability :  non-portable (multi-param classes, functional dependencies)
+
+[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 'Control.Monad.State.State' monad.
+
+  Inspired by the paper
+  /Functional Programming with Overloading and
+      Higher-Order Polymorphism/, 
+    Mark P Jones (<http://www.cse.ogi.edu/~mpj/>)
+    Advanced School of Functional Programming, 1995.
+-}
hunk ./Control/Monad/Reader/Class.hs 45
--- ----------------------------------------------------------------------------
--- class MonadReader
---  asks for the internal (non-mutable) state.
-
+{- |
+See examples in "Control.Monad.Reader".
+Note, the partially applied function type @(->) r@ is a simple reader monad.
+See the @instance@ declaration below.
+-}
hunk ./Control/Monad/Reader/Class.hs 51
+    -- | Retrieves the monad environment.
hunk ./Control/Monad/Reader/Class.hs 53
+    {- | Executes a computation in a modified environment. Parameters:
+
+    * The function to modify the environment.
+
+    * @Reader@ to run.
+
+    * The resulting @Reader@.
+    -}
hunk ./Control/Monad/Reader/Class.hs 63
--- This allows you to provide a projection function.
+{- |
+Retrieves a function of the current environment. Parameters:
+
+* The selector function to apply to the environment.
hunk ./Control/Monad/Reader/Class.hs 68
+See an example in "Control.Monad.Reader".
+-}
hunk ./Control/Monad/Reader.hs 2
--- Search for -fallow-undecidable-instances to see why this is needed
------------------------------------------------------------------------------
--- |
--- Module      :  Control.Monad.Reader
--- Copyright   :  (c) Andy Gill 2001,
---                (c) Oregon Graduate Institute of Science and Technology, 2001
--- License     :  BSD-style (see the file libraries/base/LICENSE)
---
--- Maintainer  :  libraries@haskell.org
--- Stability   :  experimental
--- Portability :  non-portable (multi-param classes, functional dependencies)
---
--- Declaration of the MonadReader class
---
---      Inspired by the paper
---      /Functional Programming with Overloading and
---          Higher-Order Polymorphism/,
---        Mark P Jones (<http://www.cse.ogi.edu/~mpj/>)
---          Advanced School of Functional Programming, 1995.
------------------------------------------------------------------------------
+{- |
+Module      :  Control.Monad.Reader
+Copyright   :  (c) Andy Gill 2001,
+               (c) Oregon Graduate Institute of Science and Technology 2001,
+               (c) Jeff Newbern 2003-2007,
+               (c) Andriy Palamarchuk 2007
+License     :  BSD-style (see the file libraries/base/LICENSE)
+
+Maintainer  :  libraries@haskell.org
+Stability   :  experimental
+Portability :  non-portable (multi-param classes, functional dependencies)
+
+[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 'Control.Monad.State.State' monad.
+
+  Inspired by the paper
+  /Functional Programming with Overloading and
+      Higher-Order Polymorphism/, 
+    Mark P Jones (<http://www.cse.ogi.edu/~mpj/>)
+    Advanced School of Functional Programming, 1995.
+-}
hunk ./Control/Monad/Reader.hs 51
+    -- * Example 1: Simple Reader Usage
+    -- $simpleReaderExample
+
+    -- * Example 2: Modifying Reader Content With @local@
+    -- $localExample
+
+    -- * Example 3: @ReaderT@ Monad Transformer
+    -- $ReaderTExample
hunk ./Control/Monad/Reader.hs 78
--- ---------------------------------------------------------------------------
--- Our parameterizable reader monad
+{- |
+The parameterizable reader monad.
+
+The @return@ function creates a @Reader@ that ignores the environment,
+and produces the given value.
hunk ./Control/Monad/Reader.hs 84
-newtype Reader r a = Reader { runReader :: r -> a }
+The binding operator @>>=@ produces a @Reader@ that uses the environment
+to extract the value its left-hand side,
+and then applies the bound function to that value in the same environment.
+-}
+newtype Reader r a = Reader {
+    {- |
+    Runs @Reader@ and extracts the final value from it.
+    To extract the value apply @(runReader reader)@ to an environment value.  
+    Parameters:
+
+    * A @Reader@ to run.
+
+    * An initial environment.
+    -}
+    runReader :: r -> a
+}
hunk ./Control/Monad/Reader.hs 104
--- This is a more general version of local.
+-- | A more general version of 'local'.
hunk ./Control/Monad/Reader.hs 123
--- ---------------------------------------------------------------------------
--- Our parameterizable reader monad, with an inner monad
-
+{- |
+The reader monad transformer.
+Can be used to add environment reading functionality to other monads.
+-}
hunk ./Control/Monad/Reader.hs 189
+{- $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 monad and retrieve data from it
+with 'runReader', how to access the Reader data with 'ask' and 'asks'.
+
+> 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 = fromJust (Map.lookup name bindings)
+>
+>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'.
+
+>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 = 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)
+-}
+
+{- $ReaderTExample
+
+Now you are thinking: 'Wow, what a great monad! I wish I could use
+Reader functionality in MyFavoriteComplexMonad!'. Don't worry.
+This can be easy done with the 'ReaderT' monad transformer.
+This example shows how to combine @ReaderT@ with the IO monad.
+
+>-- 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 = do
+>    runReaderT printReaderContent "Some Content"
+-}
}

Context:

[--configure-option and --ghc-option are now provided by Cabal
Ross Paterson <ross@soi.city.ac.uk>**20070604115936] 
[Added Haddock documentation. Converted the existing module documentation to Haddock format. Created examples. Per Jeff Newberns permission included parts his tutorial "All About Monads" http://haskell.org/all_about_monads/.
Andriy Palamarchuk <apa3a@yahoo.com>**20070604133602] 
[Remove Makefile and package.conf.in (used in the old GHC build system)
Ian Lynagh <igloo@earth.li>**20070524145902] 
[TAG GHC 6.6.1 release
Ian Lynagh <igloo@earth.li>**20070428195851] 
Patch bundle hash:
cd548a35478049f88040e67250c9d9d853d6fa8f