Using the Debugger via the Command Line Interface

## 15.6 Using the Debugger via the Command Line Interface

- Counters and Command Arguments
- Commands to Continue Execution
- Commands to Modify Execution
- Display Commands
- Navigating among Goals
- Inspecting Goals and Data
- Changing the Settings
- Environment Commands

This section describe the commands available at the debugger prompt in the debugger’s command line interface (for the graphical user interface, please refer to the online documentation).

Commands are entered by typing the corresponding key (without newline), the case of the letters is significant. The action of some of them is immediate, others require additional parameters to be typed afterwards. Since the ECLiPSe debugger has the possibility to display not only the goal that is currently being executed (the current goal or procedure), but also its ancestors, some of the commands may work on the displayed procedure whatever it is, and others on the current one.

### 15.6.1 Counters and Command Arguments

Some debugger commands accept a counter (a small integer number) before the command letter (e.g., c, i.e., creep). The number is just prefixed to the command and terminated by the command letter itself. If a counter is given for a command that doesn’t accept a counter, it is ignored.

When a counter is used and is valid for the command, the command is repeated, decrementing the counter until zero. When repeating the command, the command and the remaining counter value is printed after the debugger prompt instead of waiting for user input.

Some commands prompt for a parameter, e.g., the j (jump) command asks for the number of the level to which to jump. Usually the parameter has a sensible default value (which is printed in square backets). If just a newline is typed, then the default value is taken. If a valid parameter value is typed, followed by newline, this value is taken. If an illegal letter is typed, the command is aborted.

### 15.6.2 Commands to Continue Execution

All commands in this section continue program execution. They difference between them is the condition under which execution will stop the next time. When execution stops again, the next trace line is printed and a new command is accepted.

n c
  creep
  This command allows exhaustive tracing: the execution stops at the next port of any leashed procedure. No further parameters are required, a counter n will repeat the command n times. It always applies on the current procedure, even when the displayed procedure is not the current one (e.g., during term inspection). An alias for the c command is to just type newline (Return-key).
n s
  skip
  If given at an entry port of a box (CALL, RESUME, REDO), this command skips the execution until an exit port of this box (EXIT, FAIL, LEAVE). If given in an exit port it works like creep. (Note that sometimes the i command is more appropriate, since it skips to the next port of the current box, no matter which). A counter, if specified, repeats this command.
n l
  leap
  Continues to the next spy point (any port of a procedure which has its spy flag set). A counter, if specified, repeats this command.
i par
  invocation skip
  Continue to the next port of the box with the invocation number specified. The default invocation number is the one of the current box. Common uses for this command are to skip from CALL to NEXT, from NEXT to NEXT/EXIT/FAIL, from *EXIT to REDO, or from DELAY to RESUME.
j par
  jump to level
  Continue to the next port with the specified nesting level (which can be higher or lower than the current one). The default is the parent’s level, i.e., to continue until the current box is exited, ignoring all the remaining subgoals of the current clause. This is particularly useful when a c (creep) has been typed where a s (skip) was wanted.
n
  nodebug
  This command switches tracing off for the remainder of the execution. However, the next top-level query will be traced again. Use N to switch tracing off permanently.
q
  query the failure culprit
  The purpose of this command is to find out why a goal has failed (FAIL) or was aborted with an exception (LEAVE). It prints the invocation number of the goal which caused the failure. You can then re-run the program in creep mode and type q at the first command prompt. This will then offer you to jump to the CALL port of the culprit goal.

      [eclipse 3]: p.
        (1) 1 CALL  p   %> skip
        (1) 1 FAIL  p   %> query culprit
      failure culprit was (3) - rerun and type q to jump there   %> nodebug? [y]
      No (0.00s cpu)

      [eclipse 4]: p.
        (1) 1 CALL  p   %> query culprit
      failure culprit was (3) - jump to invoc: [3]?
        (3) 3 CALL  r(1)   %> creep
        (3) 3 FAIL  r(...)   %> creep
        (2) 2 FAIL  q   %> creep
        (1) 1 FAIL  p   %> creep
      No (0.01s cpu)

