Permalink
Browse files

Add docs for Tree::Optimizer::Pass. Last commit before I tag pencils …

…down.
  • Loading branch information...
1 parent f270ec3 commit 198314c80f6af74f267c3d0d8f7da9d30c821eea tcurtis committed Aug 16, 2010
Showing with 85 additions and 0 deletions.
  1. +85 −0 docs/Tree/Optimizer/Pass.pod
@@ -0,0 +1,85 @@
+=head1 NAME
+
+Tree::Optimizer::Pass - an optimization pass for Tree::Optimizer
+
+=head1 DESCRIPTION
+
+Tree::Optimizer::Pass objects represent optimization passes in a Tree::Optimizer. They can be created in two ways: by directly invoking Tree::Optimizer::Pass.new, or by registering a pass in a Tree::Optimizer. In the latter case, a Tree::Optimizer::Pass is implicitly created.
+
+=head1 Tree::Optimizer::Pass
+
+=head2 Attributes
+
+Each of these attributes can be accessed and modified using the method of the same name.
+
+=over 4
+
+=item dependencies
+
+A ResizablePMCArray containing the names of the passes on which the pass depends.
+
+=item name
+
+The name of the pass. Names beginning with C<__> are reserved.
+
+=item recursive
+
+A boolean flag indicating whether the pass should automatically recurse into subtrees.
+
+=item transformation
+
+The invokable object which will be used to transform the tree. If no when pattern is supplied, the transformation is called with the tree to be transformed. If a when pattern is supplied, then the transformation is invoked with the result of matching the tree against the pattern.
+
+=item when
+
+A Tree::Pattern object that is used to determine whether the transformation should be performed. If a pass has both a when pattern and the recursive flag set, then it will recurse through the tree, running the transformation on only those children that match the when pattern.
+
+=back
+
+=head2 Public methods
+
+=over 4
+
+=item new(transformation, name :named, recursive :named, when :named, depends-on :named)
+
+Creates a new pass with the supplied transformation, name, recursive flag, when pattern, and dependencies. If no name is supplied, a unique name is generated. The depends-on parameter may be either a string or an array of strings.
+
+=item clone()
+
+Creates a new pass with the same attributes. The dependencies array is also copied so that adding dependencies to the new pass does not modify the original pass.
+
+=item run(tree)
+
+Runs the pass on the supplied tree.
+
+=back
+
+=head2 Overridden methods
+
+These methods are intended to be overridden in subclasses in order to augment Tree::Optimizer::Pass's behavior.
+
+=over 4
+
+=item transformer-class()
+
+Returns the Tree::Optimizer::Transformer::Single subclass that should be used to perform the transformation for when/recursive passes.
+
+=back
+
+=head2 Internal methods
+
+These methods are used internally to implement the public methods and should not generally be used by users of Tree::Optimizer::Pass.
+
+=over 4
+
+=item BUILD(transformation :named, name :named, recursive :named, when :named, depends-on :named)
+
+Initializes the attributes of the pass to the supplied values.
+
+=item generate-transformer()
+
+Creates the transformer to be used when running a recursive pass.
+
+=back
+
+=cut

0 comments on commit 198314c

Please sign in to comment.