diff options
author | R. Tyler Ballance <tyler@monkeypox.org> | 2009-11-16 21:09:13 -0800 |
---|---|---|
committer | R. Tyler Ballance <tyler@monkeypox.org> | 2009-11-16 21:09:13 -0800 |
commit | d9ce7916e309e2393d824e249f512d2629e5e181 (patch) | |
tree | 6b7ad5cd6292f6e017e048fbeb4551facbabd174 /docs/users_guide_2_src/10_errorHandling.txt | |
parent | e43765a679b84c52df875e9629d303e304af50a1 (diff) | |
download | python-cheetah-d9ce7916e309e2393d824e249f512d2629e5e181.tar.gz |
Revert "Delete the "old" docs directory to make way for fancy smancy sphinx"docs
This reverts commit 5dc95cfcd015628665d3672e56d0551943b5db6b.
Diffstat (limited to 'docs/users_guide_2_src/10_errorHandling.txt')
-rwxr-xr-x | docs/users_guide_2_src/10_errorHandling.txt | 145 |
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: + + + + |