diff options
Diffstat (limited to 'Lib/lib2to3/pytree.py')
| -rw-r--r-- | Lib/lib2to3/pytree.py | 192 |
1 files changed, 118 insertions, 74 deletions
diff --git a/Lib/lib2to3/pytree.py b/Lib/lib2to3/pytree.py index 1c09ef1..9de810e 100644 --- a/Lib/lib2to3/pytree.py +++ b/Lib/lib2to3/pytree.py @@ -1,7 +1,8 @@ # Copyright 2006 Google, Inc. All Rights Reserved. # Licensed to PSF under a Contributor Agreement. -"""Python parse tree definitions. +""" +Python parse tree definitions. This is a very concrete parse tree; we need to keep every token and even the comments and whitespace between tokens. @@ -31,7 +32,8 @@ def type_repr(type_num): class Base(object): - """Abstract base class for Node and Leaf. + """ + Abstract base class for Node and Leaf. This provides some default functionality and boilerplate using the template pattern. @@ -51,7 +53,8 @@ class Base(object): return object.__new__(cls) def __eq__(self, other): - """Compares two nodes for equality. + """ + Compare two nodes for equality. This calls the method _eq(). """ @@ -60,7 +63,8 @@ class Base(object): return self._eq(other) def __ne__(self, other): - """Compares two nodes for inequality. + """ + Compare two nodes for inequality. This calls the method _eq(). """ @@ -69,53 +73,58 @@ class Base(object): return not self._eq(other) def _eq(self, other): - """Compares two nodes for equality. + """ + Compare two nodes for equality. - This is called by __eq__ and __ne__. It is only called if the - two nodes have the same type. This must be implemented by the - concrete subclass. Nodes should be considered equal if they - have the same structure, ignoring the prefix string and other - context information. + This is called by __eq__ and __ne__. It is only called if the two nodes + have the same type. This must be implemented by the concrete subclass. + Nodes should be considered equal if they have the same structure, + ignoring the prefix string and other context information. """ raise NotImplementedError def clone(self): - """Returns a cloned (deep) copy of self. + """ + Return a cloned (deep) copy of self. This must be implemented by the concrete subclass. """ raise NotImplementedError def post_order(self): - """Returns a post-order iterator for the tree. + """ + Return a post-order iterator for the tree. This must be implemented by the concrete subclass. """ raise NotImplementedError def pre_order(self): - """Returns a pre-order iterator for the tree. + """ + Return a pre-order iterator for the tree. This must be implemented by the concrete subclass. """ raise NotImplementedError def set_prefix(self, prefix): - """Sets the prefix for the node (see Leaf class). + """ + Set the prefix for the node (see Leaf class). This must be implemented by the concrete subclass. """ raise NotImplementedError def get_prefix(self): - """Returns the prefix for the node (see Leaf class). + """ + Return the prefix for the node (see Leaf class). This must be implemented by the concrete subclass. """ raise NotImplementedError def replace(self, new): - """Replaces this node with a new one in the parent.""" + """Replace this node with a new one in the parent.""" assert self.parent is not None, str(self) assert new is not None if not isinstance(new, list): @@ -138,7 +147,7 @@ class Base(object): self.parent = None def get_lineno(self): - """Returns the line number which generated the invocant node.""" + """Return the line number which generated the invocant node.""" node = self while not isinstance(node, Leaf): if not node.children: @@ -152,8 +161,10 @@ class Base(object): self.was_changed = True def remove(self): - """Remove the node from the tree. Returns the position of the node - in its parent's children before it was removed.""" + """ + Remove the node from the tree. Returns the position of the node in its + parent's children before it was removed. + """ if self.parent: for i, node in enumerate(self.parent.children): if node is self: @@ -162,10 +173,12 @@ class Base(object): self.parent = None return i - def get_next_sibling(self): - """Return the node immediately following the invocant in their - parent's children list. If the invocant does not have a next - sibling, return None.""" + @property + def next_sibling(self): + """ + The node immediately following the invocant in their parent's children + list. If the invocant does not have a next sibling, it is None + """ if self.parent is None: return None @@ -177,10 +190,12 @@ class Base(object): except IndexError: return None - def get_prev_sibling(self): - """Return the node immediately preceding the invocant in their - parent's children list. If the invocant does not have a previous - sibling, return None.""" + @property + def prev_sibling(self): + """ + The node immediately preceding the invocant in their parent's children + list. If the invocant does not have a previous sibling, it is None. + """ if self.parent is None: return None @@ -192,9 +207,11 @@ class Base(object): return self.parent.children[i-1] def get_suffix(self): - """Return the string immediately following the invocant node. This - is effectively equivalent to node.get_next_sibling().get_prefix()""" - next_sib = self.get_next_sibling() + """ + Return the string immediately following the invocant node. This is + effectively equivalent to node.next_sibling.get_prefix() + """ + next_sib = self.next_sibling if next_sib is None: return "" return next_sib.get_prefix() @@ -205,7 +222,8 @@ class Node(Base): """Concrete implementation for interior nodes.""" def __init__(self, type, children, context=None, prefix=None): - """Initializer. + """ + Initializer. Takes a type constant (a symbol number >= 256), a sequence of child nodes, and an optional context keyword argument. @@ -222,42 +240,44 @@ class Node(Base): self.set_prefix(prefix) def __repr__(self): - """Returns a canonical string representation.""" + """Return a canonical string representation.""" return "%s(%s, %r)" % (self.__class__.__name__, type_repr(self.type), self.children) def __str__(self): - """Returns a pretty string representation. + """ + Return a pretty string representation. This reproduces the input source exactly. """ return "".join(map(str, self.children)) def _eq(self, other): - """Compares two nodes for equality.""" + """Compare two nodes for equality.""" return (self.type, self.children) == (other.type, other.children) def clone(self): - """Returns a cloned (deep) copy of self.""" + """Return a cloned (deep) copy of self.""" return Node(self.type, [ch.clone() for ch in self.children]) def post_order(self): - """Returns a post-order iterator for the tree.""" + """Return a post-order iterator for the tree.""" for child in self.children: for node in child.post_order(): yield node yield self def pre_order(self): - """Returns a pre-order iterator for the tree.""" + """Return a pre-order iterator for the tree.""" yield self for child in self.children: for node in child.post_order(): yield node def set_prefix(self, prefix): - """Sets the prefix for the node. + """ + Set the prefix for the node. This passes the responsibility on to the first child. """ @@ -265,7 +285,8 @@ class Node(Base): self.children[0].set_prefix(prefix) def get_prefix(self): - """Returns the prefix for the node. + """ + Return the prefix for the node. This passes the call on to the first child. """ @@ -274,23 +295,29 @@ class Node(Base): return self.children[0].get_prefix() def set_child(self, i, child): - """Equivalent to 'node.children[i] = child'. This method also sets the - child's parent attribute appropriately.""" + """ + Equivalent to 'node.children[i] = child'. This method also sets the + child's parent attribute appropriately. + """ child.parent = self self.children[i].parent = None self.children[i] = child self.changed() def insert_child(self, i, child): - """Equivalent to 'node.children.insert(i, child)'. This method also - sets the child's parent attribute appropriately.""" + """ + Equivalent to 'node.children.insert(i, child)'. This method also sets + the child's parent attribute appropriately. + """ child.parent = self self.children.insert(i, child) self.changed() def append_child(self, child): - """Equivalent to 'node.children.append(child)'. This method also - sets the child's parent attribute appropriately.""" + """ + Equivalent to 'node.children.append(child)'. This method also sets the + child's parent attribute appropriately. + """ child.parent = self self.children.append(child) self.changed() @@ -306,10 +333,11 @@ class Leaf(Base): column = 0 # Column where this token tarts in the input def __init__(self, type, value, context=None, prefix=None): - """Initializer. + """ + Initializer. - Takes a type constant (a token number < 256), a string value, - and an optional context keyword argument. + Takes a type constant (a token number < 256), a string value, and an + optional context keyword argument. """ assert 0 <= type < 256, type if context is not None: @@ -320,51 +348,53 @@ class Leaf(Base): self.prefix = prefix def __repr__(self): - """Returns a canonical string representation.""" + """Return a canonical string representation.""" return "%s(%r, %r)" % (self.__class__.__name__, self.type, self.value) def __str__(self): - """Returns a pretty string representation. + """ + Return a pretty string representation. This reproduces the input source exactly. """ return self.prefix + str(self.value) def _eq(self, other): - """Compares two nodes for equality.""" + """Compare two nodes for equality.""" return (self.type, self.value) == (other.type, other.value) def clone(self): - """Returns a cloned (deep) copy of self.""" + """Return a cloned (deep) copy of self.""" return Leaf(self.type, self.value, (self.prefix, (self.lineno, self.column))) def post_order(self): - """Returns a post-order iterator for the tree.""" + """Return a post-order iterator for the tree.""" yield self def pre_order(self): - """Returns a pre-order iterator for the tree.""" + """Return a pre-order iterator for the tree.""" yield self def set_prefix(self, prefix): - """Sets the prefix for the node.""" + """Set the prefix for the node.""" self.changed() self.prefix = prefix def get_prefix(self): - """Returns the prefix for the node.""" + """Return the prefix for the node.""" return self.prefix def convert(gr, raw_node): - """Converts raw node information to a Node or Leaf instance. + """ + Convert raw node information to a Node or Leaf instance. - This is passed to the parser driver which calls it whenever a - reduction of a grammar rule produces a new complete node, so that - the tree is build strictly bottom-up. + This is passed to the parser driver which calls it whenever a reduction of a + grammar rule produces a new complete node, so that the tree is build + strictly bottom-up. """ type, value, context, children = raw_node if children or type in gr.number2symbol: @@ -379,7 +409,8 @@ def convert(gr, raw_node): class BasePattern(object): - """A pattern is a tree matching pattern. + """ + A pattern is a tree matching pattern. It looks for a specific node type (token or symbol), and optionally for a specific content. @@ -409,14 +440,16 @@ class BasePattern(object): return "%s(%s)" % (self.__class__.__name__, ", ".join(map(repr, args))) def optimize(self): - """A subclass can define this as a hook for optimizations. + """ + A subclass can define this as a hook for optimizations. Returns either self or another node with the same effect. """ return self def match(self, node, results=None): - """Does this pattern exactly match a node? + """ + Does this pattern exactly match a node? Returns True if it matches, False if not. @@ -440,7 +473,8 @@ class BasePattern(object): return True def match_seq(self, nodes, results=None): - """Does this pattern exactly match a sequence of nodes? + """ + Does this pattern exactly match a sequence of nodes? Default implementation for non-wildcard patterns. """ @@ -449,7 +483,8 @@ class BasePattern(object): return self.match(nodes[0], results) def generate_matches(self, nodes): - """Generator yielding all matches for this pattern. + """ + Generator yielding all matches for this pattern. Default implementation for non-wildcard patterns. """ @@ -461,7 +496,8 @@ class BasePattern(object): class LeafPattern(BasePattern): def __init__(self, type=None, content=None, name=None): - """Initializer. Takes optional type, content, and name. + """ + Initializer. Takes optional type, content, and name. The type, if given must be a token type (< 256). If not given, this matches any *leaf* node; the content may still be required. @@ -486,7 +522,8 @@ class LeafPattern(BasePattern): return BasePattern.match(self, node, results) def _submatch(self, node, results=None): - """Match the pattern's content to the node's children. + """ + Match the pattern's content to the node's children. This assumes the node type matches and self.content is not None. @@ -505,7 +542,8 @@ class NodePattern(BasePattern): wildcards = False def __init__(self, type=None, content=None, name=None): - """Initializer. Takes optional type, content, and name. + """ + Initializer. Takes optional type, content, and name. The type, if given, must be a symbol type (>= 256). If the type is None this matches *any* single node (leaf or not), @@ -533,7 +571,8 @@ class NodePattern(BasePattern): self.name = name def _submatch(self, node, results=None): - """Match the pattern's content to the node's children. + """ + Match the pattern's content to the node's children. This assumes the node type matches and self.content is not None. @@ -561,7 +600,8 @@ class NodePattern(BasePattern): class WildcardPattern(BasePattern): - """A wildcard pattern can match zero or more nodes. + """ + A wildcard pattern can match zero or more nodes. This has all the flexibility needed to implement patterns like: @@ -573,7 +613,8 @@ class WildcardPattern(BasePattern): """ def __init__(self, content=None, min=0, max=HUGE, name=None): - """Initializer. + """ + Initializer. Args: content: optional sequence of subsequences of patterns; @@ -641,7 +682,8 @@ class WildcardPattern(BasePattern): return False def generate_matches(self, nodes): - """Generator yielding matches for a sequence of nodes. + """ + Generator yielding matches for a sequence of nodes. Args: nodes: sequence of nodes @@ -744,7 +786,8 @@ class WildcardPattern(BasePattern): class NegatedPattern(BasePattern): def __init__(self, content=None): - """Initializer. + """ + Initializer. The argument is either a pattern or None. If it is None, this only matches an empty sequence (effectively '$' in regex @@ -776,7 +819,8 @@ class NegatedPattern(BasePattern): def generate_matches(patterns, nodes): - """Generator yielding matches for a sequence of patterns and nodes. + """ + Generator yielding matches for a sequence of patterns and nodes. Args: patterns: a sequence of patterns |