The animate action of mwalk runs the Animator java application. The user passes a list of visitors and the name of tree file on the command-line. Animator actually invokes Builder to read in and prepare the tree and thus can actually build a tree from scratch before animating it, but for this discussion we'll assume that the tree was build in a separate stage (build).
For each visitor listed, Animator attempts to instantiate the appropriate class using the passed name as a complete classname. If that fails, it tries to prepend the standard visitor package, mwalk.visitor. If neither of these classnames can be instantiated, Animator will print an error message in verbose mode and continue with the next visitor in the list.
Once the visitor class is instantiated, animation consists of four steps:
- The visitor is initialized with a reference to the tree.
- The tree is walked from the source to each receiver (depth-first) allowing the visitor to visit each node twice: prior to accessing its children (prefix) and after all children have been accessed (postfix). Results are collected from visits to each the children and are passed to the visitor during the postfix visit.
- The tree is walked from each receiver up to the source. Both prefix and postfix visits are performed, similar to the previous step.
- The visitor is queried whether it needs to walk again. If so, steps 2-4 are repeated.
All of these steps are not necessarily executed for every visitor. Visitors can control how Animator interacts with them through their particular implementation of three primary interfaces, Visitor, UpVisitor and DownVisitor. The Visitor interface is the base interface which must be implemented by all visitor classes. It provides methods to initialize the visitor (init), check whether to repeat the animation loop (again) and determine whether to perform prefix and/or postfix visits (prefix,postfix). The UpVisitor and DownVisitor interfaces can be implemented selectively. If a visitor does not implement one of them then the tree will not be walked in that direction at all. Furthermore, the interfaces provide methods to check whether or not the tree should be walked on a particular iteration (walkUp,walkDown). This allows the visitor to change its behavior from iteration to iteration. The interaction between Animator and visitors is explored in more detail in README.visitors.
To run the animate action, use the syntax listed below. The pause flag is good for debuuging because it gives you a chance to see any verbose output at each stage of the walk, but it can become quite tedious for large trees. The configuration file is used by visitors to change their default behavior. The file is formatted as key/value pairs. For the list of visitors, you must include the complete classname, including the package (unless it's in mwalk.visitors.*). You need to provide a directory list and output file only if you are adding to the tree (through Builder).