Visitor API

Defines a base Visitor class for all the outputs.

This class does almost all of the lifting for output generation. It’s super important; don’t gloss this one over.

class registermaps.visitor.Visitor(output=None, directory=None)

An abstract Visitor for working with HtiComponent trees.

Subclasses work by overloading some combination of defaultvisit and visit_Component, visit_Register, etc. These functions are all called on a single node of the tree. They do not recurse by default; overloaded functions must explicitly call either self.visit(node) on child nodes or self.visitchildren(node) on the current node.

Visitor functions are allowed to return values, but this can get complicated quickly. It’s probably better to have them directly manipulate states, either storing them in the class instance or writing results directly to self.output.

Subclasses can also overload begin and finish, which are called before tree parsing starts and after it is completed respectively. These are generally places to put initialization and cleanup code.

Create an instance of the Visitor, then call .execute on the start node. Return value is the return value of Visitor.finish, which will usually be None.

begin(startnode)

Things to do before we begin visiting the first node.

startnode is the top-level node of the tree.

defaultvisit(node)

Called when there is no explicit visitor for this node type.

execute(startnode)

Run the Visitor starting from startnode.

If a directory or filename has been provided, this is when the file will actually be opened.

finish(lastvalue)

Things to do after we have visited the entire tree.

lastvalue is the return of the top-level visit call.

classmethod preparedir(directory)

Copy README.rst to the target directory.

print(*args, **kwargs)

Prints to self.output

kwargs are as passed to the print statement. They override arguments registered in self.printoptions (default is empty).

printf(formatstr, *args, printargs={}, **kwargs)

Prints to self.output using a format string.

All args and kwargs are passed to format, not print. printargs can be explicitly provided, but are an indication you’ve overcomplicated things.

classmethod rb(resourcename)

Get a binary resource from this resource subdirectory.

classmethod rt(resourcename)

Get a text resource from this resource subdirectory.

classmethod template(resourcename)

Get a template resource from this resource subdirectory.

tempvars(**kwargs)

Stores kwargs as attributes of the class during the context.

This is extremely useful for dealing with information which must be temporarily passed down to recursive calls while making sure to clean them back up on the way out.

Overwriting existing attributes will restore them after the context.

visit(node)

Base visit operation. This shouldn’t need overloading.

visit_Register(node)

Call visit_SimpleRegister or visit_ComplexRegister.

A simple Register has no children. Override this when you don’t want two functions.

visit_RegisterArray(node)

Call visit_SimpleRegisterArray or visit_ComplexRegisterArray.

A simple RegisterArray has only 1 child. Override this when you don’t want two functions.

visitchildren(node, reverse=False)

Visit all the children of this node.

Shouldn’t need overloading, but this must be called explicitly.

Returns a list of all return values from all child nodes.

write(data)

Write binary data to self.output.