1b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)# -*- coding: utf-8 -*- 2b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)""" 3b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) jinja2.visitor 4b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) ~~~~~~~~~~~~~~ 5b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 6b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) This module implements a visitor for the nodes. 7b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 8b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) :copyright: (c) 2010 by the Jinja Team. 9b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) :license: BSD. 10b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)""" 11b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)from jinja2.nodes import Node 12b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 13b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 14b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)class NodeVisitor(object): 15b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Walks the abstract syntax tree and call visitor functions for every 16b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) node found. The visitor functions may return values which will be 17b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) forwarded by the `visit` method. 18b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 19b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) Per default the visitor functions for the nodes are ``'visit_'`` + 20b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) class name of the node. So a `TryFinally` node visit function would 21b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) be `visit_TryFinally`. This behavior can be changed by overriding 22b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) the `get_visitor` function. If no visitor function exists for a node 23b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) (return value `None`) the `generic_visit` visitor is used instead. 24b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 25b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 26b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def get_visitor(self, node): 27b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Return the visitor function for this node or `None` if no visitor 28b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) exists for this node. In that case the generic visit function is 29b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) used instead. 30b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 31b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) method = 'visit_' + node.__class__.__name__ 32b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return getattr(self, method, None) 33b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 34b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def visit(self, node, *args, **kwargs): 35b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Visit a node.""" 36b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) f = self.get_visitor(node) 37b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if f is not None: 38b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return f(node, *args, **kwargs) 39b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return self.generic_visit(node, *args, **kwargs) 40b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 41b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def generic_visit(self, node, *args, **kwargs): 42b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Called if no explicit visitor function exists for a node.""" 43b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) for node in node.iter_child_nodes(): 44b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) self.visit(node, *args, **kwargs) 45b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 46b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 47b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles)class NodeTransformer(NodeVisitor): 48b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """Walks the abstract syntax tree and allows modifications of nodes. 49b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 50b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) The `NodeTransformer` will walk the AST and use the return value of the 51b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) visitor functions to replace or remove the old node. If the return 52b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) value of the visitor function is `None` the node will be removed 53b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) from the previous location otherwise it's replaced with the return 54b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) value. The return value may be the original node in which case no 55b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) replacement takes place. 56b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 57b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 58b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def generic_visit(self, node, *args, **kwargs): 59b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) for field, old_value in node.iter_fields(): 60b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if isinstance(old_value, list): 61b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) new_values = [] 62b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) for value in old_value: 63b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if isinstance(value, Node): 64b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) value = self.visit(value, *args, **kwargs) 65b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if value is None: 66b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) continue 67b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) elif not isinstance(value, Node): 68b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) new_values.extend(value) 69b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) continue 70b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) new_values.append(value) 71b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) old_value[:] = new_values 72b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) elif isinstance(old_value, Node): 73b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) new_node = self.visit(old_value, *args, **kwargs) 74b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if new_node is None: 75b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) delattr(node, field) 76b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) else: 77b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) setattr(node, field, new_node) 78b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return node 79b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) 80b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) def visit_list(self, node, *args, **kwargs): 81b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """As transformers may return lists in some places this method 82b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) can be used to enforce a list as return value. 83b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) """ 84b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) rv = self.visit(node, *args, **kwargs) 85b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) if not isinstance(rv, list): 86b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) rv = [rv] 87b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) return rv 88