1.1 General Information

The Lisp Machine is a new computer system designed to provide a high performance and economical implementation of the Lisp language. It is a personal computation system, which means that processors and main memories are not time-multiplexed: each person gets his own for the duration of the session. It is designed this way to relieve the problems of the running of large Lisp programs on time-sharing systems. Everything on the Lisp Machine is written in Lisp, including all system programs; there is never any need to program in machine language. The system is highly interactive.

This document is intended to serve both as a User’s Guide and as a Reference Manual for the language and the Lisp Machine itself. It is hoped that anyone with some previous programming experience (not necessarily in Lisp) could learn all about the Lisp language and the Lisp Machine from this manual.

This is a preliminary version of the Manual. The authors are well aware that several sections are missing. Some small sections were left out in the interest of publishing a manual as quickly as possible. Several full chapters have not been written because the corresponding software has not settled down enough for a meaningful document to be written; these include chapters on the Chaos network, the mouse, and menus. Many more major software changes are expected in both the language and the system; this manual is far from the last word.

The Lisp Machine executes a new dialect of Lisp called Lisp Machine Lisp, developed at the M.I.T. Artificial Intelligence Laboratory for use in artificial intelligence research and related fields. It is closely related to the Maclisp dialect, and attempts to maintain a good degree of compatibility with Maclisp, while also providing many improvements and new features. Maclisp, in turn, is based on Lisp 1.5.

1.2 Structure of the Manual

This manual attempts to document both the dialect of Lisp used on the Lisp Machine, and the system itself. The manual starts out with an explanation of the language. Chapter 2 presents some basic predicate functions, Chapter 3 explains the process of evaluation, and Chapter 4 introduces the basic Lisp control structures.

Next, in Chapters 4 through 12, various Lisp data types are presented, along with functions for manipulating objects of those types. These nine chapters discuss list structure, symbols, numbers, strings, arrays, closures, stack groups, and locatives.

Chapter 13 explains the "subprimitive" functions, which are primarily useful for implementation of the Lisp language itself and the Lisp Machine’s "operating system". Chapter 14 explains areas, which give the programmer control over storage and locality of reference.

Chapter 15 discusses the Lisp compiler, which converts Lisp programs into "machine language". Chapter 16 explains the Lisp macro facility, which allows users to write their own extensions to Lisp, and Chapter 17 goes into detail about one such extension that provides structures.

Chapter 18 explains the Lisp Machine’s Input/Output system, including streams and the printed representation of Lisp objects. Chapter 19 describes the package system, which allows many name spaces within a single Lisp environment. Chapter 20 talks about how files from a file system are used from Lisp.

Chapter 21 discusses the job system, which allows shared access to the TV screen, and multiple processes. Chapter 22 goes into detail on the TV display itself. Chapter 23 explains how exceptional conditions (errors) can be handled by programs, handled by users, and debugged. Chapter 24 contains other miscellaneous functions and facilities.

1.3 Notational Conventions and Helpful Notes

There are several conventions of notation, and various points that should be understood before reading the manual, particularly the reference sections, to avoid confusion.

Most numbers shown are in octal radix (base eight). Spelled out numbers and numbers followed by a decimal point are in decimal. This is because, by default, Lisp Machine Lisp types out numbers in base 8; don’t be surprised by this. To change it, see the documentation on the symbols ibase and base (ibase-var).

The symbol " => " will be used to indicate evaluation in examples. Thus, when you see " foo => nil", this means the same thing as "the result of evaluating foo is (or would have been) nil".

All uses of the phrase "Lisp reader", unless further qualified, refer to the part of Lisp which reads characters from I/O streams (the read function), and not the person reading this manual.

There are several terms which are used widely in other references on Lisp, but are not used much in this document since they have become largely obsolete and misleading. For the benefit of those who may have seen them before, they are: "S-expression", which means a Lisp object; "Dotted pair", which means a cons, and "Atom", which means, roughly, symbols and numbers and sometimes other things, but not conses.

