1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
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:
|
