[phc-internals] [phc commit] r1749 - trunk/doc/manual
codesite-noreply at google.com
codesite-noreply at google.com
Sun Oct 5 22:19:43 IST 2008
Author: paul.biggar
Date: Sun Oct 5 14:19:14 2008
New Revision: 1749
Modified:
trunk/doc/manual/treetutorial4.sgml
trunk/doc/manual/treetutorial5.sgml
Log:
Convert next two tutorials. Not much to be changed in them.
Modified: trunk/doc/manual/treetutorial4.sgml
==============================================================================
--- trunk/doc/manual/treetutorial4.sgml (original)
+++ trunk/doc/manual/treetutorial4.sgml Sun Oct 5 14:19:14 2008
@@ -4,20 +4,24 @@
<section>
<title></title>
-<para> This tutorial explains an advanced feature of pattern matching, and
-shows an important technique in writing tree transforms: the use of state.
-Suppose we are continuing the refactoring tool that we began in <xref
-linkend="treetutorial2">, and suppose that we have replaced all calls to
-database specific functions by calls to the generic DBX functions. To
finish
-the refactoring, we want to rename any function <code>foo</code> in the
script
-to <code>foo_DB</code>, if it makes use of the database — this
clearly
-sets functions that use the database apart, which may make the structure
of the
-script clearer. </para>
-
-<para> So, we want to write a transform that renames all functions
-<code>foo</code> to <code>foo_DB</code>, if there is one or more call
within
-that function to any <code>dbx_</code><emphasis>something</emphasis>
function.
-Here is a simple example: </para>
+<para>
+ This tutorial explains an advanced feature of pattern matching, and shows
an
+ important technique in writing tree transforms: the use of state. Suppose
+ we are continuing the refactoring tool that we began in <xref
+ linkend="treetutorial2">, and suppose that we have replaced all calls to
+ database specific functions by calls to the generic DBX functions. To
finish
+ the refactoring, we want to rename any function <code>foo</code> in the
+ script to <code>foo_DB</code>, if it makes use of the database —
this
+ clearly sets functions that use the database apart, which may make the
+ structure of the script clearer.
+</para>
+
+<para>
+ So, we want to write a transform that renames all functions
<code>foo</code>
+ to <code>foo_DB</code>, if there is one or more call within that function
to
+ any <code>dbx_</code><emphasis>something</emphasis> function. Here is a
+ simple example:
+</para>
<programlisting>
<?<reserved>php</reserved>
@@ -34,7 +38,9 @@
?>
</programlisting>
-<para> After the transform, we should get </para>
+<para>
+ After the transform, we should get
+</para>
<programlisting>
<?<reserved>php</reserved>
@@ -56,25 +62,29 @@
<title>The Implementation</title>
-<para> Since we have to modify method (function) names, the nodes we are
-interested in are the nodes of type <code>Method</code>. However, how do we
-know when to modify a particular method? Should we search the method body
for
-function calls to <code>dbx_</code><emphasis>xxx</emphasis>? As we saw in
<xref
-linkend="treetutorial1">, manual searching through the tree is cumbersome;
-there must be a better solution. </para>
-
-<para> The solution is in fact very easy. At the start of each method, we
set a
-variable <code>uses_dbx</code> to <code>false</code>. When we process the
-method, we set <code>uses_dbx</code> to <code>true</code> when we find a
-function call to a DBX function. Then at the end of the method, we check
-<code>uses_dbx</code>; if it was set to <code>true</code>, we modify the
name
-of the method. This tactic is implement by the following transform
(available
-as <filename>plugins/tutorials/InsertDB.la</filename> in the &phc;
-distribution). Note the use of <code>pre_method</code> and
-<code>post_method</code> to initialise and check <code>use_dbx</code>,
-respectively. (Because we don't need to modify the structure of the tree in
-this transform, we use the simpler <code>Tree_visitor</code> API instead
of the
-<code>Tree_transform</code> API.) </para>
+<para>
+ Since we have to modify method (function) names, the nodes we are
interested
+ in are the nodes of type <code>Method</code>. However, how do we know when
+ to modify a particular method? Should we search the method body for
function
+ calls to <code>dbx_</code><emphasis>xxx</emphasis>? As we saw in <xref
+ linkend="treetutorial1">, manual searching through the tree is cumbersome;
+ there must be a better solution.
+</para>
+
+<para>
+ The solution is in fact very easy. At the start of each method, we set a
+ variable <code>uses_dbx</code> to <code>false</code>. When we process the
+ method, we set <code>uses_dbx</code> to <code>true</code> when we find a
+ function call to a DBX function. Then at the end of the method, we check
+ <code>uses_dbx</code>; if it was set to <code>true</code>, we modify the
+ name of the method. This tactic is implement by the following transform
+ (available as <filename>plugins/tutorials/InsertDB.la</filename> in the
+ &phc; distribution). Note the use of <code>pre_method</code> and
+ <code>post_method</code> to initialise and check <code>use_dbx</code>,
+ respectively. (Because we don't need to modify the structure of the tree
in
+ this transform, we use the simpler <code>AST_visitor</code> API instead of
+ the <code>AST_transform</code> API.)
+</para>
<programlisting>
<reserved>class</reserved> InsertDB : <reserved>public</reserved> Visitor
@@ -108,39 +118,47 @@
};
</programlisting>
-<para> In <xref linkend="treetutorial2">, we simply wanted to check for a
-particular function name, and we used <code>match</code> to do this:
</para>
+<para>
+ In <xref linkend="treetutorial2">, we simply wanted to check for a
+ particular function name, and we used <code>match</code> to do this:
+</para>
<programlisting>
<reserved>if</reserved>(in->match(<reserved>new</reserved>
METHOD_NAME("mysql_connect")))
</programlisting>
-<para>Here, we need to check for method names that start with
-<code>dbx_</code>. We use the STL method <code>find</code> to do this, but
we
-cannot call this directly on <code>in->method_name</code> because
-<code>in->method_name</code> has type <code>Method_name</code> (could
-either be a <code>METHOD_NAME</code> or a <code>Reflection</code>
-node). However, calling <code>match</code> on a pattern has the side
effect of
-setting the <code>value</code> to point to the node that was matched by the
-wildcard. So, if the match succeeds, we know that the name of the method
must
-have been a <code>METHOD_NAME</code>, and we can access this name by
-accessing <code>pattern->value</code>
-(<code>pattern->value->value</code> is the value field of the
-<code>METHOD_NAME</code> itself, i.e., the actual string that stores the
-name of the method.) </para>
-
-<para> (Of course, this transform is not complete; renaming methods is not
-enough, we must also rename the corresponding method invocations. This is
left
-as an exercise for the reader.) </para>
+<para>
+ Here, we need to check for method names that start with <code>dbx_</code>.
+ We use the STL method <code>find</code> to do this, but we cannot call
this
+ directly on <code>in->method_name</code> because
+ <code>in->method_name</code> has type <code>Method_name</code> (could
+ either be a <code>METHOD_NAME</code> or a <code>Reflection</code> node).
+ However, calling <code>match</code> on a pattern has the side effect of
+ setting the <code>value</code> to point to the node that was matched by
the
+ wildcard. So, if the match succeeds, we know that the name of the method
+ must have been a <code>METHOD_NAME</code>, and we can access this name by
+ accessing <code>pattern->value</code>
+ (<code>pattern->value->value</code> is the value field of the
+ <code>METHOD_NAME</code> itself, i.e., the actual string that stores the
+ name of the method.)
+</para>
+
+<para>
+ (Of course, this transform is not complete; renaming methods is not
enough,
+ we must also rename the corresponding method invocations. This is left as
an
+ exercise for the reader.)
+</para>
</section>
<section>
<title> What's Next? </title>
-<para> <xref linkend="treetutorial5"> explains how to change the order in
which
-the children of a node are visited, avoid visiting some children, or how to
-execute a piece of code in between visiting two children.</para>
+<para>
+ <xref linkend="treetutorial5"> explains how to change the order in which
the
+ children of a node are visited, avoid visiting some children, or how to
+ execute a piece of code in between visiting two children.
+</para>
</section>
Modified: trunk/doc/manual/treetutorial5.sgml
==============================================================================
--- trunk/doc/manual/treetutorial5.sgml (original)
+++ trunk/doc/manual/treetutorial5.sgml Sun Oct 5 14:19:14 2008
@@ -4,15 +4,18 @@
<section>
<title></title>
-<para> As explained in the previous tutorials (in particular, <xref
-linkend="treetutorial1" endterm="treetutorial1.title">), when a
-<code>Tree_visitor</code> traverses a tree, it first calls
<code>pre_xxx</code>
-for a node of type <emphasis>xxx</emphasis>, it then visits all the
children of
-the node, and finally it calls <code>post_xxx</code> on the node. For many
-transforms, this is sufficient — but not for all. Consider the
following
-transform. Suppose we want to add comments to the
<emphasis>true</emphasis>
-and <emphasis>false</emphasis> branches of an
-<emphasis>if</emphasis>-statement, so that the following example </para>
+<para>
+ As explained in the previous tutorials (in particular, <xref
+ linkend="treetutorial1" endterm="treetutorial1.title">), when a
+ <code>AST_visitor</code> traverses a tree, it first calls
+ <code>pre_xxx</code> for a node of type <emphasis>xxx</emphasis>, it then
+ visits all the children of the node, and finally it calls
+ <code>post_xxx</code> on the node. For many transforms, this is
sufficient
+ — but not for all. Consider the following transform. Suppose we want
+ to add comments to the <emphasis>true</emphasis> and
+ <emphasis>false</emphasis> branches of an
<emphasis>if</emphasis>-statement,
+ so that the following example
+</para>
<programlisting>
<?<reserved>php</reserved>
@@ -44,33 +47,39 @@
?>
</programlisting>
-<para> This appears to be a simple transform. One way to do implement it
would
-be to introduce a flag <code>comment</code> that is set to
<code>true</code>
-when we encounter an <code>If</code> (i.e., in <code>pre_if</code>). Then
-in <code>post_statement</code> we could check for this flag, and if it is
set,
-we could add the required comment to the statement, and reset the flag to
-<code>false</code>. </para>
-
-<para> However, this will only add a comment to the first statement in the
-<emphasis>true</emphasis> branch (try!). To add a comment to the first
-statement in the <emphasis>false</emphasis> branch too, we should set the
flag
-to <code>true</code> in between visiting the children of the
-<emphasis>true</emphasis> branch and visiting the children of the
-<emphasis>false</emphasis> branch. To be able to do this, we need to modify
-<code>children_if</code>, as explained in the next section. </para>
+<para>
+ This appears to be a simple transform. One way to do implement it would be
+ to introduce a flag <code>comment</code> that is set to <code>true</code>
+ when we encounter an <code>If</code> (i.e., in <code>pre_if</code>). Then
in
+ <code>post_statement</code> we could check for this flag, and if it is
set,
+ we could add the required comment to the statement, and reset the flag to
+ <code>false</code>.
+</para>
+
+<para>
+ However, this will only add a comment to the first statement in the
+ <emphasis>true</emphasis> branch (try it!). To add a comment to the first
+ statement in the <emphasis>false</emphasis> branch too, we should set the
+ flag to <code>true</code> in between visiting the children of the
+ <emphasis>true</emphasis> branch and visiting the children of the
+ <emphasis>false</emphasis> branch. To be able to do this, we need to
modify
+ <code>children_if</code>, as explained in the next section.
+</para>
</section>
<section>
<title> The Solution </title>
-<para> For every AST node type <emphasis>xxx</emphasis>, the TreeTransform
API
-defines a method called <code>children_xxx</code>. This method is
responsible
-for visiting all the children of the node. The default implementation for
-<code>If</code> is: </para>
+<para>
+ For every AST node type <emphasis>xxx</emphasis>, the AST Transform API
+ defines a method called <code>children_xxx</code>. This method is
+ responsible for visiting all the children of the node. The default
+ implementation for <code>If</code> is:
+</para>
<programlisting>
-<reserved>void</reserved> Visitor::children_if(If* in)
+<reserved>void </reserved>Visitor::children_if(If* in)
{
visit_expr(in->expr);
visit_statement_list(in->iftrue);
@@ -78,11 +87,12 @@
}
</programlisting>
-<para> (you can find this definition in
-<filename>Tree_visitor.cpp</filename>). If you want to change the
-order in which the children of a node are visited, entirely avoid visiting
some
-children, or simply execute a piece of code in between two children, this
is
-the method you will need to modify. </para>
+<para>
+ (you can find this definition in <filename>AST_visitor.cpp</filename>). If
+ you want to change the order in which the children of a node are visited,
+ entirely avoid visiting some children, or simply execute a piece of code
in
+ between two children, this is the method you will need to modify.
+</para>
<para> Here is the transform that does what we need (available as
<filename>plugins/tutorials/Comment_ifs.la</filename>): </para>
More information about the phc-internals
mailing list