:aliases

tpl-command, tpl package

Arguments:

This command prints the user defined command aliases (but not system defined top-level command -- see :help). Command aliases are added with the function :alias.

See top-level.html for more information on top-level commands.

:args

tpl-command, tpl package

Arguments: &key save

Lisp stores some function arguments in registers, rather than on the stack. This allows code to run significantly faster, but makes debugging harder, since the registers storing the arguments may be overwritten when an unhandled error occurs, and therefore the values will not be available for examination when debugging.

Lisp can optionally save values stored in registers (at the cost of worse performance). If argument saving is enabled, the argument values in registers will be saved and available for debugging. If argument saving is disabled, those argument values will not be saved. Unsaved arguments show up as :unknown in stack backtraces (as printed by :zoom).

This command either reports whether such arguments are saved or specifies whether arguments should be saved or should not be saved.

If the save is unspecified, this command reports on the current status of argument saving, printing (:save t) if arguments are being saved, (:save nil) if they are not.

If the save is specified t or nil, argument saving will start or stop, respectively.

The setf'able function argument-saving is the functional equivalent of this command. It takes no argument and returns t or nil as arguments are or are not saved.

Note that on some architectures (in 6.2, only the Sparc, including the 64-bit Sparc), arguments are always saved. On those architectures, this command has no effect.

See top-level.html for more information on top-level commands.

:arrest

tpl-command, tpl package

Arguments: process &rest processes

Arrests for debugging all processes given as arguments. The processes are arrested by adding :debugging to the list of arrest reasons for each process. Note that the listener process cannot be arrested.

The process and processes argument can specify as many processes as desired. Each argument can be:

• A string, which is processed as described below.
• A symbol, which is evaluated to produce a process object, a string, an integer, or a symbol. If the value is a symbol, its print name is used as if that were the string provided.
• A list, which is evaluated to produce a process object, a string, an integer, or a symbol. If the value is a symbol, its print name is used as if that were the string provided.
• An integer, which designated the process whose process-sequence value is that integer.

Strings are compared with process names. All processes whose names exactly match the string are considered matches. If no process name exactly matches, then all processes whose names contain the string as a substring are considered matches. (For example, if there are processes with names "Listener 1" and "Initial Lisp Listener", both match the string "ener".) For this command, multiple matches of parts of names with the string are considered ambiguous and the command fails with a diagnostic.

Strings which match no process cause the command to fail with a diagnostic.

The minimal abbreviation of :arrest is :arr.

See top-level.html for more information on top-level commands. See multiprocessing.html for information on multiprocessing.

:boe

tpl-command, tpl package

Arguments: (doit t) &key throws-too

When called with doit true (the default), this command marks the current frame in such a way that a break loop is invoked after the frame is removed from the stack because the function associated with the frame is returned from. No break will occur if the frame is removed because of a throw unless the throws-too keyword argument is specified true. The debugger indicates the marked frame by placing a * to the left of the frame when printing the stack.

The break-on-exit marker is removed from the current frame if :boe is called with doit specified nil.

When the break-on-exit break loop is entered, the frame contains a vector containing the return value(s) of the frame just exited. A single return value is displayed in the boe frame itself. These can be exammined by making that frame the current frame and inspecting it. See Break on exit is debugging.html for some examples.

:boe cannot be abbreviated.

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger.

:bottom

tpl-command, tpl package

Arguments: &key zoom

This command and :top move the current frame to the bottom (oldest frame) or the top (newest frame) of the stack.

The zoom keyword argument controls whether a :zoom is done after the current frame pointer is moved. That argument defaults to the value of the special variable tpl:*auto-zoom*.

The minimal abbreviation for :bottom is :bo. That for :top is :to.

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger.

:break

tpl-command, tpl package

Arguments: &optional mode &rest mode-values

This command allows the user to add or delete breakpoints and to print out information about the breakpoints currently in use.

Called without arguments, this command prints information on what breakpoints are set, if any. Breakpoint options, described below, are displayed in the output.

cl-user(131): :break
No breakpoints set
cl-user(132): :break open
Adding #<Function open>: 0
               0: 48 81 ec 88 01 subq   rsp,$392      ; 49
                  00 00 
cl-user(133): :break
#<Function open>:  asm: pc=0 not yet hit
cl-user(134): 

Called with arguments, :break sets breakpoints or otherwise manages them.

Whether or not a breakpoint is effective (that is stops code execution when reached) depends on whether it is installed or uninstalled. An installed breakpoint is one which will cause normal execution to stop and the debugger entered if an attempt is made to execute the instruction at that location. An uninstalled breakpoint will not cause such an interruption of execution. Deleted breakpoints are always uninstalled but otherwise whether breakpoints are or are not installed depends on (as we said just above) whether ldb debugging mode is on, see :ldb, or the code being evaluated is within the body of with-breakpoints-installed form.

The situation is further complicated by the fact that when a breakpoint is hit and stops execution, the debugging mode changes from ldb to ldb-step and breakpoints are then uninstalled. See The Lisp DeBug (ldb) stepper in debugging.html for information on this point.

Again, :break called with arguments adds or deletes breakpoints from the current breakpoint set. Its arguments are mode and mode-values.

mode can be

• :add or add, to add breakpoints. mode-values in that case should be one or more breakpoint specifications (described just below). Any number of breakpoint specifications can be specified. If none are specified, the command is a no-op, i.e. does nothing. If the first part of the specification is unambiguous (e.g. not add or del then the :add or add may be left out.
• :del or del, to delete breakpoints. mode-values in that case should be breakpoint specifications (described just below) for the breakpoints to be deleted (they must have been previously added). Any number of breakpoint specifications can be specified. If none are specified, the command is a no-op, i.e. does nothing.
• nil, to delete all breakpoints. Note that if you are currently stopped at a breakpoint, stepping (e.g. by hitting return) will continue stepping, because you're asking it to "step" (i.e. to break at the next instruction, in this particular case). To "continue" on after removing all breakpoints, use :step cont rather than :step :over 0 (which is the default at startup for the repeat function of hitting the return key).

A breakpoint specification is made up of a particular pc (program counter, look at the output of disassemble) offset from the beginning of a particular function. A single breakpoint can be specified by

function-name [offset] where offset defaults to 0. Multiple breakpoints can be specified by simply naming pairs:

foo 10 bar 20

When multiple breakpoints are specified, the offsets are not optional. However, multiple breakpoints within the same function can be specified by leaving out all but the first function name; thus

foo 10 20 30

is equivalent to specifying

foo 10 foo 20 foo 30

The function-name can also be elided if it is the only function that has breakpoints already set on it, or if it is the most recent function for which the lisp has stopped for a breakpoint.

Location specification

In the examples above (like foo 10), the numeric value (10) is a relative program counter, 10 bytes after the start of the function foo. You can also specify a character position, or a record number. The full specification is:

<function-name> [:pc | :pos | :rec] number

:pc for offest from the program counter; :pos for character position; and :rec for record number. The default is :pc, so that is what is used in all examples above. Thus:

  :break foo 10

is the same as

  :break foo :pc 10

Either will set a breakpoint within function foo which contains program-counter location 10 (the instruction or form may start precisely at 10, or it may start earlier but contain pc 10 as part of it).

 :break foo :rec 4

will select the fifth (zero-based) source debug record and set the breakpoint there.

Note: If none of :pc, :rec, or :pos are given and an integer is also not given, then the default is :rec 0:

 :br foo

will set the breakpoint to the first record for function foo. It may be at pc 0, and if the language for foo's breakpoints is :asm then the breakpoint will always be at pc location zero (since :asm breakpoint records are manufactured on the fly).

 :br foo :pos 12497

will set the breakpoint whose form starts at character-position 12497 in the file. If there are multiple such records, the one which has the lowest level (probably a level 0 record, which lexically appears in the file) is selected. Usually, the form will start with a left paren, and the file position is 0-based (contrast this with the 1-based position indication of emacs, so it might become a bit confusing).

Note: A breakpoint is set as soon as an integer is seen in the :break command, or, if no integer is seen, when the command arguments have been exhausted or a new function name is seen at which time the integer 0 is used). A function name starts a new breakpoint. If some of the above options are specified after an integer is seen, but before the end of the command or a new function, then that option is ignored.

Other options: :slide, :set, :inside, :not-inside, :language, etc.

The options are :slide, :set, :inside, :not-inside, :include-process, :exclude-process, :start-debug, :end-debug, :trace, :backend, :mixed, :width, and :early. These options may take arguments.

:slide

