@node User Interface, Doc, Iteration and Tests, Top
@chapter User Interface

@defvr {Special Variable} - 
Package:LISP
Holds the top-level form that GCL is currently evaluating.


@end defvr

@defun - (number &rest more-numbers)
Package:LISP

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


@end defun

@deffn {Macro} UNTRACE 
Package:LISP

Syntax:
@example
(untrace @{function-name@}*)
@end example

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


@end deffn

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


@end defvar

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


@end defun

@deffn {Macro} STEP 
Package:LISP

Syntax:
@example
(step form)
@end example

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


@end deffn

@defvar *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.


@end defvar

@defvr {Special Variable} / 
Package:LISP
Holds a list of the values of the last top-level form.


@end defvr

@defun DESCRIBE (x)
Package:LISP

Prints a description of the object X.


@end defun

@defun ED (&optional x)
Package:LISP

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


@end defun

@defvar *DEBUG-IO* 
Package:LISP
Holds the I/O stream used by the GCL debugger.


@end defvar

@defvar *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.


@end defvar

@defun CERROR (continue-format-string error-format-string &rest args)
Package:LISP

Signals a correctable error.


@end defun

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


@end defvar

@defvr {Special Variable} +++ 
Package:LISP
Gets the previous value of ++ when GCL evaluates a top-level form.


@end defvr

@defun INSPECT (x)
Package:LISP

Shows the information about the object X in an interactive manner


@end defun

@defvr {Special Variable} // 
Package:LISP
Gets the previous value of / when GCL evaluates a top-level form.


@end defvr

@defvar *TRACE-OUTPUT* 
Package:LISP
The trace output stream.


@end defvar

@defvr {Special Variable} ++ 
Package:LISP
Gets the previous value of + when GCL evaluates a top-level form.


@end defvr

@defvar *ERROR-OUTPUT* 
Package:LISP
Holds the output stream for error messages.


@end defvar

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


@end defun

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


@end defvar

@defvr {Special Variable} /// 
Package:LISP
Gets the previous value of // when GCL evaluates a top-level form.


@end defvr

@defun WARN (format-string &rest args)
Package:LISP

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


@end defun

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


@end defun

@defvr {Special Variable} + 
Package:LISP
Holds the last top-level form.


@end defvr

@deffn {Macro} TRACE 
Package:LISP

Syntax:
@example
(trace @{function-name@}*)
@end example

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):

@example
;; 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))
@end example

Syntax is @code{:keyword} @i{form1} @code{:keyword} @i{form2} ...

@table @code
@item :declarations
@example
DEFAULT: NIL
@end example

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 .

@item :COND
@example
DEFAULT: T
@end example

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.

@item :ENTRYCOND
@example
DEFAULT: T
@end example

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

@item :ENTRY
@example
DEFAULT: (CONS (QUOTE x) SI::ARGLIST),
@end example

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.

@item :EXITCOND
@example
DEFAULT: T
@end example

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.

@item :EXIT
@example
DEFAULT: (CONS (QUOTE x) VALUES),
@end example

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

@item :DEPTH
@example
DEFAULT:  No depth limit
@end example

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.

@end table

@end deffn