[Snapshot
Bryan O'Sullivan <bos@serpentine.com>**20080212231919] {
addfile ./examples/ch16/VCard.hs
hunk ./en/ch05-fp.xml 717
-      <para id="x_A8">We call the non-recursive case (when the list is empty)
-	the base case.  We'll see people refer to the case where the
-	function calls itself as the recursive case (surprise!), or
-	they might give a nod to mathematical induction and call it
-	the inductive case.</para>
+      <para id="x_A8">We call the non-recursive case (when the list is
+	empty) the <emphasis>base case</emphasis>.  We'll see people
+	refer to the case where the function calls itself as the
+	recursive case (surprise!), or they might give a nod to
+	mathematical induction and call it the <emphasis>inductive
+	  case</emphasis>.</para>
hunk ./en/ch16-monad-case.xml 3
-<chapter id="monadcase" revision="unpublished">
-  <title>Some monad examples</title>
+<chapter id="monadcase" revision="alpha;beta">
+  <title>Programming with monads</title>
hunk ./en/ch16-monad-case.xml 128
+  <sect1>
+    <title>Looking for alternatives</title>
+
+    <para>Here's a simple representation of a person's phone
+      numbers.</para>
+
+    &VCard.hs:numbers;
+
+    <para>Suppose we want to get in touch with someone to make a
+      personal call.  We don't want their business number, and we'd
+      prefer to use their home number (if they have one) instead of
+      their mobile number, because the call will be cheaper.</para>
+
+    &VCard.hs:personalPhone;
+
+    <para>Of course, if we use <type>Maybe</type> as the result type,
+      we can't accommodate the possibility that someone might have
+      more than one number that meet our criteria.  For that, we
+      switch to a list.</para>
+
+    &VCard.hs:businessPhones;
+
+    <para>Notice that these two functions structure their &case;
+      expressions similarly: one alternative handles the case where
+      the first lookup returns an empty result, while the other
+      handles the non-empty case.</para>
+
+    &vcard.ghci:simple;
+    
+    <para>Haskell's <code>Control.Monad</code> module defines a
+      typeclass, <type>MonadPlus</type>, that lets us abstract the
+      common pattern out of our &case; expressions.</para>
+
+    &VCard.hs:MonadPlus;
+
+    <para>The value <code>mzero</code> represents an empty result,
+      while <function>mplus</function> combines two results.  Here are
+      the standard definitions of <code>mzero</code> and
+      <function>mplus</function> for <type>Maybe</type> and
+      lists.</para>
+
+    &VCard.hs:instances;
+
+    <para>We can now use <function>mplus</function> to get rid of our
+      &case; expressions entirely.</para>
+
+    &VCard.hs:caseless;
+
+    <para>In these functions, because we know that
+      <function>lookup</function> returns a value of type
+      <type>Maybe</type>, and <function>filter</function> returns a
+      list, it's obvious which version of <function>mplus</function>
+      is going to be used in each case.</para>
+
+    <para>What's more interesting is that we can use
+      <code>mzero</code> and <function>mplus</function> to write
+      functions that will be useful for <emphasis>any</emphasis>
+      <type>MonadPlus</type> instance.  As an example, here's the
+      standard <function>lookup</function> function, which returns a
+      value of type <type>Maybe</type>.</para>
+
+    &VCard.hs:lookup;
+
+    <para>We can easily generalise the result type to any instance of
+      <type>MonadPlus</type> as follows.</para>
+
+    &VCard.hs:lookupM;
+
+    <para>This lets us get either no result or one, if our result type
+      is <type>Maybe</type>; all results, if our result type is a
+      list; or something of appropriate for some other exotic instance
+      of <type>MonadPlus</type>.</para>
+  </sect1>
hunk ./examples/ch16/VCard.hs 1
+import Prelude hiding (lookup)
+
+{-- snippet MonadPlus --}
+class Monad m => MonadPlus m where
+   mzero :: m a	
+   mplus :: m a -> m a -> m a
+{-- /snippet MonadPlus --}
+
+{-- snippet instances --}
+instance MonadPlus [] where
+   mzero = []
+   mplus = (++)
+
+instance MonadPlus Maybe where
+   mzero = Nothing
+
+   Nothing `mplus` ys  = ys
+   xs      `mplus` _ = xs
+{-- /snippet instances --}
+
+{-- snippet numbers --}
+data Context = Home | Mobile | Business
+               deriving (Eq, Show)
+
+type Phone = String
+
+albulena = [(Home, "+355-652-55512")]
+
+nils = [(Mobile, "+47-922-55-512"), (Business, "+47-922-12-121"),
+        (Home, "+47-925-55-121"), (Business, "+47-922-25-551")]
+
+twalumba = [(Business, "+260-02-55-5121")]
+{-- /snippet numbers --}
+
+{-- snippet personalPhone --}
+personalPhone :: [(Context, Phone)] -> Maybe Phone
+
+personalPhone ps = case lookup Home ps of
+                     Nothing -> lookup Mobile ps
+                     Just n -> Just n
+{-- /snippet personalPhone --}
+
+{-- snippet businessPhones --}
+businessPhones ps = map snd numbers
+    where numbers = case filter (contextIs Business) ps of
+                      [] -> filter (contextIs Mobile) ps
+                      ns -> ns
+
+contextIs a (b, _) = a == b
+{-- /snippet businessPhones --}
+
+{-- snippet caseless --}
+businessPhone :: [(Context, Phone)] -> Maybe Phone
+businessPhone ps = lookup Business ps `mplus` lookup Mobile ps
+
+personalPhones :: [(Context, Phone)] -> [Phone]
+personalPhones ps = map snd $ filter (contextIs Home) ps `mplus`
+                              filter (contextIs Mobile) ps
+{-- /snippet caseless --}
+
+{-- snippet lookup --}
+lookup :: (Eq a) => a -> [(a, b)] -> Maybe b
+lookup _ []                      = Nothing
+lookup k ((x,y):xys) | x == k    = Just y
+                     | otherwise = lookup k xys
+{-- /snippet lookup --}
+
+{-- snippet lookupM --}
+lookupM :: (MonadPlus m, Eq a) => a -> [(a, b)] -> m b
+lookupM _ []    = mzero
+lookupM k ((x,y):xys)
+    | x == k    = return y `mplus` lookupM k xys
+    | otherwise = lookupM k xys
+{-- /snippet lookupM --}
}