This option doesn't actually set the breakpoint, but sets the slide point instead. Sliding is a method for navigating around the source debug info for a function without actually setting these breakpoints. Contrast this option, which sets the slide point using breakpoint criteria, with the :slide top-level command, which allows the slide point to be moved around using navigation directions.

:set

Normally, sliding doesn't actually set a breakpoint; it only navigates around breakpoint structures. This option sets an actual breakpoint based on the current slide point. See also the description of the :slide top-level command.

:language language-name

This option establishes the preferred language for a breakpoint. Breakpoints set within the same command after this option will be of the specified language. The language can currently be :asm, :lisp, or :python (when cl-python is loaded). Other languages may follow.

:inside function-or-list

:not-inside function-or-list

These are identical in specification and operation the :inside and :not-inside option to trace. These determine whether the breakpoint is stopped at based on whether there is or is not a particular enclosing function on the stack. See the :inside and :not-inside options in the description of the trace macro. The argument function-or-list should be a function name, function object, or a list of those.

:include-process process

:exclude-process process

These options takes a single argument which designates the process to include or exclude. Each option can be used multiple times, as long as the opposite option has not yet been used. If neither of these options are used, then breakpoints will stop regardless of the process that is executing that code. If only one process is specified in :include-process then all others will be excluded by default.

:start-debug

The breakpoint being set is marked as a :start-debug breakpoint, which means it will not stop like other breakpoints do, but it will cause the thread being stopped at to be marked as being debugged. This means that the garbage collector will walk the stack in a conservative manner, which also means that variable slots in the stack which have died but which still have valid Lisp values in them will continue to be forwarded, so as to allow the user to see local variables even after they have just died.

:end-debug

The breakpoint being set is not stopped at, but signals to the debugger to revert the current thread back to not being debugged (i.e. back to precise-gc).

:trace

Instead of stopping, the breakpoint will be printed out.

:backend backend

The desired backend is used for presentation. The only two useful backends for the stepper are :tty and :flip-tty. See Source stepper backends for more info on backends.

:mixed boolean

If this option is true, and the current backend is :flip-tty, then the Lisp source and assembler will be intermixed as part of the output. This tends to defeat the flip-book effect, but is sometimes useful when it is desired to understand what the underlying assembler code is doing in service to the current Lisp form.

:width number

When the :flip-tty backend is in effect, the width is the number of breakpoint records that might be displayed before and after the current breakpoint. Only appropriate records are displayed, so if there are no previous or subsequent records, the current breakpoint record may be the first, last, or only record displayed.

The number should be chosen to be useful - there is no limit to how big the flip-window is. The default width is 2, which means that up to 2 records may be displayed before and after the current record, for a total of 5 records under default operation. The width is global, and once set is only changed by another `:width sub-command.

:early boolean

When moving through breakpoint records, a call to a function often has two breakpoints generated for it: the point of the call itself, which is right before the call, and also the point where the call just begins to be processed, called an "early" breakpoint.

Consider the following example:

cl-user(1): (setq *load-local-names-info* t *load-source-file-info* t *load-source-debug-info* t)
t
cl-user(2): (setq *record-source-file-info* t)
t
cl-user(3): (shell "cat callers.cl")

(eval-when (compile) (declaim (optimize debug)))

(defun foo (x y z)
  (bar (car x) (+ y z)))

(defun bar (a b)
  (list a b))
0
cl-user(4): :cl callers
;;; Compiling file callers.cl
;;; Writing fasl file /tmp/cfta174211327501
;;; Moving fasl file /tmp/cfta174211327501 to callers.fasl
;;; Fasl write complete
; Fast loading /net/gemini/home/duane/callers.fasl
cl-user(5): (print-function-meta-info 'foo)
source debug info for foo in #P"callers.cl":
i  ix  lev prev nxt  br  encl  end | par chld |  pc  nxt  br  e-type br-type  st  end   form
 Starting function #<Function foo>
   0    0 nil  2    nil  nil  12   | nil    1 | 0    16   nil   nil   nil  51   94   (defun foo (x y z) (bar (car x) (+ y z)))
   1    1 nil  2    nil  0    12   |   0  nil | 16   16   nil   nil   nil  (51) (94) (block foo (bar (car x) (+ y z)))
   2  0-1 1    3    nil  1    12   | nil  nil | 16   16   nil   :early  nil  72   93   (bar (car x) (+ y z))
   3  0-1 2    4    nil  1    6    | nil  nil | 16   16   nil   :early  nil  77   84   (car x)
   4  0-1 3    5    nil  1    nil  | nil  nil | 16   24   nil   :ref  nil  82   83   x
   5  0-1 4    6    nil  1    nil  | nil  nil | 24   24   nil   nil   nil  77   84   (car x)
   6  0-1 5    8    nil  1    11   | nil    7 | 24   24   nil   nil   nil  85   92   (+ y z)
   7  1-2 nil  8    nil  1    11   |   6  nil | 24   24   nil   :early  nil  (85) (92) (excl::+_2op y z)
   8  0-1 7    9    nil  1    nil  | nil  nil | 24   28   nil   :ref  nil  88   89   y
   9  0-1 8    10   nil  1    nil  | nil  nil | 28   28   nil   :ref  nil  90   91   z
  10  1-2 9    11   13   1    nil  | nil  nil | 28   58   83    nil   :bcc (85) (92) (excl::+_2op y z)
  11  0-1 #(10 13) 12   nil  1    nil  | nil  nil | 58   61   nil   nil   :call 72   93   (bar (car x) (+ y z))
  12  0-1 11   nil  nil  0    nil  | nil  nil | 61   nil  nil   nil   :noreturn nil  nil  (defun foo (x y z) (bar (car x) (+ y z)))
  13  1-2 10   11   nil  1    nil  | nil  nil | 83   58   nil   :clone  nil  (85) (92) (excl::+_2op y z)
cl-user(6): 

A breakpoint record is created for the beginning of the call to bar (before either of the calls to car or + are processed). This is the :early breakpoint. It causes the flow of stepping to be natural, because of the recursive nature of a lisp function call (i.e. first the argumnts to the caller are processed, which may themselves be calls, and then the call is made to the function after the arguments have been set up).

Assuming the call to bar is at character position 72 (as is the case with the example),

:br :early t foo :pos 72

will stop at the early call record, and

:br :early nil foo :pos 72

will set the breakpoint at the actual call instruction, after the arguments have been set up:

cl-user(6): :br :early t foo :pos 72
Adding #<Function foo>: 16
Function: #<Function foo> in #P"callers.cl":
    rec/pc lev nxt(rec/pc) br(rec/pc) e-type br-type  st  end       form
     0/0     0   2/16     nil/nil    nil    nil    51    94    (defun foo (x y z) (bar (car x) (+ y z)))
     1/16    1   2/16     nil/nil    nil    nil    (51)  (94)  (block foo (bar (car x) (+ y z)))
->   2/16    0-1   3/16     nil/nil    :early  nil    72    93    (bar (car x) (+ y z))
     3/16    0-1   4/16     nil/nil    :early  nil    77    84    (car x)
     4/16    0-1   5/24     nil/nil    :ref   nil    82    83    x
  level=0 pc=16 rec=2 style=:early  in #P"callers.cl" starting at 72 ending at 93.
Possible slide directions: (out over across back)
Current step/slide type: over/0
cl-user(7): :br :early nil foo :pos 72
Adding #<Function foo>: 58
Function: #<Function foo> in #P"callers.cl":
    rec/pc lev nxt(rec/pc) br(rec/pc) e-type br-type  st  end       form
     9/28    0-1  10/28     nil/nil    :ref   nil    90    91    z
    10/28    1-2  11/58      13/83     nil    :bcc   (85)  (92)  (excl::+_2op y z)
->  11/58    0-1  12/61     nil/nil    nil    :call  72    93    (bar (car x) (+ y z))
    12/61    0-1 nil/nil    nil/nil    nil    :noreturn  nil   nil   (defun foo (x y z) (bar (car x) (+ y z)))
    13/83    1-2  11/58     nil/nil    :clone  nil    (85)  (92)  (excl::+_2op y z)
  level=0 pc=58 rec=11  in #P"callers.cl" starting at 72 ending at 93.
Possible slide directions: (out across back)
Current step/slide type: over/0
cl-user(8):

The :early option is sticky: once set one way or the other, it remains the same value until changed again. The initial value for this state is to simulate :early nil in the :break command.

See The Lisp DeBug (ldb) stepper in debugging.html for information on ldb stepping. See top-level.html for more information on top-level commands.

:bt

tpl-command, tpl package

Arguments:

The :bt command provides a quick way to scan the stack (contrast with :zoom). :bt has no abbreviation.

Here is the effect of the :bt command on the error when an attempt is made to evaluate foo which has no value. When the error occured, :zoom is printing all frames (:all t) so :bt does as well.

USER(23): foo
Error: Attempt to take the value of the unbound variable `FOO'.
[condition type: UNBOUND-VARIABLE]

