1% BEGIN LICENSE BLOCK 2% Version: CMPL 1.1 3% 4% The contents of this file are subject to the Cisco-style Mozilla Public 5% License Version 1.1 (the "License"); you may not use this file except 6% in compliance with the License. You may obtain a copy of the License 7% at www.eclipse-clp.org/license. 8% 9% Software distributed under the License is distributed on an "AS IS" 10% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See 11% the License for the specific language governing rights and limitations 12% under the License. 13% 14% The Original Code is The ECLiPSe Constraint Logic Programming System. 15% The Initial Developer of the Original Code is Cisco Systems, Inc. 16% Portions created by the Initial Developer are 17% Copyright (C) 2006 Cisco Systems, Inc. All Rights Reserved. 18% 19% Contributor(s): 20% 21% END LICENSE BLOCK 22% 23% $Id: umsdebug.tex,v 1.10 2012/02/06 13:14:41 jschimpf Exp $ 24% 25 26\chapter{Debugging} 27%HEVEA\cutdef[1]{section} 28\label{chapdebug} 29 30\section{The Box Model} 31\label{boxmodel} 32 33The {\eclipse} debugger is based on a port model which is an extension 34of the classical Box Model commonly used in Prolog debugging. 35 36A procedure invocation (or goal) is represented by a box with entry 37and exit ports. Each time a procedure is invoked, a box is created 38and given a unique invocation number. The invocations of subgoals of 39this procedure are seen as boxes inside this procedure box. 40 41\begin{figure} 42% The picture has been made with xfig and exported in 43% encapsulated postscript mode 44%\psfig{figure=boxmodel.ps} 45\begin{center} 46\includegraphics{boxmodel.eps} 47\end{center} 48\caption{The box model} 49\end{figure} 50 51Tracing the flow of the execution consists in tracing the crossing of 52the execution flow through any of the port of the box. 53 54The five basic ports of the box model of {\eclipse} are the CALL, EXIT, 55REDO, FAIL and NEXT ports, the suspension facilities are traced through 56the DELAY and RESUME ports, and the exceptional exit is indicated by LEAVE. 57 58\begin{description} 59 60\item[CALL:] When a procedure is invoked, the flow of the execution 61enters the procedure box by its CALL port and enters the first clause 62box which could (since not all clauses are tried, some of them being 63sure to fail, i.e., indexing is shown) unify with the goal. 64It may happen that a procedure is 65called with arguments that make it sure to fail (because of 66indexing). In such cases, the flow does not enter any clause box. 67 68For each CALL port a new procedure box is created and is given: 69\begin{itemize} 70\item an \emph{invocation number} that is one higher than that given for 71the most recent CALL port. This allows to uniquely identify a 72procedure invocation and all its corresponding ports. 73 74\item a \emph{level} that is one higher than that of its parent goal. 75\end{itemize} 76 77The displayed variable instantiations are the ones at call time, 78i.e., before the head unification of any clause. 79 80\item[EXIT:] When a clause of a predicate succeeds (i.e., unification 81succeeded and all procedures called by the clause succeeded), 82the flow gets out of the box by the EXIT port of both boxes (only 83the EXIT port of the \emph{procedure box} is traced). 84 85When a procedure exits non-deterministically (and there are still 86other clauses to try on that procedure or one of its children goals 87has alternatives which could be resatisfied), the EXIT port is traced 88with an asterisk (*EXIT). When the last possibly matching clause of a 89procedure is exited, the exit is traced without asterisk. This means 90that this procedure box will never be retried as there is no other 91untried alternative. 92 93The instantiations shown in the EXIT port are the ones at exit time, 94they result from the (successful) execution of the procedure. 95 96\item[FAIL:] When a clause of a procedure fails (because head unification 97failed or because a sub-goal failed), the flow of the execution exits 98the clause box and leaves the procedure box via the FAIL port. 99Note that the debugger cannot display any argument information at 100FAIL ports (an ellipsis \verb:...: is displayed instead for each argument). 101 102\item[NEXT:] If a clause fails and there is another possibly 103matching clause to try, then that one is tried for unification. 104The flow of the execution from the failure of one clause to the 105head unification of a following clause is traced as a NEXT port. 106The displayed variable instantiations are the same as those of the 107corresponding CALL or REDO port. 108 109\item[ELSE:] 110This is similar to the NEXT port, but indicates that the next branch of a 111\biptxtref{disjunction (;/2)}{;/2}{../bips/kernel/control/O-2.html} 112it tried after the previous branch failed. 113The predicate that gets displayed with the port is the predicate 114which contains the disjunction (the immediate ancestor). 115 116\item[REDO:] When a procedure box is exited trough an *EXIT port, 117the box can be retried later to get a new solution. This will happen when a 118later goal fails. The backtracking will cause failing of all 119procedures that do not have any alternative, then the execution flow 120will enter a 121procedure box that an contains alternative through a REDO port. 122 123Two situations may occur: either the last tried clause has called a 124procedure that has left a choice point (it has exited through an 125*EXIT port). In that case the nested procedure box is re-entered 126though another REDO-port. 127 128Otherwise, if the last clause tried does not contain any 129nondeterministically exited boxes, but there are other untried clauses 130in the procedure box, the next possibly matching clause will be tried. 131 132The last REDO port in such a sequence is the one which contains the 133actual alternative that is tried. The variable instantiations for all 134REDO ports in such a sequence are the ones corresponding to the call 135time of the last one. 136 137%\item[UNIFY:] When a clause head successfully unifies with 138%a called goal, a UNIFY port is traced to show the result of the 139%unification. However, this port is not traced for unit clause since it 140%is identical to the EXIT port. 141% 142%Please note that this port is not shown in the default settings but it 143%can be switched on with the appropriate 144%\bipref{set_leash/2}{../bips/kernel/debug/set_leash-2.html} call. 145 146\item[LEAVE:] 147This port allows to trace the execution of exceptions. Exceptions 148are either raised implicitly by built-in predicates (in which case the 149built-in itself exits via the LEAVE port), or explicitly through a call to 150\bipref{throw/1}{../bips/kernel/control/throw-1.html} 151(or \bipref{exit_block/1}{../bips/kernel/control/exit_block-1.html}). 152All ancestors of the predicate that raised the exception will subsequently 153exit via a LEAVE port, until a 154\bipref{catch/3}{../bips/kernel/control/catch-3.html} 155(or \bipref{block/3}{../bips/kernel/control/block-3.html}) 156is found, whose second argument matches the exception. 157This invocation of 158\bipref{catch/3}{../bips/kernel/control/catch-3.html} 159then passes a NEXT port (at which point the exception has been caught), 160and then execution continues via a normal call of the recovery goal 161(the third argument of the 162\bipref{catch/3}{../bips/kernel/control/catch-3.html}). 163 164As with the FAIL port, no argument values are displayed in the LEAVE port. 165 166%\item[CUT:] The cut is considered by the debugger as a predicate 167%(it has its own box with a CALL and an EXIT port) that always 168%succeeds. The side effects it causes are traced through the CUT port. 169%Each goal whose choice point is removed are traced with a CUT port. 170%This port is actually not a real procedure port, it only notifies of 171%the destruction (performed by the cut) of the choice point of a goal. 172%When a goal has been cut, it can not be re-satisfied. Therefore, the 173%flow of the execution will never re-enter the procedure box through 174%its REDO port. The displayed variable instantiations are the current 175%ones. 176% 177%By default, the debugger only prints this port, but does not prompt for 178%a command. This can be changed using 179%\bipref{set_leash/2}{../bips/kernel/debug/set_leash-2.html}. 180% 181%\item[TRY:] The procedure creates a choicepoint. By default, the debugger does 182%not show this port. Use 183%\bipref{set_leash/2}{../bips/kernel/debug/set_leash-2.html} to make it 184%visible. 185 186\item[DELAY:] 187The displayed goal becomes suspended. This is a singleton port, it does 188not enter or leave a box. However, a new \emph{invocation number} is assigned 189to the delayed goal, and this number will be used in the matching RESUME port. 190The DELAY port is caused by one of the built-in predicates 191\bipref{suspend/3}{../bips/kernel/suspensions/suspend-3.html}, 192\bipref{suspend/4}{../bips/kernel/suspensions/suspend-4.html}, 193\bipref{make_suspension/3}{../bips/kernel/suspensions/make_suspension-3.html} 194or a delay clause. 195The port is displayed just after the delayed goal has been created. 196 197\item[RESUME:] When a waking condition causes the resuming of 198a delayed goal, the procedure box is entered through its RESUME 199port. The box then behaves as if it had been entered through its CALL 200port. The invocation number is the same as in its previous DELAY port. 201which makes it easy to identify corresponding delay and resume events. 202However the depth level of the RESUME corresponds to the waking situation. 203It is traced like a subgoal of the goal which has caused the waking. 204 205\end{description} 206 207In the rest of this chapter the user interface to the debugger is 208described, including the commands available in the debugger itself as 209well as built-in predicates which influence it. Some of the debugger 210commands are explained using an excerpt of a debugger session. In 211these examples, the user input is always underlined (it is in fact 212not always output as typed) to distinguish it from the computer output. 213 214\subsection{Breakpoints} 215 216Breakpoints can be set on specific calls to a predicate, i.e., on a specific 217body goal in the source, so that the 218debugger will stop only at a CALL port only when that specific body goal is 219executed. A breakpoint is specify by giving the source file and the line 220number where the body goal is. 221 222For example, if the following predicate is in a file called \notation{newtop}, 223with the following line numbers: 224 225\begin{verbatim} 226 243 check_words([],[]). 227 244 check_words([Word|Words],[RevWord|RevWords]) :- 228 245 check_words(Words,RevWords). 229\end{verbatim} 230 231The breakpoint for the body goal \notation{check_words(Words, RevWords)} would 232be \notation{newtop:245}. Note that the file name must be sufficiently specified 233for ECLiPSe to find the file from your current working directory. 234 235For a call that has a breakpoint set, the execution will stop when the call 236is made, i.e., at the CALL port for that specific body goal. 237 238\section{Format of the Tracing Messages} 239All trace messages are output to the 240\notationidx{debug_output} stream. 241 242The format of one trace line is as follows: 243\begin{quote} 244\begin{verbatim} 245S+(4) 2 *EXIT<5> module:foo(one, X, two) %> 24612 3 4 5 6 7 8 9 10 247\end{verbatim} 248\end{quote} 249 250\begin{enumerate} 251\item The first character shows some properties of the 252displayed procedure. 253It may be one of 254\begin{itemize} 255\item C - an external procedure, not implemented in Prolog 256\item S - a \emph{skipped} procedure, i.e., a procedure whose 257subgoals are not traced 258%\item N - a procedure compiled in non-debug mode, i.e., behaves like skipped. 259\end{itemize} 260 261\item A \notation{+} displayed here shows that the procedure has a spy point 262 set, 263 and a \notation{\#} shows that the specific call has a break-point set. 264\index{spy point} 265 266\item The number between parentheses shows the box invocation number 267of this procedure call. Since each box has a unique invocation 268number, it can be used to identify ports that belong to the same box. 269It also shows how many procedure redos have been made since the 270beginning of the query. Only boxes that can be traced obtain an 271invocation number, for instance subgoals of a procedure which is 272compiled in debug mode or has its skip-flag set are not numbered. 273 274When a delayed goal is resumed, it keeps the invocation number it was 275assigned when it delayed. This makes it easy to follow all ports of a 276specified call even in data-driven computation. 277 278\item The second number shows the level or depth of the goal, 279i.e., the number of its ancestor boxes. When a subgoal is called, the 280level increases and after exit it decreases again. The initial level 281is 1. 282 283Since a resumed goal is considered to be a descendant of the procedure 284that woke it, the level of a resumed goal may be different from 285the level the goal had when it delayed. 286 287\item An asterisk before an \notation{EXIT} means that this 288procedure is nondeterministic and that it might be resatisfied. 289 290\item The next word is the name of the port. 291It might be missing if the displayed goal is not the current position 292in the execution (e.g., when examining ancestors or delayed goals). 293 294\begin{description} 295\item[\notation{CALL}:] a procedure is called for the first time concerning a 296 particular 297invocation; 298 299\item[\notation{DELAY}:] a procedure delays; 300 301\item[\notation{EXIT}:] a procedure succeeds; 302 303\item[\notation{FAIL}:] a procedure fails, there is no (other) solution; 304 305\item[\notation{LEAVE}:] a procedure is left before having failed or exited 306 because an exception was raised by either a built-in predicate error 307condition or a call to \bipref{throw/1}{../bips/kernel/control/throw-1.html} 308or \bipref{exit_block/1}{../bips/kernel/control/exit_block-1.html}; 309 310\item[\notation{NEXT}:] the next possibly matching clause of a procedure is 311 tried 312because unification failed or a sub-goal failed; 313 314\item[\notation{ELSE}:] the next branch of a disjunction is tried because some 315 goal 316in the previous branch failed; 317 318\item[\notation{REDO}:] a procedure that already gave a solution is called again 319 for 320an alternative; 321 322\item[\notation{RESUME}:] a procedure is woken (the flow enters the procedure 323 box as for 324a call) because of a unification of a suspending variable. 325 326%\item[UNIFY] unification succeeded (not shown for unit clauses). 327 328\end{description} 329 330\item This only appears if the goal is executing at a different priority 331 than 12, the normal priority. The number between the angled brackets 332 shows the priority (between 1 and 11) that the goal is executed at. 333 334\item For the tty debugger, the optional module name followed by a colon. 335Printing of the module can be enabled and disabled by the debugger 336command \notation{m}.\dbgcmdidx{m}{module} 337If it is enabled, the module from where the procedure is called is 338displayed. By default the module printing is disabled. With tkeclipse, the 339module name is not displayed with the traceline, instead, you can get the 340information by right holding the mouse button over the trace line in the 341call stack window. 342 343\item The goal is printed according to the current instantiations 344of its variables. Arguments of the form \notation{...} represent subterms 345that are not printed due to the depth limit in effect. 346The depth limit can be changed using the 347\notation{<}\dbgcmdidxPlus{$<$}{<}{print depth} command. 348 349The goal is printed with the current \notation{output_mode} settings. 350which can be changed using the 351\notation{o}\dbgcmdidx{o}{output mode} command. 352 353\item The prompt of the debugger, which means that it is waiting 354for a command from the user. Note there is no prompt when tkeclipse tracer 355is used. 356\end{enumerate} 357 358\section{Debugging-related Predicate Properties} 359 360Predicates have a number of properties which can be listed using the 361\bipref{pred/1}{../bips/kernel/env/pred-1.html} built-in. 362The following predicate flags and properties affect the way the 363predicate is traced by the debugger: 364\begin{quote} 365\begin{description} 366\item[debugged]\mbox{}\\ 367 Indicates whether the predicate has been compiled in debug-compile mode. 368 If \notation{on}, calls to the predicate's subgoal will be traced. 369 The value of this property can only be changed by re-compiling 370 the predicate in a different mode. 371 372\item[leash]\mbox{}\\ 373 If \notation{notrace}, no port of the predicate will be shown 374 in the trace (but the invocations will be counted nevertheless). 375 If \notation{stop}, the ports of this predicate will be shown and 376 the debugger will stop and await new commands. 377 (The \notation{print} setting is currently not supported). 378 The value of this property can be changed with 379 \bipref{traceable/1}{../bips/kernel/debug/traceable-1.html}, 380 \bipref{untraceable/1}{../bips/kernel/debug/untraceable-1.html} or 381 \bipref{set_flag/3}{../bips/kernel/compiler/set_flag-3.html}. 382 383\item[spy]\mbox{}\\ 384 If \notation{on}, the predicate has a spy-point and the debugger will 385 stop at its ports when in leap mode. 386 The value of this property can be changed with 387 \bipref{spy/1}{../bips/kernel/debug/spy-1.html}, 388 \bipref{nospy/1}{../bips/kernel/debug/nospy-1.html} or 389 \bipref{set_flag/3}{../bips/kernel/compiler/set_flag-3.html}. 390 391\item[skipped]\mbox{}\\ 392 If \notation{on}, the predicate's subgoal will not be traced even 393 if it has been compiled in debug-compile mode. 394 The value of this property can be changed with 395 \bipref{skipped/1}{../bips/kernel/debug/skipped-1.html}, 396 \bipref{unskipped/1}{../bips/kernel/debug/unskipped-1.html} or 397 \bipref{set_flag/3}{../bips/kernel/compiler/set_flag-3.html}. 398 399\item[start_tracing]\mbox{}\\ 400 If \notation{on}, a call to the predicate will activate the debugger if 401 it 402 is not already running. 403 Only the execution within this predicate's box will be traced. 404 This is useful for debugging part of a big 405 program without having to change the source code. 406 The effect is similar to wrapping all call of the predicate into 407 \bipref{trace/1}{../bips/kernel/debug/trace-1.html}. 408\end{description} 409\end{quote} 410 411 412%{\it Leashing} stands for the way the trace lines of a 413%procedure at a port are displayed and handled by the debugger. 414%There are three distinct leash levels: 415% 416%\begin{description} 417%\item[stop] Full leashing, the trace line is displayed, the debugger prints 418%a prompt and waits for a command from the user. 419% 420%\item[print] The trace line is only displayed and the debugger 421%does not stop but it continues to the next trace line. 422% 423%\item[notrace] The trace line is not displayed and 424%the debugger does not prompt for a command. 425%\end{description} 426%The leashing mode can be specified separately for ports and procedures. 427%The debugger command {\bf p} and 428%\index{p --- port leashing (debugger cmd)} 429%the predicate \bipref{set_leash/2}{../bips/kernel/debug/set_leash-2.html} 430%are for ports, e.g., 431%\begin{quote}\begin{verbatim} 432%set_leash(next, notrace). 433%\end{verbatim}\end{quote} 434%will suppress printing of all NEXT ports. 435%To change the leash mode for a certain procedure, 436%the predicate \bipref{set_flag/3}{../bips/kernel/compiler/set_flag-3.html} or 437%the debugger command {\bf t} 438%\index{t --- procedure trace mode (debugger cmd)} 439%are used. For instance 440%\begin{quote}\begin{verbatim} 441%set_flag(p/3, leash, print). 442%\end{verbatim}\end{quote} 443%will cause all ports of the procedure p/3 to be printed, but the 444%debugger will not stop or prompt for commands. 445%For each trace line, the 446%effective leash mode is combined from the mode of the current 447%procedure and the current port and if the two are not equal, the more 448%restrictive one is taken. 449% 450%A particularly useful combination is to set a spy point on a procedure 451%\index{spy point} 452%and set its leash mode to {\tt print}. This will cause the 453%debugger to print a continuous trace of all ports involving this procedure. 454 455 456\section{Starting the Debugger} 457 458Several methods can be used to switch the debugger on. 459If the textual interactive top-level is used, the commands 460\bipref{trace/0}{../bips/kernel/debug/trace-0.html} and 461\bipref{debug/0}{../bips/kernel/debug/debug-0.html} are used to 462switch the debugger on for the following queries typed from the 463top-level. 464\bipref{trace/0}{../bips/kernel/debug/trace-0.html} will switch the 465debugger to \notation{creep} mode whereas 466\bipref{debug/0}{../bips/kernel/debug/debug-0.html} will switch it 467in leap mode. 468 469For the \tkeclipse{} graphical toplevel, the debugger may be switched on by 470starting the tracer from the Tools menu before executing the query. This 471puts the debugger in \notation{creep} mode. 472 473When the debugger is in \notation{creep} mode, it will 474prompt for a command at the crossing of the first 475%leashed 476port of a 477leashed procedure. When the debugger is in leap mode, 478it will prompt for a command at the first port of a leashed 479procedure that has a spy point. The debugger is switched off either 480from the toplevel with the commands 481\bipref{nodebug/0}{../bips/kernel/debug/nodebug-0.html} or 482\bipref{notrace/0}{../bips/kernel/debug/notrace-0.html}, or by 483typing \notation{n} or \notation{N} to the debugger prompt. 484 485A spy point can be set on a procedure, or a breakpoint on a specific call, 486using 487\bipref{spy/1}{../bips/kernel/debug/spy-1.html} (which will 488\index{spy point} also switch the debugger to leap) 489and removed 490with \bipref{nospy/1}{../bips/kernel/debug/nospy-1.html}. They 491both accept a \about{SpecList} as argument. Note that 492\bipref{set_flag/3}{../bips/kernel/compiler/set_flag-3.html} can 493be used to set and reset spy points without switching the debugger on 494and without printing messages. 495 496\bipref{debugging/0}{../bips/kernel/debug/debugging-0.html} can be 497used to list the spied predicates and the current debugger mode. 498 499\begin{quote} 500\begin{verbatim} 501[eclipse 1]: spy writeln/1. 502spypoint added to writeln / 1. 503 504yes. 505Debugger switched on - leap mode 506[eclipse 2]: debugging. 507Debug mode is leap 508writeln / 1 is being spied 509 510yes. 511[eclipse 3]: true, writeln(hello), true. 512B+(2) 0 CALL writeln(hello) %> l leap 513hello 514B+(2) 0 EXIT writeln(hello) %> c creep 515B (3) 0 CALL true %> l leap 516 517yes. 518[eclipse 4]: trace. 519Debugger switched to creep mode 520 521yes. 522[eclipse 5]: true, writeln(hello), true. 523B (1) 0 CALL true %> c creep 524B (1) 0 EXIT true %> c creep 525B+(2) 0 CALL writeln(hello) %> l leap 526hello 527B+(2) 0 EXIT writeln(hello) %> l leap 528 529yes. 530\end{verbatim} 531\end{quote} 532 533\section{Debugging Parts of Programs} 534 535\subsection{Mixing debuggable and non-debuggable code} 536 537The debugger can trace only procedures which have been compiled in 538debug mode. The compiler debug mode is by default switched on and it 539can be changed globally by setting the flag \notation{debug_compile} with the 540\bipref{set_flag/2}{../bips/kernel/env/set_flag-2.html} 541predicate or using 542\bipref{dbgcomp/0}{../bips/kernel/obsolete/dbgcomp-0.html} or 543\bipref{nodbgcomp/0}{../bips/kernel/obsolete/nodbgcomp-0.html}. 544The global compiler debug mode can be overruled on a file-by-file basis 545using one of the compiler pragmas 546\begin{quote} 547\begin{verbatim} 548:- pragma(nodebug). 549:- pragma(debug). 550\end{verbatim} 551\end{quote} 552Once a program (or a part of it) has been 553debugged, it can be compiled in \notation{nodbgcomp} mode so that all 554optimisations are done by the compiler. The advantages of 555non-debugged procedures are 556 557\begin{itemize} 558\item They run slightly faster than the debugged procedures 559when the debugger is switched off. When the debugger is switched on, 560the non-debugged procedures run considerably faster than the debugged 561ones and so the user can selectively influence the speed of the code 562which is being traced as well as its space consumption. 563 564\item Their code is shorter than that of the debugged procedures. 565\end{itemize} 566 567Although only procedures compiled in the \notation{dbgcomp} mode can be 568traced, it is possible to mix the execution of procedures in both 569modes. Then, calls of \notation{nodbgcomp} procedures from \notation{dbgcomp} 570ones are 571traced, however further execution within \notation{nodbgcomp} procedures, 572i.e., the execution of their subgoals, no matter in which mode, is not 573traced. In particular, when a \notation{nodbgcomp} procedure calls a 574\notation{dbgcomp} 575one, the latter is normally not traced. 576There are two important exceptions from this rule: 577\begin{itemize} 578\indextt{waking/1} 579\item When a debuggable procedure has delayed and its DELAY port has 580been traced, then its RESUME port is also traced, even when it is woken 581inside non-debuggable code. 582\index{\atsym/2@\notation{"@/2}} 583\indextt{subcall/2} 584\item When non-debuggable code \emph{meta-calls} a debuggable procedure 585(i.e., via \bipref{call/1}{../bips/kernel/control/call-1.html}), 586then this procedure can be traced. This is a useful feature for the 587implementation of meta- predicates like 588\bipref{setof/3}{../bips/kernel/allsols/setof-3.html}, because it 589allows to hide the details of the setof-implementation, while allowing 590to trace the argument goal. 591\end{itemize} 592 593Setting a procedure to skipped (with 594\bipref{set_flag/3}{../bips/kernel/compiler/set_flag-3.html} or 595\bipref{skipped/1}{../bips/kernel/debug/skipped-1.html} 596) 597%or using the fast skip command of the debugger (\notation{F}) are also ways 598is another way 599to speed up the execution of procedures that need not be 600debugged. The debugger will ignore everything that is called inside 601the skipped procedure like for a procedure compiled in \notation{nodbgcomp} 602mode. However, the debugger will keep track of the execution of a 603procedure skipped with the command \notation{s} of the debugger so that it 604will be possible to ``creep'' in it on later backtracking or switch the 605debugger to \notation{creep} mode while the skip is running (e.g., by 606interrupting a looping predicate with \notation{\^{}C} and switching to 607\notation{creep} mode). 608 609The two predicates 610\bipref{trace/1}{../bips/kernel/debug/trace-1.html} and 611\bipref{debug/1}{../bips/kernel/debug/debug-1.html} can be used to 612switch on the debugger in the middle of a program. They execute their 613argument in \notation{creep} or \notation{leap} mode respectively. This is 614particularly useful when debugging large programs that take too much 615time (or need a lot of memory) to run completely with the debugger. 616\begin{quote} 617\begin{verbatim} 618[eclipse 1]: debugging. 619Debugger is switched off 620 621yes. 622[eclipse 2]: big_goal1, trace(buggy_goal), big_goal2. 623Start debugging - creep mode 624 (1) 0 CALL buggy_goal %> c creep 625 (1) 0 EXIT buggy_goal %> c creep 626Stop debugging. 627 628yes. 629\end{verbatim} 630\end{quote} 631 632It is also possible to enable the debugger in the middle of execution 633without changing the code. To do so, use 634\bipref{set_flag/3}{../bips/kernel/compiler/set_flag-3.html} 635to set the \notationidx{start_tracing} flag of the predicate of interest. 636Tracing will then start (in leap mode) at every call of this 637predicate.\footnote{% 638 Provided the call has been compiled in debug_compile mode, 639 or the call is a meta-call.} 640To see the starting predicate itself, 641set a spy point in addition to the \notation{start_tracing} flag: 642\begin{quote} 643\begin{verbatim} 644[eclipse 1]: debugging. 645Debugger is switched off 646 647yes. 648[eclipse 2]: set_flag(buggy_goal/0, start_tracing, on), 649 set_flag(buggy_goal/0, spy, on). 650 651yes. 652[eclipse 3]: big_goal1, buggy_goal, big_goal2. 653 +(0) 0 CALL buggy_goal %> creep 654 +(0) 0 EXIT buggy_goal %> creep 655 656yes. 657\end{verbatim} 658\end{quote} 659 660In tkeclipse, the debugger can also be started in this way. The tracer tool 661will popup at the appropriate predicate if it has not been invoked 662already. The \notation{start_tracing} flag can also be set with the predicate 663browser tool. 664 665%---------------------------------------------------------------------- 666\section{Using the Debugger via the Command Line Interface} 667%---------------------------------------------------------------------- 668This section describe the commands available at the debugger prompt 669in the debugger's command line interface (for the graphical user 670interface, please refer to the online documentation). 671 672Commands are entered by typing the corresponding key 673(without newline), the case of the letters is significant. The action 674of some of them is immediate, others require additional parameters to 675be typed afterwards. Since the {\eclipse} debugger has the possibility to 676display not only the goal that is currently being executed (the {\it 677current} goal or procedure), but also its ancestors, some of the 678commands may work on the \emph{displayed} procedure whatever it is, and 679others on the \emph{current} one. 680% Any undefined debugger command will reset the displayed procedure to the 681% current one. 682 683\subsection{Counters and Command Arguments} 684Some debugger commands accept a counter (a small integer number) 685before the command letter (e.g., \notation{c}, i.e., \notation{creep}). 686The number is just prefixed to the command and terminated by the 687command letter itself. If a counter is given for a command that 688doesn't accept a counter, it is ignored. 689 690When a counter is used and is valid for the command, 691the command is repeated, decrementing the counter until zero. 692When repeating the command, the command and the remaining counter 693value is printed after the debugger prompt instead of waiting for user input. 694 695Some commands prompt for a parameter, e.g., the \notation{j} (\notation{jump)} 696command asks for the number of the level to which to jump. 697Usually the parameter has a sensible default value (which is printed 698in square backets). If just a newline is typed, then the default value 699is taken. If a valid parameter value is typed, followed by newline, 700this value is taken. If an illegal letter is typed, the command is aborted. 701 702 703%---------------------------------------------------------------------- 704\subsection{Commands to Continue Execution} 705%---------------------------------------------------------------------- 706All commands in this section continue program execution. 707They difference between them is the condition under which execution 708will stop the next time. When execution stops again, the next trace 709line is printed and a new command is accepted. 710 711\begin{descr}{1cm} 712 713\ncmd{c}{creep}\\ 714This command allows exhaustive tracing: the execution stops at the 715next port of any leashed procedure. No further parameters are 716required, a counter \about{n} will repeat the command \about{n} times. 717It always applies on the current procedure, even when the displayed 718procedure is not the current one (e.g., during term inspection). 719An alias for the \notation{c} command is to just type newline (Return-key). 720 721\ncmd{s}{skip}\\ 722If given at an entry port of a box (CALL, RESUME, REDO), this command skips 723the execution until an exit port of this box (EXIT, FAIL, LEAVE). 724If given in an exit port it works like \notation{creep}. 725(Note that sometimes the \notation{i} command is more appropriate, since it 726skips to the next port of the current box, no matter which). 727A counter, if specified, repeats this command. 728 729%\ncmd{F}{fast skip}\\ 730%Is similar to the skip command \notation{s}. The difference is that the 731%debugger does not keep track of the execution during the skip so that 732%it is faster. As a result, it is not possible to {\it creep} later on 733%inside this procedure (e.g., it will not be possible to 'creep' 734%through this procedure on later backtracking, and switching the debugger 735%back to {\it creep} mode using \^\space C while the skipped procedure is 736%looping will have no effect). 737 738\ncmd{l}{leap}\\ 739Continues to the next spy point (any port of a procedure 740which has its spy flag set). 741\index{spy point} 742A counter, if specified, repeats this command. 743 744\mcmd{i}{invocation skip}\\ 745Continue to the next port of the box with the invocation number 746specified. The default invocation number is the one of the current box. 747Common uses for this command are to skip from CALL to NEXT, from NEXT 748to NEXT/EXIT/FAIL, from *EXIT to REDO, or from DELAY to RESUME. 749 750\mcmd{j}{jump to level}\\ 751Continue to the next port with the specified nesting level (which can 752be higher or lower than the current one). 753The default is the parent's level, i.e., to continue until the current 754box is exited, ignoring all the remaining subgoals of the current clause. 755This is particularly useful when a \notation{c} (\notation{creep}) has been 756typed where a \notation{s} (\notation{skip}) was wanted. 757 758\cmd{n}{nodebug}\\ 759This command switches tracing off for the remainder of the execution. 760However, the next top-level query will be traced again. 761Use \notation{N} to switch tracing off permanently. 762 763\cmd{q}{query the failure culprit}\\ 764The purpose of this command is to find out why a goal has failed (FAIL) 765or was aborted with an exception (LEAVE). It prints the invocation 766number of the goal which caused the failure. You can then re-run the 767program in \notation{creep} mode and type \notation{q} at the first command 768 prompt. This will 769then offer you to jump to the CALL port of the culprit goal. 770%cannot quote: too wide 771\begin{verbatim} 772[eclipse 3]: p. 773 (1) 1 CALL p %> skip 774 (1) 1 FAIL p %> query culprit 775failure culprit was (3) - rerun and type q to jump there %> nodebug? [y] 776No (0.00s cpu) 777 778[eclipse 4]: p. 779 (1) 1 CALL p %> query culprit 780failure culprit was (3) - jump to invoc: [3]? 781 (3) 3 CALL r(1) %> creep 782 (3) 3 FAIL r(...) %> creep 783 (2) 2 FAIL q %> creep 784 (1) 1 FAIL p %> creep 785No (0.01s cpu) 786\end{verbatim} 787 788\cmd{v}{var/term modification skip}\\ 789This command sets up a monitor on the currently displayed term, 790which will cause a MODIFY-port to be raised on each modification to 791any variable in the term. These ports will all have a unique invocation 792number which is assigned and printed at the time the command is issued. 793This number can then be used with the \notation{i} command to skip to where 794the modifications happen. 795%cannot quote: too wide 796\begin{verbatim} 797[eclipse 4]: [X, Y] :: 1..9, X #>= Y, Y#>1. 798 (1) 1 CALL [X, Y] :: 1..9 %> var/term spy? [y] 799Var/term spy set up with invocation number (2) %> jump to invoc: [1]? 2 800 (2) 3 MODIFY [X{[1..9]}, Y{[2..9]}] :: 1..9 %> jump to invoc: [2]? 801 (2) 4 MODIFY [X{[2..9]}, Y{[2..9]}] :: 1..9 %> jump to invoc: [2]? 802\end{verbatim} 803Note that these monitors can also be set 804up from within the program code using one of the built-ins 805\bipref{spy_var/1}{../bips/kernel/debug/spy_var-1.html} or 806\bipref{spy_term/2}{../bips/kernel/debug/spy_term-2.html}. 807 808%\cmd{v}{variable skip}\\ 809%This command allows to resume tracing when a specified variable 810%becomes instantiated. The debugger prompts for the name of the 811%variable whose instantiation is looked for. The variable identification is 812%either its name or, in case it is not unique, its number. 813%The variable number has the format 814%{\it _cnnn} where {\it c} is {\it l}, denoting a local 815%variable, or empty, denoting a global variable. 816%If variables are displayed without their numbers, 817%use the {\bf o} command to toggle the 'V' flag which displays the numbers 818%in the form {\bf Name_c123} and then type in the 819%{\bf _c123} to identify the variable number. 820% 821%If the specified variable is already instantiated, or if the 822%variable is not accessible from the debugger (e.g., the life time of 823%the variable is already expired or the variable has never been traced 824%by the debugger) a warning is printed. Otherwise, the execution is 825%continued without tracing until the variable is instantiated, i.e., 826%bound to a constant or a compound term. Then the debugger displays 827%its current value and resumes tracing. The tracing is resumed at the 828%UNIFY port of a rule or at the EXIT port of a unit clause, depending 829%on the type of the clause whose head unification has bound the 830%specified variable. The UNIFY port is displayed even if it is set to 831%{\it not traced}, to allow a precise location of the call that has 832%instantiated the variable. 833% 834%\begin{quote}\begin{alltt} 835% (5) 1 CALL conslist(3, X) (dbg)?- v 836%Variable to be bound (Name or _[lg]NNN): _X\(<NL>\) 837%Variable has been bound to [3|L] in 838% (5) 1 UNIFY conslist(3, [3|L]) (dbg)?- 839%\end{alltt}\end{quote} 840% 841%It may happen that the lifetime of the variable expires before it is 842%bound. In this case the debugger prints a message and traces the next 843%port normally. 844% 845%\begin{quote}\begin{verbatim} 846% (1) 0 CALL p (dbg)?- o 847%current output mode is "QPm", toggle chars: v 848%new mode is "QvPm" 849% (1) 0 CALL p (dbg)?- c creep 850% (2) 1 CALL p(_1122) (dbg)?- V 851%Variable to be bound (Name or _[lg]NNN): _1122 852% (2) 1 EXIT p(_1122) 853%C (3) 1 CALL fail 854%C (3) 1 FAIL fail 855% (1) 0 NEXT p 856%Variable will never be bound 857% (1) 0 EXIT p (dbg)?- 858%\end{verbatim}\end{quote} 859 860%\ncmd{w}{wake skip}\\ 861%This command is used only for delayed goals. When it is used at the 862%DELAY port, it skips the execution until this goal is resumed. This 863%command does not accept any arguments. Since the resumed goal has 864%the same invocation number like the delayed one, the {\bf j} or {\bf 865%i} commands could be used for the same purpose, 866%\index{j --- jump (debugger cmd)} 867%\index{i --- invocation skip (debugger cmd)} 868%however the {\bf w} command has an additional feature, namely that the 869%tracing is also resumed when the delayed goal disappears because the 870%system backtracked to a state before this goal was called and delayed. 871%A specified counter is ignored. The command is executed even if the 872%displayed procedure is not the current one, as long as the displayed 873%port is DELAY. On other ports an error message is printed. 874% 875% \begin{quote}\begin{verbatim} 876% [eclipse 1]: spy a/1. 877% spypoint added to a / 1. 878% 879% yes. 880% Debugger switched on - leap mode 881% [eclipse 2]: p. 882% +(6) 1 CALL a(_39) (dbg)?- d delayed goals 883% 884% Delayed goals: 885% (3) p(_41, _39) 886% 887% +(6) 1 CALL a(_39) (dbg)?- u use goal (3) 888% (3) 1 DELAY p(_41, _39) (dbg)?- W wake 889% +(6) 1 EXIT a(1) 890% (7) 1 CALL b(1) 891% (7) 1 *EXIT b(1) 892% (8) 1 CALL c(1) 893% (8) 1 *EXIT c(1) 894% +(9) 1 CALL a(_41) 895% (3) 2 RESUME p(1, 1) (dbg)?- 896% \end{verbatim}\end{quote} 897 898\mcmd{z}{zap}\\ 899This command allows to skip over, or to a specified port. When this 900command is executed, the debugger prompts for a port name (e.g., 901\notation{fail}) 902or a negated port name (e.g., \tld\notation{exit}). 903Execution then continues until the specified port appears or, 904in the negated case, until a port other than the specified one appears. 905The default is the negation of the current port, which is useful 906when exiting from a deep recursion (a long sequence of EXIT or FAIL ports). 907 908%\ncmd{e}{error search}\\ 909%This is a predefined macro; it is set to {\tt "zleave"} i.e., zap to a LEAVE 910%port. It is useful for example to skip until an error that calls {\bf 911%exit_block/1} occurs. 912 913\end{descr} 914 915%---------------------------------------------------------------------- 916\subsection{Commands to Modify Execution} 917%---------------------------------------------------------------------- 918\begin{descr}{1cm} 919 920\mcmd{f}{fail}\\ 921Force a failure of the procedure with the specified invocation number. 922The default is to force failure of the current procedure. 923 924\cmd{a}{abort}\\ 925Abort the execution of the current query and return to the top-level. 926The command prompts for confirmation. 927\end{descr} 928 929 930%---------------------------------------------------------------------- 931\subsection{Display Commands} 932%---------------------------------------------------------------------- 933This group of commands cause some useful information to be displayed. 934 935\begin{descr}{1cm} 936 937\mcmd{d}{delayed goals}\\ 938Display the currently delayed goals. The optional argument allows 939to restrict the display to goal of a certain priority only. 940The goals are displayed in a format similar to the trace lines, 941except that there is no depth level and no port name. 942Instead, the goal priority is displayed in angular brackets: 943\begin{quote} 944\begin{verbatim} 945[eclipse 5]: [X, Y] :: 1..9, X #>= Y, Y #>= X. 946 (1) 1 CALL [X, Y] :: 1..9 %> creep 947 (1) 1 EXIT [X{[1..9]}, Y{[1..9]}] :: 1..9 %> creep 948 (2) 1 CALL X{[1..9]} - Y{[1..9]}#>=0 %> creep 949 (3) 2 DELAY X{[1..9]} - Y{[1..9]}#>=0 %> creep 950 (2) 1 EXIT X{[1..9]} - Y{[1..9]}#>=0 %> creep 951 (4) 1 CALL Y{[1..9]} - X{[1..9]}#>=0 %> creep 952 (5) 2 DELAY Y{[1..9]} - X{[1..9]}#>=0 %> delayed goals 953 with prio: [all]? 954------- delayed goals ------- 955 (3) <2> X{[1..9]} - Y{[1..9]}#>=0 956 (5) <2> Y{[1..9]} - X{[1..9]}#>=0 957------------ end ------------ 958 (5) 2 DELAY Y{[1..9]} - X{[1..9]}#>=0 %> 959\end{verbatim} 960\end{quote} 961 962\mcmd{u}{scheduled goals}\\ 963Similar to the \notation{d} command, but displays only those delayed goals 964that are already scheduled for execution. 965The optional argument allows 966to restrict the display to goal of a certain priority only. Example: 967\begin{quote} 968\begin{verbatim} 969[eclipse 13]: [X,Y,Z]::1..9, X#>Z, Y#>Z, Z#>1. 970 (1) 1 CALL [X, Y, Z] :: 1..9 %> creep 971 (1) 1 EXIT [X{[1..9]}, Y{[1..9]}, Z{[1..9]}] :: 1..9 %> creep 972 (2) 1 CALL X{[1..9]} - Z{[1..9]}+-1#>=0 %> creep 973 (3) 2 DELAY X{[2..9]} - Z{[1..8]}#>=1 %> creep 974 (2) 1 EXIT X{[2..9]} - Z{[1..8]}+-1#>=0 %> creep 975 (4) 1 CALL Y{[1..9]} - Z{[1..8]}+-1#>=0 %> creep 976 (5) 2 DELAY Y{[2..9]} - Z{[1..8]}#>=1 %> creep 977 (4) 1 EXIT Y{[2..9]} - Z{[1..8]}+-1#>=0 %> creep 978 (6) 1 CALL 0 + Z{[1..8]}+-2#>=0 %> creep 979 (3) 2 RESUME X{[2..9]} - Z{[2..8]}#>=1 %> scheduled goals 980 with prio: [all]? 981------ scheduled goals ------ 982 (5) <2> Y{[2..9]} - Z{[2..8]}#>=1 983------------ end ------------ 984 (3) 2 RESUME X{[2..9]} - Z{[2..8]}#>=1 %> 985\end{verbatim} 986\end{quote} 987 988%\cmd{\accent 94}{delayed by a variable}\\ 989%This command displays goals suspended by a specified 990%variable, i.e., like with the built-in predicate {\bf delayed_goals/2}. 991%The debugger will prompt for a variable number like in the {\bf v} 992%command and then print the delayed goals similarly to the {\bf d} 993%command. 994 995\cmd{G}{all ancestors}\\ 996Prints all the current goal's ancestors from the oldest to the newest. 997The display format is similar to trace lines, 998except that {\tt ....} is displayed in the port field. 999 1000\cmd{.}{print definition}\\ 1001If given at a trace line, the command displays the source code of the 1002current predicate. 1003If the predicate is not written in Prolog, or has not been compiled from 1004a file, or the source file is inaccessible, no information can be displayed. 1005 1006\cmd{w}{write source context for current goal}\\ 1007Lists the source lines around the current goal displayed by the trace line, 1008showing the context of the goal. For example: 1009 1010\begin{quote} 1011\begin{verbatim} 1012 (230) 4 CALL check_word(what, _5824) %> write source lines 1013Source file: /homes/user/EclipseTests/Chatq/newtop 1014 241 :- mode check_words(+,-). 1015 242 1016 243 check_words([],[]). 1017 244 check_words([Word|Words],[RevWord|RevWords]) :- 1018 245> check_word(Word,RevWord), 1019 245 check_words(Words,RevWords). 1020 246 1021 247 :- mode check_word(+,-). 1022 248 1023 %> 1024\end{verbatim} 1025\end{quote} 1026 1027The listing shows the line numbers for the source lines, with a \notation{>} 1028marking the line with the current goal. Note it is the actual body goal 1029that is shown, rather than the predicate definition as in the \notation{.} 1030command. 1031An optional numeric argument can be given before the command, specifying 1032the number of lines surrounding (i.e., before and after) the current goal 1033that should be listed: 1034 1035\begin{quote} 1036\begin{verbatim} 1037 %> 2write source lines 1038Source file: /homes/user/EclipseTests/Chatq/newtop 1039 243 check_words([],[]). 1040 244 check_words([Word|Words],[RevWord|RevWords]) :- 1041 245> check_word(Word,RevWord), 1042 245 check_words(Words,RevWords). 1043 246 1044 %> 1045\end{verbatim} 1046\end{quote} 1047 1048Source is only shown if the source information is available---that is, 1049the code has to be compiled debuggable from a file, and not all goals have 1050source information; for example, goals in meta-calls (e.g., those inside a 1051\predspec{call/1}). Also, source context cannot be shown at a RESUME port. 1052 1053\cmd{h}{help}\\ 1054Print a summary of the debugger commands. 1055 1056\cmd{\query}{help}\\ 1057Identical to the \notation{h} command. 1058 1059\end{descr} 1060 1061 1062%---------------------------------------------------------------------- 1063\subsection{Navigating among Goals} 1064%---------------------------------------------------------------------- 1065 1066While the debugger waits for commands, program execution is always 1067stopped at some port of some predicate invocation box, or goal. 1068Apart from this current goal, two types of other goals are also active. 1069These are the ancestors of the current goal (the enclosing, not yet 1070exited boxes in the box model) and the delayed goals. 1071The debugger allows to navigate among these goals and inspect them. 1072 1073\begin{descr}{1cm} 1074 1075\cmd{g}{ancestor}\\ 1076Move to and display the ancestor goal (or parent) of the displayed goal. 1077Repeated application of this command allows to go up the call stack. 1078 1079\mcmd{x}{examine goal}\\ 1080Move to and display the goal with the specified invocation number. 1081This must be one of the active goals, i.e., either an ancestor of the 1082current goal or one of the currently delayed goals. 1083The default is to return to the current goal, i.e., to the goal at 1084whose port the execution is currently stopped. 1085\end{descr} 1086 1087%---------------------------------------------------------------------- 1088\subsection{Inspecting Goals and Data} 1089%---------------------------------------------------------------------- 1090 1091This family of commands allow the subterms in the goal displayed at the 1092port to be inspected. 1093\index{inspect subterm commands (debugger)} 1094The ability to inspect subterms is designed to help overcome two problems 1095when examining a large goal with the normal display of the goal at a debug 1096port: 1097\begin{enumerate} 1098\item Some of the subterms may be omitted from the printed goal because 1099of the print-depth; 1100 1101\item If the user is interested in particular subterms, it 1102may be difficult to precisely locate them from the surrounding arguments, 1103even if it is printed. 1104\end{enumerate} 1105 1106With inspect subterm commands, the user is able to issue commands to 1107navigate through the subterms of the current goal and examine them. 1108A \emph{current subterm} of the goal is maintained, and this is 1109printed after each inspect subterm command, instead of the entire goal. 1110Initially, the current subterm is set to the goal, but this can then be 1111moved to the subterms of the goal with navigation commands. 1112 1113Once inspect subterm is initiated by an inspect subterm command, the 1114debugger enters into the inspect subterm mode. This is indicated in the 1115trace line by \notation{INSPECT} instead of the name of the port, and in 1116addition, 1117the goal is not shown on the trace line: 1118 1119\begin{quote} 1120\begin{verbatim} 1121 INSPECT (length/2) %> 1122\end{verbatim} 1123\end{quote} 1124 1125Instead of showing the goal, a summary of the current subterm---generally its 1126functor and arity if the subterm is a structure---is shown in brackets. 1127 1128\begin{descr}{1cm} 1129 1130 1131\mcmd{ \#}{move down to {\it par}th argument}\\ 1132The most basic command of inspect subterm is to move the current subterm to 1133an argument of the existing current subterm. This is done by typing a 1134number followed by carriage return, or by typing \verb:#:, which causes the 1135debugger to prompt for a number. In both cases, the number specifies the 1136argument number to move down to. 1137In the following example, the \verb:#: style of the command is used to move 1138to the first argument, and the number style of the command to move to the 1139third argument: 1140 1141\begin{quote} 1142\begin{verbatim} 1143 (1) 1 CALL foo(a, g(b, [1, 2]), X) %> inspect arg #: 1<NL> 1144a 1145 INSPECT (atom) %> 1146\end{verbatim} 1147\end{quote} 1148 1149\begin{quote} 1150\begin{verbatim} 1151 (1) 1 CALL foo(a, g(b, [1, 2]), X) %> 3<NL> 1152X 1153 INSPECT (var) %> 1154\end{verbatim} 1155\end{quote} 1156 1157The new current subterm is printed, followed by the INSPECT 1158trace line. Notice that the summary shows the type of the current 1159subterm, instead of \pattern{Name/Arity}, since in both cases the subterms are 1160not structures. 1161 1162If the current subterm itself is a compound term, then it is possible to 1163recursively navigate into the subterm: 1164 1165\begin{quote} 1166\begin{verbatim} 1167 (1) 1 CALL foo(a, g(b, [1, 2]), X) %> 2<NL> 1168g(b, [1, 2]) 1169 INSPECT (g/2) %> 2<NL> 1170[1, 2] 1171 INSPECT (list 1-head 2-tail) %> 2<NL> 1172[2] 1173 INSPECT (list 1-head 2-tail) %> 1174\end{verbatim} 1175\end{quote} 1176 1177Notice that lists are treated as a structure with arity 2, although the 1178functor (\predspec{./2}) is not printed. 1179 1180In addition to compound terms, it is also possible to navigate into the 1181attributes of attributed variables: 1182 1183\begin{quote} 1184\begin{verbatim} 1185[eclipse 21]: suspend(foo(X), 3, X->inst), foo(X).<NL> 1186 (1) 1 DELAY foo(X) %> <NL> 1187creep 1188 (2) 1 CALL foo(X) %> 1<NL> 1189X 1190 INSPECT (attributes 1-suspend 2-fd ) %>1<NL> 1191suspend(['SUSP-1-susp'|_218] - _218, [], []) 1192 INSPECT (struct suspend/3) %> 1193\end{verbatim} 1194\end{quote} 1195 1196The variable X is an attributed variable in this case, and when it is the 1197current subterm, this is indicated in the trace line. The debugger also 1198shows the user the currently available attributes, and the user can then 1199select one to navigate into (\notation{fd} is available in 1200this case because the finite domain library was loaded earlier in the 1201session. Otherwise, it would not be available as a choice here). 1202 1203Note that the \predspec{suspend/3} summary contains a \notation{struct} before 1204it. This is because the \predspec{suspend/3} is a predefined structure with 1205field names (see section~\ref{chapstruct}). It is possible to view the 1206field names of such structures using the \notation{.} command in inspect mode. 1207 1208If the number specified is larger than the number of the arguments of the 1209current subterm, then an error is reported and no movement is made: 1210 1211\begin{quote} 1212\begin{verbatim} 1213foo(a, g(b, [1, 2]), 3) 1214 INSPECT (foo/3) %> 4<NL> 1215 1216Out of range..... 1217 1218foo(a, g(b, [1, 2]), 3) 1219 INSPECT (foo/3) %> 1220\end{verbatim} 1221\end{quote} 1222 1223\ncmd{uparrow key}{move current subterm up by \about{n} levels} 1224\ncmd{A}{move current subterm up by \about{n} levels}\\ 1225In addition to moving the current subterm down, it can also be moved up 1226from its current position. This is done by typing the uparrow key. This key 1227is mapped to \notation{A} by the debugger, so one can also type 1228\notation{A}. Typing \notation{A} may be necessary for some configurations 1229(combination of keyboards and operating systems) because the uparrow key is 1230not correctly mapped to \notation{A}. 1231 1232An optional argument can preceded the uparrow keystroke, which indicates 1233the number of levels to move up. The default is 1: 1234 1235\begin{quote} 1236\begin{verbatim} 1237 (1) 1 CALL foo(a, g(b, [1, 2]), 3) %> 2<NL> 1238g(b, [1, 2]) 1239 INSPECT (g/2) %> 1<NL> 1240b 1241 INSPECT (atom) %> up subterm 1242g(b, [1, 2]) 1243 INSPECT (g/2) %> 1up subterm 1244foo(a, g(b, [1, 2]), 3) 1245 INSPECT (foo/3) %> 1246\end{verbatim} 1247\end{quote} 1248 1249The debugger prints \notation{up subterm} when the uparrow key is typed. The 1250current subterm moves back up the structure to its parent for each level it 1251moves up, and the above move can be done directly by specifying 2 as the 1252levels to move up: 1253 1254\begin{quote} 1255\begin{verbatim} 1256b 1257 INSPECT (atom) %> 2up subterm 1258foo(a, g(b, [1, 2]), 3) 1259 INSPECT (foo/3) %> 1260\end{verbatim} 1261\end{quote} 1262 1263If the number of levels specified is more than the number of levels that 1264can be traversed up, the current subterm stops at the toplevel: 1265 1266\begin{quote} 1267\begin{verbatim} 1268 (1) 1 CALL foo(a, g(b, [1, 2]), 3) %> 2<NL> 1269g(b, [1, 2]) 1270 INSPECT (g/2) %> 2<NL> 1271[1, 2] 1272 INSPECT (list 1-head 2-tail) %> 5up subterm 1273foo(a, g(b, [1, 2]), 3) 1274 INSPECT (foo/3) %> 1275\end{verbatim} 1276\end{quote} 1277 1278\cmd{0}{move current subterm to toplevel}\\ 1279It is possible to quickly move back to the top of a goal that is being 1280inspected by specifying 0 (zero) as the command: 1281 1282\begin{quote} 1283\begin{verbatim} 1284 (1) 1 CALL foo(a, g(b, [1, 2]), 3) %> 2<NL> 1285g(b, [1, 2]) 1286 INSPECT (g/2) %> 2<NL> 1287[1, 2] 1288 INSPECT (list 1-head 2-tail) %> 2<NL> 1289[2] 1290 INSPECT (list 1-head 2-tail) %> 2<NL> 1291[] 1292 INSPECT (atom) %> 0<NL> 1293foo(a, g(b, [1, 2]), 3) 1294 INSPECT (foo/3) %> 1295\end{verbatim} 1296\end{quote} 1297 1298Moving to the top can also be done by the \verb:#: command, and not giving 1299any argument (or notation{0}) when prompted for the argument. 1300 1301\ncmd{leftarrow key}{move current subterm left by \about{n} positions} 1302\ncmd{D}{move current subterm left by \about{n} positions}\\ 1303The leftarrow key (or the equivalent \notation{D}) moves the current subterm to 1304a sibling subterm (i.e., fellow argument of the parent structure) that is to 1305the left of it. Consider the structure \notation{foo(a, g(b, [1, 2]), 3)}, then 1306for the second argument, \notation{g(b, [1, 2])}, \notation{a} is its (only) 1307left 1308sibling, and \notation{3} its (only) right sibling. For the third argument, 1309\notation{3}, both \notation{a} (distance of 2) and 1310\notation{g(b, [1, 2])} (distance of 1) are its left siblings. The optional 1311numeric argument for the command specifies the distance to the left that 1312the current subterm should be moved. It defaults to 1. 1313 1314 1315\begin{quote} 1316\begin{verbatim} 1317foo(a, g(b, [1, 2]), 3) 1318 INSPECT (foo/3) %> 3<NL> 13193 1320 INSPECT (integer) %> 2left subterm 1321a 1322 INSPECT (atom) %> 1323\end{verbatim} 1324\end{quote} 1325 1326If the leftward movement specified would move the argument position before the 1327first argument of the parent term, then the movement will stop at the first 1328argument: 1329 1330 1331\begin{quote} 1332\begin{verbatim} 1333foo(a, g(b, [1, 2]), 3) 1334 INSPECT (foo/3) %> 3<NL> 13353 1336 INSPECT (integer) %> 5left subterm 1337a 1338 INSPECT (atom) %> 1339\end{verbatim} 1340\end{quote} 1341 1342In the above example, the current subterm was at the third argument, thus 1343trying to move left by 5 argument positions is not possible, and 1344the current subterm stopped at leftmost position---the first argument. 1345 1346\ncmd{rightarrow key}{move current subterm right by \about{n} positions} 1347\ncmd{C}{move current subterm right by \about{n} positions}\\ 1348The rightarrow key (or the equivalent \notation{C}) moves the current subterm 1349to a sibling subterm (i.e., fellow argument of the parent structure) that is 1350to the right of it. Consider the structure \notation{foo(a, g(b, [1, 2]), 3)}, 1351then for the first argument, \notation{a}, \notation{g(b, [1, 2])} is a right 1352sibling with distance of 1, and \notation{3} is a right sibling with distance 1353of 2. The optional numeric argument for the command specifies the distance 1354to the left that the current subterm should be moved. It defaults to 1. 1355 1356\begin{quote} 1357\begin{verbatim} 1358foo(a, g(b, [1, 2]), 3) 1359 INSPECT (integer) %> 2left subterm 1360a 1361 INSPECT (atom) %> 1362\end{verbatim} 1363\end{quote} 1364 1365If the rightward movement specified would move the argument position beyond 1366the last argument of the parent term, then the movement will stop at the 1367last argument: 1368 1369\begin{quote} 1370\begin{verbatim} 1371foo(a, g(b, [1, 2]), 3) 1372 INSPECT (foo/3) %> 3<NL> 13733 1374 INSPECT (integer) %> right subterm 13753 1376 INSPECT (integer) %> 1377\end{verbatim} 1378\end{quote} 1379 1380In the above example, the current subterm was at the third (and last) 1381argument, thus trying to move to the right (by the default 1 position in 1382this case) is not possible, and the current subterm remains at the third 1383argument. 1384 1385\ncmd{downarrow key}{move current subterm down by \about{n} levels} 1386\ncmd{B}{move current subterm down by \about{n} levels}\\ 1387The down-arrow key moves the current subterm down from its current 1388position. This command is only valid if the current subterm is a compound 1389term and so has subterms itself. A structure has in general more than one 1390argument, so there is a choice of which argument position to move down to. 1391This argument is not directly specified by the user as part of the command, 1392but is implicitly specified: 1393the argument position selected is the argument position of the current 1394subterm within its parent: 1395%cannot quote: too wide 1396\begin{verbatim} 1397foo(a, g(b, [1, 2]), 3) 1398 INSPECT (foo/3) %> 2<NL> 1399g(b, [1, 2]) 1400 INSPECT (list 1-head 2-tail) %> 3down subterm 2 for 3 levels 1401[] 1402 INSPECT (atom) %> 1403\end{verbatim} 1404 1405In the above example, the user moves down into the second argument, and 1406then use the down-arrow key to move down into the second argument for 2 1407levels---the numeric argument typed before the arrow key specified the 1408number of levels that the current subterm was moved down by. 1409The command moves into the second argument because it was at the 1410second argument position when the command was issue. 1411 1412However, there is not always an argument position for the current 1413sub-term. For example, when the current sub-term is at the toplevel of the goal 1414or if it is at an attribute. In these cases, the default for the argument 1415position to move down into is the first argument: 1416\begin{quote} 1417\begin{verbatim} 1418 INSPECT (atom) %> 0<NL> 1419foo(a, g(b, [1, 2]), 3) 1420 INSPECT (foo/3) %> down subterm 1 for 1 levels 1421a 1422 INSPECT (atom) %> 1423\end{verbatim} 1424\end{quote} 1425 1426In the above example, the down-arrow key is typed at the top-level, and 1427thus the argument position chosen for moving down is first argument, with 1428the default numeric argument for the 1429 1430 1431If the argument position to move into is beyond the range of the current 1432subterm's number of arguments, then no move is performed: 1433 1434\begin{quote} 1435\begin{verbatim} 1436 (1) 1 CALL foo(a, b, c(d, e)) %> 3<NL> 1437c(d, e) 1438 INSPECT (c/2) %> Out of range after traversing down arg... 1439c(d, e) 1440 INSPECT (c/2) %> 1441\end{verbatim} 1442\end{quote} 1443In this case, the down-arrow key was typed in the second trace line, which 1444had the current subterm at the third argument of its parent term, and thus 1445the command tries to move the new current subterm to the third argument of 1446the current sub-term, but the structure does not have a third argument and 1447so no move was made. In the case of moving down multiple levels, then the 1448movement will stop as soon as the argument position to move down to goes 1449out of range. 1450 1451Moving down is particularly useful for traversing lists. As discussed, 1452lists are really structures with arity two, so the $\#N$ command would 1453not move to the $N^{th}$ element of the list. With the down-arrow command , 1454it is possible to move into the $N^{th}$ position in one command: 1455 1456%cannot quote: too wide 1457\begin{verbatim} 1458[eclipse 30]: foo([1,2,3,4,5,6,7,8,9]). 1459 (1) 1 CALL foo([1, 2, 3, ...]) %> 1<NL> 1460[1, 2, 3, 4, ...] 1461 INSPECT (list 1-head 2-tail) %> 2<NL> 1462[2, 3, 4, 5, ...] 1463 INSPECT (list 1-head 2-tail) %> 6down subterm 2 for 6 levels 1464[8, 9] 1465 INSPECT (list 1-head 2-tail) %> 1466\end{verbatim} 1467 1468In order to move down a list, we repeatedly move into the tail of the 1469list---the second argument position. In order to do this with the down-arrow 1470command, we must be at the second argument position first, and this is 1471done in the second trace line. Once this is done, then it is possible to 1472move arbitrarily far down the list in one go, as is shown in the example. 1473 1474\cmd{.}{print structure definition}\\ 1475In \eclipse, it is possible to define field names for structures (see 1476section~\ref{chapstruct}). If the inspector encounters such structures, 1477then the user can get the debugger to print out the field names. Note that 1478this functionality only applies within the inspect subterm mode, as the 1479debugger command ``\notation{.}'' normally prints the source for the predicate. 1480The fact that a structure has defined field names are indicated by a 1481``struct'' in the summary: 1482 1483\begin{quote} 1484\begin{verbatim} 1485:- local struct(capital(city,country)). 1486 1487..... 1488 1489 (1) 1 CALL f(capital(london, C)) %> 1<NL> 1490capital(london, C) 1491 INSPECT (struct capital/2) %> structure definition: 14921=city 2=country 1493 %> 1494\end{verbatim} 1495\end{quote} 1496 1497In this example, a structure definition was made for \predspec{capital/2}. When 1498this structure is the current subterm in the inspect mode, the 1499\notation{struct} in the summary for the structure indicates that it has 1500a structure definition. For such structures, the field names are printed by 1501the structure definition command. 1502 1503If the command is issued for a term that does not have a structure 1504definition, an error would be reported: 1505 1506\begin{quote} 1507\begin{verbatim} 1508 INSPECT (f/1) %> structure definition: 1509No struct definition for term f/1@eclipse. 1510 %> 1511\end{verbatim} 1512\end{quote} 1513 1514\cmd{p}{show subterm path}\\ 1515As the user navigates into a term, then at each level, a particular 1516argument position (or attribute, in the case of attributed variables) is 1517selected at each level. The user can view the position the current subterm 1518is at by the \notation{p} command. For example, 1519 1520\begin{quote} 1521\begin{verbatim} 1522 (1) 1 CALL foo(a, g(b, [1, 2]), 3) %> 2<NL> 1523g(b, [1, 2]) 1524 INSPECT (g/2) %> 2<NL> 1525[1, 2] 1526 INSPECT (list 1-head 2-tail) %> 1<NL> 15271 1528 INSPECT (integer) %> p 1529Subterm path: 2, 2, 1 1530 %> 1531\end{verbatim} 1532\end{quote} 1533 1534The subterm path shows the argument positions taken at each level of the 1535toplevel term to reach the current subterm, starting from the top. 1536 1537Extra information (in addition to the numeric argument position) will be 1538printed if the subterm at a particular level is either a structure with 1539field names or an attributed variable. For example: 1540 1541%cannot quote: too wide 1542\begin{verbatim} 1543:- local struct(capital(city,country)). 1544 1545..... 1546 1547[eclipse 8]: suspend(capital(london, C), 3 ,C -> inst), 1548 f(capital(london, C)). 1549 1550.... 1551 1552 (2) 1 CALL f(capital(london, C)) %> 1<NL> 1553capital(london, C) 1554 INSPECT (struct capital/2) %> 2<NL> 1555C 1556 INSPECT (attributes 1-suspend ) %> 1<NL> 1557suspend(['SUSP-1-susp'|_244] - _244, [], []) 1558 INSPECT (struct suspend/3) %> 1<NL> 1559['SUSP-1-susp'|_244] - _244 1560 INSPECT (-/2) %> 1561Subterm path: 1, country of capital (2), attr: suspend, inst of 1562suspend (1) %> 1563\end{verbatim} 1564 1565 1566In this example, except for the toplevel argument, all the other positions are 1567either have field names or are attributes. This is reflected in the path, 1568for example, {\tt country of capital (2)} shows that the field name for 1569the selected argument position (2, shown in brackets) is \notation{country}, 1570and the structure name is \notation{capital}. For the ``position'' of the 1571selected attribute (\notation{suspend}) of the attributed variable \notation{C}, 1572the path position is shown as \notation{attr: suspend}. 1573 1574 1575\subsubsection{Interaction between inspect subterm and output modes} 1576\index{inspect subterm commands (debugger)!interaction with output modes} 1577 1578The debugger commands that affect the print formats in the debugger also 1579affects the printed current subterm. Thus, both the print depth and output 1580mode of the printed subterm can be changed. 1581 1582The changing of the output modes can have a significant impact on the 1583inspect mode. This is because for terms which are 1584transformed by write macros before they are printed (see 1585chapter~\ref{chapmacros}), different terms can be printed depending on the 1586settings of the output modes. In particular, output transformation is used 1587to hide many of the implementation related extra fields and even term names 1588of many \eclipse\ data structures (such as those used in the finite domain 1589library). For the purposes of inspect subterms, the term that is inspected 1590is always the printed form of the term, and thus changing the output mode 1591can change the term that is being inspected. 1592 1593Consider the example of looking at the attribute of a finite domain variable: 1594\begin{quote} 1595\begin{verbatim} 1596A{[4..10000000]} 1597 INSPECT (attributes 1-suspend 2-fd ) %> 2<NL> 1598[4..10000000] 1599 INSPECT (list 1-head 2-tail) %> 1<NL> 16004..10000000 1601 INSPECT (../2) %> 2up subterm 1602A{[4..10000000]} 1603 INSPECT (attributes 1-suspend 2-fd ) %> <o> 1604current output mode is "QPm", toggle char: T 1605new output mode is "TQPm". 1606A{[4..10000000]} 1607 INSPECT (attributes 1-suspend 2-fd ) %> 2<NL> 1608fd(dom([4..10000000], 9999997), [], [], []) 1609 INSPECT (struct fd/4) %> 1<NL> 1610dom([4..10000000], 9999997) 1611 INSPECT (dom/2) %> 1612\end{verbatim} 1613\end{quote} 1614 1615After selecting the output mode \notation{T}, which turns off any output 1616macros, the internal form of the attribute is shown. This allows previously 1617hidden fields of the attribute to be examined by the subterm navigation. 1618Note that if the current subterm is inside a structure which will be 1619changed by a changed output mode (such as inside the fd attribute), and the 1620output mode is changed, then until the current subterm is moved out of the 1621structure, the existing subterm path is still applicable. 1622 1623Also, after a change in output modes, the current subterm will still be 1624examining the structure that it obtained from the parent subterm. Consider 1625the finite domain variable example again: 1626 1627\begin{quote} 1628\begin{verbatim} 16294..10000000 1630 INSPECT (../2) %> up subterm 1631[4..10000000] ***** printed structure 1 1632 INSPECT (list 1-head 2-tail) %> <o> 1633current output mode is "QPm", toggle char: T 1634new output mode is "TQPm". 1635[4..10000000] 1636 INSPECT (list 1-head 2-tail) %> up subterm 1637A{[4..10000000]} 1638 INSPECT (attributes 1-suspend 2-fd ) %> 2 1639fd(dom([4..10000000], 9999997), [], [], []) 1640 INSPECT (struct fd/4) %> <o> 1641current output mode is "QPmT", toggle char: T 1642new output mode is "QPm". 1643fd(4..10000000, [], [], []) ***** printed structure 2 1644 INSPECT (struct fd/4) %> 1645 1646\end{verbatim} 1647\end{quote} 1648 1649Printed structures 1 and 2 in the above example are at the same position 1650(toplevel of the finite domain structure), and printed with the same output 1651mode (\notation{QPm}), but are different because the structure obtained from 1652the parent subterm is different---in printed structure 2, the output mode 1653was not changed until after the \notation{fd/4} structure was the current 1654subterm. 1655 1656\end{descr} 1657 1658 1659%---------------------------------------------------------------------- 1660\subsection{Changing the Settings} 1661%---------------------------------------------------------------------- 1662The following commands allow to change the parameters which 1663influence the way the tracing information is displayed or processed. 1664 1665\begin{descr}{1cm} 1666 1667\mcmdPlus{<}{<}{set print depth}\\ 1668Allows to modify the \notation{print_depth}, i.e., the depth up to which 1669nested argument terms are printed. Everything nested deeper than the 1670specified depth is abbreviated as \verb:...:. 1671Note that the debugger has a private \notation{print_depth} setting with 1672default 5, which is different from the global setting obtained from 1673\bipref{get_flag/2}{../bips/kernel/env/get_flag-2.html}. 1674 1675\mcmd{>}{set indentation step width}\\ 1676Allows to specify the number of spaces used to indent trace lines according 1677to their depth level. The default is 0. 1678 1679\cmd{m}{module}\\ 1680Toggles the module printing in the trace line. 1681If enabled, the module from where the procedure is called 1682is printed in the trace line: 1683\begin{quote} 1684\begin{verbatim} 1685 (1) 1 CALL true %> show module 1686 (1) 1 CALL eclipse : true %> 1687\end{verbatim} 1688\end{quote} 1689 1690\cmd{o}{output mode}\\ 1691This command allows to modify the options used when printing trace lines. 1692It first prints the current {\tt output_mode} string, as obtained by 1693\bipref{get_flag/2}{../bips/kernel/env/get_flag-2.html}, 1694then it prompts for a sequence of characters. 1695If it contains valid output mode flags, the value 1696of these flags is then inverted. 1697Typing an invalid character will display a list describing the different 1698options. 1699Note that this command affects the global setting of {\tt output_mode}. 1700 1701\begin{quote} 1702\begin{verbatim} 1703 (1) 1 CALL X is length([1, 2, ...]) %> current output mode 1704 is "QPm", toggle char: V 1705new output mode is "VQPm". 1706 (1) 1 CALL X_72 is length([1, 2, ...]) %> current output mode 1707 is "QVPm", toggle char: O 1708new output mode is "OQVPm". 1709 (1) 1 CALL is(X_72, length([1, 2, ...])) %> current output mode 1710 is "OQVPm", toggle char: . 1711new output mode is ".OQVPm". 1712 (1) 1 CALL is(X_72, length(.(1, .(2, .(...))))) %> 1713\end{verbatim} 1714\end{quote} 1715 1716\cmd{+}{\protect\Index{set a spy point}}\\ 1717\index{spy point!set} 1718Set a spy point on the displayed procedure, the same as using the 1719\bipref{spy/1}{../bips/kernel/debug/spy-1.html} predicate. 1720It is possible to set a spy point on any existing procedure, 1721even on a built-in on external one. 1722If the procedure already has a spy point, an error message is printed 1723and any counter is ignored. 1724 1725Note that the debugger does not check for spy points that occur inside 1726skipped procedures or during the execution of any other skip command 1727than the \notation{leap} command \notation{l}. 1728 1729\cmd{$-$}{\protect\Index{remove a spy point}}\\ 1730\index{spy point!remove} 1731Similarly to the previous command, this one removes a spy point 1732from a procedure, if it has one. 1733 1734 1735%\nmcmd{p}{port leashing}\\ 1736%Change the leashing of the displayed port. 1737%This is a two-key command, when it is executed, the debugger prompts 1738%for the second letter which may be one of 1739%\begin{itemize} 1740%\item p - print only, from now on the port will be only printed but the 1741%debugger will not stop there 1742% 1743%\item n - no trace, the debugger will not show this port at all 1744%\end{itemize} 1745%(there is no {\it stop} option since this command can be issued 1746%only if the port is already stopped). 1747%For example 1748%\begin{quote}\begin{verbatim} 1749% (4) 3 *EXIT t(1) (dbg)?- p change port to [np]: p print only 1750% (4) 3 *EXIT t(1) 1751% (3) 2 *EXIT s(1) 1752% (2) 1 *EXIT q(1) 1753% (5) 1 CALL r(1) (dbg)?- 1754%\end{verbatim}\end{quote} 1755%If any other key is typed, nothing is done. 1756%Note that in this command the asterisk printed with the port name 1757%is significant, other ports are not affected: 1758%\begin{quote}\begin{verbatim} 1759% (4) 3 EXIT e (dbg)?- p change port to [np]: p print only 1760% (4) 3 EXIT e 1761% (3) 2 EXIT d 1762% (2) 1 *EXIT b (dbg)?- 1763%\end{verbatim}\end{quote} 1764%A specified counter will repeat the command that many times and prompt 1765%for a leashing type on each repetition. 1766% 1767%\cmd{P}{print warnings}\\ 1768%This option toggles the printing of the warnings that are output 1769%in case of dangerous use of cut in coroutining mode. 1770% 1771%\nmcmd{t}{procedure trace mode}\\ 1772%Change the leashing of the displayed procedure. 1773%This is a two-key command, when it is executed, the debugger prompts 1774%for the second letter which may be one of 1775%\begin{itemize} 1776%\item f - full trace, the procedure is leashed and its {\it skip} 1777%flag, if it was set, is reset so that its subgoals are traced as well 1778% 1779%\item i - invisible, neither the procedure 1780%nor its children goals will be traced starting from its next invocation 1781%(a combination of {\bf n} and {\bf s}) 1782% 1783%\item n - no trace, the debugger will not show this procedure at all 1784%(but its subgoals are not affected by this) 1785% 1786%\item p - print only, from now on the procedure will be only printed and the 1787%debugger will not stop on it 1788% 1789%\item s - set the {\it skip} flag of the procedure so that its children goals 1790%are not traced 1791%\end{itemize} 1792%A specified counter will repeat the command that many times and prompt 1793%for a leashing type on each repetition. 1794 1795\end{descr} 1796 1797%---------------------------------------------------------------------- 1798\subsection{Environment Commands} 1799%---------------------------------------------------------------------- 1800\begin{descr}{1cm} 1801 1802\cmd{b}{break}\\ 1803This command is identical to the 1804\bipref{break/0}{../bips/lib/toplevel/break-0.html} call. 1805A new top-level loop is started with the debugger switched off. 1806The state of the database and the global settings is the same as 1807in the previous top-level loop. 1808After exiting the break level with \notation{\^{}D} (i.e., \notation{CTRL-D}), 1809or \notation{end_of_file} 1810the execution returns to the debugger and the last trace line is redisplayed. 1811 1812\cmd{N}{nodebug permanently}\\ 1813This command switches tracing off for the remainder of the execution 1814as well as for subsequent top-level queries. It affects the global 1815flag \notation{debugging}, setting it to \notation{nodebug}. 1816 1817%\ncmd{@}{Prolog goal}\\ 1818%This command allows the user to call a Prolog goal from within the debugger. 1819%When it is selected, the debugger prompts the user for a goal 1820%and executes it. 1821%If an error occurs while reading or executing the goal, 1822%the appropriate error handler is called and the execution returns 1823%back to the debugger. 1824% 1825%This command is similar to the {\bf break} command, except 1826%\index{b --- break (debugger cmd)} 1827%that the Prolog goal is read from the {\bf debug_input} stream 1828%and not from {\bf toplevel_input} like in {\bf break}. 1829%Thus it is possible to use this command inside macros 1830%and have the Prolog goal a part of the macro body. 1831%For example it is possible to define a macro '!' with the body 1832%{\bf \@nl, system(csh), nl} and then typing ! will start 1833%a subshell: 1834%\begin{quote}\begin{alltt} 1835%B (1) 0 CALL true (dbg)?- M 1836%enter macro letter: ! 1837%enter the macro contents terminated by newline: @nl, system(csh), 1838%nl\(<NL>\) 1839%B (1) 0 CALL true (dbg)?- ! 1840%usr\% date 1841%Tue Mar 14 12:17:37 MET 1989 1842%usr\% exit 1843%usr\% 1844%B (1) 0 CALL true (dbg)?- 1845%\end{alltt}\end{quote} 1846%Note also that if this command is used inside a macro and a fullstop 1847%has to be entered inside it (a dot followed by a newline would end 1848%the macro), either the sequence '\verb*+. +' can be used 1849%or the newline can be escaped by a backslash. 1850 1851\end{descr} 1852 1853%---------------------------------------------------------------------- 1854\section{Extending the Debugger} 1855%---------------------------------------------------------------------- 1856 1857\subsection{User-defined Ports} 1858 1859The standard set of ports in the debugger's box model can be extended by 1860the programmer. This facility is not so much intended for applications, 1861but rather for libraries that want to allow debugging in terms of 1862concepts of the library. Specific ports can be used to identify the 1863interesting events during execution of the library code (while the standard 1864tracing of the library internals can be suppressed by compiling the 1865library in nodebug-mode). 1866 1867The system provides 4 primitives that can generate 4 kinds of box model ports. 1868When inserted into the code, and when the debugger is on, 1869they will cause execution to stop and enter the debugger, 1870displaying a trace line with the user-defined port and data: 1871\begin{itemize} 1872\item \biptxtref{trace_call_port(+\pattern{Port},~?\pattern{Invoc},~?\pattern{Term})}{trace_call_port/3}{../bips/kernel/debug/trace_call_port-3.html} 1873 is used to create new ports similar to CALL ports, but the port name 1874 can be chosen freely. Such a port creates a new box. There must be 1875 a corresponding \predspec{trace_exit_port/0} to exit the box on 1876 success. 1877\item \biptxtref{trace_exit_port}{trace_exit_port/0}{../bips/kernel/debug/trace_exit_port-0.html} 1878 is used in conjunction with \predspec{trace_call_port/3} to exit a box 1879 on success. 1880\item \biptxtref{trace_point_port(+\pattern{Port},~?\pattern{Invoc},~?\pattern{Term})}{trace_point_port/3}{../bips/kernel/debug/trace_point_port-3.html} 1881 is used to create a standalone port, i.e., a port that causes the 1882 tracer to create a trace line, but does not create, enter or leave 1883 any box. 1884\item \biptxtref{trace_parent_port(+\pattern{Port})}{trace_parent_port/1}{../bips/kernel/debug/trace_parent_port-1.html} 1885 is used to create an additional port for the parent box, but does 1886 not enter or leave the box. 1887\end{itemize} 1888For example, \predspec{trace_call_port/3} and \predspec{trace_exit_port/0} 1889can be used to 1890create a more readable trace in the presence of source 1891transformations. Imagine that the goal \notation{Y is X*X-1} 1892has been flattened into the goal sequence \notation{*(X,X,T),-(T,1,Y)}. 1893By inserting the trace primitives the debugger can still show the 1894original source before transformation: 1895\begin{quote} 1896\begin{verbatim} 1897p(X,Y) :- 1898 trace_call_port(call,_, Y is X*X-1), 1899 *(X,X,T), 1900 -(T,1,Y), 1901 trace_exit_port. 1902\end{verbatim} 1903\end{quote} 1904The trace then looks like this: 1905\begin{quote} 1906\begin{verbatim} 1907[eclipse 8]: p(3,Y). 1908(1) 1 CALL p(3, Y) %> creep 1909(2) 2 CALL Y is 3 * 3 - 1 %> skip 1910(2) 2 EXIT 8 is 3 * 3 - 1 %> creep 1911(1) 1 EXIT p(3, 8) %> creep 1912Y = 8 1913\end{verbatim} 1914\end{quote} 1915Another example is the insertion of additional ports for existing boxes, 1916in particular the current parent box: 1917\begin{quote} 1918\begin{verbatim} 1919p :- 1920 trace_parent_port(clause1), 1921 writeln(hello), 1922 fail. 1923p :- 1924 trace_parent_port(clause2), 1925 writeln(world). 1926\end{verbatim} 1927\end{quote} 1928This gives rise to the following trace: 1929\begin{quote} 1930\begin{verbatim} 1931?- p. 1932 (1) 1 CALL p %> creep 1933 (1) 1 CLAUSE1 p %> creep 1934S (2) 2 CALL writeln(hello) %> creep 1935hello 1936S (2) 2 EXIT writeln(hello) %> creep 1937 (3) 2 CALL fail %> creep 1938 (3) 2 FAIL fail %> creep 1939 (1) 1 NEXT p %> creep 1940 (1) 1 CLAUSE2 p %> creep 1941S (4) 2 CALL writeln(world) %> creep 1942world 1943S (4) 2 EXIT writeln(world) %> creep 1944 (1) 1 EXIT p %> creep 1945Yes (0.00s cpu) 1946\end{verbatim} 1947\end{quote} 1948Note that the additional ports share the parent's invocation number, 1949so the \notation{i} command can be used to skip from one to the other. 1950 1951 1952\subsection{Attaching a Different User Interface} 1953 1954The tracer consists of a \defnotionni{trace generation} component (which is part 1955of the 1956{\eclipse} runtime kernel), and a \defnotionni{user interface} (which is part of 1957the development system). The standard {\eclipse} distribution contains two 1958user interfaces, a console-based one, and a graphical one which is part 1959of {\tkeclipse}. A programmable tracer interface (OPIUM/LSD) is under 1960development in the group of Mireille Ducasse at IRISA/Rennes. 1961Connecting new interfaces is relatively easy, for more detailed 1962information contact the {\eclipse} development team. 1963 1964 1965 1966\section{Switching To Creep Mode With \notation{CTRL-C}} 1967 1968When the debugger is on and a program is running, typing \notation{CTRL-C} 1969prompts for input of an option. The d-option switches the debugger to 1970\notation{creep} mode and continues executing the interrupted program. The 1971debugger will then stop at the next port of the running program. 1972\begin{quote} 1973\begin{verbatim} 1974[eclipse 1]: debug. 1975Debugger switched on - leap mode 1976[eclipse 2]: repeat,fail. 1977^C 1978 1979interruption: type a, b, c, d, e, or h for help : ? d 1980 (1) 1 *EXIT repeat %> 1981\end{verbatim} 1982\end{quote} 1983 1984%HEVEA\cutend 1985