1 files changed, 145 insertions, 0 deletions

diff --git a/docs/users_guide_2_src/10_errorHandling.txt b/docs/users_guide_2_src/10_errorHandling.txt
new file mode 100755
index 0000000..28eee3a
--- /dev/null
+++ b/docs/users_guide_2_src/10_errorHandling.txt
@@ -0,0 +1,145 @@
+\section{Error Handling}
+\label{errorHandling}
+
+There are two ways to handle runtime errors (exceptions) in Cheetah.  The first
+is with the Cheetah directives that mirror Python's structured exception
+handling statements. The second is with Cheetah's \code{ErrorCatcher}
+framework. These are described below.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#try ... \#except ... \#end try, \#finally, and \#assert}
+\label{errorHandling.directives}
+
+Cheetah's exception-handling directives are exact mirrors Python's 
+exception-handling statements.  See Python's documentation for details.  The
+following Cheetah code demonstrates their use:
+
+
+\begin{verbatim}
+#try
+  $mightFail()
+#except
+  It failed
+#end try
+
+#try
+  #assert $x == $y
+#except AssertionError
+  They're not the same!
+#end try
+
+#try
+  #raise ValueError
+#except ValueError
+  #pass
+#end try
+
+
+#try
+  $mightFail()
+#except ValueError
+  Hey, it raised a ValueError!
+#except NameMapper.NotFound
+  Hey, it raised a NameMapper.NotFound!
+#else
+  It didn't raise anything!
+#end try
+
+#try
+  $mightFail()
+#finally
+  $cleanup()
+#end try
+\end{verbatim}    
+
+Like Python, \code{\#except} and \code{\#finally} cannot appear in the same
+try-block, but can appear in nested try-blocks.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#errorCatcher and ErrorCatcher objects}
+\label{errorHandling.errorCatcher}
+
+Syntax:
+\begin{verbatim}
+#errorCatcher CLASS
+#errorCatcher $PLACEHOLDER_TO_AN_ERROR_CATCHER_INSTANCE
+\end{verbatim}
+
+
+\code{ErrorCatcher} is a debugging tool that catches exceptions that occur
+inside \code{\$placeholder} tags and provides a customizable warning to the
+developer.  Normally, the first missing namespace value raises a
+\code{NameMapper.NotFound} error and halts the filling of the template. This
+requires the developer to resolve the exceptions in order without seeing the
+subsequent output. When an \code{ErrorCatcher} is enabled, the developer can
+see all the exceptions at once as well as the template output around them.
+
+The \code{Cheetah.ErrorCatchers} module defines the base class for
+ErrorCatchers:
+
+\begin{verbatim}
+class ErrorCatcher:
+    _exceptionsToCatch = (NameMapper.NotFound,)
+    
+    def __init__(self, templateObj):
+        pass
+    
+    def exceptions(self):
+        return self._exceptionsToCatch
+    
+    def warn(self, exc_val, code, rawCode, lineCol):
+        return rawCode
+\end{verbatim}    
+
+This ErrorCatcher catches \code{NameMapper.NotFound} exceptions and leaves the
+offending placeholder visible in its raw form in the template output.  If the
+following template is executed:
+\begin{verbatim}
+#errorCatcher Echo
+#set $iExist = 'Here I am!'
+Here's a good placeholder: $iExist
+Here's bad placeholder: $iDontExist
+\end{verbatim}    
+
+the output will be:
+\begin{verbatim}
+Here's a good placeholder: Here I am!
+Here's bad placeholder: $iDontExist
+\end{verbatim}
+
+The base class shown above is also accessible under the alias
+\code{Cheetah.ErrorCatchers.Echo}.  \code{Cheetah.ErrorCatchers} also provides a
+number of specialized subclasses that warn about exceptions in different ways.
+\code{Cheetah.ErrorCatchers.BigEcho} will output
+
+\begin{verbatim}
+Here's a good placeholder: Here I am!
+Here's bad placeholder: ===============<$iDontExist could not be found>===============
+\end{verbatim}
+
+ErrorCatcher has a significant performance impact and is turned off by default.
+It can also be turned on with the \code{Template} class' \code{'errorCatcher'}
+keyword argument.  The value of this argument should either be a string
+specifying which of the classes in \code{Cheetah.ErrorCatchers} to use, or a
+class that subclasses \code{Cheetah.ErrorCatchers.ErrorCatcher}. The
+\code{\#errorCatcher} directive can also be used to change the errorCatcher part
+way through a template.
+
+\code{Cheetah.ErrorCatchers.ListErrors} will produce the same ouput as
+\code{Echo} while maintaining a list of the errors that can be retrieved later.
+To retrieve the list, use the \code{Template} class' \code{'errorCatcher'}
+method to retrieve the errorCatcher and then call its \code{listErrors} method.
+
+ErrorCatcher doesn't catch exceptions raised inside directives. 
+
+% @@MO: How do you turn ErrorCatcher off after turn it on.
+% '#ErrorCatcher None'?
+
+% Local Variables:
+% TeX-master: "users_guide"
+% End:      
+
+
+
+