The characters acute accent (') (also called "single quote") and semicolon (;) have special meanings when typed to Lisp; they are examples of what are called macro characters. Though the mechanism of macro characters is not of immediate interest to the new user, it is important to understand the effect of these two, which are used in the examples. When the Lisp reader encounters a "'", it reads in the next Lisp object and encloses it in a quote special form. That is, 'foo-symbol turns into (quote foo-symbol), and '(cons 'a 'b) turns into (quote (cons (quote a) (quote b))). The reason for this is that "quote" would otherwise have to be typed in very frequently, and would look ugly. The semicolon is used as a commenting character. When the Lisp reader sees one, the remainder of the line is discarded. The character "/" is used for quoting strange characters so that they are not interpreted in their usual way by the Lisp reader, but rather are treated the way normal alphabetic characters are treated. So, for example, in order to give a "/" to the reader, you must type "//", the first "/" quoting the second one. When a character is preceeded by a "/" it is said to be slashified. Slashifying also turns off the effects of macro characters such as "'" and ";". The following characters also have special meanings, and may not be used in symbols without slashification. These characters are explained in detail in the section on printed-representation (reader).

"

String quote

#

Introduces miscellaneous reader macros

,

See `

:

Package prefix

`

List structure construction

|

Symbol quoter

circleX

Octal escape

All Lisp code in this manual is written in lower case. In fact, the reader turns all symbols into upper-case, and consequently everything prints out in upper case. You may write programs in whichever case you prefer.

By convention, all "keyword" symbols in the Lisp machine system have names starting with a colon (:). The colon character is not actually part of the print name, but is a package prefix indicating that the symbol belongs to the package with a null name, which means the user package. If you are not using packages, that is, you are doing everything in the user package, it is not necessary to type the colon. However, it is recommended that you always put in the colon so that you will not have problems if you later put your program into a package. But it is necessary to leave out the colon in programs that must run in both Maclisp and Lisp Machine Lisp. The colon can usually be omitted when you are simply typing at the top-level of Lisp, since your typein is being read in the user package, but it is better to type it so you will get used to it. In this manual the colon will always be included.

Lisp Machine Lisp is descended from Maclisp, and a good deal of effort was gone through to try to allow Maclisp programs to run in Lisp Machine Lisp. There is an extensive section explaining the differences between the dialects, and how to convert Maclisp programs to work in the Lisp Machine. For the new user, it is important to note that many functions herein exist solely for Maclisp compatibility; they should not be used in new programs. Such functions are clearly marked in the text.

The Lisp Machine character set is not quite the same as that used on I.T.S. nor on Multics; it is described in all detail elsewhere in the manual. The important thing to note for now is that the character "newline" is the same as "return", and is represented by the number 215 octal.

When the text speaks of "typing Control-Q" (for example), this means to hold down the CTRL key on the keyboard (either of the two), and, while holding it down, to strike the "Q" key. Similarly, to type "Meta-P", hold down either of the META keys and strike "P". To type "Control-Meta-T" hold down both CTRL and META. Unlike the PDP-10, there are no "control characters" in the character set; Control and Meta are merely things that can be typed on the keyboard.

Many of the functions refer to "areas". The area feature is only of interest to writers of large systems, and can be safely disregarded by the casual user. It is described elsewhere.

The rest of this chapter explains more of the details of the Lisp Machine Lisp dialect. This section is also suitable for the Maclisp user, as it goes into detail about important differences between the dialects. Those Maclisp users who have skipped the previous sections should definitely read this one.

1.4 Data Types

This section enumerates the various different types of objects in Lisp Machine Lisp. The types explained below include symbols, conses, various types of numbers, two kinds of compiled code object, locatives, arrays, stack groups, and closures. With each is given the associated symbolic name, which is returned by the function data-type (data-type-fun).

A symbol (these are sometimes called "atoms" or "atomic symbols" by other texts) has a print name, a binding, a definition, a property list, and a package.

The print name is a string, which may be obtained by the function get-pname (get-pname-fun). This string serves as the printed representation (see printer) of the symbol. The binding (sometimes also called the "value") may be any object. It is also referred to sometimes as the "contents of the value cell", since internally every symbol has a cell called the value cell which holds the binding. It is accessed by the symeval function (symeval-fun), and updated by the set function (set-fun). (That is, given a symbol, you use symeval to find out what its binding is, and use set to change its binding.) The definition may also be any Lisp object. It is also referred to as the "contents of the function cell", since internally every symbol has a cell called the function cell which holds the definition. The definition can be accessed by the fsymeval function (fsymeval-fun), and updated with fset (fset-fun). The property list is a list of an even number of elements; it can be accessed directly by plist (plist-fun), and updated directly by setplist (setplist-fun), although usually the functions get, putprop, and remprop (get-fun) are used. The property list is used to associate any number of additional attributes with a symbol–attributes not used frequently enough to deserve their cells as the value and definition do. Symbols also have a package cell, which indicates which "package" of names the symbol belongs to. This is explained further in the section on packages and can be disregarded by the casual user.

The primitive function for creating symbols is make-symbol (make-symbol-fun) (currently named make-atom), although most symbols are created by read, intern, or fasload (who call make-symbol themselves.)

A cons is an object that cares about two other objects, arbitrarily named the car and the cdr. These objects can be accessed with car and cdr (car-fun), and updated with rplaca and rplacd (rplaca-fun). The primitive function for creating conses is cons (cons-fun).

There are several kinds of numbers in Lisp Machine Lisp. Fixnums represent integers in the range of -2^23 to 2^23-1. Bignums represent integers of arbitrary size, with more overhead than fixnums. The system automatically converts between fixnums and bignums as required. Flonums are floating-point numbers. Small-flonums are another kind of floating-point numbers, with less range and precision, but less computational overhead. Other types of numbers are likely to be added in the future. See number for full details.

The usual form of compiled code is a Lisp object called a "Function Entry Frame" or "FEF". A FEF contains the code for one function. This is analogous to what Maclisp calls a "subr pointer". FEFs are produced by the Lisp Compiler (compiler), and are usually found as the definitions of symbols. The printed representation of a FEF includes its name, so that it can be identified. Another Lisp object which represents executable code is a "micro-code entry". These are the microcoded primitive functions of the Lisp system, and user functions compiled into microcode.

About the only useful thing to do with one of these objects is to apply it to arguments. However, some functions are provided for examining such objects, for user convenience. See arglist (arglist-fun), args-info (args-info-fun), describe (describe-fun), and disassemble (disassemble-fun).

A locative (see locative) is a kind of a pointer to a single cell anywhere in the system. The contents of this cell can be accessed by either car or cdr (both do the same thing for a locative) (see car-fun) and updated by either rplaca or rplacd (see rplaca-fun).

An array (see array) is a set of cells indexed by a tuple of integer subscripts. The contents of cells may be accessed and changed individually. There are several types of arrays. Some have cells which may contain any object, while others (numeric arrays) may only contain small positive numbers. Strings are a type of array; the elements are 8-bit positive numbers which encode characters.

1.5 Lambda Lists

Note: the examples in this section are examples of lambda-lists, not of Lisp forms!

A lambda-expression is the form of a user-defined function in Lisp. It looks like (lambda lambda-list body). The body may be any number of forms. In Maclisp and Lisp 1.5, the lambda-list (also called a bound-variable list) is simply a list of symbols (which act like formal parameters in some other languages). When the lambda-expression is applied to its arguments (which act like actual parameters in other languages), the symbols are bound to the arguments, and the forms of the body are evaluated sequentially; the result of the last of these evaluations is returned. If the number of arguments is not the same as the length of the lambda-list, an error is generated.

In Lisp Machine Lisp the same simple lambda-lists may be used, but there are additional features accessible via certain keywords (which start with &) and by using lists as elements of the lambda-list.

The principle weakness of the simple scheme is that any function must only take a certain, fixed number of arguments. As we know, many very useful functions, such as list, append, +, and so on, may take a varying number of arguments. Maclisp solved this problem by the use of lexprs and lsubrs, which were somewhat inelegant since the parameters had to be referred to by numbers instead of names (e.g. (arg 3)). (For compatibility reasons, Lisp Machine Lisp supports lexprs, but they should not be used in new programs).

In general, a function in Lisp Machine Lisp has zero or more required parameters, followed by zero or more optional parameters, followed by zero or one rest parameter. This means that the caller must provide enough arguments so that each of the required parameters gets bound, but he may provide some extra arguments for each of the optional parameters. Also, if there is a rest parameter, he can provide as many extra arguments as he wants, and the rest parameter will be bound to a list of all these extras. Also, optional parameters may have a default-form, which is a form to be evaluated to produce the default argument if none is supplied. Here is the exact explanation of how this all works. When apply matches up the arguments with the parameters, it follows the following algorithm: The first required parameter is bound to the first argument. apply continues to bind successive required parameters to the successive arguments. If, during this process, there are no arguments left but there are still some required parameters which have not been bound yet, then an error is caused ("too few arguments"). Next, after all required parameters are handled, apply continues with the optional parameters, binding each argument to each successive parameter. If, during this process, there are no arguments left, each remaining optional parameter’s default-form is evaluated, and the parameter is bound to it. This is done one parameter at a time; that is, first one default-form is evaluated, and then the parameter is bound to it, then the next default-form is evaluated, and so on. This allows the default for an argument to depend on the previous argument. Finally, if there is no rest parameter and there are no remaining arguments, we are finished. If there is no rest parameter but there are still some arguments remaining, an error is caused ("too many arguments"). But if there is a rest parameter, it is bound to a list of all of the remaining arguments. (If there are no remaining arguments, it gets bound to nil.) The way you express which parameters are required, optional, and rest is by means of specially recognized symbols, which are called &-keywords, in the lambda-list. All such symbols’ print names begin with the character "&". A list of all such symbols is the value of the symbol lambda-list-keywords. The keywords used here are &optional and &rest. The way they are used is best explained by means of examples; the following are typical lambda-lists, followed by descriptions of which parameters are required, optional, and rest.

(a b c)

a, b, and c are all required. This function must be passed three arguments.

(a b &optional c)

a and b are required, c is optional. The function may be passed either two or three arguments.

(&optional a b c)

a, b, and c are all optional. The function may be passed any number of arguments between zero and three, inclusively.

(&rest a)

a is a rest parameter. The function may be passed any number of arguments.

(a b &optional c d &rest e)

a and b are required, c and d are optional, and e is rest. The function may be passed two or more arguments.

In all of the cases above, the default-forms for each parameter were nil. To specify your own default forms, instead of putting a symbol as the element of a lambda-list, put in a list whose first element is the symbol (the parameter itself) and whose second element is the default-form. For example:

(a &optional (b 3))

The default-form for b is 3. a is a required parameter, and so it doesn’t have a default form.

(&optional (a 'foo) b (c (symeval a)) &rest d)

a’s default-form is 'foo, b’s is nil, and c’s is (symeval a). Note that if the function whose lambda-list this is were called on no arguments, a would be bound to the symbol foo, and c would be bound to the binding of the symbol foo; this illustrates the fact that each variable is bound immediately after its default-form is evaluated, and so later default-forms may take advantage of earlier parameters in the lambda-list. b and d would be bound to nil.

It is also possible to include, in the lambda-list, some other symbols which are bound to the values of their default-forms upon entry to the function. These are not parameters, and they are never bound to arguments; they are like "prog variables". To include such symbols, put them after any parameters, preceeded by the &-keyword &aux. Examples:

(a &optional b &rest c &aux d (e 5) (f (cons a e)))

d, e, and f are bound, when the function is called, to nil, 5, and a cons of the first argument and 5.

Note that aux-variables are bound sequentially rather than in parallel.

It is important to realize that the list of arguments to which a rest-parameter is bound is set up in whatever way is most efficiently implemented, rather than in the way that is most convenient for the function receiving the arguments. It is guaranteed neither to be a "real" list, nor to be a temporary object which may be freely modified. Sometimes the rest-args list is stored in the function-calling stack, and loses its validity when the function returns; if a rest-argument is to be returned or made part of permanent list-structure, it must first be copied (see append). The system will not detect the error of omitting to copy a rest-argument; you will simply find that you have a value which seems to change behind your back. At other times the rest-args list will be an argument that was given to apply; therefore it is not safe to rplaca this list as you may modify permanent data structure. An attempt to rplacd a rest-args list will be unsafe in this case, while in the first case it would cause an error.

3.1 Functions and Special Forms

Function: eval x ¶

(eval x) evaluates x, and returns the result.

Example:

(setq x 43 foo 'bar)
(eval (list 'cons x 'foo))
    => (43 . bar)

It is unusual to explicitly call eval, since usually evaluation is done implicitly. If you are writing a simple Lisp program and explicitly calling eval, you are probably doing something wrong. eval is primarily useful in programs which deal with Lisp itself, rather than programs about knowledge or mathematics or games. Also, if you are only interested in getting at the value of a symbol (that is, the contents of the symbol’s value cell), then you should use the primitive function symeval. Note: the actual name of the compiled code for eval is "si:*eval"; this is because use of the evalhook feature binds the function cell of eval. If you don’t understand this, you can safely ignore it. Note: unlike Maclisp, eval never takes a second argument; there are no "binding context pointers" in Lisp Machine Lisp. They are replaced by Closures (see closure).

Function: apply fn arglist ¶

(apply fn arglist) applies the function fn to the list of arguments arglist. arglist should be a list; fn can be a compiled-code object, or a "lambda expression", i.e., a list whose car is the symbol lambda, or a symbol, in which case its definition (the contents of its function cell) is used.

Examples:

(setq f '+) (apply f '(1 2)) => 3
(setq f '-) (apply f '(1 2)) => -1
(apply 'cons '((+ 2 3) 4)) =>
		((+ 2 3) . 4)	not (5 . 4)

Of course, arglist may be nil. Note: unlike Maclisp, apply never takes a third argument; there are no "binding context pointers" in Lisp Machine Lisp.

Compare apply with funcall and eval.

Function: funcall f &rest args ¶

(funcall f a1 a2 ... an) applies the function f to the arguments a1, a2, ..., an. f may not be a special form nor a macro; this would not be meaningful.

Example:

(cons 1 2) => (1 . 2)
(setq cons 'plus)
(funcall cons 1 2) => 3

Function: lexpr-funcall f &rest args ¶

lexpr-funcall is like a cross between apply and funcall. (lexpr-funcall f a1 a2 ... an list) applies the function f to the arguments a1 through an followed by the elements of list.

Examples:

(lexpr-funcall 'plus 1 1 1 '(1 1 1)) => 6

(defun report-error (&rest args)
   (lexpr-funcall (function format) error-output args))

Note: the Maclisp functions subrcall, lsubrcall, and arraycall are not needed on the Lisp Machine; funcall is just as efficient.

Special Form: quote ¶

(quote x) simply returns x. It is useful because it takes the argument quoted, so that it is not evaluated by eval. quote is used to include constants in a form.

Examples:

(quote x) => x
(setq x (quote (some list)))   x => (some list)

Since quote is so useful but somewhat cumbersome to type, the reader normally converts any form preceded by a single quote (') character into a quote form.

For example,
(setq x '(some list))
is converted by read into
(setq x (quote (some list)))

Special Form: function ¶

(function x) is similar to quote, except that it implies to the compiler that x is a function. In the interpreter, if x is a symbol (function x) returns x’s definition; otherwise x itself is returned. Because of this, using function rules out the possibility of later changing the function definition of x, including tracing it. Care is required!

Special Form: comment ¶

comment ignores its form and returns the symbol comment.

Example:

(defun foo (x)
    (cond ((null x) 0)
          (t (comment x has something in it)
             (1+ (foo (cdr x))))))

Usually it is preferable to comment code using the semicolon-macro feature of the standard input syntax. This allows the user to add comments to his code which are ignored by the lisp reader.

Example:

(defun foo (x)
    (cond ((null x) 0)
          (t (1+ (foo (cdr x))))     ;x has something in it
      ))

A problem with such comments is that they are discarded when the S-expression is read into lisp. If the function is read into Lisp, modified, and printed out again, the comment will be lost. However, this style of operation is hardly ever used; usually the source of a function is kept in an editor buffer and any changes are made to the buffer, rather than the actual list structure of the function. Thus, this is not a real problem.

Macro: @define ¶

This macro turns into nil. It exists for the sake of the  listing generation program, which uses it to declare names of special forms which define objects (such as functions) which  should cross-reference.

Special Form: progn ¶

A progn-form looks like (progn form1 form2 ...). The forms are evaluated in order from left to right and the value of the last one is the result of the progn. progn is the primitive control structure construct for "compound statements". Although lambda-expressions, cond-forms, do-forms, and many other control structure forms use progn implicitly, that is, they allow multiple forms in their bodies, there are occasions when one needs to evaluate a number of forms for their side-effects and make them appear to be a single form.

Example:

(foo (cdr a)
     (progn (setq b (extract frob))
	    (car b))
     (cadr b))

Special Form: prog1 ¶

prog1 is similar to progn, but it returns the value of its first form. It is most commonly used to evaluate an expression with side effects, and return a value which must be computed before the side effects happen.

Example:

(setq x (prog1 y (setq y x)))

which interchanges the values of the variables x and y.

prog1 could have been defined as:

(defun prog1 (&rest values)
    (car values))

It is actually implemented as a macro which expands into a prog2.

Special Form: prog2 ¶

prog2 is similar to progn and prog1, but it returns its second argument. It is included largely for Maclisp compatibility. It has two purposes: to evaluate two forms sequentially, which can be done more generally with progn, or to do what prog1 is used for (c.f. prog1 above).

Special Form: let ¶

let is used to bind some variables for some objects. A let form looks like

(let ((var1 vform1)
      (var2 vform2)
      ...)
  bform1
  bform2
  ...)

When this form is evaluated, first the vforms are evaluated. Then the vars are bound to the values returned by the corresponding vforms. Finally, the bforms are evaluated sequentially and the result of the last one returned.

let is implemented as a macro which expands into a lambda-combination; however, it is preferable to use let rather than lambda because the variables and the corresponding forms appear textually close to each other, which increases readability of the program.

See also let-globally, let-globally-fun.

Special Form: progv ¶

progv is a special form to provide the user with extra control over lambda-binding. It binds a list of symbols to a list of values, and then evaluates some forms. The lists of symbols and values are computed quantities; this is what makes progv different from lambda, let, prog, and do.

(progv symbol-list value-list form1 form2 ... )

first evaluates symbol-list and value-list. Then the symbols are bound to the values. In compiled code the symbols must be special, since the compiler has no way of knowing what symbols might appear in the symbol-list. If too few values are supplied, the remaining symbols are bound to nil. If too many values are supplied, the excess values are ignored.

After the symbols have been bound to the values, the forms are evaluated, and finally the symbols’ bindings are undone. The result returned is the value of the last form. Note that the "body" of a progv is similar to that of progn, not that of prog.

Example:

(setq a 'foo b 'bar)

(progv (list a b 'b) (list b) (list a b foo bar))
    => (foo nil bar nil)

During the evaluation of the body of this progv, foo is bound to bar, bar is bound to nil, b is bound to nil, and a remains bound to foo.

See also bind (see bind-fun), which is a subprimitive which gives you maximal control over binding.

The following three functions (arg, setarg, and listify) exist only for compatibility with Maclisp lexprs.

Function: arg x ¶

(arg nil), when evaluated during the application of a lexpr, gives the number of arguments supplied to that lexpr. This is primarily a debugging aid, since lexprs also receive their number of arguments as the value of their lambda-variable.

(arg i), when evaluated during the application of a lexpr, gives the value of the i’th argument to the lexpr. i must be a fixnum in this case. It is an error if i is less than 1 or greater than the number of arguments supplied to the lexpr.

Example:

(defun foo nargs            ;define a lexpr foo.
    (print (arg 2))         ;print the second argument.
    (+ (arg 1)              ;return the sum of the first
       (arg (- nargs 1))))  ;and next to last arguments.

Function: setarg i x ¶

setarg is used only during the application of a lexpr. (setarg i x) sets the lexpr’s i’th argument to x. i must be greater than zero and not greater than the number of arguments passed to the lexpr. After (setarg i x) has been done, (arg i) will return x.

Function: listify n ¶

(listify n) manufactures a list of n of the arguments of a lexpr. With a positive argument n, it returns a list of the first n arguments of the lexpr. With a negative argument n, it returns a list of the last (abs n) arguments of the lexpr. Basically, it works as if defined as follows:

    (defun listify (n)
         (cond ((minusp n)
                (listify1 (arg nil) (+ (arg nil) n 1)))
               (t
                (listify1 n 1)) ))

    (defun listify1 (n m)      ; auxiliary function.
         (do ((i n (1- i))
              (result nil (cons (arg i) result)))
             ((< i m) result) ))

3.2 Multiple Values

The Lisp machine includes a facility by which the evaluation of a form can produce more than one value. When a function needs to return more than one result to its caller, multiple values are a cleaner way of doing this than returning a list of the values or setq’ing special variables to the extra values.

In the normal case, multiple values are not used. Special syntax is required both to produce multiple values and to receive them. If the caller does not receive multiple values, the first of the multiple values will be received as the ordinary value.

The primitive for producing multiple values is return, which when given more than one argument returns all its arguments as the values of the prog or do from which it is returning. The variant return-from also can produce multiple values. Many system functions produce multiple values, but they all do it via the return primitive.

The special forms for receiving multiple values are multiple-value, multiple-value-list, and multiple-value-bind. These include a form and an indication of where to put the values returned by that form.

Special Form: multiple-value ¶

(multiple-value var-list form) is a special form used for calling a function which is expected to return more than one value. var-list should be a list of variables. form is evaluated, and the variables in var-list will be set (not lambda-bound) to the values returned by form. If more values are returned than there are variables in var-list, then the extra values are ignored. If there are more variables than values returned, extra values of nil are supplied. It is allowed to have nil in the var-list, which means that the corresponding value is to be ignored (you can’t use nil as a variable.)

Example:

(multiple-value (symbol already-there-p)
	(intern "goo"))

intern returns a second value, which is t if the symbol returned as the first value was already on the obarray, or else nil if it just put it there. So if the symbol goo was already on the obarray, the variable already-there-p will be set to t, else it will be set to nil.

multiple-value is usually used for effect rather than for value, however its value is defined to be the first of the values returned by form.

Special Form: multiple-value-bind ¶

This is similar to multiple-value, but locally binds the variables which receive the values, rather than setqing them. The form looks like:

(multiple-value-bind (var1 var2...)
     (function args...)
  body...)

The scope of the binding of var1, var2, etc. is body; they are not bound until after the function call.

Special Form: multiple-value-list ¶

(multiple-value-list form) evaluates form, and returns a list of the values it returned. This is useful for when you don’t know how many values to expect.

Example:

(setq a (multiple-value-list (intern "goo")))
a => (goo nil #<Package User>)

This is similar to the example of multiple-value above; a will be set to a list of three elements, the three values returned by intern. The first is the newly interned symbol goo, the second is nil to indicate that it is newly-interned, and the third is the package on which it was interned.

Due to the syntactic structure of Lisp, it is often the case that the value of a certain form is the value of a sub-form of it. For example, the value of a cond is the value of the last form in the selected clause. In most such cases, if the sub-form produces multiple values, the original form will also produce all of those values. This passing-back of multiple values of course has no effect unless eventually one of the special forms for receiving multiple values is reached. The exact rule governing passing-back of multiple values is as follows:

If X is a form, and Y is a sub-form of X, then if the value of Y is unconditionally returned as the value of X, with no intervening computation, then all the multiple values returned by Y are returned by X. In all other cases, multiple values or only single values may be returned at the discretion of the implementation; users should not depend on this. The reason we don’t guarantee non-transmission of multiple values is because such a guarantee would not be very useful and the efficiency cost of enforcing it would be high. Even setq’ing a variable to the result of a form, then returning the value of that variable might be made to pass multiple values by an optimizing compiler which realized that the setqing of the variable was unnecessary.

Note that use of a form as an argument to a function never passes-back multiple values. We choose not to generate several separate arguments from the several values, because this would make the source code obscure; it would not be syntactically obvious that a single form does not coorrespond to a single argument. Instead the first value of a form is used as the argument and the remaining values are discarded. Passing-back of multiple values happens only with special forms. For clarity, the interaction of several common special forms with multiple values is described. This can all be deduced from the rule given above.

The body of a defun or a lambda, and variations such as the body of a function, the body of a let, etc. pass back multiple values from the last form in the body.

eval, apply, funcall, lexpr-funcall, and <- pass back multiple values from the function called.

progn passes back multiple values from its last form. progv does so also. prog1 and prog2 however do not pass back multiple values.

and and or pass back multiple values from their last form, but not from previous forms since the return is conditional.

cond passes back multiple values from the last form in the selected clause, but not if the clause is only one long (i.e. the returned value is the value of the predicate) since the return is conditional. This applies even to the last clause where the return is not really conditional (the implementation is allowed to pass or not to pass multiple values in this case).

The variants of cond, if, select, selectq, and dispatch pass back multiple values.

prog passes back the number of values given as arguments to the return that returns from it. (return form) may return 1 value or may return all the values of form; as always the implementation is not constrained not to return extra values. (multiple-value-return form) returns from a prog, passing back all the values of form.

do behaves like prog with respect to return. All the values of the last exit-form are returned. [This is the "right" thing unless you think of the implementation in terms of return; what should we do?] *******

unwind-protect does not pass back multiple values. It clearly should, however this is currently difficult to implement. This should be fixed later. *******

3.3 Evalhook

Variable: evalhook ¶

If the value of evalhook is non-nil, then special things happen in the evaluator. When a form (even an atom) is to be evaluated, evalhook is bound to nil and the function which was evalhook’s value is applied to one argument–the form that was trying to be evaluated. The value it returns is then returned from the evaluator. This feature is used by the step program (see step-fun).

evalhook is bound to nil by break and by the error handler, and setq’ed to nil by errors that go back to top level and print *. This provides the ability to escape from this mode if something bad happens.

In order not to impair the efficiency of the Lisp interpreter, several restrictions are imposed on evalhook. It only applies to evaluation – whether in a read-eval-print loop, internally in evaluating arguments in forms, or by explicit use of the function eval. It does not have any effect on compiled function references, on use of the function apply, or on the "mapping" functions. (On the Lisp Machine, as opposed to Maclisp, it is not necessary to do (*rset t) nor (sstatus evalhook t).) (Also, Maclisp’s special-case check for store is not implemented.)

Function: evalhook form hook ¶

evalhook is a function which helps exploit the evalhook feature. The form is evaluated with evalhook lambda-bound to the functional form hook. The checking of evalhook is bypassed in the evaluation of form itself, but not in any subsidiary evaluations, for instance of arguments in the form. This is like a "one-instruction proceed" in a machine-language debugger.

Example:

;; This function evaluates a form while printing debugging information.
(defun hook (x)
   (terpri)
   (evalhook x 'hook-function))

;; Notice how this function calls evalhook to evaluate the form f,
;; so as to hook the sub-forms.
(defun hook-function (f)
   (let ((v (evalhook f 'hook-function)))
     (format t "form: ~s~%value: ~s~%" f v)
     v))

The following output might be seen from (hook '(cons (car '(a . b)) 'c)):

form: (cons (car (quote (a . b))) (quote c))
form: (car (quote (a . b)))
form: (quote (a . b))
value: (a . b)
value: a
form: (quote c)
value: c
value: (a . c)

(a . c)

4.1 Conditionals

Special Form: and ¶

(and form1 form2 ... ) evaluates the forms one at a time, from left to right. If any form evaluates to nil, and immediately returns nil without evaluating the remaining forms. If all the forms evaluate non-nil, and returns the value of the last form. and can be used both for logical operations, where nil stands for False and t stands for True, and as a conditional expression.

Examples:

(and x y)

(and (setq temp (assq x y))
     (rplacd temp z))

(and (not error-p)
     (princ "There was no error."))

Note: (and) => t, which is the identity for this operation.

Special Form: or ¶

(or form1 form2 ...) evaluates the forms one by one from left to right. If a form evaluates to nil, or proceeds to evaluate the next form. If there are no more forms, or returns nil. But if a form evaluates non-nil, or immediately returns that value without evaluating any remaining forms. or can be used both for logical operations, where nil stands for False and t for True, and as a conditional expression.

Note: (or) => nil, the identity for this operation.

Special Form: cond ¶

The cond special form consists of the symbol cond followed by several clauses. Each clause consists of a predicate followed by zero or more forms. Sometimes the predicate is called the antecedent and the forms are called the consequents.

(cond (antecedent consequent consequent...)
      (antecedent)
      (antecedent consequent ...)
      ... )

The idea is that each clause represents a case which is selected if its antecedent is satisfied and the antecedents of all preceding clauses were not satisfied. When a clause is selected, its consequent forms are evaluated.

cond processes its clauses in order from left to right. First, the antecedent of the current clause is evaluated. If the result is nil, cond advances to the next clause. Otherwise, the cdr of the clause is treated as a list of forms, or consequents, which are evaluated in order from left to right. After evaluating the consequents, cond returns without inspecting any remaining clauses. The value of the cond special form is the value of the last consequent evaluated, or the value of the antecedent if there were no consequents in the clause. If cond runs out of clauses, that is, if every antecedent is nil, that is, if no case is selected, the value of the cond is nil.

Example:

    (cond ((zerop x)    ;First clause:
           (+ y 3))     ; (zerop x) is the antecedent.
                        ; (+ y 3) is the consequent.
          ((null y)     ;A clause with 2 consequents:
           (setq y 4)   ; this
           (cons x z))  ; and this.
          (z)           ;A clause with no consequents:
			; the antecedent is just z.
	  (t		;An antecedent of t
	   105)		; is always satisfied.
       )		;This is the end of the cond.

Macro: if ¶

if allows a simple "if-then-else" conditional to be expressed as (if pred-form then-form else-form). if is provided for stylistic reasons; some people think it looks nicer than cond for the simple case it handles. (if x y z) expands into (cond (x y) (t z)).

Macro: selectq ¶

Many programs require cond forms which check various specific values of a form.

A typical example:
(cond ((eq x 'foo) ...)
      ((eq x 'bar) ...)
      ((memq x '(baz quux mum)) ...)
      (t ...))

The selectq macro can be used for such tests. Its form is as follows:

(selectq key-form
	 (pattern consequent consequent ...)
	 (pattern consequent consequent ...)
	 (pattern consequent consequent ...)
	 ...)

Its first "argument" is a form, which is evaluated (only once) as the first thing selectq does. The resulting value is called the key. It is followed by any number of clauses. The car of each clause is compared with the key, and if it matches, the consequents of this clause are evaluated, and selectq returns the value of the last consequent. If there are no matches, selectq returns nil. Note that the patterns are not evaluated; if you want them to be evaluated use select rather than selectq. A pattern may be any of:

1) A symbol

If the key is eq to the symbol, it matches.

2) A number

If the key is eq to the number, it matches. Only small numbers (fixnums) will work.

3) A list

If the key is eq to one of the elements of the list, then it matches. The elements of the list should be symbols or fixnums.

4) t or otherwise

The symbols t and otherwise are special keywords which match anything. Either symbol may be used, it makes no difference. t is accepted for compatibility with Maclisp’s caseq construct.

Example:

(selectq x		;This is the same as the cond example
	 (foo ...)	; above.
	 (bar ...)
	 ((baz quux mum) ...)
	 (otherwise ...))

Macro: select ¶

select is the same as selectq, except that the elements of the patterns are evaluated before they are used.

Example:

(select (frob x)
   (foo 1)
   ((bar baz) 2)
   (otherwise 3))
is equivalent to
(let ((var (frob x)))
  (cond ((eq var foo) 1)
	((or (eq var bar) (eq var baz)) 2)
	(t 3)))

Macro: selector ¶

selector is the same as select, except that you get to specify the function used for the comparison instead of eq. For example,

(selector (frob x) equal
   (('(one . two)) (frob-one x))
   (('(three . four)) (frob-three x))
   (otherwise (frob-any x)))

Macro: dispatch ¶

(dispatch byte-specifier n clauses...) is the same as select (not selectq), but the key is obtained by evaluating (ldb byte-specifier n). byte-specifier and n are both evaluated.

Example:

(princ (dispatch 0202 cat-type
	   (0 "Siamese.")
	   (1 "Persian.")
	   (2 "Alley.")
	   (3 (ferror nil
		      "~S is not a known cat type."
		      cat-type))))

It is not necessary to include all possible values of the byte which will be dispatched on. [This function may get flushed.]

4.2 Iteration

Special Form: prog ¶

prog is a special form which provides temporary variables, sequential evaluation of forms, and a "goto" facility. A typical prog looks like:

(prog (var1 var2 (var3 init3) var4 (var5 init5))
 tag1
     statement1
     statement2
 tag2
     statement2
     . . .
    )

var1, var2, ... are temporary variables. When the prog is entered, the values of these variables are saved. When the prog is finished, the saved values are restored. The initial value of a variable inside the prog depends on whether the variable had an associated init form or not; if it did, then the init form is evaluated and becomes the initial value of the corresponding variable. If there was no init form, the variable is initialized to nil.

Example:

(prog ((a t)  b  (c 5)  (d (car '(zz . pp))))
      <body>
      )

The initial value of a is t, that of b is nil, that of c is the fixnum 5, and that of d is the symbol zz. The binding and initialization of the variables is done in parallel; that is, all the initial values are computed before any of the variables are changed.

The part of a prog after the variable list is called the body. An item in the body may be a symbol or a number, in which case it is called a tag, or some other form (i.e. a list), in which case it is called a statement.

After prog binds the temporary variables, it processes each form in its body sequentially. tags are skipped over. Statements are evaluated, and their returned values discarded. If the end of the body is reached, the prog returns nil. However, two special forms may be used in prog bodies to alter the flow of control. If (return x) is evaluated, prog stops processing its body, evaluates x, and returns the result. If (go tag) is evaluated, prog jumps to the part of the body labelled with the tag. tag is not evaluated. The "computed-go" (mis)feature of Maclisp is not supported.

The compiler requires that go and return forms be lexically within the scope of the prog; it is not possible for one function to return to a prog which is in progress in its caller. This restriction happens not to be enforced in the interpreter. Thus, a program which contains a go which is not contained within the body of a prog (or a do, see below) cannot be compiled. Since virtually all programs will be compiled at some time, the restriction should be adhered to.

Sometimes code which is lexically within more than one prog (or do) form wants to return from one of the outer progs. However, the return function normally returns from the innermost prog. In order to make returning from outer progs more convenient, a prog may be given a name by which it may be referenced by a function called return-from, which is similar to return but allows a particular prog to be specified. If the first subform of a prog is a non-nil symbol (rather than a variable list), it is the name of the prog. See the description of the return-from special form, on return-from-fun.

Example:

(prog george (a b d)
      (prog (c b)
            ...
            (return-from george (cons b d))
            ...))

If the symbol t is used as the name of a prog, then it will be made "invisible" to returns; returns inside that prog will return to the next outermost level whose name is not t. (return-from t ...) will return from a prog named t.

See also the do special form, which uses a body similar to prog. The do, *catch, and *throw special forms are included in Lisp Machine Lisp as an attempt to encourage goto-less programming style, which often leads to more readable, more easily maintained code. The programmer is recommended to use these functions instead of prog wherever reasonable.

Example:

(prog (x y z)  ;x, y, z are prog variables  - temporaries.
   (setq y (car w) z (cdr w))     ;w is a free variable.
loop
   (cond ((null y) (return x))
         ((null z) (go err)))
rejoin
   (setq x (cons (cons (car y) (car z))
                 x))
   (setq y (cdr y)
         z (cdr z))
   (go loop)
err
   (break are-you-sure? t)
   (setq z y)
   (go rejoin))

Special Form: prog* ¶

The prog* special form is almost the same as prog. The only difference is that the binding and initialization of the temporary variables is done sequentially, so each one can depend on the previous ones. For example,

(prog ((y z) (x y)) (return x))

returns the value of z.

Special Form: do ¶

The do special form provides a generalized iteration facility, with an arbitrary number of "index variables" whose values are saved when the do is entered and restored when it is left, i.e. they are bound by the do. The index variables are used in the iteration performed by do. At the beginning, they are initialized to specified values, and then at the end of each trip around the loop the values of the index variables are changed according to specified rules. do allows the programmer to specify a predicate which determines when the iteration will terminate. The value to be returned as the result of the form may, optionally, be specified.

do comes in two varieties.

The newer variety of do looks like:

(do ((var init repeat)...)
    (end-test exit-form...)
    body...)

The first item in the form is a list of zero or more index variable specifiers. Each index variable specifier is a list of the name of a variable var, an initial value init, which defaults to nil if it is omitted, and a repeat value repeat. If repeat is omitted, the var is not changed between repetitions.

In index variable specifier can also be just the name of a variable. In this case, the variable has an initial value of nil, and is not changed between repetitions.

All assignment to the index variables is done in parallel. At the beginning of the first iteration, all the inits are evaluated, then the vars are saved, then the vars are set to the values of the inits. To put it another way, the vars are lambda-bound to the values of the inits. Note that the inits are evaluated before the vars are bound, i.e. lexically outside of the do. At the beginning of each succeeding iteration those vars that have repeats get setq’ed to the values of their respective repeats. Note that all the repeats are evaluated before any of the vars is changed.

The second element of the do-form is a list of an end-testing predicate end-test, and zero or more forms, called the exit-forms. At the beginning of each iteration, after processing of the repeats, the end-test is evaluated. If the result is nil, execution proceeds with the body of the do. If the result is not nil, the exit-forms are evaluated from left to right and then do returns. The value of the do is the value of the last exit-form, or nil (not the value of the end-test as you might expect) if there were no exit-forms. Note that the second element of the do-form resembles a cond clause.

If the second element of the form is nil, there is no end-test nor exit-forms, and the body of the do is executed only once. In this type of do it is an error to have repeats. This type of do is a "prog with initial values."

If the second element of the form is (nil), the end-test is never true and there are no exit-forms. The body of the do is executed over and over. The infinite loop can be terminated by use of return or *throw.

The remainder of the do-form constitutes a prog-body; that is, go’s and return forms are understood within the do body, as if it were a prog body. When the end of the body is reached, the next iteration of the do begins. If a return form is evaluated, do returns the indicated value and no more iterations occur.

The older variety of do is:

(do var init repeat end-test body...)

The first time through the loop var gets the value of init; the remaining times through the loop it gets the value of repeat, which is re-evaluated each time. Note that init is evaluated before the value of var is saved, i.e. lexically outside of the do. Each time around the loop, after var is set, end-test is evaluated. If it is non-nil, the do finishes and returns nil. If the end-test evaluated to nil, the body of the loop is executed. The body is like a prog body. go may be used. If return is used, its argument is the value of the do. If the end of the prog body is reached, another loop begins.

Examples of the older variety of do:

(setq n (array-length foo-array))
(do i 0 (1+ i) (= i n)
  (aset 0 foo-array i))		;zeroes out the array foo-array

(do zz x (cdr zz) (or (null zz)
		      (zerop (f (car zz)))))
                   ; this applies f to each element of x
                   ; continuously until f returns zero.
		   ; Note that the do has no body.

return forms are often useful to do simple searches:

(do i 0 (1+ i) (= i n)	; Iterate over the length of foo-array.
  (and (= (aref foo-array i) 5)	; If we find an element which
				;equals 5,
       (return i)))	;  then return its index.

Examples of the new form of do:

(do ((i 0 (1+ i))	; This is just the same as the above example,
     (n (array-length foo-array)))
    ((= i n))		; but written as a new-style do.
  (aset 0 foo-array i))

(do ((z list (cdr z)) ; z starts as list and is cdr’ed each time.
     (y other-list)   ; y starts as other-list, and is unchanged by the do.
     (x))	      ; x starts as nil and is not changed by the do.
    (nil)	      ; The end-test is nil, so this is an infinite loop.
  body)

(do ((x) (y) (z)) (nil) body)

is like

(prog (x y z) body)
except that when it runs off the end of the body,
do loops but prog returns nil.

On the other hand,

     (do ((x) (y) (z)) nil body)

is identical to the prog above (it does not loop.)

The construction

(do ((x e (cdr x))
     (oldx x x))
    ((null x))
  body)

exploits parallel assignment to index variables. On the first iteration, the value of oldx is whatever value x had before the do was entered. On succeeding iterations, oldx contains the value that x had on the previous iteration.

In either form of do, the body may contain no forms at all. Very often an iterative algorithm can be most clearly expressed entirely in the repeats and exit-forms of a new-style do, and the body is empty.

(do ((x x (cdr x))
     (y y (cdr y))
     (z nil (cons (f x y) z))) ;exploits parallel
    ((or (null x) (null y))    ; assignment.
     (nreverse z))             ;typical use of nreverse.
    )                          ;no do-body required.

is like (maplist 'f x y).

Special Form: do-named ¶

do-named is just like do except that its first subform is a symbol, which is interpreted as the name of the do. The return-from special form allows a return from a particular prog or do-named when several are nested. See the description of such names in the explanation of the prog special form on prog-fun, and that of return-from on return-from-fun.

Special Form: dotimes ¶

dotimes is a convenient abbreviation for the most common integer iteration. (dotimes (index count) body...) performs body the number of times given by the value of count, with index bound to 0, 1, etc. on successive iterations.

Example:

(dotimes (i (// m n)
  (frob i))

is equivalent to:

(do ((i 0 (1+ i))
     (count (// m n)))
    (( i count))
  (frob i))

except that the name count is not used.

Special Form: dolist ¶

dolist is a convenient abbreviation for the most common list iteration. (dolist (item list) body...) performs body once for each element in the list which is the value of list, with item bound to the successive elements.

Example:

(dolist (item (frobs foo))
  (mung item))

is equivalent to:

(do ((lst (frobs foo) (cdr lst))
     (item))
    ((null lst))
  (setq item (car lst))
  (mung item))

except that the name lst is not used.

Special Form: go ¶

The (go tag) special form is used to do a "go-to" within the body of a do or a prog. The tag must be a symbol. It is not evaluated. go transfers control to the point in the body labelled by a tag eq to the one given. If there is no such tag in the body, the bodies of lexically containing progs and dos (if any) are examined as well. If no tag is found, an error is signalled. Note that the go form is a very special form: it does not ever return a value. A go form may not appear as an argument to a regular function, but only at the top level of a prog or do, or within certain special forms such as conditionals which are within a prog or do. A go as an argument to a regular function would be not only useless but possibly meaningless. The compiler does not bother to know how to compile it correctly. return and *throw are similar.

Example:

(prog (x y z)
  (setq x some frob)
loop
  do something
  (and some predicate (go endtag))
  do something more
  (and (minusp x) (go loop))
endtag
  (return z))

Function: return arg ¶

return is used to return from a prog or a do. The value of return’s argument is returned by prog or do as its value. In addition, break recognizes the typed-in S-expression (return value) specially. If this form is typed at a break, value will be evaluated and returned as the value of break. If not at the top level of a form typed at a break, and not inside a prog or do, return will cause an error.

Example:

(do ((x x (cdr x))
     (n 0 (* n 2)))
    ((null x) n)
 (cond ((atom (car x))
        (setq n (1+ n)))
       ((memq (caar x) '(sys boom bleah))
        (return n))))

return is, like go, a special form which does not return a value.

return can also be used to return multiple values from a prog or do, by giving it multiple arguments. For example,

(defun assqn (x table)
  (do ((l table (cdr l))
       (n 0 (1+ n)))
      ((null l) nil)
    (and (eq (caar l) x)
	 (return (car l) n))))

This function is like assq, but it returns an additional value which is the index in the table of the entry it found. See the special forms multiple-value (multiple-value-fun) and multiple-value-list (multiple-value-list-fun).

Special Form: return-from ¶

A return-from form looks like (return-from name form1 form2 form3). The forms are evaluated sequentially, and then are returned from the innermost containing prog or do-named whose name is name. See the description of prog (prog-fun) in which named progs and dos are explained, and that of do-named (do-named-fun).

Function: return-list list ¶

list must not be nil. This function is like return except that the prog returns all of the elements of list; if list has more then one element, the prog does a multiple-value return. To direct the returned values to a prog or do-named of a specific name, use (return-from name (return-list list)).

Special Form: multiple-value-return ¶

(multiple-value-return (function arg1 arg2 ...)) applies the function to the arguments, and returns from the current prog or do with the same values as function returns.

Macro: defunp ¶

Usually when a function uses prog, the prog form is the entire body of the function; the definition of such a function looks like (defun name arglist (prog varlist ...)). For convenience, the defunp macro can be used to produce such definitions. A defunp form expands as follows:

(defunp fctn (args)
    form1
    form2
    ...
    formn)

expands into

(defun fctn (args)
  (prog nil
	form1
	form2
	...
	(return formn)))

4.3 Non-local Exits

Function: *catch tag form ¶

*catch is the Lisp Machine Lisp function for doing structured non-local exits. (*catch tag form) evaluates form and returns its value, except that if, during the evaluation of form, (*throw tag y) should be evaluated, *catch immediately returns y without further evaluating x. Note that the form argument is not evaluated twice; the special action of *catch happens during the evaluation of its arguments, not during the execution of *catch itself.

The tag’s are used to match up *throw’s with *catch’s. (*catch 'foo form) will catch a (*throw 'foo form) but not a (*throw 'bar form). It is an error if *throw is done when there is no suitable *catch (or catch-all; see below).

The values t and nil for tag are special and mean that all throws are to be caught. These are used by unwind-protect and catch-all respectively. The only difference between t and nil is in the error checking; t implies that after a "cleanup handler" is executed control will be thrown again to the same tag, therefore it is an error if a specific catch for this tag does not exist higher up in the stack.

*catch returns up to four values; trailing null values are not returned for reasons of microcode simplicity, however the values not returned will default to nil if they are received with the multiple-value special form. If the catch completes normally, the first value is the value of form and the second is nil. If a *throw occurs, the first value is the second argument to *throw, and the second value is the first argument to *throw, the tag thrown to. The third and fourth values are the third and fourth arguments to *unwind-stack if that was used in place of *throw, otherwise nil. To summarize, the four values returned by *catch are the value, the tag, the active-frame-count, and the action.

Example

(*catch 'negative
	(mapcar (function (lambda (x) 
                            (cond ((minusp x)
				   (*throw 'negative x))
				  (t (f x)) )))
               y)
     )

which returns a list of f of each element of y if they are all positive, otherwise the first negative member of y.

Note: The Lisp Machine Lisp functions *catch and *throw are improved versions of the Maclisp functions catch and throw. The Maclisp ones are similar in purpose, but take their arguments in reversed order, do not evaluate the tag, and may be used in an older form in which no tag is supplied. Compatibility macros are supplied so that programs using the Maclisp functions will work.

Function: *throw tag value ¶

*throw is used with *catch as a structured non-local exit mechanism.

(*throw tag x) throws the value of x back to the most recent *catch labelled with tag or t or nil. Other *catches are skipped over. Both x and tag are evaluated, unlike the Maclisp throw function.

The values t and nil for tag are reserved. nil may not be used, because it would cause an ambiguity in the returned values of *catch. t invokes a special feature whereby the entire stack is unwound, and then a coroutine transfer to the invoking stack-group is done. During this process unwind-protects receive control, but catch-alls do not. This feature is provided for the benefit of system programs which want to completely unwind a stack. It leaves the stack-group in a somewhat inconsistent state; it is best to do a stack-group-preset immediately afterwards.

See the description of *catch for further details.

Macro: catch ¶

Macro: throw ¶

catch and throw are provided only for Maclisp compatibility. They expand as follows:

(catch form tag) ==> (*catch (quote tag) form)
(throw form tag) ==> (*throw (quote tag) form)

The forms of catch and throw without tags are not supported.

Function: *unwind-stack tag value active-frame-count action ¶

This is a generalization of *throw provided for program-manipulating programs such as the error handler.

tag and value are the same as the corresponding arguments to *throw.

active-frame-count, if non-nil, is the number of frames to be unwound. If this counts down to zero before a suitable *catch is found, the *unwind-stack terminates and that frame returns value to whoever called it. This is similar to Maclisp’s freturn function.

If action is non-nil, whenever the *unwind-stack would be ready to terminate (either due to active-frame-count or due to tag being caught as in *throw), instead, a stack-group call is forced to the previous stack-group, generally the error handler. The unwound stack-group is left in awaiting-return state, such that the value returned when the stack-group is resumed will become the value returned by the frame, (i.e. the value argument to *unwind-stack will be ignored in this case, and the value passed to the stack group when it is resumed will be used instead.)

Note that if both active-frame-count and action are nil, *unwind-stack is identical to *throw.

Macro: unwind-protect ¶

Sometimes it is necessary to evaluate a form and make sure that certain side-effects take place after the form is evaluated; a typical example is:

(progn
   (turn-on-water-faucet)
   (hairy-function 3 nil 'foo)
   (turn-off-water-faucet))

The non-local exit facility of Lisp creates a situation in which the above code won’t work, however: if hairy-function should do a *throw to a *catch which is outside of the progn form, then (turn-off-water-faucet) will never be evaluated (and the faucet will presumably be left running).

In order to allow the above program to work, it can be rewritten using unwind-protect as follows:

(unwind-protect
  (progn (turn-on-water-faucet)
	 (hairy-function 3 nil 'foo))
  (turn-off-water-faucet))

If hairy-function does a *throw which attempts to quit out of the evaluation of the unwind-protect, the (turn-off-water-faucet) form will be evaluated in between the time of the *throw and the time at which the *catch returns. If the progn returns normally, then the (turn-off-water-faucet) is evaluated, and the unwind-protect returns the result of the progn. One thing to note is that unwind-protect cannot return multiple values.

The general form of unwind-protect looks like

(unwind-protect protected-form
                form1
                form2
                ...)

protected-form is evaluated, and when it returns or when it attempts to quit out of the unwind-protect, the forms are evaluated.

Macro: let-globally ¶

let-globally is similar in form to let (see let-fun). The difference is that let-globally does not bind the variables; instead, it sets them, and sets up an unwind-protect (see unwind-protect-fun) to set them back. The important difference between let-globally and let is that when the current stack group (see stack-group) cocalls some other stack group, the old values of the variables are not restored.

Macro: catch-all ¶

(catch-all form) is like (*catch some-tag form) except that it will catch a *throw to any tag at all. Since the tag thrown to is the second returned value, the caller of catch-all may continue throwing to that tag if he wants. The one thing that catch-all will not catch is a *throw to t. catch-all is a macro which expands into *catch with a tag of nil.

4.4 Mapping

Function: map fcn &rest lists ¶

Function: mapc fcn &rest lists ¶

Function: maplist fcn &rest lists ¶

Function: mapcar fcn &rest lists ¶

Function: mapcon fcn &rest lists ¶

Function: mapcan fcn &rest lists ¶

Mapping is a type of iteration in which a function is successively applied to pieces of a list. There are several options for the way in which the pieces of the list are chosen and for what is done with the results returned by the applications of the function.

For example, mapcar operates on successive elements of the list. As it goes down the list, it calls the function giving it an element of the list as its one argument: first the car, then the cadr, then the caddr, etc., continuing until the end of the list is reached. The value returned by mapcar is a list of the results of the successive calls to the function. An example of the use of mapcar would be mapcar’ing the function abs over the list (1 -2 -4.5 6.0e15 -4.2), which would be written as (mapcar (function abs) '(1 -2 -4.5 6.0e15 -4.2)). The result is (1 2 4.5 6.0e15 4.2).

In general, the mapping functions take any number of arguments. For example,

(mapcar f x1 x2 ... xn)

In this case f must be a function of n arguments. mapcar will proceed down the lists x1, x2, ..., xn in parallel. The first argument to f will come from x1, the second from x2, etc. The iteration stops as soon as any of the lists is exhausted.

There are five other mapping functions besides mapcar. maplist is like mapcar except that the function is applied to the list and successive cdr’s of that list rather than to successive elements of the list. map and mapc are like maplist and mapcar respectively, except that they don’t return any useful value. These functions are used when the function is being called merely for its side-effects, rather than its returned values. mapcan and mapcon are like mapcar and maplist respectively, except that they combine the results of the function using nconc instead of list. That is,

(defun mapcon (f x y)
    (apply 'nconc (maplist f x y)))

Of course, this definition is less general than the real one.

Sometimes a do or a straightforward recursion is preferable to a map; however, the mapping functions should be used wherever they naturally apply because this increases the clarity of the code.

Often f will be a lambda-expression, rather than a symbol; for example,

(mapcar (function (lambda (x) (cons x something)))
	some-list)

The functional argument to a mapping function must be acceptable to apply - it cannot be a macro or the name of a special form. Of course, there is nothing wrong with using functions which have optional and rest parameters.

Here is a table showing the relations between the six map functions.

                              applies function to

                         |  successive  |   successive  |
                         |   sublists   |    elements   |
          ---------------+--------------+---------------+
              its own    |              |               | 
              second     |     map      |     mapc      |
             argument    |              |               |
          ---------------+--------------+---------------+
            list of the  |              |               |
returns      function    |    maplist   |    mapcar     |
              results    |              |               |
          ---------------+--------------+---------------+
            nconc of the |              |               |
              function   |    mapcon    |    mapcan     |
              results    |              |               |
          ---------------+--------------+---------------+

There are also functions (mapatoms and mapatoms-all) for mapping over all symbols in certain packages. See the explanation of packages (package).

5.1 Conses

Function: car x ¶

Returns the car of x.

Example:

(car '(a b c)) => a

Function: cdr x ¶

Returns the cdr of x.

Example:

(cdr '(a b c)) => (b c)

Officially car and cdr are only applicable to conses and locatives. However, as a matter of convenience, a degree of control is provided over the action taken when there is an attempt to apply one of them to a symbol or a number. There are four mode-switches known as the car-number mode, cdr-number mode, car-symbol mode, and cdr-symbol mode. Here are the meanings of the values of these mode switches:

car-number = 0

car of a number is an error. This is the default.

car-number = 1

car of a number is nil.

cdr-number = 0

cdr of a number is an error. This is the default.

cdr-number = 1

cdr of a number is nil.

car-symbol = 0

car of a symbol is an error.

car-symbol = 1

car of nil is nil, but the car of any other symbol is an error. This is the default.

car-symbol = 2

car of any symbol is nil.

car-symbol = 3

car of a symbol is its print-name.

cdr-symbol = 0

cdr of a symbol is an error.

cdr-symbol = 1

cdr of nil is nil, but the cdr of any other symbol is an error. This is the default.

cdr-symbol = 2

cdr of any symbol is nil.

cdr-symbol = 3

cdr of nil is nil, cdr of any other symbol is its property list.

The values of the mode switches can be altered with the function set-error-mode (see set-error-mode-fun). They are stored as byte fields in the special variable %m-flags. The reason that the two symbol modes default in that fashion is to allow programs to car and cdr off the ends of lists without having to check, which is sometimes useful. A few system functions depend on car and cdr of nil being nil, although they hadn’t ought to, so things may break if you change these modes.

The value of 3 for the symbol modes exists for compatibility with ancient versions of Maclisp, and should not be used for any other reasons. (The appropriate functions are get-pname (see get-pname-fun) and plist (see plist-fun).) Note: unlike Maclisp, the values of the symbols car and cdr are not used; the various mode switches above serve their purpose. Also unlike Maclisp, this error checking is always done, even in compiled code, regardless of the value of *rset.

Function: c...r x ¶

All of the compositions of up to four car’s and cdr’s are defined as functions in their own right. The names of these functions begin with "c" and end with "r", and in between is a sequence of "a"’s and "d"’s corresponding to the composition performed by the function.

Example:

(cddadr x) is the same as (cdr (cdr (car (cdr x))))

The error checking for these functions is exactly the same as for car and cdr above.

Function: cons x y ¶

cons is the primitive function to create a new cons, whose car is x and whose cdr is y.

Examples:

(cons 'a 'b) => (a . b)
(cons 'a (cons 'b (cons 'c nil))) => (a b c)
(cons 'a '(b c d)) => (a b c d)

Function: ncons x ¶

(ncons x) is the same as (cons x nil). The name of the function is from "nil-cons".

Function: xcons x y ¶

xcons ("exchanged cons") is like cons except that the order of the arguments is reversed.

Example:

(xcons 'a 'b) => (b . a)

There are two reasons this exists: one is that you might want the arguments to cons evaluated in the other order, and the other is that the compiler might convert calls to cons into calls to xcons for efficiency. In fact, it doesn’t.

Function: cons-in-area x y area-number ¶

This function creates a cons in a specific area. (Areas are an advanced feature of storage management; if you aren’t interested in them, you can safely skip all this stuff). The first two arguments are the same as the two arguments to cons, and the third is the number of the area in which to create the cons.

Example:

(cons-in-area 'a 'b my-area) => (a . b)

Function: ncons-in-area x area-number ¶

(ncons-in-area x area-number) = (cons-in-area x nil area-number)

Function: xcons-in-area x y area-number ¶

(xcons-in-area x y area-number) = (cons-in-area y x area-number)

The backquote reader macro facility is also generally useful for creating list structure, especially mostly-constant list structure, or forms constructed by plugging variables into a template. It is documented in the chapter on Macros, see macro.

Function: car-location cons ¶

car-location returns a locative pointer to the cell containing the car of cons.

Note: there is no cdr-location function; it is difficult because of the cdr-coding scheme.

5.2 Lists

The following section explains some of the basic functions provided for dealing with lists. There has been some confusion about the term list ever since the beginnings of the language: for the purposes of the following descriptions, a list is the symbol nil, or a cons whose cdr is a list. Note well that although we consider nil to be a list (the list of zero elements), it is a symbol and not a cons, and the listp predicate is not true of it (but perhaps listp will be changed in the future).

Function: last list ¶

last returns the last cons of list. If list is nil, it returns nil.

Example:

(setq x '(a b c d))
(last x) => (d)
(rplacd (last x) '(e f))
x => '(a b c d e f)

last could have been defined by:

(defun last (x)
    (cond ((atom x) x)
          ((atom (cdr x)) x)
          ((last (cdr x))) ))

Function: length list ¶

length returns the length of list. The length of a list is the number of top-level conses in it.

Examples:

(length nil) => 0
(length '(a b c d)) => 4
(length '(a (b c) d)) => 3

length could have been defined by:

(defun length (x)
    (cond ((atom x) 0)
          ((1+ (length (cdr x)))) ))
or by:

(defun length (x)
    (do ((n 0 (1+ n))
         (y x (cdr y)))
        ((atom y) n) ))

Macro: first ¶

Macro: second ¶

Macro: third ¶

Macro: fourth ¶

Macro: fifth ¶

Macro: sixth ¶

Macro: seventh ¶

(first x) ==> (car x)
(second x) ==> (cadr x)
(third x) ==> (caddr x)
(fourth x) ==> (cadddr x)
etc.

Macro: rest1 ¶

Macro: rest2 ¶

Macro: rest3 ¶

Macro: rest4 ¶

(rest1 x) ==> (cdr x)
(rest2 x) ==> (cddr x)
(rest3 x) ==> (cdddr x)
(rest4 x) ==> (cddddr x)

Function: nth n list ¶

(nth n list) returns the n’th element of list, where the zeroth element is the car of the list.

Examples:

(nth 1 '(foo bar gack)) => bar
(nth 3 '(foo bar gack)) => nil

Note: this is not the same as the InterLisp function called nth, which is similar to but not exactly the same as the Lisp Machine function nthcdr. Also, some people have used macros and functions called nth of their own in their Maclisp programs, which may not work the same way; be careful.

nth could have been defined by:

(defun nth (n list)
  (do ((i n (1- i))
       (l list (cdr l)))
      ((zerop i) (car l))))

Function: nthcdr n list ¶

(nthcdr n list) cdrs list n times, and returns the result.

Examples:

(nthcdr 0 '(a b c)) => (a b c)
(nthcdr 2 '(a b c)) => (c)

In other words, it returns the n’th cdr of the list. This is the similar to InterLisp’s function nth, except that the InterLisp function is one-based instead of zero-based; see the InterLisp manual for details. nthcdr is defined by:

(defun nthcdr (n list)
    (do ((i 0 (1+ i))
	 (list list (cdr list)))
	((= i n) list)))

Function: list &rest args ¶

list constructs and returns a list of its arguments.

Example:

(list 3 4 'a (car '(b . c)) (+ 6 -2)) => (3 4 a b 4)

list could have been defined by:

(defun list (&rest args)
    (let ((list (make-list default-cons-area (length args))))
      (do ((l list (cdr l))
	   (a args (cdr a)))
	  ((null a) list)
	(rplaca l (car a)))))

Function: list* &rest args ¶

list* is like list except that the last cons of the constructed list is "dotted". It must be given at least two arguments.

Example:

(list* 'a 'b 'c 'd) => (a b c . d)
This is like
(cons 'a (cons 'b (cons 'c 'd)))

Function: list-in-area area-number &rest args ¶

list-in-area is exactly the same as list except that it takes an extra argument, an area number, and creates the list in that area.

Function: make-list area size ¶

This creates and returns a list containing size elements, each of which is nil. size should be a fixnum. The list is allocated in the area specified; if you are not using areas in any special way, just use the value of the symbol default-cons-area.

Example:

(make-list default-cons-area 3) => (nil nil nil)

Of course, this function is not usually used when the value of the second argument is a constant; if you want a list of three nils, it is easy enough to type (nil nil nil). make-list is used when the number of elements is to be computed while the program is being run.

make-list and cons are the two primitive list-creation functions which all the other functions call. The difference is that make-list creates a cdr-coded list (see cdr-code).

Function: circular-list &rest args ¶

circular-list constructs a circular list whose elements are args, repeated infinitely. circular-list is the same as list except that the list itself is used as the last cdr, instead of nil. circular-list is especially useful with mapcar, as in the expression

(mapcar (function +) foo (circular-list 5))

which adds each element of foo to 5.

Function: append &rest lists ¶

The arguments to append are lists. The result is a list which is the concatenation of the arguments. The arguments are not changed (cf. nconc).

Example:

(append '(a b c) '(d e f) nil '(g)) => (a b c d e f g)

Note that append copies the top-level list structure of each of its arguments except the last. Thus, to copy a list but not its elements, use (append x nil). The copylist function is equivalent.

A version of append which only accepts two arguments could have been defined by:

(defun append2 (x y)
    (cond ((null x) y)
          ((cons (car x) (append2 (cdr x) y)) )))

The generalization to any number of arguments could then be made:

(defun append (&rest args)
    (and args (append2 (car args)
		       (apply (function append) (cdr args)))))

These definitions do not express the full functionality of append; the real definition minimizes storage utilization by cdr-coding the list it produces, using cdr-next except at the end where a full node is used to link to the last argument, unless the last argument was nil in which case cdr-nil is used.

Function: copylist list &optional area ¶

Returns a list which is equal to list, but not eq. Only the top level of list-structure is copied, i.e. copylist copies in the cdr direction but not in the car direction. The returned list is fully cdr-coded to minimize storage. If the list is "dotted", that is, (cdr (last list)) is a non-nil atom, this will be true of the returned list also. You may optionally specify the area in which to create the new copy.

Function: copylist* list &optional area ¶

This is the same as copylist except that the last cons of the resulting list is never cdr-coded. This makes for increased efficiency if you nconc something onto the list later.

Function: copyalist list &optional area ¶

copyalist is for copying association lists. The top level of list structure of list is copied, just as copylist does. In addition, each element of list which is a cons is replaced in the copy by a new cons with the same car and cdr. You may optionally specify the area in which to create the new copy.

Function: reverse list ¶

reverse creates a new list whose elements are the elements of list taken in reverse order. reverse does not modify its argument, unlike nreverse which is faster but does modify its argument.

Example:

(reverse '(a b (c d) e)) => (e (c d) b a)

reverse could have been defined by:

(defun reverse (x)
    (do ((l x (cdr l))         ; scan down argument,
         (r nil                ; putting each element
            (cons (car l) r))) ; into list, until
        ((null l) r)))         ; no more elements.

Function: nconc &rest lists ¶

nconc takes lists as arguments. It returns a list which is the arguments concatenated together. The arguments are changed, rather than copied. (cf. append, append-fun)

Example:

(setq x '(a b c))
(setq y '(d e f))
(nconc x y) => (a b c d e f)
x => (a b c d e f)

Note that the value of x is now different, since its last cons has been rplacd’d to the value of y. If the nconc form is evaluated again, it would yield a piece of "circular" list structure, whose printed representation would be (a b c d e f d e f d e f ...), repeating forever.

nconc could have been defined by:

(defun nconc (x y)		 ;for simplicity, this definition
    (cond ((null x) y)		 ;only works for 2 arguments.
          (t (rplacd (last x) y) ;hook y onto x
              x)))		 ;and return the modified x.

Function: nreverse list ¶

nreverse reverses its argument, which should be a list. The argument is destroyed by rplacd’s all through the list (cf. reverse).

Example:

(nreverse '(a b c)) => (c b a)

nreverse could have been defined by:

(defun nreverse  (x)
    (cond ((null x) nil)
          ((nreverse1 x nil))))

(defun nreverse1 (x y)		;auxiliary function
    (cond ((null (cdr x)) (rplacd x y))
          ((nreverse1 (cdr x) (rplacd x y)))))
          ;; this last call depends on order of argument evaluation.

Currently, nreverse does something inefficient with cdr-coded lists, however this will be changed. In the meantime reverse might be preferable in some cases.

Function: nreconc x y ¶

(nreconc x y) is exactly the same as (nconc (nreverse x) y) except that it is more efficient. Both x and y should be lists.

nreconc could have been defined by:

(defun nreconc (x y)
    (cond ((null x) y)
          ((nreverse1 x y)) ))

using the same nreverse1 as above.

Macro: push ¶

The form is (push item place), where item is an arbitrary object and place is a reference to a cell containing a list. Usually place is the name of a variable. item is consed onto the front of the list.

The form

(push (hairy-function x y z) variable)

replaces the commonly-used construct

(setq variable (cons (hairy-function x y z) variable))

and is intended to be more explicit and esthetic. In general, (push item place) expands into (setf place (cons item place)). (See setf-fun for an explanation of setf.)

Macro: pop ¶

The form is (pop place). The result is the car of the contents of place, and as a side-effect the cdr of the contents is stored back into place.

Example:

(setq x '(a b c))
(pop x) => a
x => (b c)

In general, (pop place) expands into (prog1 (car place) (setf place (cdr place))). (See setf-fun for an explanation of setf.)

Function: butlast list ¶

This creates and returns a list with the same elements as list, excepting the last element.

Examples:

(butlast '(a b c d)) => (a b c)
(butlast '((a b) (c d)) => ((a b))
(butlast '(a)) => nil
(butlast nil) => nil

The name is from the phrase "all elements but the last".

Function: nbutlast list ¶

This is the destructive version of butlast; it changes the cdr of the second-to-last cons of the list to nil. If there is no second-to-last cons (that is, if the list has fewer than two elements) it returns nil.

Examples:

(setq foo '(a b c d))
(nbutlast foo) => (a b c)
foo => (a b c)
(nbutlast '(a)) => nil

Function: firstn n list ¶

firstn returns a list of length n, whose elements are the first n elements of list. If list is fewer than n elements long, the remaining elements of the returned list will be nil.

Example:

(firstn 2 '(a b c d)) => (a b)
(firstn 0 '(a b c d)) => nil
(firstn 6 '(a b c d)) => (a b c d nil nil)

Function: ldiff list sublist ¶

list should be a list, and sublist should be a sublist of list, i.e. one of the conses that make up list. ldiff (meaning List Difference) will return a new list, whose elements are those elements of list that appear before sublist.

Examples:

(setq x '(a b c d e))
(setq y (cdddr x)) => (d e)
(ldiff x y) => (a b c)
but
(ldiff '(a b c d) '(c d)) => (a b c d)
since the sublist was not eq to any part of the list.

5.3 Alteration of List Structure

The functions rplaca and rplacd are used to make alterations in already-existing list structure; that is, to change the cars and cdrs of existing conses. The structure is not copied but is physically altered; hence caution should be exercised when using these functions, as strange side-effects can occur if portions of list structure become shared unbeknownst to the programmer. The nconc, nreverse, nreconc, and nbutlast functions already described, and the delq family described later, have the same property. However, they are normally not used for this side-effect; rather, the list-structure modification is purely for efficiency and compatible non-modifying functions are provided.

Function: rplaca x y ¶

(rplaca x y) changes the car of x to y and returns (the modified) x. x should be a cons, but y may be any Lisp object.

Example:

(setq g '(a b c))
(rplaca (cdr g) 'd) => (d c)
Now g => (a d c)

Function: rplacd x y ¶

(rplacd x y) changes the cdr of x to y and returns (the modified) x. x should be a cons, but y may be any Lisp object.

Example:

(setq x '(a b c))
(rplacd x 'd) => (a . d)
Now x => (a . d)

Note to Maclisp users: rplacd should not be used to set the property list of a symbol, although there is a compatibility mode in which it will work. See car (car-fun). The right way to set a property list is with setplist (see setplist-fun).

Function: subst new old s-exp ¶

(subst new old s-exp) substitutes new for all occurrences of old in s-exp, and returns the modified copy of s-exp. The original s-exp is unchanged, as subst recursively copies all of s-exp replacing elements equal to old as it goes. If new and old are nil, s-exp is just copied, which is a convenient way to copy arbitrary list structure.

Example:

(subst 'Tempest 'Hurricane
       '(Shakespeare wrote (The Hurricane)))
    => (Shakespeare wrote (The Tempest))

subst could have been defined by:

(defun subst (new old s-exp)
    (cond ((equal s-exp old) new) ;if item eq to old, replace.
          ((atom s-exp) s-exp)    ;if no substructure, return arg.
          ((cons (subst new old (car s-exp))  ;otherwise recurse.
                 (subst new old (cdr s-exp))))))

Note that this function is not "destructive"; that is, it does not change the car or cdr of any already-existing list structure.

Function: nsubst new old s-exp ¶

nsubst is a destructive version of subst. The list structure of s-exp is altered by replacing each occurrence of old with new. nsubst could have been defined as

(defun nsubst (new old s-exp)
    (cond ((eq s-exp old) new)	  ;If item eq to old, replace.
          ((atom s-exp) s-exp)    ;If no substructure, return arg.
	  (t ;; Otherwise, recurse.
	     (rplaca s-exp (nsubst new old (car s-exp)))
	     (rplacd s-exp (nsubst new old (cdr s-exp)))
	     s-exp)))

Function: sublis alist S-expression ¶

sublis makes substitutions for symbols in an S-expression (a structure of nested lists). The first argument to sublis is an association list (see the next section). The second argument is the S-expression in which substitutions are to be made. sublis looks at all symbols in the S-expression; if a symbol appears in the association list occurrences of it are replaced by the object it is associated with. The argument is not modified; new conses are created where necessary and only where necessary, so the newly created structure shares as much of its substructure as possible with the old. For example, if no substitutions are made, the result is eq to the old S-expression.

Example:

(sublis '((x . 100) (z . zprime))
        '(plus x (minus g z x p) 4))
   => (plus 100 (minus g zprime 100 p) 4)

Function: nsublis alist S-expression ¶

nsublis is like sublis but changes the original list structure instead of creating new.

5.4 Cdr-Coding

There is an issue which those who must be concerned with efficiency will need to think about. In the Lisp Machine there are actually two kinds of lists; normal lists and cdr-coded lists. Normal lists take two words for each cons, while cdr-coded lists require only one word for each cons. The saving is achieved by taking advantage of the usual structure of lists to avoid storing the redundant cdrs which link together the conses which make up the list. Ordinarily, rplacd’ing such a list would be impossible, since there is no explicit representation of the cdr to be modified. However, in the Lisp machine system it is merely somewhat expensive; a 2-word ordinary cons must be allocated and linked into the list by an invisible pointer. This is slower than an ordinary rplacd, uses extra space, and slows down future accessing of the list.

One should try to use normal lists for those data structures that will be subject to rplacding operations, including nconc and nreverse, and cdr-coded lists for other structures. The functions cons, xcons, ncons, and their area variants make normal lists. The functions list, list*, list-in-area, make-list, and append make cdr-coded lists. The other list-creating functions, including read, currently make normal lists, but this should not be relied upon. Some functions, such as sort, take special care to operate efficiently on cdr-coded lists (sort treats them as arrays). nreverse is rather slow on cdr-coded lists, currently, since it simple-mindedly uses rplacd, however this will be changed.

It is currently not planned that the garbage collector compact ordinary lists into cdr-coded lists. (append x nil) is a suitable way to copy a list, converting it into cdr-coded form.

5.5 Tables

Lisp Machine Lisp includes several functions which simplify the maintenance of tabular data structures of several varieties. The simplest is a plain list of items, which models (approximately) the concept of a set. There are functions to add (cons), remove (delete, delq, del, del-if, del-if-not, remove, remq, rem, rem-if, rem-if-not), and search for (member, memq, mem) items in a list. Set union, intersection, and difference functions are easily written using these.

Association lists are very commonly used. An association list is a list of conses. The car of each cons is a "key" and the cdr is a "datum", or a list of associated data. The functions assoc, assq, ass, memass, and rassoc may be used to retrieve the data, given the key.

Structured records can be stored as association lists or as stereotyped cons-structures where each element of the structure has a certain car-cdr path associated with it. However, these are better implemented using structure macros (see defstruct).

Simple list-structure is very convenient, but may not be efficient enough for large data bases because it takes a long time to search a long list. Lisp Machine lisp includes a hashing function (sxhash) which aids in the construction of more efficient, hairier structures.

Function: memq item list ¶

(memq item list) returns nil if item is not one of the elements of list. Otherwise, it returns the portion of list beginning with the first occurrence of item. The comparison is made by eq. list is searched on the top level only. Because memq returns nil if it doesn’t find anything, and something non-nil if it finds something, it is often used as a predicate.

Examples:

(memq 'a '(1 2 3 4)) => nil
(memq 'a '(g (x y) c a d e a f)) => (a d e a f)

Note that the value returned by memq is eq to the portion of the list beginning with a. Thus rplaca on the result of memq may be used, if you first check to make sure memq did not return nil.

Example:

(*catch 'lose
	(rplaca (or (memq x z)
		    (*throw 'lose nil))
		y)
	)	

memq could have been defined by:

(defun memq (item list)
    (cond ((atom list) nil)
          ((eq item (car list)) list)
          ((memq item (cdr list))) ))

memq is hand-coded in microcode and therefore especially fast.

Function: member item list ¶

member is like memq, except equal is used for the comparison, instead of eq.

member could have been defined by:

(defun member (item list)
    (cond ((null list) nil)
          ((equal item (car list)) list)
          ((member item (cdr list))) ))

Function: mem predicate item list ¶

mem is the same as memq except that it takes an extra argument which should be a predicate of two arguments, which is used for the comparison instead of eq. (mem 'eq a b) is the same as (memq a b). (mem 'equal a b) is the same as (member a b). mem is usually used with equality predicates other than eq and equal, such as =, char-equal or string-equal.

Function: tailp tail list ¶

A tail of a list is anything that can be obtained by taking cdr of it zero or more times. tailp is used to ask whether tail is a tail of list. That is, it cdr’s down list checking at each step whether what it has got is eq to tail. If so, the value is t.

Function: delq item list &optional n ¶

(delq item list) returns the list with all top-level occurrences of item removed. eq is used for the comparison. The argument list is actually modified (rplacd’ed) when instances of item are spliced out. delq should be used for value, not for effect. That is, use

(setq a (delq 'b a))

rather than

(delq 'b a)

The latter is not equivalent when the first element of the value of a is b.

(delq item list n) is like (delq item list) except only the first n instances of item are deleted. n is allowed to be zero. If n is greater than the number of occurrences of item in the list, all occurrences of item in the list will be deleted.

Example:

(delq 'a '(b a c (a b) d a e)) => (b c (a b) d e)

delq could have been defined by:

(defun delq (item list &optional (n 7777777))  ;7777777 as infinity.
    (cond ((or (atom list) (zerop n)) list)
          ((eq item (car list))
	   (delq item (cdr list) (1- n)))
          ((rplacd list (delq item (cdr list) n)))))

Function: delete item list &optional n ¶

delete is the same as delq except that equal is used for the comparison instead of eq.

Function: del predicate item list &optional n ¶

del is the same as delq except that it takes an extra argument which should be a predicate of two arguments, which is used for the comparison instead of eq. (del 'eq a b) is the same as (delq a b). (c.f. mem, mem-fun)

Function: remq item list &optional n ¶

remq is similar to delq, except that the list is not altered; rather, a new list is returned.

Examples:

(setq x '(a b c d e f))
(remq 'b x) => (a c d e f)
x => (a b c d e f)
(remq 'b '(a b c b a b) 2) => (a c a b)

Function: remove item list &optional n ¶

remove is the same as remq except that equal is used for the comparison instead of eq.

Function: rem predicate item list &optional n ¶

rem is the same as remq except that it takes an extra argument which should be a predicate of two arguments, which is used for the comparison instead of eq. (rem 'eq a b) is the same as (remq a b). (c.f. mem mem-fun)

Function: rem-if predicate list ¶

predicate should be a function of one argument. rem-if makes a new list by applying predicate to all of the elements of list and removing the ones for which the predicate returns non-nil. The function’s name means "remove if this condition is true".

Function: rem-if-not predicate list ¶

predicate should be a function of one argument. rem-if-not makes a new list by applying predicate to all of the elements of list and removing the ones for which the predicate returns nil. The function’s name means "remove if this condition is not true"; i.e. it keeps the elements for which predicate is true.

Function: del-if predicate list ¶

del-if is just like rem-if except that it modifies list rather than creating a new list. See rem-if.

Function: del-if-not predicate list ¶

del-if-not is just like rem-if-not except that it modifies list rather than creating a new list. See rem-if-not.

Function: every list predicate &optional step-function ¶

every returns t if predicate returns non-nil when applied to every element of list, or nil if predicate returns nil for some element. If step-function is present, it replaces cdr as the function used to get to the next element of the list.

Function: some list predicate &optional step-function ¶

some returns a tail of list such that the car of the tail is the first element that the predicate returns non-nil when applied to, or nil if predicate returns nil for every element. If step-function is present, it replaces cdr as the function used to get to the next element of the list.

Function: tailp sublist list ¶

Returns t if sublist is a sublist of list (i.e. one of the conses that makes up list). Otherwise returns nil.

Function: sxhash S-expression ¶

sxhash computes a hash code of an S-expression, and returns it as a fixnum, which may be positive or negative. A property of sxhash is that (equal x y) implies (= (sxhash x) (sxhash y)). The number returned by sxhash is some possibly large number in the range allowed by fixnums. It is guaranteed that:

1) sxhash for a symbol will always be positive.

2) sxhash of any particular expression will be constant in a particular implementation for all time, probably.

3) sxhash of any object of type random will be zero.

4) sxhash of a fixnum will = that fixnum.

Here is an example of how to use sxhash in maintaining hash tables of S-expressions:

(defun knownp (x)    ;look up x in the table
  (prog (i bkt)
    (setq i (plus 76 (remainder (sxhash x) 77)))	
      ;The remainder should be reasonably randomized between
      ;-76 and 76, thus table size must be > 175 octal.
    (setq bkt (aref table i))
      ;bkt is thus a list of all those expressions that hash
      ;into the same number as does x.
    (return (memq x bkt))))

To write an "intern" for S-expressions, one could

(defun sintern (x)
  (prog (bkt i tem)
    (setq bkt (aref table
		    (setq i (+ 2n-2 (\ (sxhash x) 2n-1)))))
	;2n-1 and 2n-2 stand for a power of 2 minus one and 
	;minus two respectively.  This is a good choice to 
	;randomize the result of the remainder operation.
    (return (cond ((setq tem (memq x bkt)) 
		   (car tem))
		  (t (aset (cons x bkt) table i)
		     x)))))

Function: assq item alist ¶

(assq item alist) looks up item in the association list (list of conses) alist. The value is the first cons whose car is eq to x, or nil if there is none such.

Examples:

(assq 'r '((a . b) (c . d) (r . x) (s . y) (r . z)))
	=>  (r . x)

(assq 'fooo '((foo . bar) (zoo . goo))) => nil

(assq 'b '((a b c) (b c d) (x y z))) => (b c d)

It is okay to rplacd the result of assq as long as it is not nil, if your intention is to "update" the "table" that was assq’s second argument.

Example:

(setq values '((x .  100) (y  . 200) (z .  50)))
(assq 'y values) => (y . 200)
(rplacd (assq 'y values)  201)
(assq 'y values)  => (y . 201) now

A typical trick is to say (cdr (assq x y)). Assuming the cdr of nil is guaranteed to be nil, this yields nil if no pair is found (or if a pair is found whose cdr is nil.)

assq could have been defined by:

(defun assq (item list)
    (cond ((null list) nil)
          ((eq item (caar list)) (car list))
          ((assq item (cdr list))) ))

Function: assoc item alist ¶

assoc is like assq except that the comparison uses equal instead of eq.

Example:

(assoc '(a b) '((x . y) ((a b) . 7) ((c . d) .e)))
	=> ((a b) . 7)

assoc could have been defined by:

(defun assoc (item list)
    (cond ((null list) nil)
          ((equal item (caar list)) (car list))
          ((assoc item (cdr list))) ))

Function: ass predicate item alist ¶

ass is the same as assq except that it takes an extra argument which should be a predicate of two arguments, which is used for the comparison instead of eq. (ass 'eq a b) is the same as (assq a b). (c.f. mem mem-fun)

Function: memass predicate item alist ¶

memass searches alist just like ass, but returns the portion of the list beginning with the pair containing item, rather than the pair itself. (car (memass x y z)) = (ass x y z).

Function: rassoc item alist ¶

rassoc means reverse assoc. It is like assoc, but it tries to find an element of alist whose cdr (not car) is equal to item. rassoc is defined by:

(defun rassoc (item in-list) 
    (do l in-list (cdr l) (null l) 
      (and (equal item (cdar l)) 
	   (return (car l)))))

Function: sassq item alist fcn ¶

(sassq item alist fcn) is like (assq item alist) except that if item is not found in alist, instead of returning nil, sassq calls the function fcn with no arguments. sassq could have been defined by:

(defun sassq (item alist fcn)
    (or (assq item alist)
        (apply fcn nil)))

sassq and sassoc (see below) are of limited use. These are primarily leftovers from Lisp 1.5.

Function: sassoc item alist fcn ¶

(sassoc item alist fcn) is like (assoc item alist) except that if item is not found in alist, instead of returning nil, sassoc calls the function fcn with no arguments. sassoc could have been defined by:

(defun sassoc (item alist fcn)
    (or (assoc item alist)
        (apply fcn nil)))

Function: pairlis cars cdrs ¶

pairlis takes two lists and makes an association list which associates elements of the first list with corresponding elements of the second list.

Example:

(pairlis '(beef clams kitty) '(roast fried yu-shiang))
   => ((beef . roast) (clams . fried) (kitty . yu-shiang))

Function: find-position-in-list item list ¶

find-position-in-list looks down list for an element which is eq to item, like memq. However, it returns the numeric index in the list at which it found the first occurence of item, or nil if it did not find it at all.

Examples:

(find-position-in-list 'a '(a b c)) => 0
(find-position-in-list 'c '(a b c)) => 2
(find-position-in-list 'e '(a b c)) => nil

Function: find-position-in-list-equal item list ¶

find-position-in-list-equal is exactly the same as find-position-in-list, except that the comparison is done with equal instead of eq.

5.6 Property Lists

[The stuff in FD.SYM will get moved here, leaving a pointer behind, and will be generalized for disembodied property lists and made to clarify the distinction between a plist and a paired list.]

5.7 Hash Tables

A hash table is a Lisp object that works something like a property list. Each hash table has a set of entries, each of which associates a particular key with a particular value. The basic functions that deal with hash tables can create entries, delete entries, and find the value that is associated with a given key. Finding the value is very fast even if there are many entries, because hashing is used; this is an important advantage of hash tables over property lists.

A given hash table can only associate one value with a given key; if you try to add a second value it will replace the first.

Hash tables are created with the function make-hash-table, which takes various options. New entries are added to hash tables with the puthash function. To look up a key and find the associated value, the gethash function is used. To remove an entry, use remhash. Here is a simple example.

(setq a (make-hash-table))

(puthash 'color 'brown a)

(puthash 'name 'fred a)

(gethash 'color a) => brown

(gethash 'name a) => fred

In this example, the symbols color and name are being used as keys, and the symbols brown and fred are being used as the associated values. The hash table has two items in it, one of which associates from color to brown, and the other of which associates from name to fred.

Keys do not have to be symbols; they can be any Lisp object. Likewise values can be any Lisp object. The Lisp function eq is used to compare keys, rather than equal. This means that keys are really objects, but it means that it is not reasonable to use numbers other than fixnums as keys. Hash tables are properly interfaced to the relocating garbage collector so that garbage collection will have no perceptible effect on the functionality of hash tables.

When a hash table is first created, it has a size, which is the maximum number of entries it can hold. Usually the actual capacity of the table is somewhat less, since the hashing is not perfectly collision-free. With the maximum possible bad luck, the capacity could be very much less, but this rarely happens. If so many entries are added that the capacity is exceeded, the hash table will automatically grow, and the entries will be rehashed (new hash values will be recomputed, and everything will be rearranged so that the fast hash lookup still works). This is transparent to the caller; it all happens automatically.

If the calling program is using multiprocessing, it must be careful to make sure that there are never two processes both referencing the hash table at the same time. There is no locking built into hash tables; if you have two processes that both want to reference the same hash table, you must arrange mutual exclusion yourself by using a lock or some other means. Don’t worry about this if you don’t use multiprocessing; but if you do use multiprocessing, you will have a lot of trouble if you don’t understand this.

Function: make-hash-table &rest options ¶

This creates a new hash table. Valid option keywords are:

:size

Set the initial size of the hash table, in entries, as a fixnum. The default is 100 (octal). The actual size is rounded up from the size you specify to the next "good" size. You won’t necessarily be able to store this many entries into the table before it overflows and becomes bigger; but except in the case of extreme bad luck you will be able to store almost this many.

:area

Specify the area in which the hash table should be created. This is just like the first argument to make-array (see make-array-fun). Defaults to nil (i.e. default-cons-area).

:rehash-function

Specify the function to be used for rehashing when the table becomes full. Defaults to the internal rehashing function that does the usual thing. If you want to write your own rehashing function, you will have to understand all the internals of how hash tables work. These internals are not documented here, as the best way to learn them is to read the source code.

:rehash-size

Specifies how much to increase the size of the hash table when it becomes full. This can be a fixnum which is the number of entries to add, or it can be a flonum which is the ratio of the new size to the old size. The default is 1.3, which causes the table to be made 30% bigger each time it has to grow.

Function: gethash key hash-table ¶

Find the entry in hash-table whose key is key, and return the associated value. If there is no such entry, return nil. Returns a second value, which is t if an entry was found or nil if there is no entry for key in this table.

Function: puthash key value hash-table ¶

Create an entry associating key to value; if there is already an entry for key, then replace the value of that entry with value. Returns value.

Function: remhash key hash-table ¶

Remove any entry for key in hash-table. Returns t if there was an entry or nil if there was not.

Function: maphash function hash-table ¶

For each entry in hash-table, call function on two arguments: the key of the entry and the value of the entry.

Function: clrhash hash-table ¶

Remove all the entries from hash-table. Returns the hash table itself.

The describe function (see describe-fun) prints a variety of useful information when applied to a hash table.

This hash table facility is similar to the hasharray facility of Interlisp, and some of the function names are the same. However, it is not compatible. The exact details and the order of arguments are designed to be consistent with the rest of the Lisp machine rather than with Interlisp. For instance, the order of arguments to maphash is different, we do not have the Interlisp "system hash table", and we do not have the Interlisp restriction that keys and values may not be nil.

5.8 Sorting

Several functions are provided for sorting arrays and lists. These functions use algorithms which always terminate no matter what sorting predicate is used, provided only that the predicate always terminates. The array sort is not necessarily stable; that is, equal items may not stay in their original order. However the list sort is stable.

After sorting, the argument (be it list or array) is rearranged internally so as to be completely ordered. In the case of an array argument, this is accomplished by permuting the elements of the array, while in the list case, the list is reordered by rplacd’s in the same manner as nreverse. Thus if the argument should not be clobbered, the user must sort a copy of the argument, obtainable by fillarray or append, as appropriate.

Should the comparison predicate cause an error, such as a wrong type argument error, the state of the list or array being sorted is undefined. However, if the error is corrected the sort will, of course, proceed correctly.

The sorting package is smart about cdr-coded lists.

Function: sort table predicate ¶

The first argument to sort is an array or a list. The second is a predicate, which must be applicable to all the objects in the array or list. The predicate should take two arguments, and return non-nil if and only if the first argument is strictly less than the second (in some appropriate sense).

The sort function proceeds to sort the contents of the array or list under the ordering imposed by the predicate, and returns the array or list modified into sorted order, i.e. its modified first argument. Note that since sorting requires many comparisons, and thus many calls to the predicate, sorting will be much faster if the predicate is a compiled function rather than interpreted.

Example:

(defun mostcar (x)
    (cond ((symbolp x) x)
          ((mostcar (car x)))))

(sort 'fooarray
      (function (lambda (x y)
	  (alphalessp (mostcar x) (mostcar y)))))

If fooarray contained these items before the sort:

(Tokens (The lion sleeps tonight))
(Carpenters (Close to you))
((Rolling Stones) (Brown sugar))
((Beach Boys) (I get around))
(Beatles (I want to hold your hand))

then after the sort fooarray would contain:

((Beach Boys) (I get around))
(Beatles (I want to hold your hand))
(Carpenters (Close to you))
((Rolling Stones) (Brown sugar))
(Tokens (The lion sleeps tonight))

Function: sortcar x predicate ¶

sortcar is exactly like sort, but the items in the array or list being sorted should all be conses. sortcar takes the car of each item before handing two items to the predicate. Thus sortcar is to sort as mapcar is to maplist.

The spelling of the names of the next two functions will be corrected at some point.

Function: sort-grouped-array array group-size predicate ¶

sort-grouped-array considers its array argument to be composed of records of group-size elements each. These records are considered as units, and are sorted with respect to one another. The predicate is applied to the first element of each record; so the first elements act as the keys on which the records are sorted.

Function: sort-grouped-array-group-key array group-size predicate ¶

This is like sort-grouped-array except that the predicate is applied to four arguments: an array, an index into that array, a second array, and an index into the second array. predicate should consider each index as a subscript of the first element of a record in the corresponding array, and compare the two records. This is more general than sort-grouped-array since the function can get at all of the elements of the relevant records, instead of only the first element.

6.1 The Value Cell

Each symbol has associated with it a value cell, which refers to one Lisp object. This object is called the symbol’s binding or value, since it is what you get when you evaluate the symbol. The binding of symbols to values allows symbols to be used as the implementation of variables in programs.

The value cell can also be empty, referring to no Lisp object, in which case the symbol is said to be unbound. This is the initial state of a symbol when it is created. An attempt to evaluate an unbound symbol causes an error.

The binding of a symbol can be changed either by lambda-binding or by assignment. The difference is that when a symbol is lambda-bound, its previous value is saved away, to be restored later, whereas assignment discards the previous value.

The symbols nil and t are always bound to themselves; they may not be assigned nor lambda-bound. (The error of changing the value of t or nil is not yet detected, but it will be.)

When closures are in use, the situation is a little more complicated. See the section on closures.

When a Lisp function is compiled, most of its variables are compiled into local variables, which are not represented by means of symbols. However the compiler recognizes usage of the setq special form, and of the set and value-cell-location functions with a quoted argument, as referring to variables rather than symbols, and generates the appropriate code to access the corresponding local variable rather than the symbol.

Special Form: defvar symbol &optional initial-value ¶

defvar is the recommended way to declare the use of a global variable in a program. Placed at top level in a file, it serves to initialize the variable, declare it special for the sake of compilation, and record the location for the sake of the editor so that you can ask to see where the variable is defined. It also provides a good place to put a comment describing the meaning of the variable (whereas an ordinary declare offers the temptation to declare several variables at once and not have room to describe them all). If the variable has a value already, that value is not changed. If initial-value is omitted, the variable is left unbound. defvar should be used only at top level, never in function definitions, and only for global variables (used by more than one function). (defvar foo 'bar) is equivalent to

(declare (special foo))
(or (boundp 'foo)
    (setq foo 'bar))

Function: set symbol value ¶

set is the primitive for assignment of symbols. The symbol’s value is changed to value; value may be any Lisp object. set returns value.

Example:

(set (cond ((eq a b) 'c)
           (t 'd))
     'foo)

will either set c to foo or set d to foo.

Special Form: setq ¶

The special form (setq var1 form1 var2 form2...) is the "variable assignment statement" of Lisp. First form1 is evaluated and the result is assigned to var1, using set, then form2 is evaluated and the result is assigned to var2, and so forth. setq returns the last value assigned, i.e. the result of the evaluation of its last argument.

Example:

(setq x (+ 3 2 1) y (cons x nil))

x is set to 6, y is set to (6), and the setq returns (6). Note that the first assignment was performed before the second form was evaluated, allowing that form to use the new value of x.

Macro: psetq ¶

A psetq form is just like a setq form, except that the assignments happen in parallel; first all of the forms are evaluated, and then the symbols are set to the resulting values.

Example:

(setq a 1)
(setq b 2)
(psetq a b b a)
a => 2
b => 1

Function: symeval sym ¶

symeval is the basic primitive for retrieving a symbols’s value. (symeval sym) returns sym’s current binding. This is the function called by eval when it is given a symbol to evaluate. If the symbol is unbound, then symeval causes an error.

Function: boundp sym ¶

boundp returns t if sym is bound; otherwise, it returns nil.

Function: makunbound sym ¶

makunbound causes sym to become unbound.

Example:

(setq a 1)
a => 1
(makunbound 'a)
a => causes an error.

makunbound returns its argument.

Function: value-cell-location sym ¶

value-cell-location returns a locative pointer to sym’s value cell. See the section on locatives.

[Must explain about external vs internal value cell.]

6.2 The Function Cell

Every symbol also has associated with it a function cell. The function cell is similar to the value cell; it refers to a Lisp object. When a function is referred to by name, that is, when a symbol is applied or appears as the car of a form to be evaluated, that symbol’s function cell is used to find its definition, the functional object which is to be applied. For example, when evaluating (+ 5 6), the evaluator looks in +’s function cell to find the definition of +, in this case a FEF containing a compiled program, to apply to 5 and 6. Maclisp does not have function cells; instead, it looks for special properties on the property list. This is one of the major incompatibilities between the two dialects. Like the value cell, a function cell can be empty, and it can be lambda-bound or assigned. The following functions are analogous to the value-cell related functions in the previous section.

Function: fsymeval sym ¶

fsymeval returns sym’s definition, the contents of its function cell. If the function cell is empty, fsymeval causes an error.

Function: fset sym x ¶

fset stores x, which may be any Lisp object, into sym’s function cell. It returns x.

Function: fboundp sym ¶

fboundp returns nil if sym’s function cell is empty, i.e. sym is undefined. Otherwise it returns t.

Function: fmakunbound sym ¶

fmakunbound causes sym’s to be undefined, i.e. its function cell to be empty. It returns sym.

Function: function-cell-location sym ¶

function-cell-location returns a locative pointer to sym’s function cell. See the section on locatives.

The usual means of putting a function in a symbol’s function cell (defining the symbol) is by means of the defun special form. Macros are put in a symbol’s function cell by means of the macro special form. Substitutable functions can be put there with the defsubst special form. Anything else requires the deff special form.

Special Form: defun ¶

defun is used for defining functions. A defun form looks like:

(defun name type lambda-list
       body)

The type is only for Maclisp compatibility, and is optional and usually absent. The lambda-list is as described on lambda-list and may contain "&-keywords".

Examples:

(defun addone (x)
       (1+ x))

(defun foo (a &optional (b 5) c &rest e &aux j)
	(setq j (+ a b))
	(cond ((not (null c))
	       (cons j e))
	      (t j))) 

A list (named-lambda name lambda-list . body) is left in the function cell of name.

For compatibility, the Maclisp types expr, fexpr, and macro, and Maclisp lexprs (which have an atomic lambda-list) are recognized and the corresponding Lisp Machine flavor of defun is assumed.

Special Form: defsubst ¶

defsubst is used for defining substitutable functions. It is used just like defun

(defsubst name lambda-list . body)

and does almost the same thing. It defines a function which executes identically to the one which a similar call to defun would define. The difference comes when a function which calls this one is compiled. Then, the call will be open-coded by substituting the substitutable function’s definition into the code being compiled. Substitutable functions are a sort of cross between ordinary functions and macros; they can be applied like functions, but act like macros for the compiler. The actual definition looks like (subst lambda-list . body). For example, if we define

(defsubst square (x) (* x x))

(defun foo (a b) (square (+ a b)))

then if foo is used interpreted, square will work just as if it had been defined by defun. If foo is compiled, however, the squaring will be substituted into it and it will compile just like

(defun foo (a b) (* (+ a b) (+ a b)))

You will notice that the substitution performed is very simple and takes no care about the possibility of computing an argument twice when it really ought to be computed once.

Special Form: macro ¶

macro is used for defining macros. Its form is:

(macro name (arg)
       body)

Examples:

(macro addone (x)
       (list '1+ (cadr x)))

(macro increment (x)
       (list 'setq (cadr x) (list '1+ (cadr x))))

In the function cell of name is placed a cons whose car is the symbol macro, and whose cdr is a lambda-expression of the form (lambda (arg) . body). Much of the time it is more convenient and clear to use a macro-defining macro such as defmacro (see defmacro-fun) to define macros.

Special Form: deff ¶

deff is used for giving a function a definition which is not obtainable with the specific defining forms such as defun and macro. It looks like

(deff name definition)

where definition is evaluated so you can get any object you want. For example,

(deff foo 'bar)

will make foo equivalent to bar, with an indirection so that if bar changes foo will likewise change;

(deff foo (function bar))

copies the definition of bar into foo with no indirection, so that further changes to bar will have no effect on foo.

Special Form: def ¶

[from what’s explained here, nobody would understand why def is useful. The whole section towards functions and definitions needs to be rewritten].

Function: fset-carefully symbol definition &optional force-flag ¶

This is the same as (fset symbol definition) except that it makes some checks and saves the old definition. defun, macro, undefun, load, and the compiler call fset-carefully when they define functions.

fset-carefully prints a message and asks the user if the current package (value of package) is not allowed to redefine the symbol. Specifying force-flag non-nil suppresses this check.

The previous definition, if any, of symbol is saved on the :previous-definition property. If it is a list, it is also saved on the :previous-expr-definition property. These properties are used by the undefun function (undefun-fun), which restores the previous definition, and the uncompile function (uncompile-fun), which restores the previous interpreted definition.

If symbol is not a symbol, but a list (name prop), then the definition is put on name’s prop property, the package error check is not done, and the old definition is not saved. This is used to implement the (defun (name prop) ...) feature.

Function: undefun symbol ¶

If symbol has a :previous-definition property, undefun interchanges it with symbol’s function definition. This undoes the effect of a defun, compile, etc.

Function: arglist function &optional literal-flag ¶

arglist is given a function, and returns its best guess at the nature of the function’s lambda-list. If function is a symbol, arglist of its function definition is used. If the function is an actual lambda-expression, its cadr, the lambda-list, is returned. But if function is compiled, arglist attempts to reconstruct the lambda-list of the original definition, using whatever debugging information was saved by the compiler. Sometimes the actual names of the bound variables are not available, and arglist uses the symbol *unknown* for these. Also, sometimes the initialization of an optional parameter is too complicated for arglist to reconstruct; for these it returns the symbol *hairy*. Some functions’ real argument lists are not what would be most descriptive to a user. A function may take a &rest argument for technical reasons even though there are standard meanings for the first element of that argument. For such cases, the definition of the function can specify a value to be returned when the user asks about the argument list, with a local-declare. Example:

(def foo		;So the definition of foo can be found
  (local-declare ((arglist x y &rest z))
    (defun foo (&rest rest-arg) .....)))

literal-flag allows the caller of arglist to say that declared arglists of this sort should not be used. arglist cannot be relied upon to return the exactly correct answer, since some of the information may have been lost. Programs interested in how many and what kind of arguments there are should use args-info instead. arglist is a reliable way of getting the names of the arguments, if that information is available, provided the literal-flag argument is t. This inhibits use of arglist declarations.

Function: args-info function ¶

args-info returns a fixnum called the "numeric argument descriptor" of the function, which describes the way the function takes arguments. The information in it is stored in various bits and byte fields in the fixnum, which are referenced by the symbolic names shown below. By the usual Lisp Machine convention, those starting with a single "%" are bit-masks (meant to be loganded with the number), and those starting with "%%" are byte descriptors (meant to be used with ldb). Here are the fields:

%arg-desc-quoted-rest

If this bit is set, the function has a "rest" argument, and it is "quoted". Most special forms have this bit.

%arg-desc-evaled-rest

If this bit is set, the function has a "rest" argument, and it is not "quoted".

%arg-desc-fef-quote-hair

If this bit is set, there are some quoted arguments other than the "rest" argument (if any), and the pattern of quoting is too complicated to describe here. The ADL (Argument Description List) in the FEF should be consulted.

%arg-desc-interpreted

This function is not a compiled-code object, and a numeric argument descriptor cannot be computed. Usually args-info will not return this bit, although %args-info will.

%arg-desc-fef-bind-hair

There is argument initialization, or something else too complicated to describe here. The ADL (Argument Description List) in the FEF should be consulted.

%%arg-desc-min-args

This is the minimum number of arguments which may be passed to this function, i.e., the number of "required" parameters.

%%arg-desc-max-args

This is the maximum number of arguments which may be passed to this function, i.e., the sum of the number of "required" parameters and the number of "optional" paramaters. If there is a rest argument, this is not really the maximum number of arguments which may be passed; an arbitrarily-large number of arguments is permitted, subject to limitations on the maximum size of a stack frame.

Note that %arg-desc-quoted-rest and %arg-desc-evaled-rest cannot both be set.

Function: %args-info function ¶

This is an internal function of args-info; it is like args-info but only works for compiled-code objects. It exists because it has to be in the microcode anyway, for apply.

6.3 The Property List

Every symbol has associated with it a property list, which is a list used for associating "attributes" with symbols. A property list has an even number of elements. Each pair of elements constitutes a property; the first of the pair is a symbol called the indicator, and the second is a Lisp object called the value or, more loosely, the property. The indicator serves as the name of the property, and the value as the value of the property. Here is an example of the property list of a symbol named b1 which is being used by a program which deals with blocks:

	(color blue on b6 associated-with (b2 b3 b4))

There are three properties, and so the list has six elements. The first property’s indicator is the symbol color, and its value is the symbol blue. One says that "the value of b1’s color property is blue", or, informally, that "b1’s color property is blue." The program is probably representing the information that the block represented by b1 is blue. Similarly, it is probably representing in the rest of the property list that block b1 is on top of block b6, and that b1 is associated with blocks b2, b3, and b4. When a symbol is created, its property list is initially nil. Because of the existence of print-name, value, function, and package cells, none of the Maclisp system property names (expr, fexpr, macro, array, subr, lsubr, fsubr, and in former times value and pname) exist in Lisp Machine lisp. The compiler (see compiler) and the editor use several properties, which are documented in those sections.

It is also possible to have a "disembodied" property list, which is not associated with any symbol. A disembodied property list is a cons. Its car may be used for any purpose. The property list resides in its cdr. The way to create a disembodied property list is with (ncons nil). In all of the functions in this section, disembodied property lists may be used as well as symbols; for brevity, the text speaks only of symbols.

Function: get sym indicator ¶

get looks up sym’s indicator property. If it finds such a property, it returns the value; otherwise, it returns nil.

Example: If the property list of foo is (baz 3), then

(get 'foo 'baz) => 3
(get 'foo 'zoo) => nil

Function: getl sym indicator-list ¶

getl is like get, except that the second argument is a list of indicators. getl searches down sym’s property list for any of the indicators in indicator-list, until it finds a property whose indicator is one of the elements of indicator-list. getl returns the portion of sym’s property list beginning with the first such property which it found. So the car of the returned list is an indicator, and the cadr is the property value. If none of the indicators on indicator-list are on the property list, getl returns nil.

Example:

If the property list of foo were
(bar (1 2 3) baz (3 2 1) color blue height six-two)
then
(getl 'foo '(baz height))
  => (baz (3 2 1) color blue height six-two)

Function: putprop sym x indicator ¶

This gives sym an indicator-property of x. After this is done, (get sym indicator) will return x.

Example:

(putprop 'Nixon 'not 'crook)

If sym already has a property with the name indicator, then that property is removed first; this insures that getl will always find the property that was added most recently.

Special Form: defprop ¶

defprop is a form of putprop with unevaluated arguments, which is sometimes more convenient for typing.

Example:

(defprop foo bar next-to)

is the same as

(putprop 'foo 'bar 'next-to)

Function: remprop sym indicator ¶

This removes sym’s indicator property, by splicing it out of the property list. It returns that portion of sym’s property list of which the former indicator-property was the car.

Example:

If the property list of foo was
(color blue height six-three near-to bar)
then
(remprop 'foo 'height) => (six-three near-to bar)
and foo’s property list would be
(color blue near-to bar)

If sym has no indicator-property, then remprop has no side-effect and returns nil.

Function: plist sym ¶

This returns the property list of sym.

Function: setplist sym property-list ¶

This sets the property list of sym to property-list. setplist is to be used with caution, since property lists sometimes contain internal system properties, which are used by many useful system functions. Also it is inadvisable to have the property lists of two different symbols be eq, since the shared list structure will cause unexpected effects on one symbol if putprop or remprop is done to the other.

Function: property-cell-location sym ¶

This returns a locative pointer to the location of sym’s property-list cell. See the section on locatives.

6.4 The Print Name

Every symbol has an associated string called the print-name, or pname for short. This string is used as the external representation of the symbol: if the string is typed in to read, it is read as a reference to that symbol (if it is interned), and if the symbol is printed, print types out the print-name. For more information, see the section on the reader (see reader) and printer (see printer).

Function: samepnamep sym1 sym2 ¶

This predicate returns t if the two symbols sym1 and sym2 have equal print-names; that is, if their printed representation is the same. Upper and lower case letters are normally considered the same. If either or both of the arguments is a string instead of a symbol, then that string is used in place of the print-name.

Examples:

(samepnamep 'xyz (maknam '(x y z)) => t

(samepnamep 'xyz (maknam '(w x y)) => nil

(samepnamep 'xyz "xyz") => t

This is the same function as string-equal (see string-equal-fun).

Function: get-pname sym ¶

This returns the print-name of the symbol sym.

Example:

(get-pname 'xyz) => "xyz"

Function: print-name-cell-location sym ¶

This returns a locative pointer to the location of sym’s print-name cell. See the section on locatives. Note that the contents of this cell is not actually the print name, but the symbol header, an object which may not be directly manipulated. Use get-pname, the microcode primitive which knows how to extract the pname from the symbol header.

6.5 The Creation and Interning of Symbols

Normally, one wants to refer to the same symbol every time the same print-name-like string is typed. So, when read sees such a character-string in the input to Lisp, it looks in a table called the obarray for some symbol with that print-name. If it finds such a symbol, then that is what it returns; otherwise, it creates a symbol with that print-name (using the make-symbol function, see below), enters that symbol on the obarray, and returns it. The sub-function of read which performs these functions is called intern, and when a symbol has been entered on the obarray it is said to be interned.

A symbol can also be uninterned, indicating that it is not on the obarray and cannot be referred to simply by typing its print name. Such symbols can be used as objects within a data-structure, but can cause trouble during debugging because they cannot be "typed in" directly, yet they look just like interned symbols when "typed out".

Actually there can be many obarrays; the Lisp Machine system includes a feature called the package system (see package) which keeps track of multiple packages or name spaces and their interrelationships, using separate obarrays for each package.

Function: make-symbol pname &optional permanent-p ¶

This creates a new uninterned symbol, whose print-name is the string pname. The value and function bindings will be unbound, the property list will be empty, and the package will be nil. If permanent-p is specified, the symbol is going to be interned and kept around forever; in this case it and its pname will be put in the proper areas. If permanent-p is nil (the default), nothing special is done with areas.

Examples:

(setq a (make-symbol "foo")) => foo
(symeval a) => ERROR!

Note that the symbol is not interned; it is simply created and returned.

Function: copysymbol sym copy-p ¶

This returns a new uninterned symbol with the same print-name as sym. If copy-p is non-nil, then the initial value and function-definition of the new symbol will be the same as those of sym, and the property list of the new symbol will be a copy of sym’s. If copy-p is nil, then the new symbol will be unbound and undefined, and its property list will be nil.

Function: gensym &optional x ¶

gensym invents a print-name, and creates a new symbol with that print-name. It returns the new, uninterned symbol.

The invented print-name is a character prefix (the value of si:*gensym-prefix) followed by the decimal representation of a number (the value of si:*gensym-counter), e.g. "g0001". The number is increased by one every time gensym is called.

If the argument x is present and is a fixnum, then si:*gensym-counter is set to x. If x is a string or a symbol, then si:*gensym-prefix is set to the first character of the string or of the print-name. After handling the argument, gensym creates a symbol as it would with no argument.

Examples:

if   (gensym) => g0007
then (gensym 'foo) => f0008
     (gensym 40) => f0032
     (gensym) => f0033

Note that the number is in decimal and always has four digits, and the prefix is always one character.

gensym is usually used to create a symbol which should not normally be seen by the user, and whose print-name is unimportant, except to allow easy distinction by eye between two such symbols. The optional argument is rarely supplied. The name comes from "generate symbol", and the symbols produced by it are often called "gensyms".

Function: package-cell-location symbol ¶

Returns a locative pointer to symbol’s package cell, which contains the package (see package) which owns symbol.

7.1 Numeric Predicates

Function: zerop x ¶

Returns t if x is zero. Otherwise it returns nil. If x is not a number, zerop causes an error.

Function: plusp x ¶

Returns t if its argument is a positive number, strictly greater than zero. Otherwise it returns nil. If x is not a number, plusp causes an error.

Function: minusp x ¶

Returns t if its argument is a negative number, strictly less than zero. Otherwise it returns nil. If x is not a number, minusp causes an error.

Function: oddp number ¶

Returns t if number is odd, otherwise nil. If number is not a fixnum or a bignum, oddp causes an error.

Function: evenp number ¶

Returns t if number is even, otherwise nil. If number is not a fixnum or a bignum, evenp causes an error.

Special Form: signp ¶

signp is used to test the sign of a number. It is present only for Maclisp compatibility, and is not recommended for use in new programs. (signp test x) returns t if x is a number which satisfies the test, nil if it is not. test is not evaluated, but x is. test can be one of the following:

l

x < 0

le

x lessOrEqual 0

e

x = 0

n

x notEquals 0

ge

x greaterOrEqual 0

g

x > 0

Examples:

(signp le 12) => t
(signp n 0) => nil
(signp g 'foo) => nil

See also the data-type predicates fixp, floatp, bigp, small-floatp, and numberp (fixp-fun).

All of these functions require that their arguments be numbers, and signal an error if given a non-number. They work on all types of numbers, automatically performing any required coercions.

Function: = x y ¶

Returns t if x and y are numerically equal.

Function: greaterp x y &rest more-args ¶

greaterp compares its arguments from left to right. If any argument is not greater than the next, greaterp returns nil. But if the arguments are monotonically strictly decreasing, the result is t.

Examples:

(greaterp 4 3) => t
(greaterp 4 3 2 1 0) => t
(greaterp 4 3 1 2 0) => nil

Function: > x y ¶

Returns t if x is strictly greater than y, and nil otherwise.

Macro: >= x y ¶

Macro: greaterOrEqual x y ¶

Returns t if x is greater than or equal to y, and nil otherwise.

Function: lessp x y &rest more-args ¶

lessp compares its arguments from left to right. If any argument is not less than the next, lessp returns nil. But if the arguments are monotonically strictly increasing, the result is t.

Examples:

(lessp 3 4) => t
(lessp 1 1) => nil
(lessp 0 1 2 3 4) => t
(lessp 0 1 3 2 4) => nil

Function: < x y ¶

Returns t if x is strictly less than y, and nil otherwise.

Macro: <= x y ¶

Macro: lessOrEqual x y ¶

Returns t if x is less than or equal to y, and nil otherwise.

Macro: notEquals x y ¶

Returns t if x is not equal to y, and nil otherwise.

7.2 Arithmetic

All of these functions require that their arguments be numbers, and signal an error if given a non-number. They work on all types of numbers, automatically performing any required coercions.

Function: plus &rest args ¶

Function: + &rest args ¶

Function: +$ &rest args ¶

Returns the sum of its arguments. If there are no arguments, it returns 0, which is the identity for this operation.

Function: difference arg &rest args ¶

Returns its first argument minus all of the rest of its arguments.

Function: - arg &rest args ¶

Function: -$ arg &rest args ¶

With only one argument, - is the same as minus; it returns the negative of its argument. With more than one argument, - is the same as difference; it returns its first argument minus all of the rest of its arguments.

Function: times &rest args ¶

Function: * &rest args ¶

Function: *$ &rest args ¶

Returns the product of its arguments. If there are no arguments, it returns 1, which is the identity for this operation.

Function: quotient arg &rest args ¶

Returns the first argument divided by all of the rest of its arguments.

Function: // arg &rest args ¶

Function: //$ arg &rest args ¶

The name of this function is written // rather than / because / is the quoting character in Lisp syntax and must be doubled. With more than one argument, // is the same as quotient; it returns the first argument divided by all of the rest of its arguments. With only one argument, (// x) is the same as (// 1 x).

Examples:

(// 3 2) => 1       ;Fixnum division truncates.
(// 3 2.0) => 1.5
(// 3 2.0s0) => 1.5s0
(// 4 2) => 2
(// 12. 2. 3.) => 2

Function: add1 x ¶

Function: 1+ x ¶

Function: 1+$ x ¶

(add1 x) is the same as (plus x 1).

Function: sub1 x ¶

Function: 1- x ¶

Function: 1-$ x ¶

(sub1 x) is the same as (difference x 1). Note that the short name may be confusing: (1- x) does not mean 1-x; rather, it means x-1.

Function: remainder x y ¶

Function: \ x y ¶

Returns the remainder of x divided by y. x and y may not be flonums nor small flonums.

Function: gcd x y ¶

Function: \\ x y ¶

Returns the greatest common divisor of x and y. x and y may not be flonums nor small flonums.

Function: expt x y ¶

Function: ^ x y ¶

Function: ^$ x y ¶

Returns x raised to the y’th power. y must be a fixnum. [I guess this is incompatible with Maclisp.]

Function: exp x ¶

Returns e raised to the x’th power, where e is the base of natural logarithms.

Function: log x ¶

Returns the natural logarithm of x.

Function: sin x ¶

Returns the sine of x in radians.

Function: sind x ¶

Returns the sine of x in degrees.

Function: cos x ¶

Returns the cosine of x in radians.

Function: cosd x ¶

Returns the cosine of x in degrees.

Function: sqrt x ¶

Returns the square root of x.

Function: atan y x ¶

Returns the arctangent of the angle y/x. It always returns a non-negative number between zero and /2.

Function: atan2 y x ¶

Returns the arctangent of the angle y/x, except that it returns a number between -/2 and /2.

Function: max &rest args ¶

max returns the largest of its arguments.

Example:

(max 1 3 2) => 3

max requires at least one argument.

Function: min &rest args ¶

min returns the smallest of its arguments.

Example:

(min 1 3 2) => 1

min requires at least one argument.

Function: abs x ¶

Returns |x|, the absolute value of the number x. abs could have been defined by:

(defun abs (x)
    (cond ((minusp x) (minus x))
	  (t x)))

Function: minus x ¶

Returns the negative of x.

Examples:

(minus 1) => -1
(minus -3) => 3

Function: *dif x y ¶

Function: *plus x y ¶

Function: *quo x y ¶

Function: *times x y ¶

These are the internal micro-coded arithmetic functions. There is no reason why anyone should need to refer to these explicitly, since the compiler knows how to generate the appropriate code for plus, +, etc. These names are only here for Maclisp compatibility.

The following functions are provided to allow specific conversions of data types to be forced, when desired.

Function: fix x ¶

Converts x from a flonum (or small-flonum) to an integer, by truncation. The result is a fixnum or a bignum as appropriate. If x is already a fixnum or a bignum, it is returned unchanged.

Function: fixr x ¶

Converts x from a flonum (or small-flonum) to an integer, by truncation.

Function: float x ¶

Converts x to a flonum. x may be a fixnum, a bignum, a small-flonum, or a flonum.

Function: small-float x ¶

Converts x to a small flonum. x may be a fixnum, a bignum, a small-flonum, or a flonum.

7.3 Random Functions

Function: random &optional arg (array si:random-array) ¶

(random) returns a random fixnum, positive or negative. If arg is present, a fixnum between 0 and arg-1 inclusive is returned. If array is present, the given array is used instead of the default one (see below). [The random algorithm should be described.]

Function: si:random-create-array size offset seed &optional (area default-array-area) ¶

Creates, initializes and returns a random-number-generator array. This is used for more advanced applications of the pseudo-random number generator, in which it is desirable to have several different controllable resettable sources of random numbers. For the exact meaning of the arguments, read the code. size is the size of the array, offset is an integer less than size, seed is a fixnum. This calls si:random-initialize on the random array before returning it.

Function: si:random-initialize array ¶

array must be a random-number-generator array, such as is created by si:random-create-array. It reinitializes the contents of the array from the seed (calling random changes the contents of the array and the pointers, but not the seed).

Variable: si:random-array ¶

The value of si:random-array is the default random-number-generator array. It is created if random is called and si:random-array is unbound. A random-number-generator array has a leader which is a structure with the following elements:

si:random-fill-pointer

The fill-pointer, the length of the array.

si:random-seed

The seed from which to initialize the contents.

si:random-pointer-1

The first pointer.

si:random-pointer-2

The second pointer.

7.4 Logical Operations on Numbers

Except for lsh and rot, these functions operate on either fixnums or bignums. lsh and rot have an inherent word-length limitation and hence only operate on 24-bit fixnums. Negative numbers are operated on in their 2’s-complement representation. (Negative numbers used to be disallowed in some cases.)

Function: logior &rest args ¶

Returns the bit-wise logical inclusive or of its arguments. A minimum of one argument is required.

Example:

(logior 4002 67) => 4067

Function: logxor &rest args ¶

Returns the bit-wise logical exclusive or of its arguments. A minimum of one argument is required.

Example:

(logxor 2531 7777) => 5246

Function: logand &rest args ¶

Returns the bit-wise logical and of its arguments. A minimum of one argument is required.

Examples:

(logand 3456 707) => 406
(logand 3456 -100) => 3400

Function: boole fn &rest args ¶

boole is the generalization of logand, logior, and logxor. fn should be a fixnum between 0 and 17 octal inclusive; it controls the function which is computed. If the binary representation of fn is abcd (a is the most significant bit, d the least) then the truth table for the Boolean operation is as follows:

       y
   | 0  1
---------
  0| a  c
x  |
  1| b  d

If boole has more than three arguments, it is associated left to right; thus,

(boole fn x y z) = (boole fn (boole fn x y) z)

With two arguments, the result of boole is simply its second argument. A minimum of two arguments is required.

Examples:

(boole 1 x y) = (logand x y)
(boole 6 x y) = (logxor x y)

logand, logior, and logxor are usually preferred over boole.

Function: bit-test x y ¶

bit-test is a predicate which returns t if any of the bits designated by the 1’s in x are 1’s in y. bit-test is implemented as a macro which expands as follows:

(bit-test x y) ==> (not (zerop (logand x y)))

Function: ldb-test ppss y ¶

ldb-test is a predicate which returns t if any of the bits designated by the byte specifier ppss are 1’s in y. That is, it returns t if the designated field is non-zero. ldb-test is implemented as a macro which expands as follows:

(ldb-test ppss y) ==> (not (zerop (ldb ppss y)))

Function: lsh x y ¶

Returns x shifted left y bits if y is positive or zero, or x shifted right |y| bits if y is negative. Zero bits are shifted in (at either end) to fill unused positions. x and y must be fixnums.

Examples:

(lsh 4 1) => 10    ;(octal)
(lsh 14 -2) => 3
(lsh -1 1) => -2

Function: ash x y ¶

Shifts x arithmetically left y bits, or right -y bits, depending on the sign of y. x may be a fixnum or a bignum. The sign of the result is always the same as the sign of x.

Function: rot x y ¶

Returns x rotated left y bits if y is positive or zero, or x rotated right |y| bits if y is negative. The rotation considers x as a 24-bit number (unlike Maclisp, which considers x to be a 36-bit number in both the pdp-10 and Multics implementations). x and y must be fixnums.

Examples:

(rot 1 2) => 4
(rot 1 -2) => 20000000
(rot -1 7) => -1
(rot 15 24.) => 15

Function: haipart x n ¶

Returns the high n bits of the binary representation of |x|, or the low |n| bits if n is negative. x may be a fixnum or a bignum; note that if x is negative its absolute value is used.

Function: haulong x ¶

This returns the number of significant bits in x. x may be a fixnum or a bignum. The result does not depend on the sign of x. The result is the least integer not less than the base-2 logarithm of |x|+1.

Examples:

(haulong 0) => 0
(haulong 3) => 2
(haulong -7) => 3

7.5 Byte Manipulation Functions

Several functions are provided for dealing with an arbitrary-width field of contiguous bits appearing anywhere in an integer (a fixnum or a bignum). Such a contiguous set of bits is called a byte. Note that we are not using the term byte to mean eight bits, but rather any number of bits within a number. These functions use numbers called byte specifiers to designate a specific byte position within any word. Byte specifiers are fixnums whose two lowest octal digits represent the size of the byte, and whose higher (usually two, but sometimes more) octal digits represent the position of the byte within a number, counting from the right in bits. A position of zero means that the byte is at the right end of the number. For example, the byte-specifier 0010 (i.e., 10 octal) refers to the lowest eight bits of a word, and the byte-specifier 1010 refers to the next eight bits. These byte-specifiers will be stylized below as ppss. The maximum value of the ss digits is 27 (octal), since a byte must fit in a fixnum although bytes can be loaded from and deposited into bignums. (Bytes are always positive numbers.) The format of byte-specifiers is taken from the pdp-10 byte instructions.

Function: ldb ppss num ¶

ppss specifies a byte of num, which is returned as a number, right-justified. The ss bits of the byte starting at bit pp are the lowest ss bits in the returned value, and the rest of the bits in the returned value are zero. The name of the function, ldb, means "load byte". num may be a fixnum or a bignum.

Example:

(ldb 0306 4567) => 56

Function: mask-field ppss num ¶

This is similar to ldb; however, the specified byte of num is returned as a number in position pp of the returned word, instead of position 0 as with ldb. num must be a fixnum.

Example:

(mask-field 0306 4567) => 560

Function: dpb byte ppss num ¶

Returns a number which is the same as num except in the bits specified by ppss. The low ss bits of byte are placed in those bits. byte is interpreted as being right-justified, as if it were the result of ldb. num may be a fixnum or a bignum.

Example:

(dpb 23 0306 4567) => 4237

Function: deposit-field byte ppss num ¶

This is like dpb, except that byte is not taken to be left-justified; the ppss bits of byte are used for the ppss bits of the result, with the rest of the bits taken from num. num must be a fixnum.

Example:

(deposit-field 230 0306 4567) => 4237

Function: %logldb ppss fixnum ¶

%logldb is like ldb except that it only loads out of fixnums and allows a byte size of 30 (octal), i.e. the whole fixnum.

Function: %logdpb byte ppss fixnum ¶

%logdpb is like dpb except that it only deposits into fixnums. Using this to change the sign-bit will leave the result as a fixnum, while dpb would produce a bignum result for arithmetic correctness. %logdpb is good for manipulating fixnum bit-masks such as are used in some internal system tables and data-structures.

7.6 24-Bit Numbers

Sometimes it is desirable to have a form of arithmetic which has no overflow checking (which would produce bignums), and truncates results to the word size of the machine. In Lisp Machine Lisp, this is provided by the following set of functions. Their answers are only correct modulo 2^24. These functions should not be used for "efficiency"; they are probably less efficient than the functions which do check for overflow. They are intended for algorithms which require this sort of arithmetic, such as hash functions and pseudo-random number generation.

Function: %24-bit-plus x y ¶

Returns the sum of x and y modulo 2^24. Both arguments should be fixnums.

Function: %24-bit-difference x y ¶

Returns the difference of x and y modulo 2^24. Both arguments should be fixnums.

Function: %24-bit-times x y ¶

Returns the product of x and y modulo 2^24. Both arguments should be fixnums.

7.7 Double-Precision Arithmetic

These peculiar functions are useful in programs that don’t want to use bignums for one reason or another.

Function: %multiply-fractions num1 num2 ¶

Returns bits 24 through 46 (the most significant half) of the product of num1 and num2. If you call this and %24-bit-times on the same arguments num1 and num2, regarding them as integers, you can combine the results into a double-precision product. If num1 and num2 are regarded as fractions, -1 lessOrEqual num < 1, %multiply-fractions returns 1/2 of their correct product as a fraction. (The name of this function isn’t too great.)

Function: %divide-double dividend[24:46] dividend[0:23] divisor ¶

Divides the double-precision number given by the first two arguments by the third argument, and returns the single-precision quotient. Causes an error if division by zero or if the quotient won’t fit in single precision.

Function: %remainder-double dividend[24:46] dividend[0:23] divisor ¶

Divides the double-precision number given by the first two arguments by the third argument, and returns the remainder. Causes an error if division by zero.

Function: %float-double high24 low24 ¶

high24 and low24, which must be fixnums, are concatenated to produce a 48-bit unsigned positive integer. A flonum containing the same value is constructed and returned. Note that only the 31 most-significant bits are retained (after removal of leading zeroes.) This function is mainly for the benefit of read.

8.1 String Manipulation

Function: character x ¶

character coerces x to a single character, represented as a fixnum. If x is a number, it is returned. If x is a string or an array, its first element is returned. If x is a symbol, the first character of its pname is returned. Otherwise, an error occurs.

Function: char-equal ch1 ch2 ¶

This is the primitive for comparing characters for equality; many of the string functions call it. ch1 and ch2 must be fixnums. The result is t if the characters are equal ignoring case and font, otherwise nil. %%ch-char is the byte-specifier for the portion of a character which excludes the font information.

Function: char-lessp ch1 ch2 ¶

This is the primitive for comparing characters for order; many of the string functions call it. ch1 and ch2 must be fixnums. The result is t if ch1 comes before ch2 ignoring case and font, otherwise nil.

Variable: alphabetic-case-affects-string-comparison ¶

This variable is normally nil. If it is t, char-equal, char-lessp, and the string searching and comparison functions will distinguish between upper-case and lower-case letters. It is alright to bind this to t, but changing its global value to t will break many system functions and user interfaces and so is not recommended.

Function: string x ¶

string coerces x into a string. Most of the string functions apply this to their string arguments. If x is a string or an array, it is returned. If x is a symbol, its pname is returned. If x is a number, a 1-character long string containing it is returned. Otherwise, an error occurs.

Function: string-length string ¶

string-length returns the number of characters in string. This is 1 if string is a number, the array-active-length (see array-active-length-fun) if string is an array, or the array-active-length of the pname if string is a symbol.

Function: string-equal string1 string2 &optional (idx1 0) (idx2 0) lim1 lim2 ¶

string-equal compares two strings, returning t if they are equal and nil if they are not. The comparison ignores the extra "font" bits in 16-bit strings and ignores alphabetic case. equal calls string-equal if applied to two strings. The optional arguments idx1 and idx2 are the starting indices into the strings. The optional arguments lim1 and lim2 are the final indices; the comparison stops just before the final index. lim1 and lim2 default to the lengths of the strings. These arguments are provided so that you can efficiently compare substrings.

Examples:

(string-equal "Foo" "foo") => t
(string-equal "foo" "bar") => nil
(string-equal "element" "select" 0 1 3 4) => t

Function: %string-equal string1 idx1 string2 idx2 count ¶

%string-equal is the microcode primitive which string-equal calls. It returns t if the count characters of string1 starting at idx1 are char-equal to the count characters of string2 starting at idx2, or nil if the characters are not equal or if count runs off the length of either array.

Instead of a fixnum, count may also be nil. In this case, %string-equal compares the substring from idx1 to (string-length string1) against the substring from idx2 to (string-length string2). If the lengths of these substrings differ, then they are not equal and nil is returned.

Examples:

To compare the two strings foo and bar:
(%string-equal foo 0 bar nil)
To see if the string foo starts with the characters "bar":
(%string-equal foo 0 "bar" 0 3)

Function: string-lessp string1 string2 ¶

string-lessp compares two strings using dictionary order. The result is t if string1 is the lesser, and nil if they are equal or string2 is the lesser.

Function: substring string start &optional end area ¶

This extracts a substring of string, starting at the character specified by start and going up to but not including the character specified by end. start and end are 0-origin indices. The length of the returned string is end minus start. If end is not specified it defaults to the length of string. The area in which the result is to be consed may be optionally specified.

Example:

(substring "Nebuchadnezzar" 4 8) => "chad"

Function: nsubstring string start &optional end area ¶

nsubstring is the same as substring except that the substring is not copied; instead an indirect array (see indirect-array) is created which shares part of the argument string. Modifying one string will modify the other.

Note that nsubstring does not necessarily use less storage than substring; an nsubstring of any length uses the same amount of storage as a substring 12 characters long.

Function: string-append &rest strings ¶

Any number of strings are copied and concatenated into a single string. With a single argument, string-append simply copies it. If the first argument is an array, the result will be an array of the same type. Thus string-append can be used to copy and concatenate any type of 1-dimensional array.

Example:

(string-append 41 "foo" 41) => "!foo!"

Function: string-trim char-list string ¶

This returns a substring of string, with all characters in char-list stripped off of the beginning and end.

Example:

(string-trim '(40) "  Dr. No  ") => "Dr. No"

Function: string-left-trim char-list string ¶

This returns a substring of string, with all characters in char-list stripped off of the beginning.

Function: string-right-trim char-list string ¶

This returns a substring of string, with all characters in char-list stripped off of the end.

Function: char-upcase ch ¶

If ch, which must be a fixnum, is a lower-case alphabetic character its upper-case form is returned; otherwise, ch itself is returned. If font information is present it is preserved.

Function: char-downcase ch ¶

If ch, which must be a fixnum, is a upper-case alphabetic character its lower-case form is returned; otherwise, ch itself is returned. If font information is present it is preserved.

Function: string-upcase string ¶

Returns a copy of string, with all lower case alphabetic characters replaced by the corresponding upper case characters.

Function: string-downcase string ¶

Returns a copy of string, with all upper case alphabetic characters replaced by the corresponding lower case characters.

Function: string-reverse string ¶

Returns a copy of string with the order of characters reversed. This will reverse a 1-dimensional array of any type.

Function: string-nreverse string ¶

Returns string with the order of characters reversed, smashing the original string, rather than creating a new one. If string is a number, it is simply returned without consing up a string. This will reverse a 1-dimensional array of any type.

Function: string-search-char char string &optional (from 0) to ¶

string-search-char searches through string starting at the index from, which defaults to the beginning, and returns the index of the first character which is char-equal to char, or nil if none is found. If the to argument is supplied, it is used in place of (string-length string) to limit the extent of the search.

Example:

(string-search-char 101 "banana") => 1

Function: %string-search-char char string from to ¶

%string-search-char is the microcode primitive which string-search-char and other functions call. string must be an array and char, from, and to must be fixnums. Except for this lack of type-coercion, and the fact that none of the arguments is optional, %string-search-char is the same as string-search-char.

Function: string-search-not-char char string &optional (from 0) to ¶

string-search-not-char searches through string starting at the index from, which defaults to the beginning, and returns the index of the first character which is not char-equal to char, or nil if none is found. If the to argument is supplied, it is used in place of (string-length string) to limit the extent of the search.

Example:

(string-search-char 102 "banana") => 1

Function: string-search key string &optional (from 0) to ¶

string-search searches for the string key in the string string. The search begins at from, which defaults to the beginning of string. The value returned is the index of the first character of the first instance of key, or nil if none is found. If the to argument is supplied, it is used in place of (string-length string) to limit the extent of the search.

Example:

(string-search "an" "banana") => 1
(string-search "an" "banana" 2) => 3

Function: string-search-set char-list string &optional (from 0) to ¶

string-search-set searches through string looking for a character which is in char-list. The search begins at the index from, which defaults to the beginning. It returns the index of the first character which is char-equal to some element of char-list, or nil if none is found. If the to argument is supplied, it is used in place of (string-length string) to limit the extent of the search.

Example:

(string-search-set '(116 117) "banana") => 2

Function: string-search-not-set char-list string &optional (from 0) to ¶

string-search-not-set searches through string looking for a character which is not in char-list. The search begins at the index from, which defaults to the beginning. It returns the index of the first character which is not char-equal to any element of char-list, or nil if none is found. If the to argument is supplied, it is used in place of (string-length string) to limit the extent of the search.

Example:

(string-search-not-set '(141 142) "banana") => 2

Function: string-reverse-search-char char string &optional from (to 0) ¶

string-reverse-search-char searches through string in reverse order, starting from the index one less than from, which defaults to the length of string, and returns the index of the first character which is char-equal to char, or nil if none is found. Note that the index returned is from the beginning of the string, although the search starts from the end. If the to argument is supplied, it limits the extent of the search.

Example:

(string-reverse-search-char 156 "banana") => 4

Function: string-reverse-search-not-char char string &optional from (to 0) ¶

string-reverse-search-not-char searches through string in reverse order, starting from the index one less than from, which defaults to the length of string, and returns the index of the first character which is not char-equal to char, or nil if none is found. Note that the index returned is from the beginning of the string, although the search starts from the end. If the to argument is supplied, it limits the extent of the search.

Example:

(string-reverse-search-not-char 101 "banana") => 4

Function: string-reverse-search key string &optional from (to 0) ¶

string-reverse-search searches for the string key in the string string. The search proceeds in reverse order, starting from the index one less than from, which defaults to the length of string, and returns the index of the first (leftmost) character of the first instance found, or nil if none is found. Note that the index returned is from the beginning of the string, although the search starts from the end. The from condition, restated, is that the instance of key found is the rightmost one whose rightmost character is before the from’th character of string. If the to argument is supplied, it limits the extent of the search.

Example:

(string-reverse-search "na" "banana") => 4

Function: string-reverse-search-set char-list string &optional from (to 0) ¶

string-reverse-search-set searches through string in reverse order, starting from the index one less than from, which defaults to the length of string, and returns the index of the first character which is char-equal to some element of char-list, or nil if none is found. Note that the index returned is from the beginning of the string, although the search starts from the end. If the to argument is supplied, it limits the extent of the search.

(string-reverse-search-set '(141 142) "banana") => 5

Function: string-reverse-search-not-set char-list string &optional from (to 0) ¶

string-reverse-search-not-set searches through string in reverse order, starting from the index one less than from, which defaults to the length of string, and returns the index of the first character which is not char-equal to any element of char-list, or nil if none is found. Note that the index returned is from the beginning of the string, although the search starts from the end. If the to argument is supplied, it limits the extent of the search.

(string-reverse-search-not-set '(141 156) "banana") => 0

See also intern (intern-fun), which given a string will return "the" symbol with that print name.

8.2 I/O to Strings

The special forms in this section allow you to create I/O streams which input from or output to a string rather than a real I/O device. See streams for documentation of I/O streams.

Special Form: with-input-from-string ¶

The form

(with-input-from-string (var string)
    body)

evaluates the forms in body with the variable var bound to a stream which reads characters from the string which is the value of the form string. The value of the special form is the value of the last form in its body.

The stream is a "downward closure", so be careful what you do with it. You cannot use it after control leaves the body, and you cannot nest two with-input-from-string special forms and use both streams since the special-variable bindings associated with the stream will conflict. It is done this way to avoid any consing.

After string you may optionally specify two additional "arguments".

(with-input-from-string (var string index)
    body)

uses index as the starting index into the string, and updates it when it is done to the index of the first character not read (the length of the string if all of it was read.) Since index is updated it may not be a general expression; it must be a variable or a setf-able reference. The index is not updated in the event of an abnormal exit from the body, such as a *throw.

Use of the index feature prevents multiple values from being returned out of the body, currently.

(with-input-from-string (var string index limit)
    body)

uses the value of the form limit in place of the length of the string if it is not nil. If you want to specify a limit but not an index, put nil for index.

Special Form: with-output-to-string ¶

This special form provides a variety of ways to send output to a string through an i/o stream.

(with-output-to-string (var)
  body)

evaluates the forms in body with var bound to a stream which saves the characters output to it in a string. The value of the special form is the string.

(with-output-to-string (var string)
  body)

will append its output to the string which is the value of the form string. (This is like the string-nconc function.) The value returned is the value of the last form in the body, rather than the string. Multiple values are not returned. If string has an array-leader, element 0 of the array-leader will be used as the fill-pointer. If string is too small to contain all the output, adjust-array-size will be used to make it bigger.

(with-output-to-string (var string index)
  body)

is similar to the above except that index is a variable or setf-able reference which contains the index of the next character to be stored into. It must be initialized outside the with-output-to-string and will be updated upon normal exit.

The stream is a "downward closure", so be careful what you do with it. You cannot use it after control leaves the body, and you cannot nest two with-input-from-string special forms and use both streams since the special-variable bindings associated with the stream will conflict. It is done this way to avoid any consing.