yagdoc.scanner.Tree

Package yagdoc :: Module scanner :: Class Tree

[show private | hide private]

Type Tree

object --+
         |
        Tree

Expanded parse tree branch.

It supports the list protocol, behaving like a proxy for Tree.items in this regards. Empty tree evaluates as False in boolean context. For performance reasons one often operates on the items field directly. However for operations such as:

   for node in tree:
       ...

the proxying overhead exists only in the creation of the iterator and should be small.

It also overrides the comparison protocol, operators '==' and '!=' compare two trees without regard to token positions in the file. This means that Tree objects corresponding to declarations:

   int foo(int x, double y);

   int
   foo(int    x,
       double y);

will evaluate as equal. This is what one is normally interested in.

Note due to the recursive nature of the comparision it does not help to compare the type and items fields directly in order to compare two trees including token positions (which should be seldom needed).

Note the presence of type attribute in both Tree and Token enables duck-typed walking through the expanded parse trees.

Method Summary
	`__init__(self, root, items)` Create a new expanded parse Tree.
	`__delitem__(self, key)`
	`__eq__(self, other)`
	`__getitem__(self, key)`
	`__iter__(self)`
	`__len__(self)`
	`__ne__(self, other)`
	`__setitem__(self, key, value)`
`Tree`	`descend(self, names, pos)` Descend an expanded parse tree through branches of given names.
`tuple` of `str` or `None`	`find_name(self)` Find the name of a tree (corresponding to for instance a variable or user function).
`list` of `Tree`	`gather_all(self, name)` Gather all branches of given name in an expanded parse tree.
Inherited from `object`: `__delattr__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__repr__`, `__setattr__`, `__str__`
Subname scanners
	`subnames_enum_body(self, symbols, stack)` Scan `'enum_body'` tree for symbol names.
	`subnames_struct_body(self, symbols, stack)` Scan `'struct_body'` tree for symbol names.
	`subnames_user_function_parent(self, symbols, stack)` Scan function type sub tree for symbol names.
	`subnames_prototype_args(self, symbols, stack)` Scan `'prototype_args'` tree for symbol names.
	`subnames_type(self, symbols, stack)` Scan `'type'` tree for symbol names.

Instance Variable Summary
list of `Token` or `Tree`	`items`: List of items this branch consits of.
`str`	`type`: Name of this branch.

Class Variable Summary
`list`	`__slots__` = `['type', 'items']`

Method Details

subnames_enum_body(self, symbols, stack)

Scan 'enum_body' tree for symbol names.

Parameters:: symbols - List of symbol names and their properties found so far, new symbols will be added to it.
(type=list of tuple of str); stack - Symbol stack, containing all parent symbols in order (except the top-level one as it does not enter the prefixes).
(type=list of str)

subnames_struct_body(self, symbols, stack)

Scan 'struct_body' tree for symbol names.

Parameters:: symbols - List of symbol names and their properties found so far, new symbols will be added to it.
(type=list of tuple of str); stack - Symbol stack, containing all parent symbols in order (except the top-level one as it does not enter the prefixes).
(type=list of str)

subnames_user_function_parent(self, symbols, stack)

Scan function type sub tree for symbol names.

The tree root note is a parent of 'user_function', for instance 'argument', 'struct_field', 'typedef' or 'variable'. It is expected to contain 'type', possibly some 'variable_modifier's and 'user_function'. The name of the parent must be already on stack and in symbols, only return type and arguments are scanned.

Parameters:: symbols - List of symbol names and their properties found so far, new symbols will be added to it.
(type=list of tuple of str); stack - Symbol stack, containing all parent symbols in order (except the top-level one as it does not enter the prefixes).
(type=list of str)

subnames_prototype_args(self, symbols, stack)

Scan 'prototype_args' tree for symbol names.

Parameters:: symbols - List of symbol names and their properties found so far, new symbols will be added to it.
(type=list of tuple of str); stack - Symbol stack, containing all parent symbols in order (except the top-level one as it does not enter the prefixes).
(type=list of str)

subnames_type(self, symbols, stack)

Scan 'type' tree for symbol names.

Parameters:: symbols - List of symbol names and their properties found so far, new symbols will be added to it.
(type=list of tuple of str); stack - Symbol stack, containing all parent symbols in order (except the top-level one as it does not enter the prefixes).
(type=list of str)

init(self, root, items=None)
(Constructor)

Create a new expanded parse Tree.

The constructor has two possible forms:

   # Construct from values
   tree = Tree(root_type, items)

   # Construct from simpleparser tree
   tree = Tree(root_branch, tokens)

The parse tree produced by simpleparser is unexpanded, its nodes just reference the token soup, leaves are not explicitly present at all. Scanner uses expanded (and selfcontained) parse trees that directly embed tokens.

Parameters:: root - type field or simpleparser tree root branch.; items - items field (can be omitted for an empty list) or list of Token.

Overrides:: __builtin__.object.__init__

descend(self, names, pos=0)

Descend an expanded parse tree through branches of given names.

The first branch with given name is always taken.

Parameters:: names - List of node names to descend through, it does not include the name of self.
(type=string or sequence of strings)

Returns:: Tree branch corresponding to the last item of names, or None if we went astray.
(type=Tree)

find_name(self)

Find the name of a tree (corresponding to for instance a variable or user function).

How the name is determined depends on the particular tree branch type.

Returns:: Couple (kind, name) where the second item is the name sought, the first item is 'name' or 'user_function' depending on the relation of the name to the tree. If the tree does not seem to have any name, (None, None) is returned.
(type=tuple of str or None)

gather_all(self, name)

Gather all branches of given name in an expanded parse tree.

Parameters:: name - Name of nodes (i.e. type field) to gather.
(type=str)

Returns:: List of all nodes in the tree of specified type. Only Tree nodes are gathered, does not work for Token nodes.
(type=list of Tree)

Instance Variable Details

items

List of items this branch consits of. Leaves are Tokens, no-leaf branches are Trees.

Type:: list of Token or Tree
Value:: <member 'items' of 'Tree' objects>

type

Name of this branch. That is the corresponding parser grammar rule name, except the couple of cases we refactor the tree into new branch types.

Type:: str
Value:: <member 'type' of 'Tree' objects>

Class Variable Details

slots

Type:: list
Value:: ['type', 'items']

Generated by Epydoc 2.1 on Fri Oct 5 00:36:53 2007

http://epydoc.sf.net