Changeset 4206 for trunk/manuals/userman/running.html

Timestamp:

04/12/08 14:14:06 (8 months ago)

Author:

pmoura

Message:

Added documentation on using compilation hooks and the term expansion mechanism for conditional compilation of debugging goals.

Files:

• trunk/manuals/userman/running.html (modified) (2 diffs)

trunk/manuals/userman/running.html

@@ -182 +182 @@
     <dl>
         <dt><code>hook(Object)</code></dt>
-            <dd>Allows the definition of a compiler hooks that are called for each term read form a source file and for each compiled goal. This option specifies both an object (which can be the pseudo-object <code>user</code>) implementing the <code>expanding</code> built-in protocol. The object is expected to define clauses for the <a title="Consult reference manual" href="../refman/methods/term_expansion2.html"><code>term_expansion/2</code></a> and <a title="Consult reference manual" href="../refman/methods/goal_expansion2.html"><code>goal_expansion/2</code></a> predicates. In the case of the <code>term_expansion/2</code> predicate, the first argument is the term read form the source file while the second argument returns a list of terms corresponding to the expansion of the first argument. In the case of the <code>goal_expansion/2</code> predicate, the second argument should be a goal resulting from the expansion of the goal in the first argument. The predicate <code>goal_expansion/2</code> is called on the expanded goals so care must be taken to avoid compilation loops.</dd>
+            <dd>Allows the definition of a compiler hooks that are called for each term read form a source file and for each compiled goal. This option specifies an object (which can be the pseudo-object <code>user</code>) implementing the <code>expanding</code> built-in protocol. The object is expected to define clauses for the <a title="Consult reference manual" href="../refman/methods/term_expansion2.html"><code>term_expansion/2</code></a> and <a title="Consult reference manual" href="../refman/methods/goal_expansion2.html"><code>goal_expansion/2</code></a> predicates. In the case of the <code>term_expansion/2</code> predicate, the first argument is the term read form the source file while the second argument returns a list of terms corresponding to the expansion of the first argument. In the case of the <code>goal_expansion/2</code> predicate, the second argument should be a goal resulting from the expansion of the goal in the first argument. The predicate <code>goal_expansion/2</code> is called on the expanded goals so care must be taken to avoid compilation loops.</dd>
     </dl>
     <dl>
@@ -490 +490 @@
 </p>
 
+<h3 id="running_hooks">Using compilation hooks and term expansion for debugging</h3>
+
+<p>
+It is possible to use compilation hooks and the term expansion mechanism for conditional compilation of debugging goals. Assume that we chose the predicate <code>debug/1</code> to represent debug goals. For example:
+</p>
+<pre>append([], List, List) :-
+    debug((write('Base case: '), writeq(append([], List, List)), nl)).
+append([Head| Tail], List, [Head| Tail2]) :-
+    debug((write('Recursive case: '), writeq(append(Tail, List, Tail2)), nl)),
+    append(Tail, List, Tail2).</pre>
+<p>
+When debugging, we want to call the argument of the predicate <code>debug/1</code>. This can be easily accomplished by defining a hook object containing the following definition for <code>goal_expansion/2</code>:
+</p>
+<pre>goal_expansion(debug(Goal), Goal).</pre>
+<p>
+When not debugging, we can use a second hook object to discard the <code>debug/1</code> calls by defining the predicate <code>goal_expansion/2</code> as follows:
+</p>
+<pre>goal_expansion(debug(_), true).</pre>
+<p>
+The Logtalk compiler automatically removes any redundant calls to the built-in predicate <code>true/0</code> when compiling object predicates.
+</p>
+
 <div class="footer">
     <div class="copyright">
         <span>Copyright &copy; <a href="mailto:pmoura@logtalk.org">Paulo Moura</a> &mdash; <a href="http://logtalk.org">Logtalk.org</a></span><br/> 
-        <span>Last updated on: December 3, 2007</span>
+        <span>Last updated on: April 9, 2008</span>
     </div>
     <div class="navbottom">