From eec3555383752ae346889ddf9ee760d556d415f7 Mon Sep 17 00:00:00 2001
From: Correl Roush <correl@gmail.com>
Date: Fri, 25 Apr 2014 14:03:54 -0400
Subject: [PATCH] Add an error monad example to the README

---
 README.rst | 51 ++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 46 insertions(+), 5 deletions(-)

diff --git a/README.rst b/README.rst
index 66d837d..a8c60e4 100644
--- a/README.rst
+++ b/README.rst
@@ -7,8 +7,9 @@ Introduction
 ============
 
 Calrissian is an implementation of monads in LFE, inspired by
-`erlando`_, mostly as a learning exercise. So far, only the Maybe and
-Identity monads are supported.
+`erlando`_, mostly as a learning exercise. So far, only the Maybe,
+Error and Identity monads are supported.
+
 
 Dependencies
 ------------
@@ -44,10 +45,50 @@ And then do the usual:
     $ rebar compile
 
 
-Usage
-=====
+Examples
+========
 
-Coming soon          
+The following examples demonstrate some of the possible uses of monads
+in real-world code.
+
+Error Monad
+-----------
+
+The following is an example of using the error monad and do-notation
+to simplify flow control through a series of sequential operations
+that, if any step should fail, should halt execution and return an
+error.
+
+The error monad will inspect the result of the previous operation. If
+it was successful (represented as ``'ok`` or ``(tuple 'ok result)``),
+the result will be passed on to the next operation. If it failed
+(represented as ``(tuple 'error reason)``, the error will be returned
+and execution will cease.
+
+.. code:: scheme
+
+    (include-lib "deps/calrissian/include/monads.lfe")
+
+    (defun dostuff ()
+           (do-m error-monad
+                 (input <- (fetch-input))        ;; fetch-input -> (tuple 'ok result) | (tuple 'error reason)
+                 (parsed <- (parse-input input)) ;; parse-input -> (tuple 'ok result) | (tuple 'error reason)
+                 (store-data parsed)))           ;; store-data -> 'ok | (tuple 'error reason)
+
+Without the error monad, the code might have looked like this:
+
+.. code:: scheme
+
+    (defun dostuff ()
+           (case (fetch-input)
+                 ((tuple 'error reason)
+                  (tuple 'error reason))
+                 ((tuple 'ok input)
+                  (case (parse-input input)
+                        ((tuple 'error reason)
+                         (tuple 'error reason))
+                        ((tuple 'ok parsed)
+                         (store-data parsed))))))
 
 .. Links
 .. -----