[Pkg-haskell-commits] [SCM] haskell-testpack branch, master, updated. debian/1.0.2-1-4-gb0d6b36

[John Goerzen]

The following commit has been merged in the master branch:
commit 6cddd67ddd87097f38ef9f72c748a19163cac5d2
Author: John Goerzen <jgoerzen at complete.org>
Date:   Wed Dec 1 03:57:23 2004 +0100

    Checkpointing doc progress
    
    Keywords:
    
    
    (jgoerzen at complete.org--projects/missingh--head--0.5--patch-132)

diff --git a/ChangeLog b/ChangeLog
index f51a573..1b061c4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -2,6 +2,22 @@
 # arch-tag: automatic-ChangeLog--jgoerzen at complete.org--projects/missingh--head--0.5
 #
 
+2004-11-30 20:57:23 GMT	John Goerzen <jgoerzen at complete.org>	patch-132
+
+    Summary:
+      Checkpointing doc progress
+    Revision:
+      missingh--head--0.5--patch-132
+
+
+    new files:
+     testsrc/ConfigParser/test.cfg
+
+    modified files:
+     ChangeLog libsrc/MissingH/ConfigParser.hs
+     testsrc/ConfigParser/Maintest.hs
+
+
 2004-11-30 20:34:05 GMT	John Goerzen <jgoerzen at complete.org>	patch-131
 
     Summary:
diff --git a/libsrc/MissingH/ConfigParser.hs b/libsrc/MissingH/ConfigParser.hs
index 0a1898e..3e7e0be 100644
--- a/libsrc/MissingH/ConfigParser.hs
+++ b/libsrc/MissingH/ConfigParser.hs
@@ -55,6 +55,14 @@ module MissingH.ConfigParser
      -- ** Case Sensitivity
      -- $casesens
 
+     -- * Usage Examples
+     -- $usage
+
+     -- ** Non-Monadic Usage
+     -- $usagenomonad
+
+     -- ** Error Monad Usage
+
      -- * Types
      SectionSpec, OptionSpec, ConfigParser(..),
      CPErrorData(..), CPError, CPResult,
@@ -519,12 +527,55 @@ comment character at the start of the line.
 By default, section names are case-sensitive but option names are
 not. The latter can be adjusted by adjusting 'optionxform'.  -}
 
-{- $initialization
+{- $usage
+
+The basic theory of working with ConfigParser is this:
+
+ 1. Parse or build a 'ConfigParser' object
+ 
+ 2. Work with it in one of several ways
+
+ 3. To make changes, you discard the original object and use a new one.
+    Changes can be "chained" through one of several monads.
+
+The default 'ConfigParser' object that you always start with is 'emptyCP'.
+From here, you load data into it (merging data into the empty object),
+set up structures yourself, or adjust options.
+
+Let's take a look at some basic use cases.
 
-The variable 'emptyCP' is exported, and contains a default empty
-'ConfigParser'.
 -}
 
+{- $usagenomonad
+You'll notice that many functions in this module return a 'CPResult' over some
+type.  Although its definition is not this simple, you can consider this to
+hold:
+
+ at type 'CPResult' a = Either 'CPError' a@
+
+That is, these functions will return @Left error@ if there's a problem
+or @Right result@ if things are fine.  The documentation for individual
+functions describes the specific circumstances in which an error may occur in
+more detail.
+
+Some people find it annoying to have to deal with errors manually.
+You can transform errors into exceptions in your code by using 
+'MissingH.Either.forceEither'.  Here's an example of this style of programming:
+
+> import MissingH.Either
+> do
+>    val <- readfile emptyCP "/etc/foo.cfg"
+>    let cp = forceEither val
+>    putStrLn "Your setting is:"
+>    putStrLn $ forceEither $ get cp "sect1" "opt1"
+
+In short, you can just put @forceEither $@ in front of every call that returns
+a 'CPResult'.  This is still a pure functional call, so it can be used outside
+of any monads.
+
+-}
+
+
 {- $reading
 
 You can use these functions to read data from a file.
diff --git a/testsrc/ConfigParser/Maintest.hs b/testsrc/ConfigParser/Maintest.hs
index 400501d..634112d 100644
--- a/testsrc/ConfigParser/Maintest.hs
+++ b/testsrc/ConfigParser/Maintest.hs
@@ -22,7 +22,10 @@ import MissingH.ConfigParser
 import MissingH.Either
 import Testutil
 import Control.Exception
+import System.IO
 
+nullfile = openFile "/dev/null" ReadWriteMode
+testfile = "testsrc/ConfigParser/test.cfg"
 p inp = forceEither $ readstring emptyCP inp
 f msg inp exp conv = TestLabel msg $ TestCase $ assertEqual "" (Right exp) (conv (p inp))
 f2 msg exp res = TestLabel msg $ TestCase $ assertEqual "" exp res
@@ -97,8 +100,19 @@ test_nodefault =
       -- default float
       -- default bool
       ]
+
+test_ex_nomonad = 
+    do 
+       fh <- nullfile
+       val <- readfile emptyCP testfile
+       let cp = forceEither val
+       hPutStr fh "Your setting is:"
+       hPutStr fh $ forceEither $ get cp "file1" "location"
+
+                 
      
 
 tests = TestList [TestLabel "test_basic" (TestList test_basic),
                  TestLabel "test_defaults" (TestList test_defaults),
-                 TestLabel "test_nodefault" (TestList test_nodefault)]
+                 TestLabel "test_nodefault" (TestList test_nodefault),
+                 TestLabel "test_ex_nomonad" (TestCase test_ex_nomonad)]
diff --git a/testsrc/ConfigParser/test.cfg b/testsrc/ConfigParser/test.cfg
new file mode 100644
index 0000000..985012d
--- /dev/null
+++ b/testsrc/ConfigParser/test.cfg
@@ -0,0 +1,15 @@
+# arch-tag: test file for ConfigParser tests
+# Default options
+[DEFAULT]
+hostname: localhost 
+# Options for the first file
+[file1]
+location: /usr/local
+user: Fred
+uid: 1000
+optionaltext: Hello, this  entire string is included 
+[file2]
+location: /opt
+user: Fred
+uid: 1001 
+hostname: somewhere

-- 
haskell-testpack