1 # -*- coding: utf-8 -*-
6 Jinja extensions allow to add custom tags similar to the way django custom
7 tags work. By default two example extensions exist: an i18n and a cache
10 :copyright: Copyright 2008 by Armin Ronacher.
13 from collections import deque
14 from jinja2 import nodes
15 from jinja2.environment import get_spontaneous_environment
16 from jinja2.runtime import Undefined
17 from jinja2.parser import statement_end_tokens
18 from jinja2.exceptions import TemplateAssertionError
19 from jinja2.utils import import_string
22 # the only real useful gettext functions for a Jinja template. Note
23 # that ugettext must be assigned to gettext as Jinja doesn't support
24 # non unicode strings.
25 GETTEXT_FUNCTIONS = ('_', 'gettext', 'ngettext')
28 class Extension(object):
29 """Instances of this class store parser extensions."""
31 #: if this extension parses this is the list of tags it's listening to.
34 def __init__(self, environment):
35 self.environment = environment
37 def parse(self, parser):
38 """Called if one of the tags matched."""
41 class CacheExtension(Extension):
42 """An example extension that adds cacheable blocks."""
45 def __init__(self, environment):
46 Extension.__init__(self, environment)
47 def dummy_cache_support(name, timeout=None, caller=None):
48 if caller is not None:
50 environment.globals['cache_support'] = dummy_cache_support
52 def parse(self, parser):
53 lineno = parser.stream.next().lineno
54 args = [parser.parse_expression()]
55 if parser.stream.current.type is 'comma':
57 args.append(parser.parse_expression())
58 body = parser.parse_statements(('name:endcache',), drop_needle=True)
59 return nodes.CallBlock(
60 nodes.Call(nodes.Name('cache_support', 'load'), args, [], None, None),
65 class TransExtension(Extension):
66 """This extension adds gettext support to Jinja."""
69 def __init__(self, environment):
70 Extension.__init__(self, environment)
71 environment.globals.update({
73 'gettext': lambda x: x,
74 'ngettext': lambda s, p, n: (s, p)[n != 1]
77 def parse(self, parser):
78 """Parse a translatable tag."""
79 lineno = parser.stream.next().lineno
81 # skip colon for python compatibility
82 if parser.stream.current.type is 'colon':
85 # find all the variables referenced. Additionally a variable can be
86 # defined in the body of the trans block too, but this is checked at
90 while parser.stream.current.type is not 'block_end':
92 parser.stream.expect('comma')
93 name = parser.stream.expect('name')
94 if name.value in variables:
95 raise TemplateAssertionError('translatable variable %r defined '
96 'twice.' % name.value, name.lineno,
100 if parser.stream.current.type is 'assign':
102 variables[name.value] = var = parser.parse_expression()
104 variables[name.value] = var = nodes.Name(name.value, 'load')
105 if plural_expr is None:
107 parser.stream.expect('block_end')
109 plural = plural_names = None
113 # now parse until endtrans or pluralize
114 singular_names, singular = self._parse_block(parser, True)
116 referenced.update(singular_names)
117 if plural_expr is None:
118 plural_expr = nodes.Name(singular_names[0], 'load')
120 # if we have a pluralize block, we parse that too
121 if parser.stream.current.test('name:pluralize'):
124 if parser.stream.current.type is not 'block_end':
125 plural_expr = parser.parse_expression()
126 parser.stream.expect('block_end')
127 plural_names, plural = self._parse_block(parser, False)
129 referenced.update(plural_names)
133 # register free names as simple name expressions
134 for var in referenced:
135 if var not in variables:
136 variables[var] = nodes.Name(var, 'load')
138 # no variables referenced? no need to escape
140 singular = singular.replace('%%', '%')
142 plural = plural.replace('%%', '%')
146 elif plural_expr is None:
147 raise TemplateAssertionError('pluralize without variables',
148 lineno, parser.filename)
151 variables = nodes.Dict([nodes.Pair(nodes.Const(x, lineno=lineno), y)
152 for x, y in variables.items()])
156 node = self._make_node(singular, plural, variables, plural_expr)
157 node.set_lineno(lineno)
160 def _parse_block(self, parser, allow_pluralize):
161 """Parse until the next block tag with a given name."""
165 if parser.stream.current.type is 'data':
166 buf.append(parser.stream.current.value.replace('%', '%%'))
168 elif parser.stream.current.type is 'variable_begin':
170 name = parser.stream.expect('name').value
171 referenced.append(name)
172 buf.append('%%(%s)s' % name)
173 parser.stream.expect('variable_end')
174 elif parser.stream.current.type is 'block_begin':
176 if parser.stream.current.test('name:endtrans'):
178 elif parser.stream.current.test('name:pluralize'):
181 raise TemplateSyntaxError('a translatable section can '
182 'have only one pluralize '
184 parser.stream.current.lineno,
186 raise TemplateSyntaxError('control structures in translatable'
187 ' sections are not allowed.',
188 parser.stream.current.lineno,
191 assert False, 'internal parser error'
193 return referenced, u''.join(buf)
195 def _make_node(self, singular, plural, variables, plural_expr):
196 """Generates a useful node from the data provided."""
198 if plural_expr is None:
199 gettext = nodes.Name('gettext', 'load')
200 node = nodes.Call(gettext, [nodes.Const(singular)],
203 node = nodes.Mod(node, variables)
205 # singular and plural
207 ngettext = nodes.Name('ngettext', 'load')
208 node = nodes.Call(ngettext, [
209 nodes.Const(singular),
214 node = nodes.Mod(node, variables)
215 return nodes.Output([node])
218 def extract_from_ast(node, gettext_functions=GETTEXT_FUNCTIONS):
219 """Extract localizable strings from the given template node.
221 For every string found this function yields a ``(lineno, function,
222 message)`` tuple, where:
224 * ``lineno`` is the number of the line on which the string was found,
225 * ``function`` is the name of the ``gettext`` function used (if the
226 string was extracted from embedded Python code), and
227 * ``message`` is the string itself (a ``unicode`` object, or a tuple
228 of ``unicode`` objects for functions with multiple string arguments).
230 for node in node.find_all(nodes.Call):
231 if not isinstance(node.node, nodes.Name) or \
232 node.node.name not in gettext_functions:
236 for arg in node.args:
237 if isinstance(arg, nodes.Const) and \
238 isinstance(arg.value, basestring):
239 strings.append(arg.value)
243 if len(strings) == 1:
246 strings = tuple(strings)
247 yield node.lineno, node.node.name, strings
250 def babel_extract(fileobj, keywords, comment_tags, options):
251 """Babel extraction method for Jinja templates.
253 :param fileobj: the file-like object the messages should be extracted from
254 :param keywords: a list of keywords (i.e. function names) that should be
255 recognized as translation functions
256 :param comment_tags: a list of translator tags to search for and include
257 in the results. (Unused)
258 :param options: a dictionary of additional options (optional)
259 :return: an iterator over ``(lineno, funcname, message, comments)`` tuples.
260 (comments will be empty currently)
262 encoding = options.get('encoding', 'utf-8')
264 have_trans_extension = False
266 for extension in options.get('extensions', '').split(','):
267 extension = extension.strip()
270 extension = import_string(extension)
271 if extension is TransExtension:
272 have_trans_extension = True
273 extensions.append(extension)
274 if not have_trans_extension:
275 extensions.append(TransExtension)
277 environment = get_spontaneous_environment(
278 options.get('block_start_string', '{%'),
279 options.get('block_end_string', '%}'),
280 options.get('variable_start_string', '{{'),
281 options.get('variable_end_string', '}}'),
282 options.get('comment_start_string', '{#'),
283 options.get('comment_end_string', '#}'),
284 options.get('line_statement_prefix') or None,
285 options.get('trim_blocks', '').lower() in ('1', 'on', 'yes', 'true'),
287 # fill with defaults so that environments are shared
288 # with other spontaneus environments.
289 True, Undefined, unicode
292 node = environment.parse(fileobj.read().decode(encoding))
293 for lineno, func, message in extract_from_ast(node, keywords):
294 yield lineno, func, message, []