1# -*- coding: utf-8 -*-
2"""
3    jinja2.meta
4    ~~~~~~~~~~~
5
6    This module implements various functions that exposes information about
7    templates that might be interesting for various kinds of applications.
8
9    :copyright: (c) 2010 by the Jinja Team, see AUTHORS for more details.
10    :license: BSD, see LICENSE for more details.
11"""
12from jinja2 import nodes
13from jinja2.compiler import CodeGenerator
14
15
16class TrackingCodeGenerator(CodeGenerator):
17    """We abuse the code generator for introspection."""
18
19    def __init__(self, environment):
20        CodeGenerator.__init__(self, environment, '<introspection>',
21                               '<introspection>')
22        self.undeclared_identifiers = set()
23
24    def write(self, x):
25        """Don't write."""
26
27    def pull_locals(self, frame):
28        """Remember all undeclared identifiers."""
29        self.undeclared_identifiers.update(frame.identifiers.undeclared)
30
31
32def find_undeclared_variables(ast):
33    """Returns a set of all variables in the AST that will be looked up from
34    the context at runtime.  Because at compile time it's not known which
35    variables will be used depending on the path the execution takes at
36    runtime, all variables are returned.
37
38    >>> from jinja2 import Environment, meta
39    >>> env = Environment()
40    >>> ast = env.parse('{% set foo = 42 %}{{ bar + foo }}')
41    >>> meta.find_undeclared_variables(ast)
42    set(['bar'])
43
44    .. admonition:: Implementation
45
46       Internally the code generator is used for finding undeclared variables.
47       This is good to know because the code generator might raise a
48       :exc:`TemplateAssertionError` during compilation and as a matter of
49       fact this function can currently raise that exception as well.
50    """
51    codegen = TrackingCodeGenerator(ast.environment)
52    codegen.visit(ast)
53    return codegen.undeclared_identifiers
54
55
56def find_referenced_templates(ast):
57    """Finds all the referenced templates from the AST.  This will return an
58    iterator over all the hardcoded template extensions, inclusions and
59    imports.  If dynamic inheritance or inclusion is used, `None` will be
60    yielded.
61
62    >>> from jinja2 import Environment, meta
63    >>> env = Environment()
64    >>> ast = env.parse('{% extends "layout.html" %}{% include helper %}')
65    >>> list(meta.find_referenced_templates(ast))
66    ['layout.html', None]
67
68    This function is useful for dependency tracking.  For example if you want
69    to rebuild parts of the website after a layout template has changed.
70    """
71    for node in ast.find_all((nodes.Extends, nodes.FromImport, nodes.Import,
72                              nodes.Include)):
73        if not isinstance(node.template, nodes.Const):
74            # a tuple with some non consts in there
75            if isinstance(node.template, (nodes.Tuple, nodes.List)):
76                for template_name in node.template.items:
77                    # something const, only yield the strings and ignore
78                    # non-string consts that really just make no sense
79                    if isinstance(template_name, nodes.Const):
80                        if isinstance(template_name.value, basestring):
81                            yield template_name.value
82                    # something dynamic in there
83                    else:
84                        yield None
85            # something dynamic we don't know about here
86            else:
87                yield None
88            continue
89        # constant is a basestring, direct template name
90        if isinstance(node.template.value, basestring):
91            yield node.template.value
92        # a tuple or list (latter *should* not happen) made of consts,
93        # yield the consts that are strings.  We could warn here for
94        # non string values
95        elif isinstance(node, nodes.Include) and \
96             isinstance(node.template.value, (tuple, list)):
97            for template_name in node.template.value:
98                if isinstance(template_name, basestring):
99                    yield template_name
100        # something else we don't care about, we could warn here
101        else:
102            yield None
103