v
  var/term modification skip
  This command sets up a monitor on the currently displayed term, which will cause a MODIFY-port to be raised on each modification to any variable in the term. These ports will all have a unique invocation number which is assigned and printed at the time the command is issued. This number can then be used with the i command to skip to where the modifications happen.

      [eclipse 4]: [X, Y] :: 1..9, X #>= Y, Y#>1.
        (1) 1 CALL  [X, Y] :: 1..9   %> var/term spy? [y]
      Var/term spy set up with invocation number (2)   %> jump to invoc: [1]? 2
        (2) 3 MODIFY  [X{[1..9]}, Y{[2..9]}] :: 1..9   %> jump to invoc: [2]?
        (2) 4 MODIFY  [X{[2..9]}, Y{[2..9]}] :: 1..9   %> jump to invoc: [2]?

  Note that these monitors can also be set up from within the program code using one of the built-ins spy_var/1 or spy_term/2.
z par
  zap
  This command allows to skip over, or to a specified port. When this command is executed, the debugger prompts for a port name (e.g., fail) or a negated port name (e.g., ∼exit). Execution then continues until the specified port appears or, in the negated case, until a port other than the specified one appears. The default is the negation of the current port, which is useful when exiting from a deep recursion (a long sequence of EXIT or FAIL ports).

### 15.6.3 Commands to Modify Execution

f par
  fail
  Force a failure of the procedure with the specified invocation number. The default is to force failure of the current procedure.
a
  abort
  Abort the execution of the current query and return to the top-level. The command prompts for confirmation.

### 15.6.4 Display Commands

This group of commands cause some useful information to be displayed.

d par
  delayed goals
  Display the currently delayed goals. The optional argument allows to restrict the display to goal of a certain priority only. The goals are displayed in a format similar to the trace lines, except that there is no depth level and no port name. Instead, the goal priority is displayed in angular brackets:

  >     [eclipse 5]: [X, Y] :: 1..9, X #>= Y, Y #>= X.
  >       (1) 1 CALL  [X, Y] :: 1..9   %> creep
  >       (1) 1 EXIT  [X{[1..9]}, Y{[1..9]}] :: 1..9   %> creep
  >       (2) 1 CALL  X{[1..9]} - Y{[1..9]}#>=0   %> creep
  >       (3) 2 DELAY  X{[1..9]} - Y{[1..9]}#>=0   %> creep
  >       (2) 1 EXIT  X{[1..9]} - Y{[1..9]}#>=0   %> creep
  >       (4) 1 CALL  Y{[1..9]} - X{[1..9]}#>=0   %> creep
  >       (5) 2 DELAY  Y{[1..9]} - X{[1..9]}#>=0   %> delayed goals
  >                                                     with prio: [all]?
  >     ------- delayed goals -------
  >       (3) <2>  X{[1..9]} - Y{[1..9]}#>=0
  >       (5) <2>  Y{[1..9]} - X{[1..9]}#>=0
  >     ------------ end ------------
  >       (5) 2 DELAY  Y{[1..9]} - X{[1..9]}#>=0   %>

u par
  scheduled goals
  Similar to the d command, but displays only those delayed goals that are already scheduled for execution. The optional argument allows to restrict the display to goal of a certain priority only. Example:

  >     [eclipse 13]: [X,Y,Z]::1..9, X#>Z, Y#>Z, Z#>1.
  >       (1) 1 CALL  [X, Y, Z] :: 1..9   %> creep
  >       (1) 1 EXIT  [X{[1..9]}, Y{[1..9]}, Z{[1..9]}] :: 1..9   %> creep
  >       (2) 1 CALL  X{[1..9]} - Z{[1..9]}+-1#>=0   %> creep
  >       (3) 2 DELAY  X{[2..9]} - Z{[1..8]}#>=1   %> creep
  >       (2) 1 EXIT  X{[2..9]} - Z{[1..8]}+-1#>=0   %> creep
  >       (4) 1 CALL  Y{[1..9]} - Z{[1..8]}+-1#>=0   %> creep
  >       (5) 2 DELAY  Y{[2..9]} - Z{[1..8]}#>=1   %> creep
  >       (4) 1 EXIT  Y{[2..9]} - Z{[1..8]}+-1#>=0   %> creep
  >       (6) 1 CALL  0 + Z{[1..8]}+-2#>=0   %> creep
  >       (3) 2 RESUME  X{[2..9]} - Z{[2..8]}#>=1   %> scheduled goals
  >                                                     with prio: [all]?
  >     ------ scheduled goals ------
  >       (5) <2>  Y{[2..9]} - Z{[2..8]}#>=1
  >     ------------ end ------------
  >       (3) 2 RESUME  X{[2..9]} - Z{[2..8]}#>=1   %>

