top-level variables

The initial default value is t, which causes a :zoom after moving to a new frame with the top-level commands :dn, :up, :top, and :bottom.

If the value is nil, then there will not be an automatic zoom after moving to a new frame with any of those commands.

If the value is :current, then the top-level commands :dn, :up, :top, :bottom, and :find will print only the current frame.

If the value is an integer n, then the top-level commands :dn, :up, :top, :bottom, and :find will print n frames. Setting *auto-zoom* to an integer will not affect the number of frames :zoom shows (see the :zoom keyword argument count).

This variable is not available in Lisp images built with a minimal top level, that is built with the include-tpl argument to build-lisp-image specified nil. See Minimal top levels in building-images.html for information on minimal top levels.

*command-char*

The value of this variable is character recognized as the prefix for top-level commands. The value of this variable must be a character, and is initially #\: (the colon character).

See top-level.html for more information on the top level and top-level commands.

*default-lisp-listener-bindings*

This variable holds an alist of special variable symbols and forms to evaluate for binding values. These bindings are put into effect at entry to top-level-read-eval-print-loop. These bindings are also put into effect at the outermost entry to a break level read-eval-print loop if the stack-group or thread is not already executing inside top-level-read-eval-print-loop.

*eval*

The values of *read*, eval (this variable), and *print*, if valid functions (that is, ones acceptable to the function funcall), will be funcalled to read user input, evaluate the result from the read, and print the result of the evaluation. If the value of this variable is not a funcallable object, the default function, eval will be used in place of the non-funcallable object. The default value for all three variables is nil.

To be a value of one of these variables, a function must accept one argument (for eval (this variable) and *read*) or two arguments (for *print*). The value of *read* will be passed the stream which is to be read. The value of eval (this variable) will be passed a form to evaluate. The value of *print* will be passed a value to print and a stream. Great care should be taken before setting any of these variables, since binding these to something other than a proper function will result in a recursive error (since after an error, another read-eval-print loop is called). If you change the value of one of these variables, you may return to the default behavior by changing the value back to nil.

If you build an image with the include-tpl keyword argument to build-lisp-image nil, the image will have a minimal top level which will use *read*, eval (this variable), and *print*. The values must be valid functions in that case. See Minimal top levels in building-images.html for information on minimal top levels.

See top-level.html for more information on the top level and top-level commands.

*exit-on-eof*

When the top-level read-eval-print loop reads an EOF (end of file, simulated by Control-D on some systems), the action of Allegro CL depends on the value of this variable. If *exit-on-eof* is t, Lisp will exit. If it is nil (which is the default), the user will be asked if he really wants to exit Lisp. If it is a positive integer, Lisp will exit after exactly that number of consecutive EOFs. Any value other than nil or a positive integer is equivalent to the value t. EOF calls exit with no arguments.

See top-level.html for more information on the top level and top-level commands.

*help-page-length*

The value of this variable must be an integer. If it is a positive integer, that number of lines will be printed by the :help command before it pauses. When the value is a negative integer or zero, :help will print without pausing.

See top-level.html for more information on the top level and top-level commands.

*history*

Evaluates to the number of commands that are remembered by the history mechanism. The most recent elements of the history list are printed by the :history command. The initial value of this variable is 20.

See top-level.html for more information on the top level and top-level commands.

*print-length*

Warning: because this variable does not exist in a minimal top level image, returned values are printed with the specification of *print-length*. If that value is nil, much more may be printed than actually desired.

*print-level*

Warning: because this variable does not exist in a minimal top level image, returned values are printed with the specification of *print-level*. If that value is nil, much more may be printed than actually desired.

*print-long-string-length*

When a string is the return value printed to a Lisp listener, the value of *print-long-string-length* is bound to the value of this variable. That controls how much of the string is printed. Printing all of very long strings (hundreds or thousands or more characters) can make output unreadable and can also cause problems with screens or buffers overflowing.

