19.4 compiler.visitor -- Walk ASTs Using Visitors

compiler.visitor.ASTVisitor walks the abstract syntax tree created by the parser. The compiler package uses a variant on the visitor pattern that takes advantage of Python's introspection features to eliminate the need for much of the visitor's infrastructure.

The classes being visited do not need to be programmed to accept visitors. The visitor need only define visit methods for nodes it is specifically interested in; a default visit method handles the rest.

walk(tree, visitor[, walker [, verbose]])

    Initiate a preorder walk of tree. visitor is an instance of a class that defines a visitNodeType method for each AST node of interest. NodeType is the name of the AST class to be visited.
    
    walker is an instance of ASTVisitor (the default) or a subclass. This is the class that will actually walk the tree and dispatch to the visitor.
    
    The verbose argument is used to set the VERBOSE attribute of walker. It is used by ExampleASTVisitor, not by ASTVisitor.
    
    Note: This function is also exposed as compiler.walk().

class ASTVisitor()

    ASTVisitor is responsible for walking over the tree in the correct order. A walk begins with a call to preorder(). For each node, it checks the visitor argument to preorder() for a method named `visitNodeType,' where NodeType is the name of the node's class, e.g. for a While node the method visitWhile() would be called. If the visitNodeType() method exists, it is called with the node as its first argument. If the visitNodeType() method does not exist, ASTVisiter.default() is called instead.

    The visitNodeType() method for a particular node type controls how child nodes are visited during the walk. Only children explicitly visited by the visitNodeType() method will be visited. The ASTVisitor modifies the visitor argument by adding a visit() method to the visitor; this method can be used to visit a particular child node.

ASTVisitor objects have the following methods:

default(node[, ...])

    The default node handler. The dispatch() method calls default() for a node when the visitor does not define a handler for the node. The default handler visits each child node of the given node. Any extra arguments are passed to the dispatch method.

dispatch(node[, ...])

    Finds the handler for a node and dispatches to it. Any extra arguments are passed to the handler.
    
preorder(tree, visitor[, ...])

    Initiates a preorder walk of the tree. Any extra arguments are passed to the node handlers.


class ExampleASTVisitor()

    This subclass of ASTVisitor can be passed as the walker argument to walk. It prints information about any node that is not handled by the visitor object. This is useful for inspecting a tree and developing a visitor. Set the verbose parameter of walk to 1 or higher to get the extra output.


Example:

    from compiler import parse, walk
    from compiler.visitor import ExampleASTVisitor

    testdata = '''
    def aFunction(anArg):
        return anArg + 1
    '''

    class SimpleVisitor(object):
        def visitFunction(self, parsedFunc):
            print "Function %(name)s at %(lineno)s takes %(argnames)s " \
                  " with code %(code)s" % parsedFunc.__dict__

    if __name__ == "__main__":
        ast = parse(testdata)
        walk(ast, SimpleVisitor(), walker=ExampleASTVisitor(), verbose=1)