[1] USER(24): :bt
Evaluation stack:

  EVAL <-
  TPL::READ-EVAL-PRINT-ONE-COMMAND <- 
  EXCL::READ-EVAL-PRINT-LOOP <-
  TPL::TOP-LEVEL-READ-EVAL-PRINT-LOOP1 <-
  TPL:TOP-LEVEL-READ-EVAL-PRINT-LOOP <- APPLY <-
  TPL:START-INTERACTIVE-TOP-LEVEL <- TPL::START-TOP-LEVEL <-
  EXCL::START-REBORN-LISP

See top-level.html for more information on top-level commands.

:cd

tpl-command, tpl package

Arguments: &optional dir

This command and the related :popd and :pushd work just like their Unix C shell counterparts. :cd changes the current directory to dir (if supplied) or to the user's home directory (if dir is not supplied). On Windows, the home directory is taken to be C:. :pushd changes the current directory to dir and adds it to the directory stack. If no argument is supplied, :pushd changes to the directory at the top of the directory stack and swaps the top two directories on the stack. :popd pops the current directory off the directory stack and changes the current directory to the directory that was next on that stack.

:cd, :popd, and :pushd all change the value of *default-pathname-defaults* so that its directory component is the new current directory.

dir will be treated as a string but need not be surrounded in quotation marks.

