## Program Development Facilities

### 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 both to `2`, so that the current form may not 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, :skip

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

:b, :back

  Backwards. Steps back to previous step form.

:pr, :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, :return

  Return. Return without evaluating the current form.

:x, :exit

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

`?`

  Help. Lists the commands.

### Errors

>      Variable: *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, and thus an error will invoke the break loop. If the value is (), 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 is (), no backtrace appears on the screen.

> When the break loop is entered, break-enable will be bound to ().

### The Break Loop

The break loop is a read-eval-print loop similar to the top-level loop. In addition to ordinary Lisp forms, the break loop accepts various commands with which the user can inspect and modify the state of the program execution. Each break loop command is identified with a keyword (i.e., a symbol in the `keyword` package). A break loop command is executed when the user inputs a list whose first element is the keyword that identifies the command. The rest of the list is the arguments to the command. They are evaluated before being passed to the command. If the command needs no arguments, then the user may input only the keyword. It is an error if the given keyword does not identify any command. Any other input to the break loop is regarded as an ordinary Lisp form; the form will be evaluated and the resulting values will be printed on the terminal.

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 command, for example, lists events in terms of their event 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 as :c. The break loop commands return no values at all.

>      Break Command: :current

>      Break Command: :c

> Prints the event symbol of the current event.

>      Break Command: :previous &optional n

>      Break Command: :p &optional n

> 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 n

>      Break Command: :n &optional n

> 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 n

>      Break Command: :q &optional n

> 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 () as its value and 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 n

>      Break Command: :l &optional n

> 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 above.

>      Break Command: :unhide symbol

> :unhide is the inverse command of :hide. If, however, symbol belongs to one of the :hide-packaged 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 is the inverse command of :hide-package. However, an 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.

### 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.

### 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 address

> 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.

### Online Help

Online help is provided by the following functions.

>      Function: help &optional symbol

> `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 package

> 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 (), then all packages are searched.