G
  all ancestors
  Prints all the current goal’s ancestors from the oldest to the newest. The display format is similar to trace lines, except that .... is displayed in the port field.
.
  print definition
  If given at a trace line, the command displays the source code of the current predicate. If the predicate is not written in Prolog, or has not been compiled from a file, or the source file is inaccessible, no information can be displayed.
w
  write source context for current goal
  Lists the source lines around the current goal displayed by the trace line, showing the context of the goal. For example:

  >       (230) 4 CALL  check_word(what, _5824)   %> write source lines
  >     Source file: /homes/user/EclipseTests/Chatq/newtop
  >       241  :- mode check_words(+,-).
  >       242
  >       243  check_words([],[]).
  >       244  check_words([Word|Words],[RevWord|RevWords]) :-
  >       245>    check_word(Word,RevWord),
  >       245     check_words(Words,RevWords).
  >       246
  >       247  :- mode check_word(+,-).
  >       248
  >        %>

  The listing shows the line numbers for the source lines, with a > marking the line with the current goal. Note it is the actual body goal that is shown, rather than the predicate definition as in the . command. An optional numeric argument can be given before the command, specifying the number of lines surrounding (i.e., before and after) the current goal that should be listed:

  >         %> 2write source lines
  >     Source file: /homes/user/EclipseTests/Chatq/newtop
  >       243  check_words([],[]).
  >       244  check_words([Word|Words],[RevWord|RevWords]) :-
  >       245>    check_word(Word,RevWord),
  >       245     check_words(Words,RevWords).
  >       246
  >        %>

  Source is only shown if the source information is available—that is, the code has to be compiled debuggable from a file, and not all goals have source information; for example, goals in meta-calls (e.g., those inside a call/1). Also, source context cannot be shown at a RESUME port.

h
  help
  Print a summary of the debugger commands.
?
  help
  Identical to the h command.

### 15.6.5 Navigating among Goals

While the debugger waits for commands, program execution is always stopped at some port of some predicate invocation box, or goal. Apart from this current goal, two types of other goals are also active. These are the ancestors of the current goal (the enclosing, not yet exited boxes in the box model) and the delayed goals. The debugger allows to navigate among these goals and inspect them.

g
  ancestor
  Move to and display the ancestor goal (or parent) of the displayed goal. Repeated application of this command allows to go up the call stack.
x par
  examine goal
  Move to and display the goal with the specified invocation number. This must be one of the active goals, i.e., either an ancestor of the current goal or one of the currently delayed goals. The default is to return to the current goal, i.e., to the goal at whose port the execution is currently stopped.

### 15.6.6 Inspecting Goals and Data

This family of commands allow the subterms in the goal displayed at the port to be inspected. The ability to inspect subterms is designed to help overcome two problems when examining a large goal with the normal display of the goal at a debug port:

1. Some of the subterms may be omitted from the printed goal because of the print-depth;
2. If the user is interested in particular subterms, it may be difficult to precisely locate them from the surrounding arguments, even if it is printed.

With inspect subterm commands, the user is able to issue commands to navigate through the subterms of the current goal and examine them. A current subterm of the goal is maintained, and this is printed after each inspect subterm command, instead of the entire goal. Initially, the current subterm is set to the goal, but this can then be moved to the subterms of the goal with navigation commands.

