[svn:parrot] r47515 - in branches/gsoc_past_optimization/runtime/parrot/library/PAST: . Transformer Walker
tcurtis at svn.parrot.org
tcurtis at svn.parrot.org
Wed Jun 9 21:39:34 UTC 2010
Author: tcurtis
Date: Wed Jun 9 21:39:33 2010
New Revision: 47515
URL: https://trac.parrot.org/parrot/changeset/47515
Log:
Add and update POD docs.
Modified:
branches/gsoc_past_optimization/runtime/parrot/library/PAST/Transformer.pir
branches/gsoc_past_optimization/runtime/parrot/library/PAST/Transformer/Dynamic.pir
branches/gsoc_past_optimization/runtime/parrot/library/PAST/Walker.pir
branches/gsoc_past_optimization/runtime/parrot/library/PAST/Walker/Dynamic.pir
Modified: branches/gsoc_past_optimization/runtime/parrot/library/PAST/Transformer.pir
==============================================================================
--- branches/gsoc_past_optimization/runtime/parrot/library/PAST/Transformer.pir Wed Jun 9 19:57:52 2010 (r47514)
+++ branches/gsoc_past_optimization/runtime/parrot/library/PAST/Transformer.pir Wed Jun 9 21:39:33 2010 (r47515)
@@ -1,6 +1,16 @@
# Copyright (C) 2010, Parrot Foundation.
# $Id$
+=head1 NAME
+
+PAST::Transformer - A tool for traversing and modifying PAST::Nodes.
+
+=head1 DESCRIPTION
+
+A tool for traversing and modifying Parrot Abstract Syntax Trees.
+
+=cut
+
.sub 'onload' :anon :init :load
load_bytecode 'PAST/Walker.pbc'
load_bytecode 'P6object.pbc'
@@ -12,6 +22,22 @@
.namespace ['PAST'; 'Walker']
+=head1 PAST::Transformer
+
+=head2 Multi-methods
+
+As a PAST::Walker subclass, PAST::Transformer's interface consists of two multi-methods in the PAST::Walker namespace, 'walk' and 'walkChildren'. It also declares the helper function PAST::Walker::replaceChildren. PAST::Transformer subclasses, unlike PAST::Walker subclasses, should return the desired node to replace the original node. If the original node should be unchanged, return it. If the node should be removed from its parent, return null.
+
+=over 4
+
+=item walk(walker, node)
+
+By default, 'walk' calls 'walkChildren', calls 'replaceChildren' with the node and the result, and returns the node with its children transformed.
+
+Subclasses should override this for specific PAST::Node subclasses in order to transform the node. Subclasses that wish to transform the node's children must remember to call 'walkChildren' and 'replaceChildren' in their specialization of the multi-method.
+
+=cut
+
.sub 'walk' :multi(['PAST';'Transformer'], ['PAST';'Node'])
.param pmc walker
.param pmc node
@@ -22,6 +48,14 @@
.return (result)
.end
+=item walkChildren(walker, node)
+
+Iterates through the children of node, calling 'walk' with the walker and each child node. This should not generally be overridden.
+
+It returns an array of the results from the children. This should be supplied to 'replaceChildren'.
+
+=cut
+
.sub 'walkChildren' :multi(['PAST';'Transformer'], ['PAST';'Node'])
.param pmc walker
.param pmc node
@@ -41,6 +75,18 @@
.return (result)
.end
+=back
+
+=head2 Helper functions
+
+=over 4
+
+=item replaceChildren(node, newChildren)
+
+Replaces the children of node with the nodes in newChildren. This should be called with the result node and the result of 'walkChildren' in speccializations of 'walk' that wish to transform the subtrees of a node.
+
+=cut
+
.sub 'replaceChildren'
.param pmc node
.param pmc newChildren
@@ -67,6 +113,10 @@
.return ()
.end
+=back
+
+=cut
+
# Local Variables:
# mode: pir
# fill-column: 100
Modified: branches/gsoc_past_optimization/runtime/parrot/library/PAST/Transformer/Dynamic.pir
==============================================================================
--- branches/gsoc_past_optimization/runtime/parrot/library/PAST/Transformer/Dynamic.pir Wed Jun 9 19:57:52 2010 (r47514)
+++ branches/gsoc_past_optimization/runtime/parrot/library/PAST/Transformer/Dynamic.pir Wed Jun 9 21:39:33 2010 (r47515)
@@ -1,6 +1,16 @@
# Copyright (C) 2010, Parrot Foundation.
# $Id$
+=head1 NAME
+
+PAST::Transformer::Dynamic - A PAST::Transformer subclass that doesn't require creating a new subclass to change its behavior.
+
+=head1 DESCRIPTION
+
+PAST::Transformer's behavior can only be customized by subclassing. This subclass determines its behavior based on Subs stored in its attributes, allowing modification of its behavior without creating a new class, including at runtime.
+
+=cut
+
.sub 'onload' :anon :init :load
load_bytecode 'PAST/Transformer.pbc'
load_bytecode 'PAST/Walker/Dynamic.pbc'
@@ -14,6 +24,14 @@
p6meta.'add_parent'($P0, trans)
.end
+=head1 PAST::Transformer::Dynamic
+
+It has the same attributes as PAST::Walker::Dynamic.
+
+They should behave just like specializations of 'walk' for PAST::Transformer subclasses, taking a walker and a PAST::Node and returning the replacement node or null to delete it.
+
+=cut
+
.namespace ['PAST'; 'Walker']
.sub 'walk' :multi(['PAST'; 'Transformer'; 'Dynamic'], ['PAST'; 'Block'])
@@ -76,6 +94,10 @@
.tailcall $P0(walker, node)
.end
+=back
+
+=cut
+
# Local Variables:
# mode: pir
# fill-column: 100
Modified: branches/gsoc_past_optimization/runtime/parrot/library/PAST/Walker.pir
==============================================================================
--- branches/gsoc_past_optimization/runtime/parrot/library/PAST/Walker.pir Wed Jun 9 19:57:52 2010 (r47514)
+++ branches/gsoc_past_optimization/runtime/parrot/library/PAST/Walker.pir Wed Jun 9 21:39:33 2010 (r47515)
@@ -7,7 +7,7 @@
=head1 DESCRIPTION
-A tool for traversing and modifying Parrot Abstract Syntax Trees.
+A tool for traversing Parrot Abstract Syntax Trees.
=cut
Modified: branches/gsoc_past_optimization/runtime/parrot/library/PAST/Walker/Dynamic.pir
==============================================================================
--- branches/gsoc_past_optimization/runtime/parrot/library/PAST/Walker/Dynamic.pir Wed Jun 9 19:57:52 2010 (r47514)
+++ branches/gsoc_past_optimization/runtime/parrot/library/PAST/Walker/Dynamic.pir Wed Jun 9 21:39:33 2010 (r47515)
@@ -1,6 +1,16 @@
# Copyright (C) 2010, Parrot Foundation.
# $Id$
+=head1 NAME
+
+PAST::Walker::Dynamic - A PAST::Walker subclass that doesn't require creating a new subclass to change its behavior.
+
+=head1 DESCRIPTION
+
+PAST::Walker's behavior can only be customized by subclassing. This subclass determines its behavior based on Subs stored in its attributes, allowing modification of its behavior without creating a new class, including at runtime.
+
+=cut
+
.sub 'onload' :anon :init :load
load_bytecode 'PAST/Walker.pbc'
load_bytecode 'P6object.pbc'
@@ -15,6 +25,24 @@
.namespace ['PAST'; 'Walker'; 'Dynamic']
+=head1 PAST::Walker::Dynamic
+
+=head2 Attribute accessors
+
+Each attribute should hold a sub that takes a walker and a PAST::Node.
+
+It will be called when the appropriate node type is traversed.
+
+As with PAST::Walker, the sub must explicitly call 'walkChildren' in order to traverse the children.
+
+=over 4
+
+=item block([sub])
+
+Gets/sets the sub to be called when traversing a PAST::Block node.
+
+=cut
+
.sub 'block' :method
.param pmc value :optional
.param int has_value :opt_flag
@@ -25,6 +53,12 @@
setattribute self, 'block', value
.end
+=item op([sub])
+
+Gets/sets the sub to be called when traversing a PAST::Op node.
+
+=cut
+
.sub 'op' :method
.param pmc value :optional
.param int has_value :opt_flag
@@ -35,6 +69,12 @@
setattribute self, 'op', value
.end
+=item stmts([sub])
+
+Gets/sets the sub to be called when traversing a PAST::Stmts node.
+
+=cut
+
.sub 'stmts' :method
.param pmc value :optional
.param int has_value :opt_flag
@@ -45,6 +85,12 @@
setattribute self, 'stmts', value
.end
+=item val([sub])
+
+Gets/sets the sub to be called when traversing a PAST::Val node.
+
+=cut
+
.sub 'val' :method
.param pmc value :optional
.param int has_value :opt_flag
@@ -55,6 +101,12 @@
setattribute self, 'val', value
.end
+=item var([sub])
+
+Gets/sets the sub to be called when traversing a PAST::Var node.
+
+=cut
+
.sub 'var' :method
.param pmc value :optional
.param int has_value :opt_flag
@@ -117,6 +169,10 @@
.tailcall $P0(walker, node)
.end
+=back
+
+=cut
+
# Local Variables:
# mode: pir
# fill-column: 100
More information about the parrot-commits
mailing list