See also chdir (which is like :cd but does not change the value of *default-pathname-defaults* and current-directory.

See also :dirs, which prints the stack of directories and :pwd, which prints the full path of the current directory.

:cd has no abbreviation.

See top-level.html for more information on top-level commands.

:cf

tpl-command, tpl package

Arguments: files

The one or more arguments are read as strings (but don't wrap in quotation marks), and are interpreted as filenames. They should represent the names of Allegro CL source files. If the type of a source file is not given explicitly in the command, the file must have a type appearing in the list bound to the variable *source-file-types*. The source files in the list are compiled, resulting in files with the same name, but with the file type specified by the variable *fasl-default-type*. For example,

:cf foo

would compile foo.cl into foo.fasl, (assuming that *fasl-default-type* is "fasl"). The files are compiled in the order they appear in the argument list. Pathnames are discussed in pathnames.html.

If no arguments are given to :cf, then the arguments to the last call to :cf are used again.

:cf has no abbreviation.

See top-level.html for more information on top-level commands. See compiling.html for information on the compiler.

:cload

tpl-command, tpl package

Arguments: &rest files

The one or more arguments, which are read as strings (but don't wrap in quotation marks), are interpreted as file names. They should represent the names of Allegro CL source files. If the corresponding fasl file exists, and it is newer than the source file, it is loaded. If it does not exist or is older than the source file, the source file is compiled, a new fasl file is produced, and that file is loaded. The files are processed, that is compiled and loaded, in order. The files must have extensions which appear in the list bound to the variable *source-file-types* unless extensions are explicitly specified.

Note that the file will not be recompiled just because the Lisp environment has changed (perhaps with new values of the optimization qualities speed, safety, space, debug, and compilation-speed, see :optimize). The file is only recompiled if the fasl file is older than the source file.

If no arguments are given to :cload, then the arguments to the last call to :cload are used.

The minimal abbreviation of :cload is :cl.

See top-level.html for more information on top-level commands. See also loading.html and compiling.html.

:continue

tpl-command, tpl package

Arguments: &optional restart-number

When Lisp encounters an error with restarts (including a continuable error, which gave the name to this command), it produces a list of possible restart actions, numbered from 0. Entering :continue with a restart-number corresponding to the action you want will cause computation to continue with the effects specified for the restart action. You may be prompted for more information as part of the restart action. The default value for restart-number is 0. After this command is evaluated, Lisp will leave the break level entered by the error.

See also the :error top-level command.

The minimal abbreviation of :continue is :cont.

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger.

:current

tpl-command, tpl package

Arguments:

This command prints the current stack frame, as a lisp expression and sets the value of cl:* to the frame object. The current frame pointer may be moved by the :up and :dn top-level commands.

The minimal abbreviation of :current is :cur.

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger.

:debug-control

tpl-command, tpl package

Arguments: &key process current on-return

Displays or controls the current and future debug state of the selected process. The debug state can be true or nil. The only purpose of this debug state is to control whether the garbage-collector uses a precise-gc (as it will when the debug state is nil) or a conservative-gc (as it will when the debug state is true). See Precise gc's of the stack in gc.html for information on precise versus conservative gc's of the stack.

The advantage of a non-nil debug state is that variables on the stack last longer, being preserved even after they have become dead (that is, after any reference in current or future executing code), so that a user can debug the current frame and have the values that were originally available. The disadvantage of a non-nil debug state is variables on the stack last even after they have become dead, meaning that any finalizations on the objects the variables contain will be delayed longer than necessary.

process indicates what process is to be controlled or queried. The default is the current process.

current can have two values, nil (false) or non-nil (true). The debug state of the process/thread will be set to this boolean value.

on-return can be nil (for false), :revert, or any other non-nil value (for true). This value determines what will happen to the debug state of the process/thread when any break-level is returned from (or thrown out of). The :revert means that the remembered value of the break-level that is being returned to is used as the debug state. The other true or false values indicate that the debug state will either be true or false on returning. The default on-return value is :revert.

Called with no arguments or just a value for process, the current debug status of the process is returned. The new status of the selected process after any change is also returned.

The debug state is also shown in the Processes dialog.

The minimal abbreviation of :debug-control is :deb.

:dirs

tpl-command, tpl package

Arguments:

This command prints the stack of directories that are used by :pushd and :popd.

See also chdir, :cd and current-directory.

See also :pwd, which prints the full path of the current directory.

The minimal abbreviation of :dirs is :di.

See top-level.html for more information on top-level commands.

:dn

tpl-command, tpl package

Arguments: &optional arg &key zoom

This command and :up move the current frame down and up the stack.

If arg is a number, this command moves the current frame pointer down the stack by arg frames, or 1 if no argument is supplied. The zoom keyword argument controls whether a :zoom is done after the current frame pointer is moved. That argument defaults to the value of the special variable tpl:*auto-zoom*.

If the specified number of frames to move is out of range, this command moves to the bottom of the stack and the actual number of frames moved is printed.

If arg is non-numeric, then :up and :dn behave like :find, i.e. finding the frame containing the arg string.

:up and :dn cannot be abbreviated.

See top-level.html for more information on top-level commands.

:edit

tpl-command, tpl package

Arguments: &optional fspec

This command causes the file containing the definition of fspec (if supplied) or the function called in the current debugger frame (if fspec is not supplied) to be opened in an editor buffer (in an Emacs buffer on Unix and in a text-edit-window on Windows). fspec should name a function. This command will signal an error if (on Unix) the emacs-lisp interface is not running or if the file containing the definition of fspec is not known to the system.

See top-level.html for more information on top-level commands.

:error

tpl-command, tpl package

Arguments: &key verbose

Print the error message associated with the current break level and set the value of * to be the condition object associated with the error. If the current break level is continuable, then print the continue message as well.

If the condition which caused the break level contains a source-context, it is printed first, as part of the condition.

Next, if there is a source-context and it contains a compiler backtrace, that backtrace is printed, according to the :verbose option, described below.

Finally, whether or not the current break level is continuable, all currently active restarts are printed, numbered from the most recent to the least recent. These restarts can be invoked with :continue top-level command.

The :verbose argument defaults to the value of *print-verbose-source-context* and can be true, which causes whole forms to be pretty-printed, or it can be nil, which causes concise-printing to print forms on one line only. These values only affect the current execution of this command. However, the :verbose option can be the value :always, which sets *print-verbose-source-context* for the current thread, so that subsequent conditions or calls to the :error command will print verbosely. Finally, :verbose may be :never, which sets *print-verbose-source-context* to nil in the current thread and thus affects future conditions or calls to the :error command.

The minimal abbreviation of :error is :err.

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger. See the Compiler backtrace examples and the extra example for examples of this command in action.

:evalmode

tpl-command, tpl package

Arguments: &key context

If called with context specified true, evaluation is done, as best as possible (see warning just below) with respect to the current frame rather than the top level. All known local variables (those printed by the :local command) can be referenced by name in ordinary Lisp forms, if their names were saved during the compilation of the function associated with the frame. See save-local-names-switch and save-local-scopes-switch for information on when the compiler saves local names.

Setting those variables sets the value in the frame. All specials will also evaluate to their value in the context of the current frame. If context is specified nil, evaluation is done with respect to the top level, not the current frame.

Warning: The context evaluation mode (i.e. when running in :evalmode :context t) is intended only as a debugging aid, and is not supported for normal extended operation of the lisp system. Its purpose is to emulate a dynamic-binding style debugging interface to make interactions with variables within compiled-functions easier. The emulation is not and can never be perfect, due to the information loss that occurs during compilation in a lexically-scoped lisp like Common Lisp. Therefore, extreme care must be used when running in context mode, and the normal operating environment must be a no-context evaluation mode.

In particular, whenever the current read-eval-print-loop changes, there is a possibility that the context sensitivity will be inconsistent, due to the binding and unbinding of special variables. Context evaluation simulates the binding environment of the desired context frame, not by unbinding the bindstack to the required point, but by binding again those specials to their previously bound values. This simulates the desired context adequately for most simple evaluations, but because the bindstack actually grows instead of shrinking, some binding-orders are lost and the top-level might become confused. Thus, context evaluation may or may not continue after pops or resets.

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger.

:exit

tpl-command, tpl package

Arguments: &optional status &key no-unwind quiet

:exit simply calls the function exit, passing all arguments to exit except when there are several interactive processes, in which case :exit asks the user whether or not he wants to exit Lisp in the presence of other processes, and if the answer is yes, then exit is called.

The minimal abbreviation of :exit is :ex.

See top-level.html for more information on top-level commands.

:find

tpl-command, tpl package

Arguments: function-name &key up skip

Find the frame where function-name is being called. The default direction to search the stack is down, or towards older stack frames. The current frame pointer is set to point to the matching stack frame, the lisp expression corresponding to the match is bound to the variable cl:*. :find does an auto-zoom, that is it does a :zoom with the current frame being the frame found. The keyword arguments to :find are:

• :up, which, if specified true, will search the stack up, toward newer stack frames.
• :skip, which if specified as a positive integer, will skip that many occurrences of frames associated with the function-name.

This command operates on the focused process when multiprocessing is active.

The minimal abbreviation for :find is :fin.

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger.

:focus

tpl-command, tpl package

Arguments: &optional process

With no arguments, print the process on which the listener process is focused. Otherwise, focus on process, arresting it for debugging if :debugging is not already on process's list of arrest reasons. Focus on the listener process if the argument is :listener. Note that the listener process is not arrested.

:focus keeps a stack of processes on which the user has focused. When the current focus is moved from a process by using the command :unarrest, this stack is used to determine which process will become the focused process. The listener will become the focused process if no other processes are on the stack.

The process argument can be:

• A string, which is processed as described below.
• A symbol, which is evaluated to produce a process object, a string, an integer, or a symbol. If the value is a symbol, its print name is used as if that were the string provided.
• A list, which is evaluated to produce a process object, a string, an integer, or a symbol. If the value is a symbol, its print name is used as if that were the string provided.
• An integer, which designated the process whose process-sequence value is that integer.

Strings are compared with process names. All processes whose names exactly match the string are considered matches. If no process name exactly matches, then all processes whose names contain the string as a substring are considered matches. (For example, if there are processes with names "Listener 1" and "Initial Lisp Listener", both match the string "ener".) Since only one argument process is allowed, multiple matches cause the command to fail with a diagnostic.

Strings which match no process also cause the command to fail with a diagnostic.

The minimal abbreviation of :focus is :fo.

See top-level.html for more information on top-level commands. See also multiprocessing.html.

:frame

tpl-command, tpl package

Arguments:

This command prints out interesting information about the current frame (of a :zoom output). The information printed can include the values of local variables and the source code that they are set in.

The minimal abbreviation of :frame is :fr.

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger.

:function

tpl-command, tpl package

Arguments:

This command prints the function object called in the current stack frame and sets the value of cl:* to that object. Some frames represent calls to internal functions and don't have any associated function objects. If a frame does not have an associated function object, then this command just prints nil.

The minimal abbreviation of :function is :fun.

See top-level.html for more information on top-level commands.

:help

tpl-command, tpl package

Arguments: &optional command-name

Without an argument, this command prints a summary of the commands, mostly consisting of name, abbreviation, and valid arguments; if command-name is present, it prints more detailed documentation about the command. Commands added with tpl:alias will be included in the list, with [alias] as part of the description. Documentation strings and abbreviations will shown for alias commands.

This command will print a page of output at a time (page is defined below). When a page has been output, the system will pause. Entering a return at that point will cause the next page to be displayed. Entering a number causes the command to take that value as the page size (the value holds for this call to :help only). Any fixnum may be entered. A negative or zero value causes the remainder of the output to be displayed with no further breaks.

A page is defined to be *help-page-length* number of lines, if the value of that variable is a positive integer. If the value is negative or zero, :help will print without pausing.

The minimal abbreviation of :help is :he.

See top-level.html for more information on top-level commands.

:hide

tpl-command, tpl package

Arguments: &optional function-name frame-type &key package package-internals

This command and :unhide affect the behavior of :zoom. They allow the user to declare that certain frames should not be printed when the stack is displayed by :zoom. To :hide a frame means that :zoom will not show it, and to :unhide a frame means that :zoom will show it. The objects which can be hidden are functions named by specific symbols, all functions named by symbols in a package, and all frames of a given type.

All functions named by symbols in a package can be hidden by specifying the symbol or string identifying the package. A single function can be hidden by specifying the function name. Note, however, that if there is a function named with the same symbol that names a package, it is impossible to hide the function alone (since :hide will interpret the symbol as naming the package).

The minimal abbreviation for :hide is :hid.

:hide called with no arguments prints out what is currently hidden.

The function-name argument, if supplied, names a function that is to be hidden.

The frame-type argument, if supplied, names the type of frames that are to be hidden. The four valid frame types are:

1. :binding, which are binding frames (from let, let*, prog, labels, flet, and so on);

2. :eval, which are evaluation frames;

3. :interpreter, which are the interpreter machinery frames;

4. :special-form which are the special form frames.

The package keyword argument can be used to specify that all symbols of the given package should be hidden. The value given for this argument should be a symbol naming a package.

The package-internals keyword argument can be used to specify that internal symbols of the given package should be hidden. The value given for this argument should be a symbol naming a package.

The default set of hidden objects includes:

• hidden packages: lep excl system clos debugger multiprocessing
• hidden packages internals: top-level
• hidden functions: block apply
• hidden frames: :interpreter :eval :internal

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger.

:history

tpl-command, tpl package

Arguments: &key count reverse

Print the items on the history list. If the keyword argument count is specified as a positive integer, that number of items will be printed. If the count argument is not specified, 15 items will be printed. (Of course, if the list contains fewer items than are called for, the whole list will be printed.) The list is printed most recent item last, but will print most recent item first if the reverse argument is specified and true.

Repeated commands (entering the same command several times in a row) are collapsed into a single entry, and so appear only once in the history.

For example,

:history :count 5 :reverse t 

will print out the 5 most recent items on the history list, most recent first; while

:history :count 5 

will print out the five most recent items, oldest first.

The minimal abbreviation of :history is :his.

See top-level.html for more information on top-level commands. In particular, see Command and expression history in that document for pattern matching commands not documented on their own pages.

:inspect

tpl-command, tpl package

Arguments: object

This command is similar to a call to inspect applied to object and starts inspection of an object (note that object is evaluated by inspect (of course) and by this top-level command). When inspection starts, an inspection loop is entered (see :istep which inspects something but does not enter an inspection loop). On Windows with the Integrated Development Environment, this command causes an Inspector window to be displayed so there is no opportunity to use the :inspect top-level command.

The minimal abbreviation of :inspect is :in. Note: in releases prior to 6.0, the minimal abbreviation was :i but :istep, new in 6.0, now has minimal abbreviation :i.

See inspector.html for more information.

See top-level.html for more information on top-level commands.

:istep

tpl-command, tpl package

Arguments: object-or-option option-args*

This command works when the inspector has been entered using inspect or :inspect and when there is no current inspection. In the latter case, an inspector breakloop is not entered (and the argument is not evaluated). See inspector.html for a description of options and the arguments to options.

Multiple options can be put in a single :istep command. The options are carried out serially, although no information is printed until the last option is performed. However the pprint option orders the system to print the current object and pprint options placed among the multiple options in a single command cause printing as the multiple commands are processed. (Do not confuse pprint with print in this case. print simply sets the number of components to be printed and does not itself cause printing.)

Here is an example which shows the difference between using this command and :inspect:

;; Here we use the function cl:inspect.
;; Note that an inspector loop is entered.
USER(1): :cur
(TOP-LEVEL:TOP-LEVEL-READ-EVAL-PRINT-LOOP)
USER(2): (inspect *)
A proper list @ #x305db8e9 with 1 element
   0-> The symbol TPL:TOP-LEVEL-READ-EVAL-PRINT-LOOP
[1i] USER(3): :cur
(INSPECT (TOP-LEVEL:TOP-LEVEL-READ-EVAL-PRINT-LOOP))
[1i] USER(4): 

;; Here we use :istep. No inspector loop is entered.
USER(1): :cur
(TOP-LEVEL:TOP-LEVEL-READ-EVAL-PRINT-LOOP)
USER(2): :istep *
A proper list @ #x305db8e9 with 1 element
   0-> The symbol TPL:TOP-LEVEL-READ-EVAL-PRINT-LOOP
USER(3): :cur
(TOP-LEVEL:TOP-LEVEL-READ-EVAL-PRINT-LOOP)
USER(4): 

:kill

tpl-command, tpl package

Arguments: &optional process &rest processes

This command uses process-kill to kill each identified process. Confirmation is sought if the user tries to kill the last running process. If there are processes that a listener process has left in an arrested state, :kill of that listener is disallowed and a warning is given. If the focused process is killed, the listener process is automatically refocused. This new focus is printed before :kill returns. (See the description of the command :focus above for a discussion of which process will become the focused process.)

The process and processes arguments can specify as many processes as desired. Each argument can be:

• A string, which is processed as described below.
• A symbol, which is evaluated to produce a process object, a string, an integer, or a symbol. If the value is a symbol, its print name is used as if that were the string provided.
• A list, which is evaluated to produce a process object, a string, an integer, or a symbol. If the value is a symbol, its print name is used as if that were the string provided.
• An integer, which designated the process whose process-sequence value is that integer.

Strings are compared with process names. All processes whose names exactly match the string are considered matches. If no process name exactly matches, then all processes whose names contain the string as a substring are considered matches. (For example, if there are processes with names "Listener 1" and "Initial Lisp Listener", both match the string "ener".) For this command, multiple matches of parts of names with the string are considered ambiguous and the command fails with a diagnostic.

Strings which match no process cause the command to fail with a diagnostic.

The minimal abbreviation of :kill is :ki.

See top-level.html for more information on top-level commands. See multiprocessing.html for information on processes.

:ld

tpl-command, tpl package

Arguments: &rest files

The one or more arguments are read as strings (but don't wrap in quotation marks), and are interpreted as filenames. They should represent the names of Lisp files (source or compiled) to be loaded into Lisp by the load function.

If no arguments are given to :ld, then the arguments to the last call to :ld are used again.

:ld has no abbreviation.

See top-level.html for more information on top-level commands. See also loading.html.

:ldb

tpl-command, tpl package

Arguments: &optional mode

This command controls the installing (enabling) and uninstalling (disabling) of breakpoints, and the establishment of ldb mode. The functional equivalent is the with-breakpoints-installed macro.

When given no arguments, this command prints the current mode. When given t as an argument, ldb mode is entered, and when given nil, an attempt is made to quit ldb-mode.

Note that in order to do stepping (see :step), you must be at a breakpoint.

See The Lisp DeBug (ldb) stepper in debugging.html for information on ldb stepping. See top-level.html for more information on top-level commands.

:local

tpl-command, tpl package

Arguments: [:i] [:c] [:x] [:d] [:r] [name|index]

If not in ldb mode (ldb does not appear in the prompt), this command prints information on local variables in the current frame, as we now describe. See below for behavior in ldb mode.

This command causes the values of local variables for the current stack frame (see :zoom) to be printed. See debugging.html for information on the handling of local variables by the debugger.

Note that the compiler may not save the names of local variables in compiled code. In that case variables will be listed identified by an index, which is a number from 0 to n-1, where n is the number of compiled local variables. The compiler will save names of compiled local variables if the compiler switch save-local-names-switch is bound to a function which returns t. Further, local name information is only loaded from compiled file is the variable *load-local-names-info* is non-nil when the compiled (fasl) file is loaded. (There is an example on the *load-local-names-info* page showing :local output when local names are and are not loaded.)

When local names are saved (as described in the paragraph above), closure variables are also printed out.

If the name/index option is specified, the value of the local variable identified by the name or index will be printed. With no other options, all instances of name are looked for. If the option :i (:c) is specified, just interpreted (compiled) code is searched for name. index always refers to compiled local variables. The variable cl:* is set only if you specify a name or index argument to :local. The commands :local, :local :i and :local :c do not set cl:*.

The :x argument, if specified, causes any numeric values to be printed in hexadecimal. (The related :set-local does not support the :x argument.)

The :d option

When compiling is done with save-local-scopes-switch or save-source-level-debug-info-switch returning true, and when either of these debug info sets is loaded for a function, then the debugger is given a sense of lexical variables within that function being "live" or "dead" at a particular program counter point in the function. Under these circumstances, when the :local command is executed with no arguments, the output will include :dead as part of the name of the variable, if the variable is indeed not live at the current program counter in the function.

Normally, these dead values will not even be printed by the :local command, because it is likely that they are not useful to the current path through the function. It is, however, sometimes useful to know what a variable's value was before it was last used (and thus died). The :d option causes all variables to be printed, regardless of the liveness of the variable. Any variable which is deemed to be dead will have its name wrapped in (:dead ...) to indicate that the variable is not currently in scope in the function.

The garbage collector will, when running in its normal mode, will replace the values of dead locals on the stack with values that cannot be mistaken for a Lisp value or pointer thus ensuring that other values are not kept alive inappropriately. This action does destroy information that might be useful when debugging. So when a process is in debugging mode, the garbage collector is inhibited from destroying such values. A process is put into debugging mode by the :break top-level command. See that command for more information.

The :r option

The :r argument, if specified, displays locals in raw layout. That means they are not interpreted as required, optional, local, etc., just all as raw-local.

If :r is specified, the name/index argument should be index. Names in raw mode are always :unknown. The purpose of this option is to access the stack in a way similar to the way the garbage collector and heap-walkers access it. Both the gc and heapwalkers use the same stack frame walker to look at various slots in the stack. This includes all argument and local slots, but it also includes slots not normally visible by the debugger; for example, slots within a stack-allocated object are not normally shown normally, but are shown with the :r option.

When :r is specified, the result differs from when it is not in the following ways:

• The ordering tends to be opposite: ascending locals under normal display appear as descending under the :r option.
• The arguments to the function are not interpreted in :r mode. Usually the :r mode shows locations in the stack which constitute the next newer frame's arguments, so one would have to move to the next older frame before being able to see the arguments seen under normal mode. No atempt to reconstruct a calling expression for this frame is made, so some arguments which reside as not-given keywords are not interpreted as such. If &rest arguments are rearranged, no attempt to expand them are made.
• If there are stack-allocated objects, the header words in each will appear as non-lisp-objects, and likely any filler words or empty space in the objects will also be either non-lisp objects, or else objects that have survived from previous function invocations. Sometimes stack space is allocated for stack-objects, but the objects or parts of the objects are not initialized during a particular function invocation, so the previous objets refernced from the stack are still seen. It is these references that are potential memory leaks.

Further notes

The minimal abbreviation for :local is :loc.

See also :set-local.

This command operates on the focused process when multiprocessing is active. See :focus.

:local in ldb mode

When in ldb-step mode, the :local command works as follows:

When a breakpoint is hit and the frame is a "context-saving" frame, saved registers are simply considered local variable names and values and they are printed when the :local command is given with no arguments. Otherwise register values are not printed. The :register command will print registers.

The :x modifier can be used to ask for any numeric output in hexadecimal. Typical register names start with :% and are named according to hardware convention, eg. :%r10, :%ebx (on x86).

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger.

:macroexpand

tpl-command, tpl package

Arguments: expression

Pretty print the macro expansion of expression, which is not evaluated.

The minimal abbreviation of :macroexpand is :ma.

See top-level.html for more information on top-level commands.

:optimize

tpl-command, tpl package

Arguments:

This command allows you to set the global values of the safety, space, speed, debug, and compilation-speed optimization qualities interactively. When you enter this command, you are asked for the desired value of safety, the desired value of space, the desired value of speed, the desired value of debug, and the desired value of compilation-speed. In each case, the current global value is displayed in brackets. The current value serves as the default and is chosen by hitting a carriage return rather than inputting a value. Because the current value is displayed, this command allows you to poll the global values as well as set them. Your responses are summarized after you finish supplying values.

The minimal abbreviation of :optimize is :opt.

Note that we strongly discourage you from ever globally setting safety to 0, since if speed is 3 and safety is 0 checking for interrupts is disabled.

See compiling.html for information on the safety, space, speed, and debug optimization qualities and on compiler switches.

See top-level.html for more information on top-level commands.

:package

tpl-command, tpl package

Arguments: &optional package-name

If package-name is not given, print the name of the current package (using the value of *package*). Otherwise, if a package with package-name exists, then make that package current, using in-package. If no such package exists, a warning is printed, but no package change is done. The argument package-name must be a symbol or a string but do not use quotation marks.

The minimal abbreviation of :package is :pa.

See top-level.html for more information on top-level commands.

:pop

tpl-command, tpl package

Arguments: &optional n

XXXX

Pop up to the previous level, or to the nth previous one, if n is given. Note that an end-of-file character read in a break loop will have the same effect as :pop 1.

:pop has no abbreviation.

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger.

:popd

tpl-command, tpl package

Arguments:

This command and the related :cd and :pushd work just like their Unix C shell counterparts. :popd pops the current directory off the directory stack and changes the current directory to the directory that was next on that stack. :cd changes the current directory to its argument dir (if supplied) or to the user's home directory (if dir is not supplied). On Windows, the home directory is taken to be C:. :pushd changes the current directory to its argument dir and adds it to the directory stack. If no argument is supplied, :pushd changes to the directory at the top of the directory stack and swaps the top two directories on the stack.

:cd, :popd, and :pushd all change the value of *default-pathname-defaults* so that its directory component is the new current directory.

See also chdir (which is like :cd but does not change the value of *default-pathname-defaults* and current-directory.

See also :dirs, which prints the stack of directories and :pwd, which prints the full path of the current directory.

:popd has no abbreviation.

See top-level.html for more information on top-level commands.

:printer-variables

tpl-command, tpl package

Arguments:

This command prompts the user for the value of many printer control variables, including, for example, *print-level* and *print-length*.

The minimal abbreviation of :printer-variables is :pri.

See top-level.html for more information on top-level commands.

:processes

tpl-command, tpl package

Arguments: &rest processes

Prints information about the state of the processes running in Lisp. If no processes are specified, all live processes are described. The information is displayed in columns. :help proc describes the fields in the display.

The processes argument can specify as many processes as desired. Each argument can be:

• A string, which is processed as described below.

• A symbol, which is evaluated to produce a process object, a string, an integer, or a symbol. If the value is a symbol, its print name is used as if that were the string provided.

• A list, which is evaluated to produce a process object, a string, an integer, or a symbol. If the value is a symbol, its print name is used as if that were the string provided.

• An integer, which designated the process whose process-sequence value is that integer.

Strings are compared with process names. All processes whose names exactly match the string are considered matches. If no process name exactly matches, then all processes whose names contain the string as a substring are considered matches. (For example, if there are processes with names "Listener 1" and "Initial Lisp Listener", both match the string "ener".) For this command, multiple matches of parts of names with the string are considered ambiguous and the command fails with a diagnostic.

Strings which match no process cause the command to fail with a diagnostic.

The minimal abbreviation of :processes is :pro.

See here in top-level.html for an example showing the output of :processes and details of the column headings.

See top-level.html for more information on top-level commands.

:prt

tpl-command, tpl package

Arguments:

Return to the previous level, and re-evaluate the expression that caused the entry into the break level. The previous user input is printed before re-evaluation as a reminder. prt stands for pop and retry.

Note, however, that expressions which cause reader errors will not be re-evaluated since reader errors cause input to be flushed. In the presence of a reader error, the immediately previous expression will be re-evaluated, and you will have to enter the expression which caused the reader error yourself.

:prt has no abbreviation.

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger.

:pushd

tpl-command, tpl package

Arguments: &optional dir

This command and the related :popd and :cd work just like their Unix C shell counterparts. :pushd changes the current directory to dir and adds it to the directory stack. If no argument is supplied, :pushd changes to the directory at the top of the directory stack and swaps the top two directories on the stack. :popd pops the current directory off the directory stack and changes the current directory to the directory that was next on that stack. :cd changes the current directory to dir (if supplied) or to the user's home directory (if dir is not supplied). On Windows, the home directory is taken to be C:.

:cd, :popd, and :pushd all change the value of *default-pathname-defaults* so that its directory component is the new current directory.

dir will be treated as a string but need not be surrounded in quotation marks.

See also chdir (which is like :cd but does not change the value of *default-pathname-defaults*) and current-directory.

See also :dirs, which prints the stack of directories and :pwd, which prints the full path of the current directory.

The minimal abbreviation of :pushd is :pu.

See top-level.html for more information on top-level commands.

:pwd

tpl-command, tpl package

Arguments:

This command prints the full path of the current directory.

See also :dirs, :popd, :pushd, :cd, chdir, and current-directory.

The minimal abbreviation of :pwd is :pw.

See top-level.html for more information on top-level commands.

:register

tpl-command, tpl package

Arguments: &optional name-or-x name-if-x-supplied

The argument list is a bit hard to specify. :register can be called with these arguments:

:register            ;; No arguments, print all registers and values
:register :x         ;; print all registers, values in hexidecimal
:register name       ;; print the value of the names register
:register :x name    ;; print the value of the names register in hexidecimal

Called without arguments, for any frame which has a saved register context, print the registers of that function. Called with :x as the value of name, show values in hexadecimal.

Called with name the name of a register, print the value of that register (called with :x name, print the value in hexadecimal).

See also the :set-register command.

The minimal abbreviation of :register is :reg.

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger and examples of stepping.

:reset

tpl-command, tpl package

Arguments:

This will reset the state of the top-level, and return the user to the top-level read-eval-print loop. throw is used to remove break levels, which means that all unwind-protect clean-up forms will be evaluated.

The minimal abbreviation of :reset is :res.

See *reset-hook*.

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger.

:restart

tpl-command, tpl package

Arguments: &optional frame

The frame argument to :restart must evaluate to either a frame object or nil. A frame object is a list whose first element is a symbol naming a function and whose later arguments are the evaluated arguments to the function. When :zoom is printing frames in moderate mode, it prints frame objects as described and sets the value of cl:* to the chosen current frame object.

The frame argument replaces the current frame in the evaluation stack and computation is continued. (If the argument evaluates to nil or is left out altogether, computation is restarted from the current frame. You have presumably done something to change the state of Lisp - e.g. defined an undefined function or changed the value of a variable - so that whatever error threw you into a break loop is not repeated.)

You cannot restart every frame. If you attempt to :restart over an inappropriate frame, Lisp will signal an error.

The minimal abbreviation of :restart is :rest. Note that :res is the abrieviation for the :reset command.

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger. See section :return and :restart in that document for examples of :restart and a comparison between :restart and :return.

:return

tpl-command, tpl package

Arguments: &rest values

This command sequentially evaluates the arguments provided and returns their values from the current stack frame. The function associated with the current stack frame is not executed, and its arguments are not again evaluated.

This command operates on the focused process when multiprocessing is active (see :focus). Unless the focused process is the listener, the focused process is unarrested when this command is executed, and a new process becomes the focused process.

The minimal abbreviation of :return is :ret.

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger. See section :return and :restart in that document for examples of :restart and a comparison between :restart and :return.

:scont

tpl-command, tpl package

Arguments: &optional n

Continue stepping, for n expressions, beginning with the evaluation of the last expression printed by the stepper. If n is not provided, it defaults to 1. After evaluating n expressions, the next expression to be evaluated is printed. If there are no more expressions stepping is turned off. When stepping is enabled, a carriage return, #\return (or new-line, #\linefeed) is equivalent to :scont 1, allowing the user to step quickly with minimum keystrokes. See :step and :sover.

The minimal abbreviation of :scont is :sc.

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger and examples of stepping.

:set-local

tpl-command, tpl package

Arguments: [:i] [:c] [:r] [name|index] value

This command sets the value of the specified local variable to value, which is evaluated. The local variable is identified by name if interpreted, or name or index if compiled. :local shows the current value of a local.

The :r option cause the :local command to display locals in raw mode. It can be used with this coomand to set raw values (by index, as names are not displayed in raw mode. See :local for more information on the option.

The minimal abbreviation of :set-local is :set-l.

This command operates on the focused process when multiprocessing is active. See :focus.

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger.

:set-register

tpl-command, tpl package

Arguments: name value

This command sets the value of the specified register to value, which is evaluated. The register is identified by name. :register shows the current value of a register.

The minimal abbreviation of :set-register is :set-r.

This command operates on the focused process when multiprocessing is active. See :focus.

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger.

:slide

tpl-command, tpl package

Arguments: direction

The :slide top-level command is associated with the source stepper (see The source stepper in debugging.html).

Slide allows navigation around breakpoints in a function without actually affecting the current breakpoint, if any. Sliding is related to stepping but does not require stepping.

slide point

A slide point is a virtual cursor that points to a Lisp breakpoint record. The current slide point is not the same as the current breakpoint.

Current valid commands are:

• :slide in/into: to slide deeper into macro forms.
• :slide across: to slide forward to a form at the same level.
• :slide back: to slide backward to a form at the same level.
• :slide enclosed: to slide out until a form with source position is encountered.
• :slide out: to slide out to the macro form which expanded to the current form, or to slide to the enclosing form.
• :slide over: to slide over a macro, a call, or a special form.
• :slide point/here: to print the current slide point.
• :slide ?: to print the possible slide directions for the slide. point
• :slide \<func\> [ \<pc\>]: to slide to a function spec <func> at optional relative-pc <pc>.

When not at a macroexpansion point, in and across are equivalent.

The minimal abbreviation of :slide is :sl.

See The source stepper in debugging.html for more information.

:sover

tpl-command, tpl package

Arguments:

Evaluate the current expression being stepped in normal, non-stepping mode. See :step and :scont.

The minimal abbreviation of :sover is :so.

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger and examples of stepping.

:step

tpl-command, tpl package

Arguments: &rest args

If not in ldb mode (ldb does not appear in the prompt), this command initiates or affects stepping, as we now describe. See below for behavior in ldb mode.

The :step top-level command implements the functionality of the step macro.

With an argument of t, stepping is enabled globally, otherwise the arguments are assumed to be symbols naming functions wherein stepping should occur. Any non-functions supplied to :step will be flagged as invalid arguments, but an error will not be signaled.

Called with no arguments or nil as an argument while not stepping, stepping is disabled. Use the command :sover to get out of stepping in order to turn stepping off. :step and :step nil have no effect while stepping is going on. It is only useful to step through compiled code. When you try to step through interpreted code, you end up stepping through the interpreter itself, with most output irrelevant to understanding your own code.

See also :sover and :scont.

The minimal abbreviation of :step is :st.

:step in ldb mode

When in ldb-step mode, the step command recognizes several sub-commands as its first argument:

To step through only the top-level forms (i.e. un-macroexpanded) specify :step :over 0.

slide-direction

slide-dir is optional and directs the stepper how to deal with macroexpansions and forms. The choices are:

• into: means expand macros
• across: means step across the top levels of the current form
• over: means step over this form or macroexpansion and to the next form
• out: means step until the next outer macroexpansion is re-entered
• [N]: where N is a positive fixnum, allows N macroexpand levels deep

The default is :step :over 0 which steps over function calls, but only stops at level 0 breakpoints.

To use :step in ldb mode, you must be at a breakpoint. Thus:

cl-user(1): :ldb t
[ldb] cl-user(2): :step into
You must be stopped at a breakpoint before ldb-stepping can begin.
[ldb] cl-user(3):

When not at a function call point, over and into are equivalent. Typing return repeats the remembered previous command.

Example

cl-user(1): (declaim (optimize debug))
                ;; Code compiled when the DEBUG optimization
                ;; is not 3 will not associated code with the
                ;; courses and so :pos and :rec will not work
                ;; for the :break command.
t
cl-user(2): (shell "cat times.cl")

(defun doit (n)
  (let ((res))
    (do ((i 0 (1+ i)))
    ((= i n)
     res)
      (push i res))))
0
cl-user(3): :cf times
;;; Compiling file times.cl
;;; Writing fasl file times.fasl
;;; Fasl write complete
cl-user(4): :ld times
; Fast loading /net/penn/acl/duane/acl91/src/times.fasl
cl-user(5): :br doit :pos 27
Adding #<Function doit>: 0
  Form=(defun doit (n) (let ((res)) (do (#) (# res)  (push i res))))
  lev=0 pc=0 rec=0  in #P"times.cl" starting at 23 ending at 115.
Possible slide directions: (into over across)
Current step/slide type: over/into
cl-user(6): :ldb t             ;; necessary so stepping/breakpoints work
[ldb] cl-user(7): (doit 10)

Hit breakpoint at func = #<Function doit>, pc=0
  Form=(defun doit (n) (let ((res)) (do (#) (# res)  (push i res))))
  lev=0 pc=0 rec=0  in #P"times.cl" starting at 23 ending at 115.
Possible slide directions: (into over across)
Current step/slide type: over/into
[ldb-step] cl-user(8): :loc
Compiled lexical environment:
0(Required): n: 10
[ldb-step] cl-user(10): :step cont 2
Continuing past #<Lisp Bpt doit #0 pc: 0 @23:115 lev:   0  @ #x20279eda2> 2 times
(9 8 7 6 5 4 3 2 1 0)
[ldb-step] cl-user(11):  :br
#<Function doit>: lisp:rec=0 pc=0 pos=23:115 hit 3 times 
                  
[ldb-step] cl-user(12): 

See with-breakpoints-installed and the :break.

See The Lisp DeBug (ldb) stepper in debugging.html for information on ldb stepping.

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger and examples of stepping.

:top

tpl-command, tpl package

Arguments: &key zoom

This command and :bottom move the current frame to the top (newest frame) or the bottom (oldest frame) of the stack.

The zoom keyword argument controls whether a :zoom is done after the current frame pointer is moved. That argument defaults to the value of the special variable tpl:*auto-zoom*.

The minimal abbreviation for :bottom is :bo. That for :top is :to.

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger.

:trace

tpl-command, tpl package

Arguments: &rest function-or-option-list

When called with no arguments, all the functions currently being traced are printed, otherwise the arguments to :trace are function names (symbols) or option lists. An option list starts with a function name, and the other elements of the list are options for tracing that particular function. The options for one function do not affect the tracing of any other function. The options come in pairs, the first element of the pair being the option name (i.e., a keyword), and the second part being the option value. Missing options default to nil. Here are some valid calls to :trace:

:trace foo
:trace foo (bar :break-before t) baz
:trace (baz :inside foo :break-before t)
:trace 

Note that the following is invalid:

:trace foo :inside bar   ;; INVALID WILL CAUSE ERROR

You must enclose options in a list along with the function name and the option value. If you enter the invalid case above, Lisp will complain that :inside does not have a function definition. The correct command is:

:trace (foo :inside bar)

The minimal abbreviation of :trace is :tr.

See top-level.html for more information on top-level commands. See The tracer in debugging.html for information on the debugger and examples of tracing.

Valid options to :trace

The options to :trace are listed in The tracer in debugging.html. In brief the options and their arguments are:

• :condition expr
• :break-before val
• :break-after val
• :break-all val
• :inside func
• :not-inside func
• :print-before expr
• :print-after expr
• :print-all expr
• :show-stack n

Again, see The tracer in debugging.html for details.

:unarrest

tpl-command, tpl package

Arguments: &rest processes

Revokes the :debugging arrest reason on each of the given processes. With the argument :all, unarrests all processes arrested for debugging by the listener process. If no arguments are supplied, the focused process is unarrested. If the focused process is unarrested, the stack maintained by :focus is used to find a new process on which to focus. Except for the listener, a focused process must be arrested, so the command :unarrest applied to the focused process automatically changes the focus.

The processes argument can specify as many processes as desired. Each argument can be:

• A string, which is processed as described below.
• A symbol, which is evaluated to produce a process object, a string, an integer, or a symbol. If the value is a symbol, its print name is used as if that were the string provided.
• A list, which is evaluated to produce a process object, a string, an integer, or a symbol. If the value is a symbol, its print name is used as if that were the string provided.
• An integer, which designated the process whose process-sequence value is that integer.

Strings are compared with process names. All processes whose names exactly match the string are considered matches. If no process name exactly matches, then all processes whose names contain the string as a substring are considered matches. (For example, if there are processes with names "Listener 1" and "Initial Lisp Listener", both match the string "ener".) For this command, multiple matches of parts of names with the string are considered ambiguous and the command fails with a diagnostic.

Strings which match no process cause the command to fail with a diagnostic.

The minimal abbreviation of :unarrest is :unar.

See top-level.html for more information on top-level commands. See also multiprocessing.html.

:unhide

tpl-command, tpl package

Arguments: &optional function-name frame-type &key package package-internals

This command and :hide affect the behavior of :zoom. They allow the user to declare that certain frames should not be printed when the stack is displayed by :zoom. To :hide a frame means that :zoom will not show it, and to :unhide a frame means that :zoom will show it. The objects which can be hidden are functions named by specific symbols, all functions named by symbols in a package, and all frames of a given type.

:unhide called with no arguments causes the list of hidden objects to revert to the default set of hidden objects (which is given below). Note that if you want to see all frames in the stack, you should call :zoom with a true value for the all argument. :unhide itself is not designed to unhide all frames.

The function-name argument, if supplied, names a function that is to be unhidden.

The frame-type argument, if supplied, names the type of frames that are to be unhidden. The four valid frame types are:

1. :binding, which are binding frames (from let, let*, prog, labels, flet, and so on);

2. :eval, which are evaluation frames;

3. :interpreter, which are the interpreter machinery frames;

4. :special-form which are the special form frames.

The package keyword argument can be used to specify that all symbols of the given package should be unhidden. The value given for this argument should be a symbol naming a package.

The package-internals keyword argument can be used to specify that internal symbols of the given package should be unhidden. The value given for this argument should be a symbol naming a package.

The default set of hidden objects includes:

• hidden packages:
  lep excl system clos debugger multiprocessing

• hidden packages internals:
  top-level

• hidden functions:
  block apply

• hidden frames:
  :interpreter :eval :internal

The minimal abbreviation for :unhide is :unh.

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger.

:untrace

tpl-command, tpl package

Arguments: &rest functions

With no arguments, stop tracing all functions currently being traced, otherwise the arguments are assumed to be the names of currently traced functions which are to be untraced. :untrace also has a functional counterpart, the macro untrace. Tracing is started with :trace.

The minimal abbreviation of :untrace is :untr.

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger and examples of tracing.

:up

tpl-command, tpl package

Arguments: &optional arg &key zoom

This command and :dn move the current frame down and up the stack.

If arg is a number, this command moves the current frame pointer up the stack by arg frames, or 1 if no argument is supplied. The zoom keyword argument controls whether a :zoom is done after the current frame pointer is moved. That argument defaults to the value of the special variable tpl:*auto-zoom*.

If the specified number of frames to move is out of range, this command moves to the top of the stack and the actual number of frames moved is printed.

If arg is non-numeric, then :up and :dn behave like :find, i.e. finding the frame containing the arg string.

:up and :dn cannot be abbreviated.

See top-level.html for more information on top-level commands.

:who-binds

tpl-command, tpl package

Arguments: name &key inverse in-files in-functions

This is the top-level command equivalent of who-binds.

When the value of the inverse argument is 'nil' (the default), this command prints information in the database about those functions which bind the global variable identified by name. When the value of the inverse argument is true, this command prints information on the global variables bound by the function identified by name.

When inverse is nil, name can be any lisp object but only global variables make sense as the value (no cross reference information is gathered for other types of Lisp objects). When inverse is true, name must be a function name (either a symbol or a list of the type described in the discussion of function specs in implementation.html).

The in-functions and in-files keyword arguments can be used to restrict the search to particular functions (for in-functions) or functions defined in particular files (for in-files). The default value for each argument is nil, which calls for an unrestricted search. When inverse is nil (so a list of functions is printed by this function) a true value for in-functions or in-files should be a list of function names or file names (respectively) and the information printed will be the intersection of the functions found in the database and the functions in the list or defined in files in the list (respectively). Note that source file information must have been recorded for the files in the in-files list. When inverse is true (so this command is printing the list of global variables bound by the function identified by name), the list that is the value of in-functions should be a list of global variables and only those found in the database and in the list will be printed.

See top-level.html for more information on top-level commands. See cross-reference.html for information on the cross reference utility.

:who-calls

tpl-command, tpl package

Arguments: name &key inverse in-files in-functions

This is the top-level command equivalent of who-calls.

This command prints the information that would be printed by successively calling who-directly-calls, who-indirectly-calls, and macros-called-by with exactly the arguments passed to this command. See the description of those functions for information on what is printed and what the effect of various argument values are.

See top-level.html for more information on top-level commands. See cross-reference.html for information on the cross reference utility.

:who-references

tpl-command, tpl package

Arguments: name &key inverse in-files in-functions

This is the top-level command equivalent of who-references.

When the value of the inverse argument is nil (the default), this command prints information in the database about those functions which reference the global variable identified by name. When the value of the inverse argument is true, this command prints information on the global variables referenced by the function identified by name.

When inverse is nil, name can be any lisp object but only global variables make sense as the value (no cross reference information is gathered for other types of Lisp objects). When inverse is true, name must be a function name (either a symbol or a list of the type described in the discussion of function specs in implementation.html).

The in-functions and in-files keyword arguments can be used to restrict the search to particular functions (for in-functions) or functions defined in particular files (for in-files). The default value for each argument is nil, which calls for an unrestricted search. When inverse is nil (so a list of functions is printed by this command) a true value for in-functions or in-files should be a list of function names or file names (respectively) and the information printed will be the intersection of the functions found in the database and the functions in the list or defined in files in the list (respectively). Note that source file information must have been recorded for the files in the in-files list. When inverse is true (so this function is printing the list of global variables referenced by the function identified by name), the list that is the value of in-functions should be a list of global variables and only those found in the database and in the list will be printed.

See top-level.html for more information on top-level commands. See cross-reference.html for information on the cross reference utility.

:who-sets

tpl-command, tpl package

Arguments: name &key inverse in-files in-functions

This is the top-level command equivalent of who-sets.

When the value of the inverse argument is nil (the default), this command prints information in the database about those functions which set the global variable identified by name. When the value of the inverse argument is true, this command prints information on the global variables set by the function identified by name.

When inverse is nil, name can be any lisp object but only global variables make sense as the value (no cross reference information is gathered for other types of Lisp objects). When inverse is true, name must be a function name (either a symbol or a list of the type described in the discussion of function specs in implementation.html).

The in-functions and in-files keyword arguments can be used to restrict the search to particular functions (for in-functions) or functions defined in particular files (for in-files). The default value for each argument is nil, which calls for an unrestricted search. When inverse is nil (so a list of functions is printed by this function) a true value for in-functions or in-files should be a list of function names or file names (respectively) and the information printed will be the intersection of the functions found in the database and the functions in the list or defined in files in the list (respectively). Note that source file information must have been recorded for the files in the in-files list. When inverse is true (so this function is printing the list of global variables set by the function identified by name), the list that is the value of in-functions should be a list of global variables and only those found in the database and in the list will be printed.

See top-level.html for more information on top-level commands. See cross-reference.html for information on the cross reference utility.

:who-uses

tpl-command, tpl package

Arguments: name &key inverse in-files in-functions

This is the top-level command equivalent of who-uses.

This command prints the information that would be printed by successively calling who-binds, who-references, and who-sets with exactly the arguments passed to this command. See the description of those functions for information on what is printed and what the effect of various argument values are.

See top-level.html for more information on top-level commands. See cross-reference.html for information on the cross reference utility.

:zoom

tpl-command, tpl package

Arguments: &key from-read-eval-print-loop brief moderate intermediate verbose top bottom count catches specials function relative all

This command prints the evaluation stack. It uses the current stack frame as the center of attention, and prints some number of frames on either side of the current frame. The value of the variable *zoom-display* is the total number of frames to display, and an equal number of frames are printed above and below the current stack frame, if possible. The arguments to the :zoom command control the type and quantity of the displayed stack.

After a :zoom or any of its analogs (such as :top or :bottom) the special variable cl:* contains the lisp expression representing the current frame. That expression is approximately what is shown in a moderate display with :function nil, regardless of the mode in which :zoom itself displays.

This command operates on the focused process when multiprocessing is active.

The minimal abbreviation of :zoom is :zo.

The from-read-eval-print-loop argument controls whether frames after the most recent entry to the Lisp read-eval-print-loop are ignored (when this argument is true, the default) or not (when this argument is nil). This argument should be specified nil when :zoom is called programmatically. It should be left t when :zoom is called interactively.

The remaining keyword arguments to :zoom are described in the following table.

:zoom and the Debug window in the IDE on Windows

The Debug window in the Integrated Development Environment, supplied with Allegro CL on Windows, also provides a view of the stack similar to :zoom. See the description of the Debug window after an error for details. Note that these two views (that in the Debug window and that displayed by :zoom) are independent, meaning each view controls how it is displayed (for example, whether hidden frames are shown or left out, how many frames are shown, etc.) independently from the other.

See top-level.html for more information on top-level commands. See debugging.html for information on the debugger and examples of tracing.

Copyright (c) 2023, Franz Inc. Lafayette, CA., USA. All rights reserved.