5. Program Development Facilities

5.1 The Tracer
5.2 The Stepper
5.3 Errors
5.4 The Break Loop
5.5 Describe and Inspect
5.6 The Profiler
5.7 Online Help

5.1 The Tracer

  level > (name   arg1   ...   argn) 

On return from a traced function, it prints

< level (name value1 ... valuen)

name is the name of the traced function, args are the arguments, and values are the return values. level is a number which is incremented each time a traced function is invoked and is decremented at the completion of the invocation. Trace print-outs are indented according to the level.

In the current version of ECL, macros and special forms cannot be traced.

Macro: trace {{function-name | (function-name {&key

Causes one or more functions to be traced. Each function-name must be a symbol which is not evaluated. If a function is called from a compiled function in the same file, tracing will not be enabled. If this is the case, to enable tracing, recompile the caller with a notinline declaration for the called function. trace returns a name list of those functions that were traced by the call to trace. If no function-name is given, trace simply returns a name list of all the currently traced functions.

Trace options can cause the normal printout to be suppressed, or cause extra information to be printed. Each option is a pair of an option keyword and a value form. If an already traced function is traced again, any new options replace the old options. form is an expression to be evaluated in an environment where sys::arglist is bound to the current list of arguments to the function.

The following options are defined:

:cond

:cond-before

:cond-after

If :cond-before form evaluates to true at the time of the call. :cond-after similar, but suppresses the initial printout, and is tested when the function returns. :cond

:step

If form evaluates to true, the stepper is entered.

:break

:break-after

If specified, and form evaluates to true, then the debugger is invoked at the start of the function or at the end of the function according to the respective option.

:print

:print-after

In addition to the usual printout, the result of evaluating form is printed at the start of the function or at the end of the function, according to the respective option. Multiple print options cause multiple values to be

Macro: untrace {{function-name}*}

Causes the specified functions to be not traced any more. function-names must be symbols and they are not evaluated. untrace returns a name list of those functions that were untraced by the call to untrace. If no function-name is given, untrace will untrace all the currently traced functions and will return a list of their names.

5.2 The Stepper

Macro: step {form}

Starts evaluating the form in the single-step mode. In this mode, before any form is evaluated, the Stepper will print the form and prompt the user for a Stepper command. The Stepper binds the two variables print-level and print-length occupy too much space on the screen. A Stepper command will be executed when the user types the single character for the command followed by the required arguments, if any, and presses the newline key. If the user presses the newline key without having typed any character, then the Stepper will assume that the Stepper command n was abbreviated.

The stepper commands are:

Newline

Next. Evaluates the current form in the single-step mode.

:s@c, :skip

Skip. Evaluates the current form in the ordinary mode. The single-step mode will be resumed at completion of the evaluation.

:b@c, :back

Backwards. Steps back to previous step form.

:pr@c, :print

Print. Pretty-prints the current form.

:form

Form. Return the current form. Nothing is done, but the current form is returned as the value of this command. As a consequence, it is printed by the top level in the usual way and saved in the variable *. The main purpose of this command is to allow the current form to be examined further by accessing *.

:ret@c, :return

Return. Return without evaluating the current form.

:x@c, :exit

Exit. Evaluates the current form and any other forms in the ordinary mode.

?

Help. Lists the commands.

5.3 Errors

Variable: @defvar{*break-enable*}

This variable is used to determine whether to enter the break loop (see Section 5.4) when an error occurs. Even the function break checks this variable. Initially, this variable is set to T@c, and thus an error will invoke the break loop. If the value is ()@c, functions that cause fatal errors, such as error, will just print an error message and control will return to the top-level loop (or to the current break loop, if already in the break loop). Functions that cause correctable errors, such as cerror, will print an error message and a "continue message", and control will return to the next form. In ECL, backtrace is not part of an error message, but a break loop command will print backtrace. Therefore, if break-enable

When the break loop is entered, break-enable ()@c.

5.4 The Break Loop

There can be several instances of the break loop at the same time, and each such instance is identified by a level number. When the break loop is entered during execution in the top-level loop, the break loop instance is given the level number 1. The break loop instance that is entered from the level n break loop is given the level number n+1. The prompt of the level n break loop is n+1 consecutive >'s, occasionally prefixed with the name of the current package.

The break loop keeps track of the invocation sequence of functions (including special forms and macro expansion functions), which led up to the break loop from the previous break loop (or from the top-level loop, if the current break loop is level 1). The invocation sequence is maintained in a pushdown stack of events. An event consists of an event function and an event environment. An event function is:

1. an interpreted (i.e., not compiled) function (global function, local function, lambda-expression, or closure),

2. a special form within an interpreted function,

3. a macro expansion function called from an interpreted function,

4. a compiled function called from an interpreted function, or

5. a compiled function called from another compiled function which was compiled while the safety optimize level is 3 or with a notinline declaration for the called function (see Chapter 7).

An event is pushed on the event stack when execution of its event function begins, and is popped away at the completion of the execution. An event environment is the `environment' of the event function at the time the next event is pushed. Actually, an event environment is a pointer to the main stack of ECL. For each interpreted event function (i.e., event function in classes 1, 2, and 3), the pointer points to the first entry of the three contiguous main stack entries that hold the lexical environment of the event function. For each compiled event function (i.e., event function in classes 4 and 5), the pointer is set to the first entry of the main stack area that is used locally by the compiled code. In most cases, the first argument to the compiled function is saved in the first entry, the second argument in the second entry, and so on. The local variables of the function are allocated in the entries following the arguments. However, this is not always the case. Refer to Section 7.3 for variable allocations in compiled functions.

By break level commands, the user can choose one of the events as the current event. If the current event function is an interpreted event function, then the break loop evaluates Lisp forms in the lexical environment retrieved from the event environment. In particular, local variables may be referenced by the variable names, local functions and local macros may be invoked as usual, established blocks may be exited from, and tags may be used as the destination of go. If the current function is a compiled function, Lisp forms are evaluated in the null environment.

Within the break loop, each event is represented by the event symbol. The :backtrace symbols. If the event function is a named function (global or local) or a macro expansion function, then the function or macro name is used as the event symbol. If the event function is a special form, then the name of the special form is used. If the event function is a lambda-expression (or a closure), then the symbol lambda (or lambda-closure) is used.

To suppress unnecessary information, the user can hide (or make invisible) some of the events. Invisible events do not appear in the backtrace, for example. Initially, only those events are invisible whose event symbols belong to the system internal package system. When the break loop is entered, the last visible event becomes the current event.

The break loop commands are described below. Some of the commands allow abbreviation in the keywords that identify them. For example, the user may abbreviate :current at all.

Break Command: :current

Break Command: :c {}

Prints the event symbol of the current event.

Break Command: :previous &optional

Break Command: :p {&optional

Makes the n-th previous visible event the new current event. Invisible events are not counted. If there are less than n previous events, then the first visible event in the invocation sequence becomes the new current event. n must be a positive integer and the default is 1.

Break Command: :next &optional

Break Command: :n {&optional

Makes the n-th next visible event the new current event. If there are less than n next events, then the last visible event in the invocation sequence becomes the new current event. n must be a positive integer and the default is 1.

Break Command: :backtrace

Break Command: :b {}

Prints the event symbols of all visible events in order. The symbol of the current event is printed in upper-case letters and the event symbols of other events are in lower-case.

Break Command: :help

Break Command: :h {}

Lists the break loop commands.

Break Command: :quit &optional

Break Command: :q {&optional

Returns control to the level n break loop. If n is 0 or if n is omitted, then control will return to the top-level loop. n must be a non-negative integer smaller than the current break level.

Break Command: :continue

Break Command: :c {}

Returns control to the caller of the break loop. If the break loop has been entered from cerror, cerror returns () control will resume at that point. Otherwise, this command returns control to the previous break loop (or to the top-level loop, if the current break level is 1).

Break Command: :variables

Break Command: :v {}

Prints the names of the bound variables in the current environment. To see the value of a bound variable, just type the variable name.

Break Command: :functions

Prints the names of the local functions and local macros in the current environment. To see the definition of a local function or macro, use the function special form in the usual way. That is, (function name) will return the definition of the local function or macro whose name is name. Local functions and local macros may be invoked as usual.

Break Command: :blocks

Prints the names of the blocks established in the current environment. If a block block is established, then the return-from form (return-from block value) works as usual. That is, the block form that established block will return value as its value and control will resume at that point.

Break Command: :tags

Prints the tags established in the current environment. If a tag tag is established, then the go form (go tag) works as usual. That is, control will resume at the position of tag in the surrounding tagbody.

Break Command: :local &optional

Break Command: :l {&optional

If n is 0 or if it is omitted, then this command prints the value stored in the main stack entry that is pointed to by the current event environment. n is an offset from that entry. If n is positive, then the value of the n-th next (i.e., toward the top of the main stack) entry is printed. If n is negative, then the value of the n-th previous (i.e., toward the bottom of the main stack) entry is printed. n must be an integer. It is an error if the specified entry does not lie between the bottom and the top of the stack.

Break Command: :hide symbol

Hides all events whose event symbol is symbol. In particular, by :hide 'lambda and hide 'lambda-closure, all events become invisible whose event functions are lambda-expressions and closures, respectively. If the event symbol of the current event happens to be symbol, then the last previous visible event will become the new current event. symbol must be a symbol.

Events of eval and evalhook may never become invisible and attempts to hide them are simply ignored. It is always the case that the first event function is either eval or evalhook. Keeping both of them visible is the simplest way to avoid the silly attempts of the user to hide all events.

Break Command: :hide-package package

Hides all events whose event symbol belongs to the package package. package may be any object that represents a package, i.e., a package object, a symbol, or a string. If the event symbol of the current event happens to belong to the package package, then the last previous visible event will become the new current event. Even if lisp package was specified as package, events of eval and evalhook do not become invisible. See the description of :hide

Break Command: :unhide symbol

:unhide belongs to one of the :hide-package@cd packages, events of symbol become visible only after the package is :unhide-package 'd. symbol must be a symbol.

Break Command: :unhide-package package

:unhide-package event whose event symbol belongs to package becomes visible only after the symbol is unhide 'd, if the symbol was :code 'd before. package may be any object that represents a package, i.e., a package object, a symbol, or a string.

Example:

> (defun fact (x) (if (= x 0) one (* x (fact (1- x))))) fact ;;; Wrong definition for fact, the factorial. > (fact 6) ;;; Tries to calculate factorial 6. Error: The variable ONE is unbound. Error signalled by IF. Broken at IF: ;;; Enters the break-loop. >> :h ;;; Help. Break commands: :q(uit) Return to some previous break level. :pop Pop to previous break level. :c(ontinue) Continue execution. :b(acktrace) Print backtrace. :f(unction) Show current function. :p(revious) Go to previous function. :n(ext) Go to next function. :g(o) Go to next function. :fs Search forward for function. :bs Search backward for function. :v(ariables) Show local variables, functions, blocks, and tags. :l(ocal) Return the nth local value on the stack. :hide Hide function. :unhide Unhide function. :hp Hide package. :unhp Unhide package. :unhide-all Unhide all variables and packages. :vs Show value stack. :bds Show binding stack. :m(essage) Show error message. :hs Help stack. Top level commands: :cf Compile file. :exit or ^D Exit Lisp. :ld Load file. :step Single step form. :tr(ace) Trace function. :untr(ace) Untrace function. Help commands: :apropos Apropos. :doc(ument) Document. :h(elp) or ? Help. Type ":help help" for more information. >> :b ;;; Backtrace. Backtrace: eval > fact > if > fact > if > fact > if > fact > if > fact > if > fact > if > fact > IF >>: p ;;; Moves to the previous event. Broken at FACT. >> :b ;;; Now inside of fact but outside of if. Backtrace: eval > fact > if > fact > if > fact > if > fact > if > fact > if > fact > if > FACT > if >> :v ;;; Shows local variables. Local variables: X: 1 Block names: FACT. >> x ;;; The value of x is 1. 1 >> (return-from fact 1) ;;; Returns from the fact block with value 1. 720 ;;; Now the correct answer. > ;;; Top-level.

5.5 Describe and Inspect

Function: describe {object}

Prints the information about object to the stream that is the value of *standard-output*. The description of an object consists of several fields, each of which is described in a recursive manner. For example, a symbol may have fields such as home package, variable documentation, value, function documentation, function binding, type documentation, deftype definition, properties.

Function: inspect {object}

Prints the information about object in an interactive manner. The output of inspect is similar to that of describe, but after printing the label and the value of a field (the value itself is not describe 'd), it prompts the user to input a one-character command. The input to inspect is taken from the stream that is the value of *query-io*. Normally, the inspection of object terminates after all of its fields have been inspected. The following commands are supported:

n

Next. Goes to the next level; the field is inspected recursively.

s

Skip. Skips the inspection of the field. inspect proceeds to the next field.

p

Print. Pretty-prints the field and prompts again.

u form]

Update. The form is evaluated and the field is replaced by the resulting value. If the field cannot be updated, the message Not updated. will be printed.

a

Abort. Aborts the inspection of the current object. The field and the rest of the fields are not inspected.

e form

Eval. Evaluates the specified form in the null environment and prints the resulting values. Then prompts again with the same field.

q

Quit. Aborts the entire inspection.

?

Help. Lists the inspect commands.

5.6 The Profiler

The profiler tool is enabled by default in the basic ECL configuration. It can be disabled with the configure option --disable-profiler.

sys: profile grain &optional

This function activates the profiling of subsequent executions. grain is a value between 1 and 16384 which indicates the granularity of code segments to consider. There is a counter for each such segment. With each clock tick, the current segment is identified and its corresponding histogram count is incremented. A value of 0 for grain means stop profiling. address indicates the base address for the code being profiled.

sys: display-profile

Displays the histogram of accumulated tick counts. The ticks are attributed to the compiled Lisp function whose base address is closest to the start of the segment. This may not be totally accurate for system functions which invoke some auxiliary function to do the job.

sys: clear-profile

Clears the profile histogram.

Variable: sys {*profile-array*}

Contains the profile histogram: two short integer counters are packed in each value of this array of fixnums.

5.7 Online Help

Online help is provided by the following functions.

Function: help {&optional

help with no arguments prints a greeting message to ECL beginners. help with a symbol argument prints the documentation associated with the symbol.

Function: help* {string &optional

Prints the documentation associated with those symbols in the specified package whose print names contain string as substring. string may be a symbol, in which case the print name of that symbol is used. package is optional and defaults to the LISP package. If package is ()@c, then all packages are searched.