Once inspect subterm is initiated by an inspect subterm command, the debugger enters into the inspect subterm mode. This is indicated in the trace line by INSPECT instead of the name of the port, and in addition, the goal is not shown on the trace line:

>             INSPECT  (length/2)   %>

Instead of showing the goal, a summary of the current subterm—generally its functor and arity if the subterm is a structure—is shown in brackets.

# par
  move down to parth argument
  The most basic command of inspect subterm is to move the current subterm to an argument of the existing current subterm. This is done by typing a number followed by carriage return, or by typing `#`, which causes the debugger to prompt for a number. In both cases, the number specifies the argument number to move down to. In the following example, the `#` style of the command is used to move to the first argument, and the number style of the command to move to the third argument:

  >       (1) 1 CALL  foo(a, g(b, [1, 2]), X)   %> inspect arg #: 1<NL>
  >     a
  >             INSPECT  (atom)   %>

  >       (1) 1 CALL  foo(a, g(b, [1, 2]), X)   %>  3<NL>
  >     X
  >             INSPECT  (var)   %>

  The new current subterm is printed, followed by the INSPECT trace line. Notice that the summary shows the type of the current subterm, instead of Name/Arity, since in both cases the subterms are not structures.

  If the current subterm itself is a compound term, then it is possible to recursively navigate into the subterm:

  >       (1) 1 CALL  foo(a, g(b, [1, 2]), X)   %> 2<NL>
  >     g(b, [1, 2])
  >             INSPECT  (g/2)   %> 2<NL>
  >     [1, 2]
  >             INSPECT  (list  1-head 2-tail)   %> 2<NL>
  >     [2]
  >             INSPECT  (list  1-head 2-tail)   %>

  Notice that lists are treated as a structure with arity 2, although the functor (./2) is not printed.

  In addition to compound terms, it is also possible to navigate into the attributes of attributed variables:

  >     [eclipse 21]: suspend(foo(X), 3, X->inst), foo(X).<NL>
  >       (1) 1 DELAY  foo(X)   %> <NL>
  >     creep
  >       (2) 1 CALL  foo(X)   %> 1<NL>
  >     X
  >             INSPECT  (attributes  1-suspend 2-fd )   %>1<NL>
  >     suspend(['SUSP-1-susp'|_218] - _218, [], [])
  >             INSPECT  (struct suspend/3)   %>

  The variable X is an attributed variable in this case, and when it is the current subterm, this is indicated in the trace line. The debugger also shows the user the currently available attributes, and the user can then select one to navigate into (fd is available in this case because the finite domain library was loaded earlier in the session. Otherwise, it would not be available as a choice here).

  Note that the suspend/3 summary contains a struct before it. This is because the suspend/3 is a predefined structure with field names (see section 5.1). It is possible to view the field names of such structures using the . command in inspect mode.

  If the number specified is larger than the number of the arguments of the current subterm, then an error is reported and no movement is made:

  >     foo(a, g(b, [1, 2]), 3)
  >             INSPECT  (foo/3)   %> 4<NL>

  >     Out of range.....

  >     foo(a, g(b, [1, 2]), 3)
  >             INSPECT  (foo/3)   %>

n uparrow key
  move current subterm up by n levels