;; For readability, we first set this variable's value to 100
cl-user(49): (setq tpl:*print-long-string-length* 100)
100
cl-user(50): (make-string 101 :initial-element #\x)
#<Long string(101): "xxxxxxxxxxxxxxxxxxxx..." @ #x10007fb99d2>
cl-user(51): (make-string 99 :initial-element #\y)
"yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
cl-user(52):

See Printing long strings in top-level.html for more information and links to variables that control printing of long strings in various debugging contexts.

*print*

The values of *read*, *eval*, and print (this variable), if valid functions (that is, ones acceptable to the function funcall), will be funcalled to read user input, evaluate the result from the read, and print the result of the evaluation. If the value of this variable is not a funcallable object, the default function, prin1 will be used in place of the non-funcallable object. The default value for all three variables is nil.

To be a value of one of these variables, a function must accept one argument (for *eval* and *read*) or two arguments (for print (this variable)). The value of *read* will be passed the stream which is to be read. The value of *eval* will be passed a form to evaluate. The value of print (this variable) will be passed a value to print and a stream. Great care should be taken before setting any of these variables, since binding these to something other than a proper function will result in a recursive error (since after an error, another read-eval-print loop is called). If you change the value of one of these variables, you may return to the default behavior by changing the value back to nil.

If you build an image with the include-tpl keyword argument to build-lisp-image nil, the image will have a minimal top level which will use *read*, *eval*, and print (this variable). The values must be valid functions in that case. See Minimal top levels in building-images.html for information on minimal top levels.

Note about this variable and the Integrated Development Environment on Windows

In the IDE, listeners bind this variable internally due to the IDE's particular multithreaded and windowized implementation. So binding or setting this variable will have no effect on IDE listeners, but will still affect the console listener and the emacs listener (if any) while the IDE is running.

See top-level.html for more information on the top level and top-level commands.

*prompt*

The value of this variable is used to produce the top-level prompt. It must be a format string or a formatter function that consumes 8 arguments. See The prompt in top-level.html for information on the arguments.

See top-level.html for more information on the top level and top-level commands.

*read*

The values of read (this variable), *eval*, and *print*, if valid functions (that is, ones acceptable to the function funcall), will be funcalled to read user input, evaluate the result from the read, and print the result of the evaluation. If the value of read (this variable) is not a funcallable object, the default function, read will be used in place of the non-funcallable object. The default value for all three variables is nil.

To be a value of one of these variables, a function must accept one argument (for *eval* and read (this variable)) or two arguments (for *print*). The value of read (this variable) will be passed the stream which is to be read. The value of *eval* will be passed a form to evaluate. The value of *print* will be passed a value to print and a stream. Great care should be taken before setting any of these variables, since binding these to something other than a proper function will result in a recursive error (since after an error, another read-eval-print loop is called). If you change the value of one of these variables, you may return to the default behavior by changing the value back to nil.

If you build an image with the include-tpl keyword argument to build-lisp-image nil, the image will have a minimal top level which will use read (this variable), *eval*, and *print*. The values must be valid functions in that case.
See Minimal top levels in building-images.html for information on minimal top levels.

Note about this variable and the Integrated Development Environment on Windows

*reset-hook*

If true and bound to a valid function (something acceptable to funcall), then this function is called (with no arguments) after executing the :reset command.

See top-level.html for more information on the top level and top-level commands. See debugging.html for information on the debugger.

*time-threshold*

The value of this variable can be nil or a positive number. If it is a positive number, then evaluations which take longer than that number of seconds will have a time report (such as printed by the time macro) printed along with the value of the evaluation.

cl-user(1): (setq top-level:*time-threshold* 5.0)
5.0
cl-user(2): (sleep 4)
nil
cl-user(3): (sleep 5.5)
; cpu time (non-gc) 0 msec user, 0 msec system
; cpu time (gc)     0 msec user, 0 msec system
; cpu time (total)  0 msec user, 0 msec system
; real time  5,495 msec
; space allocation:
;  4 cons cells, 32 other bytes, 0 static bytes
nil
cl-user(4):

*top-level-read-eval-print-loop-wrapper*

The value of this variable should be nil or a function which takes two arguments and typically makes some customizations before applying the first argument to the second. The initial value of this variable is nil, which has no effect.

In this rather trivial example, we define the wrapper so that the command character (the value of *command-char*, initially #:) is #$. Of course, in a real example, something more complex would be done, but the form would be similar to this example. These forms must be in an initialization file (such as you .clinit.cl file) because they need to be executed before the top-level starts up.

;;  These forms whould be in an initialization file. When Lisp
;;  starts (assuming the .clinit.cl file is read), the command 
;;  character will be $ (rather than :) in any new lisp listener 
;;  process.
(defun my-lisp-listener-wrapper (function args)
  (let ((tpl:*command-char* #\$))
    (apply function args)))

(setq tpl:*top-level-read-eval-print-loop-wrapper*
      'my-lisp-listener-wrapper)

*zoom-display*

The value of this variable is the maximum number of stack frames displayed by the :zoom command unless a value is specified for the count argument to :zoom. If a value is specified for count, this variable is set to that value. This value should be a positive integer or t (but not another true value and not nil). An integer specifies the number of frames. t specifies that all applicable frames should be printed.

*zoom-print-catches*

If this variable is true, :zoom will print any any currently active catches within active functions. The catches are printed before or after the expression for the frame depending on whether the zoom output-style is :moderate/:intermediate or :verbose, respectively. Note that this variable may be changed with the catches keyword argument to :zoom. The initial value of this variable is nil.

Note: It is difficult to view other threads' catch blocks, so if a lisp process is being focussed when a zoom sees this variable non-nil, a warning is printed and the option is automatically shut off.

*zoom-print-circle*

*zoom-print-length*

:zoom takes a length keyword argument. If that argument is specified, *print-length* is bound to the specified value during the call to :zoom and the value of this argument is ignored.

*zoom-print-level*

:zoom takes a level keyword argument. If that argument is specified, *print-level* is bound to the specified value during the call to :zoom and the value of this argument is ignored.

*zoom-print-long-string-length*

During the printing of stack frames (e.g. because of a call to :zoom), this variable controls how long strings (strings with lengths in the hundreds or thousands) are printed in zoom output.

cl-user(64): (setq short-string (make-string 30 :initial-element #\x))
"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
cl-user(65): (1+ short-string)
Error: `"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"' is not of the expected type `number'
  [condition type: type-error]

Restart actions (select using :continue):
 0: Return to Top Level (an "abort" restart).
 1: Abort entirely from this (lisp) process.
[1] cl-user(66): :zoom :all t
Evaluation stack:

... 1 more newer frame ...

   (excl::internal-invoke-debugger "Error" #<type-error @ #x10008b79792> ...)
   (error type-error :datum ...)
   (excl::.type-error "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" number)
   (excl::.type-error_2op "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" number)
   [... excl::%eval ]
 ->(eval (1+ short-string))
   (tpl::read-eval-print-one-command nil nil)
   (excl::read-eval-print-loop :level 0)
   (tpl::top-level-read-eval-print-loop1)
   (tpl:top-level-read-eval-print-loop)

... more older frames ...
[1] cl-user(67): :res
cl-user(68): (setq long-string (make-string 200 :initial-element #\y))
"#<String of length 200 that starts "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyy" @
   #x10008b8a8f2>"
cl-user(69): (1+ long-string)
Error: `"yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"'
       is not of the expected type `number'
  [condition type: type-error]

Restart actions (select using :continue):
 0: Return to Top Level (an "abort" restart).
 1: Abort entirely from this (lisp) process.
[1] cl-user(70): :zoom :all t
Evaluation stack:

... 1 more newer frame ...

   (excl::internal-invoke-debugger "Error" #<type-error @ #x10008b8c6e2> ...)
   (error type-error :datum ...)
   (excl::.type-error "#<String of length 200 that starts "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyy" @ #x10008b8a8f2>" number)
   (excl::.type-error_2op "#<String of length 200 that starts "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyy" @ #x10008b8a8f2>" number)
   [... excl::%eval ]
 ->(eval (1+ long-string))
   (tpl::read-eval-print-one-command nil nil)
   (excl::read-eval-print-loop :level 0)
   (tpl::top-level-read-eval-print-loop1)
   (tpl:top-level-read-eval-print-loop)

... more older frames ...
[1] cl-user(71):

See Printing long strings in top-level.html for more information and links to variables that control printing of long strings in various debugging contexts. Also see debugging.html for more information on the debugger.

*zoom-print-special-bindings*

If this variable is true, :zoom will print any specials that are bound by active functions. The special bindings are printed before or after the expression for the frame depending on whether the zoom output-style is :moderate/:intermediate or :verbose, respectively. If the value of this variable is a list of special variable names, only those special bindings are printed. Note that this variable may be changed with the specials keyword argument to :zoom. The initial value of this variable is nil.

*zoom-show-newer-frames*

If the value of this variable is true, then :zoom shows frames newer than the current frame. If the value is nil, the first displayed frame will be the current frame. The initial value of this variable is t.

This variable is not aable in Lisp images built with a minimal top level, that is built with the include-tpl argument to build-lisp-image