12 User Interface

Special Variable: -

Package:LISP Holds the top-level form that GCL is currently evaluating.

Function: - (number &rest more-numbers)

Package:LISP

Subtracts the second and all subsequent NUMBERs from the first NUMBER. With one arg, negates it.

Macro: UNTRACE

Package:LISP

Syntax:

(untrace {function-name}*)

Removes tracing from the specified functions. With no FUNCTION-NAMEs, untraces all functions.

Variable: ***

Package:LISP Gets the previous value of ** when GCL evaluates a top-level form.

Function: MAKE-STRING-INPUT-STREAM (string &optional (start 0) (end (length string)))

Package:LISP

Returns an input stream which will supply the characters of String between Start and End in order.

Macro: STEP

Package:LISP

Syntax:

(step form)

Evaluates FORM in the single-step mode and returns the value.

Variable: *BREAK-ENABLE*

Package:LISP GCL specific: When an error occurrs, control enters to the break loop only if the value of this variable is non-NIL.

Special Variable: /

Package:LISP Holds a list of the values of the last top-level form.

Function: DESCRIBE (x)

Package:LISP

Prints a description of the object X.

Function: ED (&optional x)

Package:LISP

Invokes the editor. The action depends on the version of GCL.

Variable: *DEBUG-IO*

Package:LISP Holds the I/O stream used by the GCL debugger.

Variable: *BREAK-ON-WARNINGS*

Package:LISP When the function WARN is called, control enters to the break loop only if the value of this varialbe is non-NIL.

Function: CERROR (continue-format-string error-format-string &rest args)

Package:LISP

Signals a correctable error.

Variable: **

Package:LISP Gets the previous value of * when GCL evaluates a top-level form.

Special Variable: +++

Package:LISP Gets the previous value of ++ when GCL evaluates a top-level form.

Function: INSPECT (x)

Package:LISP

Shows the information about the object X in an interactive manner

Special Variable: //

Package:LISP Gets the previous value of / when GCL evaluates a top-level form.

Variable: *TRACE-OUTPUT*

Package:LISP The trace output stream.

Special Variable: ++

Package:LISP Gets the previous value of + when GCL evaluates a top-level form.

Variable: *ERROR-OUTPUT*

Package:LISP Holds the output stream for error messages.

Function: DRIBBLE (&optional pathname)

Package:LISP

If PATHNAME is given, begins to record the interaction to the specified file. If PATHNAME is not given, ends the recording.

Variable: *

Package:LISP Holds the value of the last top-level form.

Special Variable: ///

Package:LISP Gets the previous value of // when GCL evaluates a top-level form.

Function: WARN (format-string &rest args)

Package:LISP

Formats FORMAT-STRING and ARGs to *ERROR-OUTPUT* as a warning message.

Function: BREAK (&optional (format-string nil) &rest args)

Package:LISP

Enters a break loop. If FORMAT-STRING is non-NIL, formats FORMAT-STRING and ARGS to *ERROR-OUTPUT* before entering a break loop. Typing :HELP at the break loop will list the break-loop commands.

Special Variable: +

Package:LISP Holds the last top-level form.

Macro: TRACE

Package:LISP

Syntax:

(trace {function-name}*)

Traces the specified functions. With no FUNCTION-NAMEs, returns a list of functions currently being traced.

Additional Keywords are allowed in GCL with the syntax (trace {fn | (fn {:kw form}*)}*)

For each FN naming a function, traces that function. Each :KW should be one of the ones listed below, and FORM should have the corresponding form. No :KW may be given more than once for the same FN. Returns a list of all FNs now traced which weren’t already traced.

EXAMPLE (Try this with your favorite factorial function FACT):

;; print entry args and exit values

(trace FACT)

;; Break coming out of FACT if the value is bigger than 1000.

(trace (fact :exit
	     (progn
	       (if (> (car values) 1000)(break "big result"))
	       (car values))))

;; Hairy example:

;;make arglist available without the si:: prefix
(import 'si::arglist)

(trace (fact
        :DECLARATIONS
        ((in-string "Here comes input: ")
         (out-string "Here comes output: ")
         all-values
         (silly (+ 3 4)))
        :COND
        (equal (rem (car arglist) 2) 0)
        :ENTRY
        (progn
          (cond
           ((equal (car arglist) 8)
            (princ "Entering FACT on input 8!! ")
            (setq out-string "Here comes output from inside (FACT 8): "))
           (t
            (princ in-string)))
          (car arglist))
        :EXIT
        (progn
          (setq all-values (cons (car values) all-values))
          (princ out-string)
          (when (equal (car arglist) 8)
                ;; reset out-string
                (setq out-string "Here comes output: "))
          (cons 'fact values))
        :ENTRYCOND
        (not (= (car arglist) 6))
        :EXITCOND
        (not (= (car values) (* 6 (car arglist))))
        :DEPTH
        5))

Syntax is :keyword form1 :keyword form2 ...

:declarations

DEFAULT: NIL

FORM is ((var1 form1 )(var2 form2 )...), where the var_i are symbols distinct from each other and from all symbols which are similarly declared for currently traced functions. Each form is evaluated immediately. Upon any invocation of a traced function when not already inside a traced function call, each var is bound to that value of form .

:COND

DEFAULT: T

Here, FORM is any Lisp form to be evaluated (by EVAL) upon entering a call of FN, in the environment where si::ARGLIST is bound to the current list of arguments of FN. Note that even if the evaluation of FORM changes the value of SI::ARGLIST (e.g. by evaluation of (SETQ si::ARGLIST ...)), the list of arguments passed to FN is unchanged. Users may alter args passed by destructively modifying the list structure of SI::ARGLIST however. The call is traced (thus invoking the :ENTRYCOND and :EXITCOND forms, at least) if and only if FORM does not evaluate to NIL.

:ENTRYCOND

DEFAULT: T

This is evaluated (by EVAL) if the :COND form evaluates to non-NIL, both in an environment where SI::ARGLIST is bound to the current list of arguments of FN. If non-NIL, the :ENTRY form is then evaluated and printed with the trace "prompt".

:ENTRY

DEFAULT: (CONS (QUOTE x) SI::ARGLIST),

where x is the symbol we call FN If the :COND and :ENTRYCOND forms evaluate to non-NIL, then the trace "prompt" is printed and then this FORM is evaluated (by EVAL) in an environment where SI::ARGLIST is bound to the current list of arguments of FN. The result is then printed.

:EXITCOND

DEFAULT: T

This is evaluated (by EVAL) in the environment described below for the :EXIT form. The :EXIT form is then evaluated and printed with the "prompt" if and only if the result here is non-NIL.

:EXIT

DEFAULT: (CONS (QUOTE x) VALUES),

where x is the symbol we call FN Upon exit from tracing a given call, this FORM is evaluated (after the appropriate trace "prompt" is printed), using EVAL in an environment where SI::ARGLIST is bound to the current list of arguments of FN and VALUES is bound to the list of values returned by FN (recalling that Common Lisp functions may return multiple values).

:DEPTH

DEFAULT:  No depth limit

FORM is simply a positive integer specifying the maximum nesting of traced calls of FN, i.e. of calls of FN in which the :COND form evaluated to non-NIL. For calls of FN in which this limit is exceeded, even the :COND form is not evaluated, and the call is not traced.