alias

macro, top-level package

Arguments: name args &body body

This macro is used to define top-level aliases. The syntax of alias is similar to that of defun, and body can be anything acceptable in the body of a lambda expression. name can be a string or a list of a string and options. The string is the name of the top-level alias. If (string option*) is used, the options are (either or both may be specified) the keyword :case-sensitive and the integer abbreviation index.

As with defun, if there is more than one form after the argument list, and the first form is a string, it is assumed to be a documentation string and is used for documenting the command. The :help top-level command will display the new command created by alias and will use the documentation string, if present, for documentation.

If the :case-sensitive option is chosen, the arguments will be read in case-sensitive mode without regard to the current reader mode. This option is most appropriate when the argument is a filename. Case-sensitivity is fully described in case.html.

If an abbreviation index is supplied, it must be an integer which is interpreted as an index into the string specified by the string which is either the value of or the first element of name. This index identifies the shortest substring which will stand for the entire command. Note that string indexing is zero-based. For example,

("load" 1)

specifies that lo and loa are valid abbreviations for load, while

("load" 0)

specifies l as well. Note that it is possible that the same substring will be common to more than one command. In that case, the substring calls the most recently defined command. However, no warning is printed when a command is defined that leads to such a conflict.

args is the list of formal parameters to the alias, and has the same form as the formal list of a lambda expression.

An alias can also be defined with setf, in the following way:

  (setf (top-level:alias "foo") 
     #'(lambda (arg) (format t "foo: arg is ~s~%"
  arg))) 

That form has the same effect as:

  (top-level:alias "foo" (arg) 
             (format t "foo: arg is ~s~%"
  arg)) 

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

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

do-command

function, top-level package

Arguments: name &rest args

This function allows the execution of top-level commands from programs. It hides the method of dispatch for top-level commands, and should be the sole means of accessing top-level commands outside typing them to the top-level read-eval-print loop.

name must be a string or symbol naming a top-level command. An error is signaled if it is not. args are the arguments that are passed to the command.

For example, the form

(tpl:do-command "history" :reverse t)

will print the command history in reverse order, just like

:history :reverse t

When Lisp is starting up, information necessary or environment necessary to process many top-level commands is not available while initialization files (such as .clinit.cl, clinit.cl, and sys:siteinit.cl) are being read. Therefore, using this function to call those top-level commands from within initialization files may cause an error (perhaps an unrecoverable error). Among the commands that are known to fail are :zoom and its relatives. We recommend that you do not call any top-level commands in initialization files.

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

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

remove-alias

function, top-level package

Arguments: &rest aliases

This function will remove the alias commands specified by aliases, or all user-defined aliases if the argument is :all. Built-in top-level commands may not be removed with this function. If abbreviations were specified for aliases, then all abbreviations are also removed from the command set.

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

Aliases are defined with alias.

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

setq-default

macro, top-level package

Arguments: symbol value

This macro does two things: (1) it sets the global value (as returned by global-symbol-value of symbol to be the value of value (note: symbol is not evaluated, value is evaluated, just as in setq); (2) checks the relevant alists and modifies them as necessary.

Here is exactly what happens in (2). The system checks whether symbol is the key of any pair in the alist which is the value of *default-lisp-listener-bindings*; if it is, the system changes the value of that pair to

(sys:global-symbol-value variable)

If symbol is not the key of any pair on *default-lisp-listener-bindings*, the system checks whether it is the key of any pair on *cl-default-special-bindings*; if it is, the system changes the value on that alist as above. If the symbol is not the key of a pair on either list, the system adds the pair

(variable . (sys:global-symbol-value symbol))

to the *cl-default-special-bindings* alist.

The variable *default-lisp-listener-bindings* is used by the system only when listener processes (including the Initial Lisp Listener which provides the prompt when Lisp comes up) are created. Therefore, only those processes will see the value on the alist and the symbol will be bound (meaning that changing it with setf and setq will affect that process only) on listeners. This macro does not affect the binding of any running process. You should use this macro in your .clinit.cl or sys:siteinit.cl files and in custom.cl (used when the Lisp image is built - see building-images.html) only for those symbols already on the *cl-default-special-bindings* alist or the *default-lisp-listener-bindings* alist unless you want to bind the symbol in Lisp-listener processes. Note further the form

(setq <em>variable value</em>) 

in the sys:siteinit.cl, .clinit.cl file or custom.cl file will usually not change the value for a listener process for any variable that does appear in either of the lists because the values on the lists are often specific values (t or nil or 10) and the binding is made to that specific value.

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

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

start-interactive-top-level

function, top-level package

Arguments: stream function args &key initial-bindings

It is the purpose of some processes to communicate with a user over a separate dedicated *terminal-io* stream. (This user is not necessarily a human -- it might be a socket connection to another program, possibly on a different host.) This function is intended as a convenient way to start a process which maintains its own bindings for the standard Common Lisp dynamic variables. *terminal-io* is first bound to stream. Then the process-initial-bindings slot of the process is examined, and if it is nil, the bindings in the initial-bindings keyword to this function are established. (If process-initial-bindings is not nil, the value of the initial-bindings argument is ignored.) The default value for the initial-bindings argument is *cl-default-special-bindings*. Then function is applied to the arguments. Note that the arguments argument is a single list, not an &rest argument.

The name of this function implies a dichotomy between functions created to do predetermined computation which might not need to bind these Lisp-package variables, and those which interact with a user or other external process. Such a dichotomy is reasonable, but of course, only approximates the diversity of real applications.

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

top-level-read-eval-print-loop

function, top-level package

Arguments:

Although the basic algorithm of a Lisp listener is a simple repetition of

(print (eval (read))) 

it is greatly complicated by the need to handle command history, error levels, and other useful features. When an application needs a Lisp listener, often it will be simplest to use this, the default Lisp listener provided by the Allegro CL top level. It takes no arguments, but must be run inside a start-interactive-top-level function. This function does not return. Listeners stop through a non-local exit (triggered, for example, by a call to exit).

The Allegro CL idiom for running a standard Lisp listener communicating with *terminal-io* (this might be done in a *restart-app-function*) looks something like this:

(tpl:start-interactive-top-level *terminal-io* 
       #'tpl:top-level-read-eval-print-loop
        nil)

And the idiom for running a standard Lisp listener inside a window looks something like this:

(process-run-function "My Lisp Listener"
     #'tpl:start-interactive-top-level
     my-window-stream
     #'tpl:top-level-read-eval-print-loop
       nil)

Entry to top-level-read-eval-print-loop establishes additional bindings for certain variables used by the top level loop. These bindings are established inside any bindings established by start-interactive-top-level. The variables and initial binding values are taken from the alist bound to the variable *default-lisp-listener-bindings*.

An operator with this name but with a different definition is used in a Lisp image 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. Follow the link to see the definition (Lisp source code) of top-level-read-eval-print-loop in a minimal top level.

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

Copyright (c) 2023, Franz Inc. Lafayette, CA., USA. All rights reserved.