<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.06-7 of 2001-11-14">
<TITLE>
Debugging predicates
</TITLE>
</HEAD>
<BODY TEXT=black BGCOLOR=white>
<A HREF="manual011.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="manual009.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
<A HREF="manual013.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#66dbff"><DIV ALIGN=center><TABLE>
<TR><TD><FONT SIZE=4><B><A NAME="htoc22">4.3</A></B></FONT></TD>
<TD WIDTH="100%" ALIGN=center><FONT SIZE=4><B>Debugging predicates</B></FONT></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE><UL>
<LI><A HREF="manual012.html#toc12"> Running and stopping the debugger</A>
<LI><A HREF="manual012.html#toc13"> Leashing ports</A>
<LI><A HREF="manual012.html#toc14"> Spy-points</A>
</UL>
<BR>
<A NAME="toc12"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98e7ff"><DIV ALIGN=center><TABLE>
<TR><TD><B><A NAME="htoc23">4.3.1</A></B></TD>
<TD WIDTH="100%" ALIGN=center><B>Running and stopping the debugger</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
<A NAME="Running-and-stopping-the-debugger"></A>
<BR>
<TT>trace/0</TT> activates the debugger. The next invocation of a predicate
will be traced.<BR>
<BR>
<TT>debug/0</TT> activates the debugger. The next invocation of a predicate
on which a spy-point has been set will be traced.<BR>
<BR>
It is important to understand that the information associated to the control
flow is only available when the debugger is on. For efficiency reasons, when
the debugger is off the information concerning the control flow (i.e. the
boxes) is not retained. So, if the debugger is activated in the middle of a
computation (by a call to <TT>debug/0</TT> or <TT>trace/0</TT> in the
program or after the interrupt key sequence (<TT>Ctl-C</TT>) by choosing
<TT>trace</TT> or <TT>debug</TT>), information prior to this point is not
available.<BR>
<BR>
<TT>debugging/0</TT>: prints onto the terminal information about the current
debugging state (whether the debugger is switched on, what are the leashed
ports, spy-points defined,...).<BR>
<BR>
<TT>notrace/0</TT> or <TT>nodebug/0</TT> switches the debugger off.<BR>
<BR>
<TT>wam_debug/0</TT> invokes the sub-debugger devoted to the WAM data
structures (section <A HREF="manual015.html#The-WAM-debugger">4.6</A>). It can be also invoked using the
<TT>W</TT> debugger command (section <A HREF="manual014.html#Debugger-commands">4.5</A>).<BR>
<BR>
<A NAME="toc13"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98e7ff"><DIV ALIGN=center><TABLE>
<TR><TD><B><A NAME="htoc24">4.3.2</A></B></TD>
<TD WIDTH="100%" ALIGN=center><B>Leashing ports</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
<A NAME="Leashing-ports"></A>
<BR>
<TT>leash(Ports)</TT> requests the debugger to prompt the user, as
he creeps through the program, for every port defined in the <TT>Ports</TT>
list. Each element of <TT>Ports</TT> is an atom in <TT>call</TT>,
<TT>exit</TT>, <TT>redo</TT>, <TT>fail</TT>, <TT>exception</TT>.
<TT>Ports</TT> can also be an atom defining a shorthand:
<UL><LI><TT>full</TT>: equivalent to <TT>[call, exit, redo, fail,
exception]</TT><BR>
<BR>
<LI><TT>half</TT>: equivalent to <TT>[call, redo]</TT><BR>
<BR>
<LI><TT>loose</TT>: equivalent to <TT>[call]</TT><BR>
<BR>
<LI><TT>none</TT>: equivalent to <TT>[]</TT><BR>
<BR>
<LI><TT>tight</TT>: equivalent to <TT>[call, redo, fail,
exception]</TT></UL>
When an unleashed port is encountered the debugger continues to show the
associated goal but does not stop the execution to prompt the user. <BR>
<BR>
<A NAME="toc14"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98e7ff"><DIV ALIGN=center><TABLE>
<TR><TD><B><A NAME="htoc25">4.3.3</A></B></TD>
<TD WIDTH="100%" ALIGN=center><B>Spy-points</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
<A NAME="Spy-points"></A>
<BR>
When dealing with big sources it is not very practical to creep through the
entire program. It is preferable to define a set of spy-points on
interesting predicates to be prompted when the debugger reaches one of these
predicates. Spy-points can be added either using <TT>spy/1</TT> (or
<TT>spypoint_condition/3</TT>) or dynamically when prompted by the debugger
using the <TT>+</TT> (or <TT>*</TT>) debugger command
(section <A HREF="manual014.html#Debugger-commands">4.5</A>). The current mode of leashing does not
affect spy-points in the sense that user interaction is requested on
every port.<BR>
<BR>
<TT>spy(PredSpec)</TT> sets a spy-point on all the predicates given by
<TT>PredSpec</TT>. <TT>PredSpec</TT> defines one or several predicates and
has one of the following forms:
<UL><LI><TT>[PredSpec1, PredSpec2,...]</TT>: set a spy-point for each
element of the list.<BR>
<BR>
<LI><TT>Name</TT>: set a spy-point for any predicate whose name is
<TT>Name</TT> (whatever the arity).<BR>
<BR>
<LI><TT>Name/Arity</TT>: set a spy-point for the predicate whose name is
<TT>Name</TT> and arity is <TT>Arity</TT>.<BR>
<BR>
<LI><TT>Name/A1-A2</TT>: set a spy-point for the each predicate whose name
is <TT>Name</TT> and arity is between <TT>A1</TT> and <TT>A2</TT>.</UL>
It is not possible to set a spy-point on an undefined predicate. <BR>
<BR>
The following predicate is used to remove one or several spy-points:<BR>
<BR>
<TT>nospy(PredSpec)</TT> removes the spy-points from the specified
predicates.<BR>
<BR>
<TT>nospyall/0</TT> removes all spy-points:<BR>
<BR>
It is also possible to define conditional spy-points. <BR>
<BR>
<TT>spypoint_condition(Goal, Port, Test)</TT> sets a
conditional spy-point on the predicate for <TT>Goal</TT>. When the debugger
reaches a conditional spy-point it only shows the associated goal if the
following conditions are verified:
<UL><LI>the actual goal unifies with <TT>Goal</TT>.<BR>
<BR>
<LI>the actual port unifies with <TT>Port</TT>.<BR>
<BR>
<LI>the Prolog goal <TT>Test</TT> succeeds.</UL>
<HR SIZE=2>
Copyright (C) 1999-2002 Daniel Diaz
<BR>
<BR>
Verbatim copying and distribution of this entire article is permitted in any
medium, provided this notice is preserved. <BR>
<BR>
<A HREF="index.html#copyright">More about the copyright</A>
<HR>
<A HREF="manual011.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="manual009.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
<A HREF="manual013.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
