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
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
|
##############################################################################
#
# Copyright (c) 2003 Zope Foundation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""
Interface that a TAL expression implementation provides to the
METAL/TAL implementation.
This package does not provide an implementation of
:class:`ITALExpressionCompiler`, :class:`ITALExpressionEngine` or
:class:`ITALIterator`. An external package must provide those. The
most commonly used are :class:`zope.tales.tales.ExpressionEngine`,
:class:`zope.tales.tales.Context`, and
:class:`zope.tales.tales.Iterator`, respectively.
"""
from zope.interface import Attribute
from zope.interface import Interface
class ITALExpressionCompiler(Interface):
"""Compile-time interface provided by a TAL expression implementation.
The TAL compiler needs an instance of this interface to support
compilation of TAL expressions embedded in documents containing
TAL and METAL constructs.
"""
def getCompilerError():
"""Return the exception class raised for compilation errors.
"""
def compile(expression):
"""Return a compiled form of *expression* for later evaluation.
*expression* is the source text of the expression.
The return value may be passed to the various ``evaluate*()``
methods of the :class:`ITALExpressionEngine` interface. No
compatibility is required for the values of the compiled expression
between different :class:`ITALExpressionEngine` implementations.
"""
def getContext(namespace):
"""Create an expression execution context
The given *namespace* provides the initial top-level names.
"""
class ITALExpressionEngine(Interface):
"""Render-time interface provided by a TAL expression implementation.
The TAL interpreter uses this interface to TAL expression to support
evaluation of the compiled expressions returned by
:meth:`ITALExpressionCompiler.compile`.
"""
def getDefault():
"""Return the value of the ``default`` TAL expression.
Checking a value for a match with ``default`` should be done
using the ``is`` operator in Python.
"""
def setPosition(position):
"""Inform the engine of the current position in the source file.
*position* is a tuple (lineno, offset).
This is used to allow the evaluation engine to report
execution errors so that site developers can more easily
locate the offending expression.
"""
def setSourceFile(filename):
"""Inform the engine of the name of the current source file.
This is used to allow the evaluation engine to report
execution errors so that site developers can more easily
locate the offending expression.
"""
def beginScope():
"""Push a new scope onto the stack of open scopes.
"""
def endScope():
"""Pop one scope from the stack of open scopes.
"""
def evaluate(compiled_expression):
"""Evaluate an arbitrary expression.
No constraints are imposed on the return value.
"""
def evaluateBoolean(compiled_expression):
"""Evaluate an expression that must return a Boolean value.
"""
def evaluateMacro(compiled_expression):
"""Evaluate an expression that must return a macro program.
"""
def evaluateStructure(compiled_expression):
"""Evaluate an expression that must return a structured
document fragment.
The result of evaluating *compiled_expression* must be a
string containing a parsable HTML or XML fragment. Any TAL
markup contained in the result string will be interpreted.
"""
def evaluateText(compiled_expression):
"""Evaluate an expression that must return text.
The returned text should be suitable for direct inclusion in
the output: any HTML or XML escaping or quoting is the
responsibility of the expression itself.
If the expression evaluates to None, then that is returned. It
represents ``nothing`` in TALES.
If the expression evaluates to what :meth:`getDefault()`
returns, by comparison using ``is``, then that is returned. It
represents ``default`` in TALES.
"""
def evaluateValue(compiled_expression):
"""Evaluate an arbitrary expression.
No constraints are imposed on the return value.
"""
def createErrorInfo(exception, position):
"""Returns an :class:`ITALExpressionErrorInfo` object.
*position* is a tuple (lineno, offset).
The returned object is used to provide information about the
error condition for the on-error handler.
"""
def setGlobal(name, value):
"""Set a global variable.
The variable will be named *name* and have the value *value*.
"""
def setLocal(name, value):
"""Set a local variable in the current scope.
The variable will be named *name* and have the value *value*.
"""
def getValue(name, default=None):
"""Get a variable by name.
If the variable does not exist, return default.
"""
def setRepeat(name, compiled_expression):
"""Start a repetition, returning an :class:`ITALIterator`.
The engine is expected to add the a value (typically the
returned iterator) for the name to the variable namespace.
"""
def translate(msgid, domain=None, mapping=None, default=None):
"""See zope.i18n.interfaces.ITranslationDomain.translate"""
# NB: This differs from the Zope 2 equivalent in the order of
# the arguments. This will be a (hopefully minor) issue when
# creating a unified TAL implementation.
def evaluateCode(lang, code):
"""Evaluates code of the given language.
Returns whatever the code outputs. This can be defined on a
per-language basis. In Python this usually everything the print
statement will return.
"""
class ITALIterator(Interface):
"""A TAL iterator
Not to be confused with a Python iterator.
"""
def next():
"""Advance to the next value in the iteration, if possible
Return a true value if it was possible to advance and return
a false value otherwise.
"""
class ITALExpressionErrorInfo(Interface):
"""Information about an error."""
type = Attribute("type",
"The exception class.")
value = Attribute("value",
"The exception instance.")
lineno = Attribute("lineno",
"The line number the error occurred on in the source.")
offset = Attribute("offset",
"The character offset at which the error occurred.")
|