n A
  move current subterm up by n levels
  In addition to moving the current subterm down, it can also be moved up from its current position. This is done by typing the uparrow key. This key is mapped to A by the debugger, so one can also type A. Typing A may be necessary for some configurations (combination of keyboards and operating systems) because the uparrow key is not correctly mapped to A.

  An optional argument can preceded the uparrow keystroke, which indicates the number of levels to move up. The default is 1:

  >       (1) 1 CALL  foo(a, g(b, [1, 2]), 3)   %> 2<NL>
  >     g(b, [1, 2])
  >             INSPECT  (g/2)   %> 1<NL>
  >     b
  >             INSPECT  (atom)   %> up subterm
  >     g(b, [1, 2])
  >             INSPECT  (g/2)   %> 1up subterm
  >     foo(a, g(b, [1, 2]), 3)
  >             INSPECT  (foo/3)   %>

  The debugger prints up subterm when the uparrow key is typed. The current subterm moves back up the structure to its parent for each level it moves up, and the above move can be done directly by specifying 2 as the levels to move up:

  >     b
  >             INSPECT  (atom)   %> 2up subterm
  >     foo(a, g(b, [1, 2]), 3)
  >             INSPECT  (foo/3)   %>

  If the number of levels specified is more than the number of levels that can be traversed up, the current subterm stops at the toplevel:

  >       (1) 1 CALL  foo(a, g(b, [1, 2]), 3)   %> 2<NL>
  >     g(b, [1, 2])
  >             INSPECT  (g/2)   %> 2<NL>
  >     [1, 2]
  >             INSPECT  (list  1-head 2-tail)   %> 5up subterm
  >     foo(a, g(b, [1, 2]), 3)
  >             INSPECT  (foo/3)   %>

0
  move current subterm to toplevel
  It is possible to quickly move back to the top of a goal that is being inspected by specifying 0 (zero) as the command:

  >       (1) 1 CALL  foo(a, g(b, [1, 2]), 3)   %> 2<NL>
  >     g(b, [1, 2])
  >             INSPECT  (g/2)   %> 2<NL>
  >     [1, 2]
  >             INSPECT  (list  1-head 2-tail)   %> 2<NL>
  >     [2]
  >             INSPECT  (list  1-head 2-tail)   %> 2<NL>
  >     []
  >             INSPECT  (atom)   %> 0<NL>
  >     foo(a, g(b, [1, 2]), 3)
  >             INSPECT  (foo/3)   %>

  Moving to the top can also be done by the `#` command, and not giving any argument (or notation0) when prompted for the argument.

n leftarrow key
  move current subterm left by n positions
n D
  move current subterm left by n positions
  The leftarrow key (or the equivalent D) moves the current subterm to a sibling subterm (i.e., fellow argument of the parent structure) that is to the left of it. Consider the structure foo(a, g(b, [1, 2]), 3), then for the second argument, g(b, [1, 2]), a is its (only) left sibling, and 3 its (only) right sibling. For the third argument, 3, both a (distance of 2) and g(b, [1, 2]) (distance of 1) are its left siblings. The optional numeric argument for the command specifies the distance to the left that the current subterm should be moved. It defaults to 1.

  >     foo(a, g(b, [1, 2]), 3)
  >             INSPECT  (foo/3)   %> 3<NL>
  >     3
  >             INSPECT  (integer)   %> 2left subterm
  >     a
  >             INSPECT  (atom)   %>

  If the leftward movement specified would move the argument position before the first argument of the parent term, then the movement will stop at the first argument:

  >     foo(a, g(b, [1, 2]), 3)
  >             INSPECT  (foo/3)   %> 3<NL>
  >     3
  >             INSPECT  (integer)   %> 5left subterm
  >     a
  >             INSPECT  (atom)   %>

  In the above example, the current subterm was at the third argument, thus trying to move left by 5 argument positions is not possible, and the current subterm stopped at leftmost position—the first argument.

n rightarrow key
  move current subterm right by n positions
n C
  move current subterm right by n positions
  The rightarrow key (or the equivalent C) moves the current subterm to a sibling subterm (i.e., fellow argument of the parent structure) that is to the right of it. Consider the structure foo(a, g(b, [1, 2]), 3), then for the first argument, a, g(b, [1, 2]) is a right sibling with distance of 1, and 3 is a right sibling with distance of 2. The optional numeric argument for the command specifies the distance to the left that the current subterm should be moved. It defaults to 1.

  >     foo(a, g(b, [1, 2]), 3)
  >             INSPECT  (integer)   %> 2left subterm
  >     a
  >             INSPECT  (atom)   %>

  If the rightward movement specified would move the argument position beyond the last argument of the parent term, then the movement will stop at the last argument:

  >     foo(a, g(b, [1, 2]), 3)
  >             INSPECT  (foo/3)   %> 3<NL>
  >     3
  >             INSPECT  (integer)   %> right subterm
  >     3
  >             INSPECT  (integer)   %>

  In the above example, the current subterm was at the third (and last) argument, thus trying to move to the right (by the default 1 position in this case) is not possible, and the current subterm remains at the third argument.

