1# Copyright 2015 Google Inc. All Rights Reserved. 2# 3# Licensed under the Apache License, Version 2.0 (the "License"); 4# you may not use this file except in compliance with the License. 5# You may obtain a copy of the License at 6# 7# http://www.apache.org/licenses/LICENSE-2.0 8# 9# Unless required by applicable law or agreed to in writing, software 10# distributed under the License is distributed on an "AS IS" BASIS, 11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12# See the License for the specific language governing permissions and 13# limitations under the License. 14"""Generic visitor pattern for pytrees. 15 16The lib2to3 parser produces a "pytree" - syntax tree consisting of Node 17and Leaf types. This module implements a visitor pattern for such trees. 18 19It also exports a basic "dumping" visitor that dumps a textual representation of 20a pytree into a stream. 21 22 PyTreeVisitor: a generic visitor pattern fo pytrees. 23 PyTreeDumper: a configurable "dumper" for displaying pytrees. 24 DumpPyTree(): a convenience function to dump a pytree. 25""" 26 27import sys 28 29from lib2to3 import pytree 30 31from yapf.yapflib import pytree_utils 32 33 34class PyTreeVisitor(object): 35 """Visitor pattern for pytree trees. 36 37 Methods named Visit_XXX will be invoked when a node with type XXX is 38 encountered in the tree. The type is either a token type (for Leaf nodes) or 39 grammar symbols (for Node nodes). The return value of Visit_XXX methods is 40 ignored by the visitor. 41 42 Visitors can modify node contents but must not change the tree structure 43 (e.g. add/remove children and move nodes around). 44 45 This is a very common visitor pattern in Python code; it's also used in the 46 Python standard library ast module for providing AST visitors. 47 48 Note: this makes names that aren't style conformant, so such visitor methods 49 need to be marked with # pylint: disable=invalid-name We don't have a choice 50 here, because lib2to3 nodes have under_separated names. 51 52 For more complex behavior, the visit, DefaultNodeVisit and DefaultLeafVisit 53 methods can be overridden. Don't forget to invoke DefaultNodeVisit for nodes 54 that may have children - otherwise the children will not be visited. 55 """ 56 57 def Visit(self, node): 58 """Visit a node.""" 59 method = 'Visit_{0}'.format(pytree_utils.NodeName(node)) 60 if hasattr(self, method): 61 # Found a specific visitor for this node 62 getattr(self, method)(node) 63 else: 64 if isinstance(node, pytree.Leaf): 65 self.DefaultLeafVisit(node) 66 else: 67 self.DefaultNodeVisit(node) 68 69 def DefaultNodeVisit(self, node): 70 """Default visitor for Node: visits the node's children depth-first. 71 72 This method is invoked when no specific visitor for the node is defined. 73 74 Arguments: 75 node: the node to visit 76 """ 77 for child in node.children: 78 self.Visit(child) 79 80 def DefaultLeafVisit(self, leaf): 81 """Default visitor for Leaf: no-op. 82 83 This method is invoked when no specific visitor for the leaf is defined. 84 85 Arguments: 86 leaf: the leaf to visit 87 """ 88 pass 89 90 91def DumpPyTree(tree, target_stream=sys.stdout): 92 """Convenience function for dumping a given pytree. 93 94 This function presents a very minimal interface. For more configurability (for 95 example, controlling how specific node types are displayed), use PyTreeDumper 96 directly. 97 98 Arguments: 99 tree: the tree to dump. 100 target_stream: the stream to dump the tree to. A file-like object. By 101 default will dump into stdout. 102 """ 103 dumper = PyTreeDumper(target_stream) 104 dumper.Visit(tree) 105 106 107class PyTreeDumper(PyTreeVisitor): 108 """Visitor that dumps the tree to a stream. 109 110 Implements the PyTreeVisitor interface. 111 """ 112 113 def __init__(self, target_stream=sys.stdout): 114 """Create a tree dumper. 115 116 Arguments: 117 target_stream: the stream to dump the tree to. A file-like object. By 118 default will dump into stdout. 119 """ 120 self._target_stream = target_stream 121 self._current_indent = 0 122 123 def _DumpString(self, s): 124 self._target_stream.write('{0}{1}\n'.format(' ' * self._current_indent, s)) 125 126 def DefaultNodeVisit(self, node): 127 # Dump information about the current node, and then use the generic 128 # DefaultNodeVisit visitor to dump each of its children. 129 self._DumpString(pytree_utils.DumpNodeToString(node)) 130 self._current_indent += 2 131 super(PyTreeDumper, self).DefaultNodeVisit(node) 132 self._current_indent -= 2 133 134 def DefaultLeafVisit(self, leaf): 135 self._DumpString(pytree_utils.DumpNodeToString(leaf)) 136