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.