n downarrow key
  move current subterm down by n levels
n B
  move current subterm down by n levels
  The down-arrow key moves the current subterm down from its current position. This command is only valid if the current subterm is a compound term and so has subterms itself. A structure has in general more than one argument, so there is a choice of which argument position to move down to. This argument is not directly specified by the user as part of the command, but is implicitly specified: the argument position selected is the argument position of the current subterm within its parent:

      foo(a, g(b, [1, 2]), 3)
              INSPECT  (foo/3)   %> 2<NL>
      g(b, [1, 2])
              INSPECT  (list  1-head 2-tail)   %> 3down subterm 2 for 3 levels
      []
              INSPECT  (atom)   %>

  In the above example, the user moves down into the second argument, and then use the down-arrow key to move down into the second argument for 2 levels—the numeric argument typed before the arrow key specified the number of levels that the current subterm was moved down by. The command moves into the second argument because it was at the second argument position when the command was issue.

  However, there is not always an argument position for the current sub-term. For example, when the current sub-term is at the toplevel of the goal or if it is at an attribute. In these cases, the default for the argument position to move down into is the first argument:

  >             INSPECT  (atom)   %> 0<NL>
  >     foo(a, g(b, [1, 2]), 3)
  >             INSPECT  (foo/3)   %> down subterm 1 for 1 levels
  >     a
  >             INSPECT  (atom)   %>

  In the above example, the down-arrow key is typed at the top-level, and thus the argument position chosen for moving down is first argument, with the default numeric argument for the

  If the argument position to move into is beyond the range of the current subterm’s number of arguments, then no move is performed:

  >       (1) 1 CALL  foo(a, b, c(d, e))   %> 3<NL>
  >     c(d, e)
  >             INSPECT  (c/2)   %> Out of range after traversing down arg...
  >     c(d, e)
  >             INSPECT  (c/2)   %>

  In this case, the down-arrow key was typed in the second trace line, which had the current subterm at the third argument of its parent term, and thus the command tries to move the new current subterm to the third argument of the current sub-term, but the structure does not have a third argument and so no move was made. In the case of moving down multiple levels, then the movement will stop as soon as the argument position to move down to goes out of range.

  Moving down is particularly useful for traversing lists. As discussed, lists are really structures with arity two, so the #N command would not move to the Nth element of the list. With the down-arrow command , it is possible to move into the Nth position in one command:

      [eclipse 30]: foo([1,2,3,4,5,6,7,8,9]).
        (1) 1 CALL  foo([1, 2, 3, ...])   %> 1<NL>
      [1, 2, 3, 4, ...]
              INSPECT  (list  1-head 2-tail)   %> 2<NL>
      [2, 3, 4, 5, ...]
              INSPECT  (list  1-head 2-tail)   %> 6down subterm 2 for 6 levels
      [8, 9]
              INSPECT  (list  1-head 2-tail)   %>

  In order to move down a list, we repeatedly move into the tail of the list—the second argument position. In order to do this with the down-arrow command, we must be at the second argument position first, and this is done in the second trace line. Once this is done, then it is possible to move arbitrarily far down the list in one go, as is shown in the example.

.
  print structure definition
  In ECLiPSe, it is possible to define field names for structures (see section 5.1). If the inspector encounters such structures, then the user can get the debugger to print out the field names. Note that this functionality only applies within the inspect subterm mode, as the debugger command “.” normally prints the source for the predicate. The fact that a structure has defined field names are indicated by a “struct” in the summary:

  >     :- local struct(capital(city,country)).

  >     .....

  >       (1) 1 CALL  f(capital(london, C))   %> 1<NL>
  >     capital(london, C)
  >             INSPECT  (struct capital/2)   %> structure definition:
  >     1=city 2=country
  >        %>

  In this example, a structure definition was made for capital/2. When this structure is the current subterm in the inspect mode, the struct in the summary for the structure indicates that it has a structure definition. For such structures, the field names are printed by the structure definition command.

  If the command is issued for a term that does not have a structure definition, an error would be reported:

  >             INSPECT  (f/1)   %> structure definition:
  >     No struct definition for term f/1@eclipse.
  >        %>

