1##############################################################################
2#
3# Copyright (c) 2003 Zope Corporation and Contributors.
4# All Rights Reserved.
5#
6# This software is subject to the provisions of the Zope Public License,
7# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
8# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
9# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
10# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
11# FOR A PARTICULAR PURPOSE.
12#
13##############################################################################
14"""Interface that describes the 'macros' attribute of a PageTemplate.
15
16$Id: interfaces.py 28655 2004-12-20 22:37:19Z fdrake $
17"""
18from zope.interface import Interface
19
20try:
21    from zope import tal
22except ImportError:
23    tal = None
24
25
26class ITALESFunctionNamespace(Interface):
27    """Function namespaces can be used in TALES path expressions to extract
28    information in non-default ways."""
29
30    def setEngine(engine):
31        """Sets the engine that is used to evaluate TALES expressions."""
32
33class ITALESExpression(Interface):
34    """TALES expression
35
36    These are expression handlers that handle a specific type of
37    expression in TALES, e.g. path or string expression.
38    """
39
40    def __call__(econtext):
41        """Evaluate expression according to the given execution
42        context 'econtext' and return computed value.
43        """
44
45if tal is not None:
46    from zope.tal.interfaces import ITALIterator
47
48    class ITALESIterator(ITALIterator):
49        """TAL Iterator provided by TALES
50
51        Values of this iterator are assigned to items in the repeat namespace.
52
53        For example, with a TAL statement like: tal:repeat="item items",
54        an iterator will be assigned to "repeat/item".  The iterator
55        provides a number of handy methods useful in writing TAL loops.
56
57        The results are undefined of calling any of the methods except
58        'length' before the first iteration.
59        """
60
61        def index():
62            """Return the position (starting with "0") within the iteration
63            """
64
65        def number():
66            """Return the position (starting with "1") within the iteration
67            """
68
69        def even():
70            """Return whether the current position is even
71            """
72
73        def odd():
74            """Return whether the current position is odd
75            """
76
77        def parity():
78            """Return 'odd' or 'even' depending on the position's parity
79
80            Useful for assigning CSS class names to table rows.
81            """
82
83        def start():
84            """Return whether the current position is the first position
85            """
86
87        def end():
88            """Return whether the current position is the last position
89            """
90
91        def letter():
92            """Return the position (starting with "a") within the iteration
93            """
94
95        def Letter():
96            """Return the position (starting with "A") within the iteration
97            """
98
99        def roman():
100            """Return the position (starting with "i") within the iteration
101            """
102
103        def Roman():
104            """Return the position (starting with "I") within the iteration
105            """
106
107        def item():
108            """Return the item at the current position
109            """
110
111        def length():
112            """Return the length of the sequence
113
114            Note that this may fail if the TAL iterator was created on a Python
115            iterator.
116            """
117