p
  show subterm path
  As the user navigates into a term, then at each level, a particular argument position (or attribute, in the case of attributed variables) is selected at each level. The user can view the position the current subterm is at by the p command. For example,

  >       (1) 1 CALL  foo(a, g(b, [1, 2]), 3)   %> 2<NL>
  >     g(b, [1, 2])
  >             INSPECT  (g/2)   %> 2<NL>
  >     [1, 2]
  >             INSPECT  (list  1-head 2-tail)   %> 1<NL>
  >     1
  >             INSPECT  (integer)   %> p
  >     Subterm path:  2, 2, 1
  >        %>

  The subterm path shows the argument positions taken at each level of the toplevel term to reach the current subterm, starting from the top.

  Extra information (in addition to the numeric argument position) will be printed if the subterm at a particular level is either a structure with field names or an attributed variable. For example:

      :- local struct(capital(city,country)).

      .....

      [eclipse 8]: suspend(capital(london, C), 3 ,C -> inst),
                           f(capital(london, C)).

      ....

        (2) 1 CALL  f(capital(london, C))   %> 1<NL>
      capital(london, C)
              INSPECT  (struct capital/2)   %> 2<NL>
      C
              INSPECT  (attributes  1-suspend )   %> 1<NL>
      suspend(['SUSP-1-susp'|_244] - _244, [], [])
              INSPECT  (struct suspend/3)   %> 1<NL>
      ['SUSP-1-susp'|_244] - _244
              INSPECT  (-/2)   %>
      Subterm path: 1, country of capital (2), attr: suspend, inst of
      suspend (1) %>

  In this example, except for the toplevel argument, all the other positions are either have field names or are attributes. This is reflected in the path, for example, country of capital (2) shows that the field name for the selected argument position (2, shown in brackets) is country, and the structure name is capital. For the “position” of the selected attribute (suspend) of the attributed variable C, the path position is shown as attr: suspend.

  #### Interaction between inspect subterm and output modes

  The debugger commands that affect the print formats in the debugger also affects the printed current subterm. Thus, both the print depth and output mode of the printed subterm can be changed.

  The changing of the output modes can have a significant impact on the inspect mode. This is because for terms which are transformed by write macros before they are printed (see chapter 13), different terms can be printed depending on the settings of the output modes. In particular, output transformation is used to hide many of the implementation related extra fields and even term names of many ECLiPSe data structures (such as those used in the finite domain library). For the purposes of inspect subterms, the term that is inspected is always the printed form of the term, and thus changing the output mode can change the term that is being inspected.

  Consider the example of looking at the attribute of a finite domain variable:

  >     A{[4..10000000]}
  >             INSPECT  (attributes  1-suspend 2-fd )   %> 2<NL>
  >     [4..10000000]
  >             INSPECT  (list  1-head 2-tail)   %> 1<NL>
  >     4..10000000
  >             INSPECT  (../2)   %> 2up subterm
  >     A{[4..10000000]}
  >             INSPECT  (attributes  1-suspend 2-fd )   %> <o>
  >     current output mode is "QPm", toggle char: T
  >     new output mode is "TQPm".
  >     A{[4..10000000]}
  >             INSPECT  (attributes  1-suspend 2-fd )   %> 2<NL>
  >     fd(dom([4..10000000], 9999997), [], [], [])
  >             INSPECT  (struct fd/4)   %> 1<NL>
  >     dom([4..10000000], 9999997)
  >             INSPECT  (dom/2)   %>

  After selecting the output mode T, which turns off any output macros, the internal form of the attribute is shown. This allows previously hidden fields of the attribute to be examined by the subterm navigation. Note that if the current subterm is inside a structure which will be changed by a changed output mode (such as inside the fd attribute), and the output mode is changed, then until the current subterm is moved out of the structure, the existing subterm path is still applicable.

  Also, after a change in output modes, the current subterm will still be examining the structure that it obtained from the parent subterm. Consider the finite domain variable example again:

  >     4..10000000
  >             INSPECT  (../2)   %> up subterm
  >     [4..10000000]        ***** printed structure 1
  >             INSPECT  (list  1-head 2-tail)   %> <o>
  >     current output mode is "QPm", toggle char: T
  >     new output mode is "TQPm".
  >     [4..10000000]
  >             INSPECT  (list  1-head 2-tail)   %> up subterm
  >     A{[4..10000000]}
  >             INSPECT  (attributes  1-suspend 2-fd )   %> 2
  >     fd(dom([4..10000000], 9999997), [], [], [])
  >             INSPECT  (struct fd/4)   %> <o>
  >     current output mode is "QPmT", toggle char: T
  >     new output mode is "QPm".
  >     fd(4..10000000, [], [], [])    ***** printed structure 2
  >             INSPECT  (struct fd/4)   %>

  Printed structures 1 and 2 in the above example are at the same position (toplevel of the finite domain structure), and printed with the same output mode (QPm), but are different because the structure obtained from the parent subterm is different—in printed structure 2, the output mode was not changed until after the fd/4 structure was the current subterm.

### 15.6.7 Changing the Settings

The following commands allow to change the parameters which influence the way the tracing information is displayed or processed.

< par
  set print depth
  Allows to modify the print_depth, i.e., the depth up to which nested argument terms are printed. Everything nested deeper than the specified depth is abbreviated as `...`. Note that the debugger has a private print_depth setting with default 5, which is different from the global setting obtained from get_flag/2.
> par
  set indentation step width
  Allows to specify the number of spaces used to indent trace lines according to their depth level. The default is 0.
m
  module
  Toggles the module printing in the trace line. If enabled, the module from where the procedure is called is printed in the trace line:

  >       (1) 1 CALL  true   %> show module
  >       (1) 1 CALL  eclipse : true   %>

o
  output mode
  This command allows to modify the options used when printing trace lines. It first prints the current output_mode string, as obtained by get_flag/2, then it prompts for a sequence of characters. If it contains valid output mode flags, the value of these flags is then inverted. Typing an invalid character will display a list describing the different options. Note that this command affects the global setting of output_mode.

  >       (1) 1 CALL  X is length([1, 2, ...])   %> current output mode
  >                                                 is "QPm", toggle char: V
  >     new output mode is "VQPm".
  >       (1) 1 CALL  X_72 is length([1, 2, ...])   %> current output mode
  >                                                 is "QVPm", toggle char: O
  >     new output mode is "OQVPm".
  >       (1) 1 CALL  is(X_72, length([1, 2, ...]))   %> current output mode
  >                                                 is "OQVPm", toggle char: .
  >     new output mode is ".OQVPm".
  >       (1) 1 CALL  is(X_72, length(.(1, .(2, .(...)))))   %>

+
  set a spy point
  Set a spy point on the displayed procedure, the same as using the spy/1 predicate. It is possible to set a spy point on any existing procedure, even on a built-in on external one. If the procedure already has a spy point, an error message is printed and any counter is ignored.

  Note that the debugger does not check for spy points that occur inside skipped procedures or during the execution of any other skip command than the leap command l.

−
  remove a spy point
  Similarly to the previous command, this one removes a spy point from a procedure, if it has one.

### 15.6.8 Environment Commands

b
  break
  This command is identical to the break/0 call. A new top-level loop is started with the debugger switched off. The state of the database and the global settings is the same as in the previous top-level loop. After exiting the break level with ^D (i.e., CTRL-D), or end_of_file the execution returns to the debugger and the last trace line is redisplayed.
N
  nodebug permanently
  This command switches tracing off for the remainder of the execution as well as for subsequent top-level queries. It affects the global flag debugging, setting it to nodebug.