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: when using a Lisp Machine, you get your own processor and memory system 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.

The Lisp Machine executes a new dialect of Lisp called Zetalisp, 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.

This document is the reference manual for the Zetalisp language. This document is not a tutorial, and it sometimes refers to functions and concepts that are not explained until later in the manual. It is assumed that you have a basic working knowledge of some Lisp dialect; you will be able to figure out the rest of the language from this manual.

There are also facilities explained in this manual that are not really part of the Lisp language. Some of these are subroutine packages of general use, and others are tools used in writing programs. However, the Lisp Machine window system, and the major utility programs, are not documented here.

1.2 Structure of the Manual

The manual starts out with an explanation of the language. Chapter object-chapter explains the different primitive types of Lisp object, and presents some basic predicate functions for testing types. Chapter evaluator-chapter explains the process of evaluation, which is the heart of the Lisp language. Chapter flow-chapter introduces the basic Lisp control structures.

The next several chapters explain the details of the various primitive data-types of the language, and the functions that deal with them. Chapter cons-chapter deals with conses and the higher-level structures that can be built out of them, such as trees, lists, association lists, and property lists. Chapter symbol-chapter deals with symbols, chapter number-chapter with the various kinds of numbers, and chapter array-chapter with arrays. Chapter string-chapter explains character strings, which are a special kind of array.

After this there are some chapters that explain more about functions, function-calling, and related matters. Chapter function-chapter presents all the kinds of functions in the language, explains function-specs, and tells how to manipulate definitions of functions. Chapters closure-chapter and stack-group-chapter discuss closures and stack-groups, two facilities useful for creating coroutines and other advanced control and access structures.

Next, a few lower-level issues are dealt with. Chapter locative-chapter explains locatives, which are a kind of pointer to memory cells. Chapter subprimitive-chapter explains the "subprimitive" functions, which are primarily useful for implementation of the Lisp language itself and the Lisp Machine’s "operating system". Chapter area-chapter discusses areas, which give you control over storage allocation and locality of reference.

Chapter compiler-chapter discusses the Lisp compiler, which converts Lisp programs into "machine language". Chapter macros-chapter explains the Lisp macro facility, which allows users to write their own extensions to Lisp, extending both the interpreter and the compiler. The next two chapters go into detail about two such extensions, one that provides a powerful iteration control structure (chapter loop-chapter), and one that provides a powerful data structure facility (chapter defstruct-chapter).

Chapter flavor-chapter documents flavors, a language facility to provide generic functions using the paradigm used in Smalltalk and the Actor families of languages, called "object-oriented programming" or "message passing". Flavors are widely used by the system programs of the Lisp Machine, as well as being available to the user as a language feature.

Chapter io-chapter explains the Lisp Machine’s Input/Output system, including streams and the printed representation of Lisp objects. Chapter pathname-chapter documents how to deal with pathnames (the names of files).

Chapter package-chapter describes the package system, which allows many name spaces within a single Lisp environment. Chapter system-chapter documents the "system" facility, which helps you create and maintain programs that reside in many files.

Chapter process-chapter discusses the facilities for multiple processes and how to write programs that use concurrent computation. Chapter error-chapter explains how exceptional conditions (errors) can be handled by programs, handled by users, and debugged. Chapter code-chapter explains the instruction set of the Lisp Machine, and tells you how to examine the output of the compiler. Chapter query-chapter documents some functions for querying the user, chapter time-chapter explains some functions for manipulating dates and times, and chapter misc-chapter 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 to avoid confusion. This section explains those conventions.

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

The symbol "==>" will be used to indicate macro expansion in examples. This, when you see "(foo bar) ==> (aref bar 0)", this means the same thing as "the result of macro-expanding (foo bar) is (or would have been) (aref bar 0)".

A typical description of a Lisp function looks like this:

Function: function-name arg1 arg2 &optional arg3 (arg4 (foo 3)) ¶

The function-name function adds together arg1 and arg2, and then multiplies the result by arg3. If arg3 is not provided, the multiplication isn’t done. function-name then returns a list whose first element is this result and whose second element is arg4. Examples:

(function-name 3 4) => (7 4)
(function-name 1 2 2 'bar) => (6 bar)

Note the use of fonts (typefaces). The name of the function is in bold-face in the first line of the description, and the arguments are in italics. Within the text, printed representations of Lisp objects are in a different bold-face font, such as (+ foo 56), and argument references are italicized, such as arg1 and arg2. A different, fixed-width font, such as function-name, is used for Lisp examples that are set off from the text.

The word "&optional" in the list of arguments tells you that all of the arguments past this point are optional. The default value can be specified explicitly, as with arg4 whose default value is the result of evaluating the form (foo 3). If no default value is specified, it is the symbol nil. This syntax is used in lambda-lists in the language, which are explained in lambda-list. Argument lists may also contain "&rest", which is part of the same syntax.

The descriptions of special forms and macros look like this:

Special Form: do-three-times form ¶

This evaluates form three times and returns the result of the third evaluation.

Macro: with-foo-bound-to-nil form... ¶

This evaluates the forms with the symbol foo bound to nil. It expands as follows:

(with-foo-bound-to-nil
    form1
    form2 ...) ==>
(let ((foo nil))
    form1
    form2 ...)

Since special forms and macros are the mechanism by which the syntax of Lisp is extended, their descriptions must describe both their syntax and their semantics; functions follow a simple consistent set of rules, but each special form is idiosyncratic. The syntax is displayed on the first line of the description using the following conventions. Italicized words are names of parts of the form which are referred to in the descriptive text. They are not arguments, even though they resemble the italicized words in the first line of a function description. Parentheses ("( )") stand for themselves. Square brackets ("[ ]") indicate that what they enclose is optional. Ellipses ("...") indicate that the subform (italicized word or parenthesized list) which precedes them may be repeated any number of times (possibly no times at all). Curly brackets followed by ellipses ("{ }...") indicate that what they enclose may be repeated any number of times. Thus the first line of the description of a special form is a "template" for what an instance of that special form would look like, with the surrounding parentheses removed. The syntax of some special forms is sufficiently complicated that it does not fit comfortably into this style; the first line of the description of such a special form contains only the name, and the syntax is given by example in the body of the description.

The semantics of a special form includes not only what it "does for a living", but also which subforms are evaluated and what the returned value is. Usually this will be clarified with one or more examples.

A convention used by many special forms is that all of their subforms after the first few are described as "body...". This means that the remaining subforms constitute the "body" of this special form; they are Lisp forms which are evaluated one after another in some environment established by the special form.

This ridiculous special form exhibits all of the syntactic features:

Special Form: twiddle-frob [(frob option...)] parameter value... ¶

This twiddles the parameters of frob, which defaults to default-frob if not specified. Each parameter is the name of one of the adjustable parameters of a frob; each value is what value to set that parameter to. Any number of parameter/value pairs may be specified. If any options are specified, they are keywords which select which safety checks to override while twiddling the parameters. If neither frob nor any options are specified, the list of them may be omitted and the form may begin directly with the first parameter name.

frob and the values are evaluated; the parameters and options are syntactic keywords and not evaluated. The returned value is the frob whose parameters were adjusted. An error is signalled if any safety checks are violated.

Methods, the message-passing equivalent of ordinary Lisp’s functions, are described in this style:

Method on flavor-name: message-name arg1 arg2 &optional arg3 ¶

This is the documentation of the effect of sending a message named message-name, with arguments arg1, arg2, and arg3, to an instance of flavor flavor-name.

Descriptions of variables ("special" or "global" variables) look like this:

Variable: typical-variable ¶

The variable typical-variable has a typical value....

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, Zetalisp types out numbers in base 8; don’t be surprised by this. If you wish to change it, see the documentation on the variables ibase and base (ibase-var).

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 terms "list" and "tree" are defined in list-and-tree.

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

"

Double-quote delimits character strings.

#

Number-sign introduces miscellaneous reader macros.

`

Backquote is used to construct list structure.

,

Comma is used in conjunction with backquote.

:

Colon is the package prefix.

|

Characters between pairs of vertical-bars are quoted.

circleX

Circle-cross lets you type in characters using their octal codes.

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.

You will see various symbols that have the colon (:) character in their names. 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. So, when you print such a symbol, you won’t see the colon if the current package is user. However, you should always type in the colons where the manual tells you to. This is all explained in chapter package-chapter; until you read that, just make believe that the colons are part of the names of the symbols, and don’t worry that they sometimes don’t get printed out for keyword symbols.

This manual documents a number of internal functions and variables, which can be identified by the "si:" prefix in their names. The "si" stands for "system internals". These functions and variables are documented here because they are things you sometimes need to know about. However, they are considered internal to the system and their behavior is not as guaranteed as that of everything else. They may be changed in the future.

Zetalisp is descended from Maclisp, and a good deal of effort was expended to try to allow Maclisp programs to run in Zetalisp. Throughout the manual, there are notes about differences between the dialects. 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 full 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. (This number should not be built into any programs.)

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 ASCII, 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 in chapter area-chapter.

2.1 Data Types

This section enumerates some of the various different primitive types of objects in Zetalisp. The types explained below include symbols, conses, various types of numbers, two kinds of compiled code objects, 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. Each symbol has a binding (sometimes also called the "value"), which may be any Lisp 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.) Each symbol has a definition, which 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), although usually the functions fdefinition and fdefine are employed (fdefine-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 own 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 (chapter package-chapter) and can be disregarded by the casual user.

The primitive function for creating symbols is make-symbol (make-symbol-fun), although most symbols are created by read, intern, or fasload (which 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 Zetalisp. Fixnums represent integers in the range of -2^23 to 2^23-1. Bignums represent integers of arbitrary size, but they are more expensive to use than fixnums because they occupy storage and are slower. 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 of these types and the conversions between them.

The usual form of compiled, executable 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 any of these compiled code 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 memory cell anywhere in the system. The contents of this cell can be accessed by cdr (see cdr-fun) and updated by rplacd (see rplacd-fun).

An array (see array) is a set of cells indexed by a tuple of integer subscripts. The contents of the 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 unsigned numbers which encode characters.

A list is not a primitive data type, but rather a data structure made up out of conses and the symbol nil. See list-and-tree.

2.2 Predicates

A predicate is a function which tests for some condition involving its arguments and returns the symbol t if the condition is true, or the symbol nil if it is not true. Most of the following predicates are for testing what data type an object has; some other general-purpose predicates are also explained.

By convention, the names of predicates usually end in the letter "p" (which stands for "predicate").

The following predicates are for testing data types. These predicates return t if the argument is of the type indicated by the name of the function, nil if it is of some other type.

Function: symbolp arg ¶

symbolp returns t if its argument is a symbol, otherwise nil.

Function: nsymbolp arg ¶

nsymbolp returns nil if its argument is a symbol, otherwise t.

Function: listp arg ¶

listp returns t if its argument is a cons, otherwise nil. Note that this means (listp nil) is nil even though nil is the empty list. [This may be changed in the future.]

Function: nlistp arg ¶

nlistp returns t if its argument is anything besides a cons, otherwise nil. nlistp is identical to atom, and so (nlistp nil) returns t. [This may be changed in the future, if and when listp is changed.]

Function: atom arg ¶

The predicate atom returns t if its argument is not a cons, otherwise nil.

Function: numberp arg ¶

numberp returns t if its argument is any kind of number, otherwise nil.

Function: fixp arg ¶

fixp returns t if its argument is a fixed-point number, i.e a fixnum or a bignum, otherwise nil.

Function: floatp arg ¶

floatp returns t if its argument is a floating-point number, i.e a flonum or a small flonum, otherwise nil.

Function: fixnump arg ¶

fixnump returns t if its argument is a fixnum, otherwise nil.

Function: bigp arg ¶

bigp returns t if arg is a bignum, otherwise nil.

Function: flonump arg ¶

flonump returns t if arg is a (large) flonum, otherwise nil.

Function: small-floatp arg ¶

small-floatp returns t if arg is a small flonum, otherwise nil.

Function: stringp arg ¶

stringp returns t if its argument is a string, otherwise nil.

Function: arrayp arg ¶

arrayp returns t if its argument is an array, otherwise nil. Note that strings are arrays.

Function: functionp arg &optional allow-special-forms ¶

functionp returns t if its argument is a function (essentially, something that is acceptable as the first argument to apply), otherwise it returns nil. In addition to interpreted, compiled, and microcoded functions, functionp is true of closures, select-methods (see select-method), and symbols whose function definition is functionp. functionp is not true of objects which can be called as functions but are not normally thought of as functions: arrays, stack groups, entities, and instances. If allow-special-forms is specified and non-nil, then functionp will be true of macros and special-form functions (those with quoted arguments). Normally functionp returns nil for these since they do not behave like functions. As a special case, functionp of a symbol whose function definition is an array returns t, because in this case the array is being used as a function rather than as an object.

Function: subrp arg ¶

subrp returns t if its argument is any compiled code object, otherwise nil. The Lisp Machine system doesn’t use the term "subr", but the name of this function comes from Maclisp.

Function: closurep arg ¶

closurep returns t if its argument is a closure, otherwise nil.

Function: entityp arg ¶

entityp returns t if its argument is an entity, otherwise nil. See entity for information about "entities".

Function: locativep arg ¶

locativep returns t if its argument is a locative, otherwise nil.

Function: typep arg &optional type ¶

typep is really two different functions. With one argument, typep is not really a predicate; it returns a symbol describing the type of its argument. With two arguments, typep is a predicate which returns t if arg is of type type, and nil otherwise. Note that an object can be "of" more than one type, since one type can be a subset of another.

The symbols that can be returned by typep of one argument are:

:symbol

arg is a symbol.

:fixnum

arg is a fixnum (not a bignum).

:bignum

arg is a bignum.

:flonum

arg is a flonum (not a small-flonum).

:small-flonum

arg is a small flonum.

:list

arg is a cons.

:locative

arg is a locative pointer (see locative).

:compiled-function

arg is the machine code for a compiled function (sometimes called a FEF).

:microcode-function

arg is a function written in microcode.

:closure

arg is a closure (see closure).

:select-method

arg is a select-method table (see select-method).

:stack-group

arg is a stack-group (see stack-group).

:string

arg is a string.

:array

arg is an array that is not a string.

:random

Returned for any built-in data type that does not fit into one of the above categories.

foo

An object of user-defined data type foo (any symbol). The primitive type of the object could be array, instance, or entity. See Named Structures, named-structure, and Flavors, flavor.

The type argument to typep of two arguments can be any of the above keyword symbols (except for :random), the name of a user-defined data type (either a named structure or a flavor), or one of the following additional symbols:

:atom

Any atom (as determined by the atom predicate).

:fix

Any kind of fixed-point number (fixnum or bignum).

:float

Any kind of floating-point number (flonum or small-flonum).

:number

Any kind of number.

:instance

An instance of any flavor. See flavor.

:entity

An entity. typep of one argument returns the name of the particular user-defined type of the entity, rather than :entity.

See also data-type, data-type-fun.

Note that (typep nil) => :symbol, and (typep nil ':list) => nil; the latter may be changed.

The following functions are some other general purpose predicates.

Function: eq x y ¶

(eq x y) => t if and only if x and y are the same object. It should be noted that things that print the same are not necessarily eq to each other. In particular, numbers with the same value need not be eq, and two similar lists are usually not eq.

Examples:

(eq 'a 'b) => nil
(eq 'a 'a) => t
(eq (cons 'a 'b) (cons 'a 'b)) => nil
(setq x (cons 'a 'b)) (eq x x) => t

Note that in Zetalisp equal fixnums are eq; this is not true in Maclisp. Equality does not imply eq-ness for other types of numbers. To compare numbers, use =; see =-fun.

Function: neq x y ¶

(neq x y) = (not (eq x y)). This is provided simply as an abbreviation for typing convenience.

Function: equal x y ¶

The equal predicate returns t if its arguments are similar (isomorphic) objects. (cf eq) Two numbers are equal if they have the same value and type (for example, a flonum is never equal to a fixnum, even if = is true of them). For conses, equal is defined recursively as the two car’s being equal and the two cdr’s being equal. Two strings are equal if they have the same length, and the characters composing them are the same; see string-equal, string-equal-fun. Alphabetic case is ignored (but see alphabetic-case-affects-string-comparison, alphabetic-case-affects-string-comparison-var). All other objects are equal if and only if they are eq. Thus equal could have been defined by:

(defun equal (x y)
  (cond ((eq x y) t)
	((neq (typep x) (typep y)) nil)
	((numberp x) (= x y))
	((stringp x) (string-equal x y))
	((listp x) (and (equal (car x) (car y))
			(equal (cdr x) (cdr y))))))

As a consequence of the above definition, it can be seen that equal may compute forever when applied to looped list structure. In addition, eq always implies equal; that is, if (eq a b) then (equal a b). An intuitive definition of equal (which is not quite correct) is that two objects are equal if they look the same when printed out. For example:

(setq a '(1 2 3))
(setq b '(1 2 3))
(eq a b) => nil
(equal a b) => t
(equal "Foo" "foo") => t

Function: not x ¶

Function: null x ¶

not returns t if x is nil, else nil. null is the same as not; both functions are included for the sake of clarity. Use null to check whether something is nil; use not to invert the sense of a logical value. Even though Lisp uses the symbol nil to represent falseness, you shouldn’t make understanding of your program depend on this fortuitously. For example, one often writes:

(cond ((not (null lst)) ... )
      ( ... ))
rather than
(cond (lst ... )
      ( ... ))

There is no loss of efficiency, since these will compile into exactly the same instructions.

3.1 Variables

In Zetalisp, variables are implemented using symbols. Symbols are used for many things in the language, such as naming functions, naming special forms, and being keywords; they are also useful to programs written in Lisp, as parts of data structures. But when the evaluator is given a symbol, it treats it as a variable, using the value cell to hold the value of the variable. If you evaluate a symbol, you get back the contents of the symbol’s value cell.

There are two different ways of changing the value of a variable. One is to set the variable. Setting a variable changes its value to a new Lisp object, and the previous value of the variable is forgotten. Setting of variables is usually done with the setq special form.

The other way to change the value of a variable is with binding (also called "lambda-binding"). When a variable is bound, its old value is first saved away, and then the value of the variable is made to be the new Lisp object. When the binding is undone, the saved value is restored to be the value of the variable. Bindings are always followed by unbindings. The way this is enforced is that binding is only done by special forms that are defined to bind some variables, then evaluate some subforms, and then unbind those variables. So the variables are all unbound when the form is finished. This means that the evaluation of the form doesn’t disturb the values of the variables that are bound; whatever their old value was, before the evaluation of the form, gets restored when the evaluation of the form is completed. If such a form is exited by a non-local exit of any kind, such as *throw (see *throw-fun) or return (see return-fun), the bindings are undone whenever the form is exited.

The simplest construct for binding variables is the let special form. The do and prog special forms can also bind variables, in the same way let does, but they also control the flow of the program and so are explained elsewhere (see do-fun). let* is just a sequential version of let; the other special forms below are only used for esoteric purposes.

Binding is an important part of the process of applying interpreted functions to arguments. This is explained in the next section.

When a Lisp function is compiled, the compiler understands the use of symbols as variables. However, the compiled code generated by the compiler does not actually use symbols to represent variables. Rather, the compiler converts the references to variables within the program into more efficient references, that do not involve symbols at all. A variable that has been changed by the compiler so that it is not implemented as a symbol is called a "local" variable. When a local variable is bound, a memory cell is allocated in a hidden, internal place (the Lisp control stack) and the value of the variable is stored in this cell. You cannot use a local variable without first binding it; you can only use a local variable inside of a special form that binds that variable. Local variables do not have any "top level" value; they do not even exist outside of the form that binds them.

The variables which are associated with symbols (the kind which are used by non-compiled programs) are called "special" variables.

Local variables and special variables do not behave quite the same way, because "binding" means different things for the two of them. Binding a special variable saves the old value away and then uses the value cell of the symbol to hold the new value, as explained above. Binding a local variable, however, does not do anything to the symbol. In fact, it creates a new memory cell to hold the value, i.e a new local variable.

Thus, if you compile a function, it may do different things after it has been compiled. Here is an example:

(setq a 2)	      ;Set the variable a to the value 2.

(defun foo ()	      ;Define a function named foo.
  (let ((a 5))	      ;Bind the symbol a to the value 5.
    (bar)))	      ;Call the function bar.

(defun bar ()	      ;Define a function named bar.
  a)		      ;It just returns the value of the variable a.

(foo) => 5	      ;Calling foo returns 5.

(compile 'foo)	      ;Now compile foo.

(foo) => 2	      ;This time, calling foo returns 2.

This is a very bad thing, because the compiler is only supposed to speed things up, without changing what the function does. Why did the function foo do something different when it was compiled? Because a was converted from a special variable into a local variable. After foo was compiled, it no longer had any effect on the value cell of the symbol a, and so the symbol retained its old contents, namely 2.

In most uses of variables in Lisp programs, this problem doesn’t come up. The reason it happened here is because the function bar refers to the symbol a without first binding a to anything. A reference to a variable that you didn’t bind yourself is called a free reference; in this example, bar makes a free reference to a.

We mentioned above that you can’t use a local variable without first binding it. Another way to say this is that you can’t ever have a free reference to a local variable. If you try to do so, the compiler will complain. In order for our functions to work, the compiler must be told not to convert a into a local variable; a must remain a special variable. Normally, when a function is compiled, all variables in it are made to be "local". You can stop the compiler from making a variable local by "declaring" to the compiler that the variable is "special". When the compiler sees references to a variable that has been declared special, it uses the symbol itself as the variable instead of making a local variable.

Variables can be declared by the special forms defvar and defconst (see below), or by explicit compiler declarations (see special-fun). The most common use of special variables is as "global" variables: variables used by many different functions throughout a program, that have top-level values.

Had bar been compiled, the compiler would have seen the free reference and printed a warning message: Warning: a declared special. It would have automatically declared a to be special and proceeded with the compilation. It knows that free references mean that special declarations are needed. But when a function is compiled that binds a variable that you want to be treated as a special variable but that you have not explicitly declared, there is, in general, no way for the compiler to automatically detect what has happened, and it will produce incorrect output. So you must always provide declarations for all variables that you want to be treated as special variables.

When you declare a variable to be special using declare rather than local-declare, the declaration is "global"; that is, it applies wherever that variable name is seen. After fuzz has been declared special using declare, all following uses of fuzz will be treated by the compiler as references to the same special variable. Such variables are called "global variables", because any function can use them; their scope is not limited to one function. The special forms defvar and defconst are useful for creating global variables; not only do they declare the variable special, but they also provide a place to specify its initial value, and a place to add documentation. In addition, since the names of these special forms start with "def" and since they are used at the top-level of files, the Lisp Machine editor can find them easily.

Here are the special forms used for setting variables.

Special Form: setq variable value... ¶

The setq special form is used to set the value of a variable or of many variables. The first value is evaluated, and the first variable is set to the result. Then the second value is evaluated, the second variable is set to the result, and so on for all the variable/value pairs. setq returns the last value, i.e the result of the evaluation of its last subform.

Example:

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

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

Special Form: psetq variable value... ¶

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

Example:

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

Here are the special forms used for binding variables.

Special Form: let ((var value)...) body... ¶

let is used to bind some variables to some objects, and evaluate some forms (the "body") in the context of those bindings. A let form looks like

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

When this form is evaluated, first the vforms (the values) are evaluated. Then the vars are bound to the values returned by the corresponding vforms. Thus the bindings happen in parallel; all the vforms are evaluated before any of the vars are bound. Finally, the bforms (the body) are evaluated sequentially, the old values of the variables are restored, and the result of the last bform is returned.

You may omit the vform from a let clause, in which case it is as if the vform were nil: the variable is bound to nil. Furthermore, you may replace the entire clause (the list of the variable and form) with just the variable, which also means that the variable gets bound to nil. Example:

(let ((a (+ 3 3))
      (b 'foo)
      (c)
      d)
  ...)

Within the body, a is bound to 6, b is bound to foo, c is bound to nil, and d is bound to nil.

Special Form: let* ((var value)...) body... ¶

let* is the same as let except that the binding is sequential. Each var is bound to the value of its vform before the next vform is evaluated. This is useful when the computation of a vform depends on the value of a variable bound in an earlier vform. Example:

(let* ((a (+ 1 2))
       (b (+ a a)))
 ...)

Within the body, a is bound to 3 and b is bound to 6.

Special Form: let-if condition ((var value)...) body... ¶

let-if is a variant of let in which the binding of variables is conditional. The variables must all be special variables. The let-if special form, typically written as

(let-if cond
	((var-1 val-1) (var-2 val-2)...)
  body-form1 body-form2...)

first evaluates the predicate form cond. If the result is non-nil, the value forms val-1, val-2, etc are evaluated and then the variables var-1, var-2, etc are bound to them. If the result is nil, the vars and vals are ignored. Finally the body forms are evaluated.

Special Form: let-globally ((var value)...) body... ¶

let-globally is similar in form to let (see let-fun). The difference is that let-globally does not bind the variables; instead, it saves the old values and sets the variables, 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) co-calls some other stack group, the old values of the variables are not restored. Thus let-globally makes the new values visible in all stack groups and processes that don’t bind the variables themselves, not just the current stack group.

Special Form: progv symbol-list value-list body... ¶

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

progv first evaluates symbol-list and value-list, and then binds each symbol to the corresponding value. 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 body forms are evaluated, and finally the symbols’ bindings are undone. The result returned is the value of the last form in the body.

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 retains its top-level value foo.

Special Form: progw vars-and-vals-form body... ¶

progw is a somewhat modified kind of progv. Like progv, it only works for special variables. First, vars-and-val-forms-form is evaluated. Its value should be a list that looks like the first subform of a let:

  ((var1 val-form-1)
   (var2 val-form-2)
   ...)

Each element of this list is processed in turn, by evaluating the val-form, and binding the var to the resulting value. Finally, the body forms are evaluated sequentially, the bindings are undone, and the result of the last form is returned. Note that the bindings are sequential, not parallel.

This is a very unusual special form because of the way the evaluator is called on the result of an evaluation. Thus progw is mainly useful for implementing special forms and for functions part of whose contract is that they call the interpreter. For an example of the latter, see sys:*break-bindings* (sys:*break-bindings*-var); break implements this by using progw.

Here are the special forms for defining special variables.

Special Form: defvar variable [initial-value] [documentation] ¶

defvar is the recommended way to declare the use of a global variable in a program. Placed at top level in a file,

(defvar variable)

declares variable special for the sake of compilation, and records its location for the sake of the editor so that you can ask to see where the variable is defined. If a second subform is supplied,

(defvar variable initial-value)

variable is initialized to the result of evaluating the form initial-value unless it already has a value, in which case it keeps that value. initial-value is not evaluated unless it is used; this is useful if it does something expensive like creating a large data structure.

defvar should be used only at top level, never in function definitions, and only for global variables (those used by more than one function). (defvar foo 'bar) is roughly equivalent to

(declare (special foo))
(if (not (boundp 'foo))
    (setq foo 'bar))

(defvar variable initial-value documentation)

allows you to include a documentation string which describes what the variable is for or how it is to be used. Using such a documentation string is even better than commenting the use of the variable, because the documentation string is accessible to system programs that can show the documentation to you while you are using the machine.

If defvar is used in a patch file (see patch-facility) or is a single form (not a region) evaluated with the editor’s compile/evaluate from buffer commands, if there is an initial-value the variable is always set to it regardless of whether it is already bound.

Special Form: defconst variable [initial-value] [documentation] ¶

defconst is the same as defvar except that if an initial value is given the variable is always set to it regardless of whether it is already bound. The rationale for this is that defvar declares a global variable, whose value is initialized to something but will then be changed by the functions that use it to maintain some state. On the other hand, defconst declares a constant, whose value will never be changed by the normal operation of the program, only by changes to the program. defconst always sets the variable to the specified value so that if, while developing or debugging the program, you change your mind about what the constant value should be, and then you evaluate the defconst form again, the variable will get the new value. It is not the intent of defconst to declare that the value of variable will never change; for example, defconst is not license to the compiler to build assumptions about the value of variable into programs being compiled.

3.2 Functions

In the description of evaluation on description-of-evaluation, we said that evaluation of a function form works by applying the function to the results of evaluating the argument subforms. What is a function, and what does it mean to apply it? In Zetalisp there are many kinds of functions, and applying them may do many different kinds of things. For full details, see function-functions. Here we will explain the most basic kinds of functions and how they work. In particular, this section explains lambda lists and all their important features.

The simplest kind of user-defined function is the lambda-expression, which is a list that looks like:

(lambda lambda-list body1 body2...)

The first element of the lambda-expression is the symbol lambda; the second element is a list called the lambda list, and the rest of the elements are called the body. The lambda list, in its simplest form, is just a list of variables. Assuming that this simple form is being used, here is what happens when a lambda expression is applied to some arguments. First, the number of arguments and the number of variables in the lambda list must be the same, or else an error is signalled. Each variable is bound to the corresponding argument value. Then the forms of the body are evaluated sequentially. After this, the bindings are all undone, and the value of the last form in the body is returned.

This may sound something like the description of let, above. The most important difference is that the lambda-expression is not a form at all; if you try to evaluate a lambda-expression, you will get told that lambda is not a defined function. The lambda-expression is a function, not a form. A let form gets evaluated, and the values to which the variables are bound come from the evaluation of some subforms inside the let form; a lambda-expression gets applied, and the values are the arguments to which it is applied.

The variables in the lambda list are sometimes called parameters, by analogy with other languages. Some other terminologies would refer to these as formal parameters, and to arguments as actual parameters.

Lambda lists can have more complex structure than simply being a list of variables. There are additional features accessible by using certain keywords (which start with &) and/or lists as elements of the lambda list.

The principal weakness of the simple lambda lists is that any function written with one must only take a certain, fixed number of arguments. As we know, many very useful functions, such as list, append, +, and so on, accept 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, Zetalisp supports lexprs, but they should not be used in new programs). Simple lambda lists also require that arguments be matched with parameters by their position in the sequence. This makes calls hard to read when there are a great many arguments. Keyword parameters enable the use of other styles of call which are more readable.

In general, a function in Zetalisp has zero or more positional parameters, followed if desired by a single rest parameter, followed by zero or more keyword parameters. The positional and keyword parameters may be required or optional, but all the optional parameters must follow all the required ones. The required/optional distinction does not apply to the rest parameter.

The caller must provide enough arguments so that each of the required parameters gets bound, but he may provide extra arguments, for some 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. Optional parameters may have a default-form, which is a form to be evaluated to produce the default value for the parameter if no argument is supplied.

Positional parameters are matched with arguments by the position of the arguments in the argument list. Keyword parameters are matched with their arguments by matching the keyword name; the arguments need not appear in the same order as the parameters. If an optional positional argument is omitted, then no further arguments can be present. Keyword parameters allow the caller to decide independently for each one whether to specify it. Here is the exact explanation of how this all works. When apply (the primitive function that applies functions to arguments) matches up the arguments with the parameters, it follows the following algorithm: The positional parameters are dealt with first. The first required positional parameter is bound to the first argument. apply continues to bind successive required positional parameters to the successive arguments. If, during this process, there are no arguments left but there are still some required parameters (positional or keyword) which have not been bound yet, it is an error ("too few arguments"). Next, after all required parameters are handled, apply continues with the optional positional parameters, if any. It binds successive parameter to the next argument. 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. Now, if there are no remaining parameters (rest or keyword), and there are no remaining arguments, we are finished. If there are no more parameters but there are still some arguments remaining, an error is caused ("too many arguments"). If parameters remain, all the remaining arguments are used for both the rest parameter, if any, and the keyword parameters.

First, if there is a rest parameter, it is bound to a list of all the remaining arguments. If there are no remaining arguments, it gets bound to nil. If there are keyword parameters, the same remaining arguments are used to bind them, as follows. The arguments for the keyword parameters are treated as a list of alternating keyword symbols and associated values. Each symbol is matched with the keyword parameter names, and the matching keyword paramater is bound to the value which follows the symbol. All the remaining arguments are treated in this way. Since the arguments are usually obtained by evaluation, those arguments which are keyword symbols are typically quoted in the call; but they do not have to be. The keyword symbols are compared by means of eq, which means they must be specified in the correct package. The keyword symbol for a parameter has the same print name as the parameter, but resides in the keyword package regardless of what package the parameter name itself resides in. (You can specify the keyword symbol explicitly in the lambda list if you must; see below). If any keyword parameter has not received a value when all the arguments have been processed, this is an error if the parameter is required. If it is optional, the default-form for the parameter is evaluated and the parameter is bound to its value. There may be a keyword symbol among the arguments which does not match any keyword parameter name. The function itself specifies whether this is an error. If it is not an error, then the non-matching symbols and their associated values are ignored. The function can access these symbols and values through the rest parameter, if there is one. It is common for a function to check only for certain keywords, and pass its rest parameter to another function using lexpr-funcall; then that function will check for the keywords that concern it. 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 &key, &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 positional, rest or keyword; and required or optional.

(a b c)

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

(a b &optional c)

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

(&optional a b c)

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

(&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 positional, c and d are optional positional, and e is rest. The function may be passed two or more arguments.

(&key a b)

a and b are both required keyword parameters. A typical call would look like

(foo ':b 69 ':a '(some elements))

This illustrates that the parameters can be matched in either order.

(&key a &optional b)

a is required keyword, and b is optional keyword. The sample call above would be legal for this function also; so would

(foo ':a '(some elements))

which doesn’t specify b.

(x &optional y &rest z &key a b)

x is required positional, y is optional positional, z is rest, and a and b are optional keyword. One or more arguments are allowed. One or two arguments specify only the positional parameters. Arguments beyond the second specify both the rest parameter and the keyword parameters, so that

(foo 1 2 ':b '(a list))

specifies 1 for x, 2 for y, (:b (a list)) for z, and (a list) for b. It does not specify a.

(&rest z &key a b c &allow-other-keys)

z is rest, and a, b and c are optional keyword parameters. &allow-other-keys says that absolutely any keyword symbols may appear among the arguments; these symbols and the values that follow them have no effect on the keyword parameters, but do become part of the value of z.

(&rest z &key &allow-other-keys)

This is equivalent to (&rest z). So, for that matter, is the previous example, if the function does not use the values of a, b and c.

In all of the cases above, the default-form for each optional parameter is 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. Only optional parameters may have default forms; required parameters are never defaulted, and rest parameters always default to nil. 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) &rest d &key b (c (symeval a)))

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.

For a keyword parameter, you normally specify the variable name, and the keyword proper is usually computed from it. You can specify the keyword symbol independently if you need to. To do this, use a two-level list instead of a symbol: ((keyword variable)). The top level of list can also contain an default value and supplied-p variable, for optional arguments.

(&key ((foo:a a)) ((foo:b b)))

The function with this argument list will accept two keywords foo:a and foo:b, which will set variables a and b.

Occasionally it is important to know whether a certain optional parameter was defaulted or not. You can’t tell from just examining its value, since if the value is the default value, there’s no way to tell whether the caller passed that value explicitly, or whether the caller didn’t pass any value and the parameter was defaulted. The way to tell for sure is to put a third element into the list: the third element should be a variable (a symbol), and that variable is bound to nil if the parameter was not passed by the caller (and so was defaulted), or t if the parameter was passed. The new variable is called a "supplied-p" variable; it is bound to t if the parameter is supplied. For example:

(a &optional (b 3 c))

The default-form for b is 3, and the "supplied-p" variable for b is c. If the function is called with one argument, b will be bound to 3 and c will be bound to nil. If the function is called with two arguments, b will be bound to the value that was passed by the caller (which might be 3), and c will be bound to t.

It is possible to specify a keyword parameter’s symbol independently of its parameter name. To do this, use two nested lists to specify the parameter. The outer list is the one which can contain the default-form and supplied-p variable, if the parameter is optional. The first element of this list, instead of a symbol, is again a list, whose elements are the keyword symbol and the parameter variable name. For example:

(&key ((:a a)) &optional ((:b b) t))

This is equivalent to (&key a &optional (b t)).

(&key ((:base base-value)))

This allows a keyword which the user will know under the name :base, without making the parameter shadow the value of base, which is used for printing numbers.

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 just get bound, as if they appeared in a let form. (Whether you use these aux-variables or bind the variables with let is a stylistic decision.) 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 not guaranteed to be a "real" list. 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 copylist, page copylist-fun), as you must always assume that it is one of these special lists. 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, since lists in the stack are impossible to rplacd.

There are some other keywords in addition to those mentioned here. See lambda-list-keywords for a complete list. You only need to know about &optional and &rest in order to understand this manual.

Lambda lists provide "positional" arguments: the meaning of an argument comes from its position in the lambda list. For example, the first argument to cons is the object that will be the car of the new cons. Sometimes it is desirable to use "keyword" arguments, in which the meaning of an argument comes from a "keyword" symbol that tells the callee which argument this is. While lambda lists do not provide keyword arguments directly, there is a convention for functions that want arguments passed to them in the keyword fashion. The convention is that the function takes a rest-argument, whose value is a list of alternating keyword symbols and argument values. If cons were written as a keyword-style function, then instead of saying

(cons 4 (foo))

you could say either of

(cons ':car 4 ':cdr (foo))
or
(cons ':cdr (foo) ':car 4)

assuming the keyword symbols were :car and :cdr. Keyword symbols are always in the keyword package, and so their printed representations always start with a colon; the reason for this is given in chapter package-chapter.

This use of keyword arguments is only a convention; it is not built into the function-calling mechanism of the language. Your function must contain Lisp programming to take apart the rest parameter and make sense of the keywords and values. The special form keyword-extract (see keyword-extract-fun) may be useful for this.

3.3 Some Functions and Special Forms

This section describes some functions and special forms. Some are parts of the evaluator, or closely related to it. Some have to do specifically with issues discussed above such as keyword arguments. Some are just fundamental Lisp forms that are very important.

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 (see symeval-fun). 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 Zetalisp. They are replaced by Closures (see closure).

Function: apply f arglist ¶

(apply f arglist) applies the function f to the list of arguments arglist. arglist should be a list; f can be any function.

Examples:

(setq fred '+) (apply fred '(1 2)) => 3
(setq fred '-) (apply fred '(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 Zetalisp.

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

This shows that the use of the symbol cons as the name of a function and the use of that symbol as the name of a variable do not interact. The cons form invokes the function named cons. The funcall form evaluates the variable and gets the symbol plus, which is the name of a different function.

Function: lexpr-funcall f &rest args ¶

lexpr-funcall is like a cross between apply and funcall. (lexpr-funcall f a1 a2 ... an l) applies the function f to the arguments a1 through an followed by the elements of the list l. Note that since it treats its last argument specially, lexpr-funcall requires at least two arguments.

Examples:

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

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

lexpr-funcall with two arguments does the same thing as apply.

Note: the Maclisp functions subrcall, lsubrcall, and arraycall are not needed on the Lisp Machine; funcall is just as efficient. arraycall is provided for compatibility; it ignores its first subform (the Maclisp array type) and is otherwise identical to aref. subrcall and lsubrcall are not provided.

Function: call function &rest argument-specifications ¶

call offers a very general way of controlling what arguments you pass to a function. You can provide either individual arguments a la funcall or lists of arguments a la apply, in any order. In addition, you can make some of the arguments optional. If the function is not prepared to accept all the arguments you specify, no error occurs if the excess arguments are optional ones. Instead, the excess arguments are simply not passed to the function.

The argument-specs are alternating keywords (or lists of keywords) and values. Each keyword or list of keywords says what to do with the value that follows. If a value happens to require no keywords, provide () as a list of keywords for it.

Two keywords are presently defined: :optional and :spread. :spread says that the following value is a list of arguments. Otherwise it is a single argument. :optional says that all the following arguments are optional. It is not necessary to specify :optional with all the following argument-specs, because it is sticky.

Example:

(call #'foo () x ':spread y '(:optional :spread) z () w)

The arguments passed to foo are the value of x, the elements of the value of y, the elements of the value of z, and the value of w. The function foo must be prepared to accept all the arguments which come from x and y, but if it does not want the rest, they are ignored.

Special Form: quote object ¶

(quote x) simply returns x. It is useful specifically because x is not evaluated; the quote is how you make a form that returns an arbitrary Lisp object. 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 f ¶

This means different things depending on whether f is a function or the name of a function. (Note that in neither case is f evaluated.) The name of a function is a symbol or a function-spec list (see function-spec). A function is typically a list whose car is the symbol lambda, however there are several other kinds of functions available (see kinds-of-functions).

If you want to pass an anonymous function as an argument to a function, you could just use quote; for example:

(mapc (quote (lambda (x) (car x))) some-list)

This works fine as far as the evaluator is concerned. However, the compiler cannot tell that the first argument is going to be used as a function; for all it knows, mapc will treat its first argument as a piece of list structure, asking for its car and cdr and so forth. So the compiler cannot compile the function; it must pass the lambda-expression unmodified. This means that the function will not get compiled, which will make it execute more slowly than it might otherwise.

The function special form is one way to tell the compiler that it can go ahead and compile the lambda-expression. You just use the symbol function instead of quote:

(mapc (function (lambda (x) (car x))) some-list)

This will cause the compiler to generate code such that mapc will be passed a compiled-code object as its first argument.

That’s what the compiler does with a function special form whose subform f is a function. The evaluator, when given such a form, just returns f; that is, it treats function just like quote.

To ease typing, the reader converts #'thing into (function thing). So #' is similar to ' except that it produces a function form instead of a quote form. So the above form could be written as

(mapc #'(lambda (x) (car x)) some-list)

If f is not a function but the name of a function (typically a symbol, but in general any kind of function spec), then function returns the definition of f; it is like fdefinition except that it is a special form instead of a function, and so

(function fred)  is like  (fdefinition 'fred)
                 which is like (fsymeval 'fred)

since fred is a symbol. function is the same for the compiler and the interpreter when f is the name of a function.

Another way of explaining function is that it causes f to be treated the same way as it would as the car of a form. Evaluating the form (f arg1 arg2...) uses the function definition of f if it is a symbol, and otherwise expects f to be a list which is a lambda-expression. Note that the car of a form may not be a non-symbol function spec, to avoid difficult-to-read code. This can be written as

(funcall (function spec) args...)

You should be careful about whether you use #' or '. Suppose you have a program with a variable x whose value is assumed to contain a function that gets called on some arguments. If you want that variable to be the car function, there are two things you could say:

(setq x 'car)
or
(setq x #'car)

The former causes the value of x to be the symbol car, whereas the latter causes the value of x to be the function object found in the function cell of car. When the time comes to call the function (the program does (funcall x ...)), either of these two will work (because if you use a symbol as a function, the contents of the symbol’s function cell is used as the function, as explained in the beginning of this chapter). The former case is a bit slower, because the function call has to indirect through the symbol, but it allows the function to be redefined, traced (see trace-fun), or advised (see advise-fun). The latter case, while faster, picks up the function definition out of the symbol car and does not see any later changes to it.

The other way to tell the compiler that an argument that is a lambda expression should be compiled is for the function that takes the function as an argument to use the &functional keyword in its lambda list; see lambda-list-keywords. The basic system functions that take functions as arguments, such as map and sort, have this &functional keyword and hence quoted lambda-expressions given to them will be recognized as functions by the compiler.

In fact, mapc uses &functional and so the example given above is bogus; in the particular case of the first argument to the function mapc, quote and function are synonymous. It is good style to use function (or #') anyway, to make the intent of the program completely clear.

Function: false ¶

Takes no arguments and returns nil.

Function: true ¶

Takes no arguments and returns t.

Function: ignore &rest ignore ¶

Takes any number of arguments and returns nil. This is often useful as a "dummy" function; if you are calling a function that takes a function as an argument, and you want to pass one that doesn’t do anything and won’t mind being called with any argument pattern, use this.

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

Special Form: progn body... ¶

The body forms are evaluated in order from left to right and the value of the last one is returned. 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))

(When form1 is 'compile, the progn form has a special meaning to the compiler. This is discussed on progn-quote-compile-discussion.)

Special Form: prog1 first-form body... ¶

prog1 is similar to progn, but it returns the value of its first form rather than its last. 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)))

interchanges the values of the variables x and y. prog1 never returns multiple values.

Special Form: prog2 first-form second-form body... ¶

prog2 is similar to progn and prog1, but it returns its second form. It is included largely for compatibility with old programs.

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

The following three functions (arg, setarg, and listify) exist only for compatibility with Maclisp lexprs. To write functions that can accept variable numbers of arguments, use the &optional and &rest keywords (see function-section).

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.4 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 most Lisp function calls, multiple values are not used. Special syntax is required both to produce multiple values and to receive them.

The primitive for producing multiple values is values, which takes any number of arguments and returns that many values. If the last form in the body of a function is a values with three arguments, then a call to that function will return three values. The other 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 values and return primitives.

The special forms for receiving multiple values are multiple-value, multiple-value-bind, and multiple-value-list. These consist of a form and an indication of where to put the values returned by that form. With the first two of these, the caller requests a certain number of returned values. If fewer values are returned than the number requested, then it is exactly as if the rest of the values were present and had the value nil. If too many values are returned, the rest of the values are ignored. This has the advantage that you don’t have to pay attention to extra values if you don’t care about them, but it has the disadvantage that error-checking similar to that done for function calling is not present.

Function: values &rest args ¶

Returns multiple values, its arguments. This is the primitive function for producing multiple values. It is legal to call values with no arguments; it returns no values in that case.

Function: values-list list ¶

Returns multiple values, the elements of the list. (values-list '(a b c)) is the same as (values 'a 'b 'c). list may be nil, the empty list, which causes no values to be returned.

return and its variants can only be used within the do and prog special forms and their variants, and so they are explained on return-fun.

Special Form: multiple-value (variable...) form ¶

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

Example:

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

In addition to its first value (the symbol), intern returns a second value, which is t if the symbol returned as the first value was already interned, or else nil if intern had to create it. So if the symbol goo was already known, the variable already-there-p will be set to t, otherwise it will be set to nil. The third value returned by intern will be ignored.

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 (variable...) form body... ¶

This is similar to multiple-value, but locally binds the variables which receive the values, rather than setting them, and has a body–a set of forms which are evaluated with these local bindings in effect. First form is evaluated. Then the variables are bound to the values returned by form. Then the body forms are evaluated sequentially, the bindings are undone, and the result of the last body form is returned.

Special Form: multiple-value-list form ¶

multiple-value-list 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.

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 whatever way it happens to work, as it may change in the future or in other implementations. 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 receives multiple values from that form. That is, if the form (foo (bar)) is evaluated and the call to bar returns many values, foo will still only be called on one argument (namely, the first value returned), rather than being called on all the values returned. 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 correspond to a single argument. Instead, the first value of a form is used as the argument and the remaining values are discarded. Receiving of multiple values is done only with the above-mentioned special forms.

For clarity, descriptions of the interaction of several common special forms with multiple values follow. This can all be deduced from the rule given above. Note well that when it says that multiple values are not returned, it really means that they may or may not be returned, and you should not write any programs that depend on which way it works.

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, and lexpr-funcall pass back multiple values from the function called.

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

Multiple values are passed back from the last subform of an and or or form, but not from previous forms since the return is conditional. Remember that multiple values are only passed back when the value of a sub-form is unconditionally returned from the containing form. For example, consider the form (or (foo) (bar)). If foo returns a non-nil first value, then only that value will be returned as the value of the form. But if it returns nil (as its first value), then or returns whatever values the call to bar returns.

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 rule 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, and so you shouldn’t depend on what it does). t should be used as the predicate of the last clause if multiple values are desired, to make it clear to the compiler (and any human readers of the code!) that the return is not conditional.

The variants of cond such as if, select, selectq, and dispatch pass back multiple values from the last form in the selected clause.

The number of values returned by prog depends on the return form used to return from the prog. (If a prog drops off the end it just returns a single nil.) If return is given two or more subforms, then prog will return as many values as the return has subforms. However, if the return has only one subform, then the prog will return all of the values returned by that one subform.

do behaves like prog with respect to return. All the values of the last exit-form are returned.

unwind-protect passes back multiple values from its protected form.

*catch does not pass back multiple values from the last form in its body, because it is defined to return its own second value (see *catch-fun) to tell you whether the *catch form was exited normally or abnormally. This is sometimes inconvenient when you want to propagate back multiple values but you also want to wrap a *catch around some forms. Usually people get around this problem by enclosing the *catch in a prog and using return to pass out the multiple values, returning through the *catch. This is inelegant, but we don’t know anything that’s much better.

4.1 Conditionals

Special Form: if ¶

if is the simplest conditional form. The "if-then" form looks like:

(if predicate-form then-form)

predicate-form is evaluated, and if the result is non-nil, the then-form is evaluated and its result is returned. Otherwise, nil is returned.

In the "if-then-else" form, it looks like

(if predicate-form then-form else-form)

predicate-form is evaluated, and if the result is non-nil, the then-form is evaluated and its result is returned. Otherwise, the else-form is evaluated and its result is returned.

If there are more than three subforms, if assumes you want more than one else-form; they are evaluated sequentially and the result of the last one is returned, if the predicate returns nil. There is disagreement as to whether this consistutes good programming style or not.

Special Form: cond ¶

The cond special form consists of the symbol cond followed by several clauses. Each clause consists of a predicate form, called the antecedent, followed by zero or more consequent forms.

(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 consequent forms 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 evaluates to nil, and thus 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.  If z is non-nil, it will be returned.
	  (t		;An antecedent of t
	   105)		; is always satisfied.
       )		;This is the end of the cond.

Special Form: cond-every ¶

cond-every has the same syntax as cond, but executes every clause whose predicate is satisfied, not just the first. If a predicate is the symbol otherwise, it is satisfied if and only if no preceding predicate is satisfied. The value returned is the value of the last consequent form in the last clause whose predicate is satisfied. Multiple values are not returned.

Special Form: and form... ¶

and 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 to non-nil values, and returns the value of the last form.

and can be used in two different ways. You can use it as a logical and function, because it returns a true value only if all of its arguments are true. So you can use it as a predicate:

(if (and socrates-is-a-person
         all-people-are-mortal)
    (setq socrates-is-mortal t))

Because the order of evaluation is well-defined, you can do

(if (and (boundp 'x)
         (eq x 'foo))
    (setq y 'bar))

knowing that the x in the eq form will not be evaluated if x is found to be unbound.

You can also use and as a simple conditional form:

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

(and bright-day
     glorious-day
     (princ "It is a bright and glorious day."))

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

Special Form: or form... ¶

or 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 to a non-nil value, or immediately returns that value without evaluating any remaining forms.

As with and, or can be used either as a logical or function, or as a conditional.

(or it-is-fish
    it-is-fowl
    (print "It is neither fish nor fowl."))

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

Special Form: selectq ¶

selectq is a conditional which chooses one of its clauses to execute by comparing the value of a form against various constants, which are typically keyword symbols. Its form is as follows:

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

The first thing selectq does is to evaluate key-form; call the resulting value key. Then selectq considers each of the clauses in turn. If key matches the clause’s test, the consequents of this clause are evaluated, and selectq returns the value of the last consequent. If there are no matches, selectq returns nil.

A test 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 mainly for compatibility with Maclisp’s caseq construct. To be useful, this should be the last clause in the selectq.

Note that the tests are not evaluated; if you want them to be evaluated use select rather than selectq.

Example:

(selectq x
  (foo (do-this))
  (bar (do-that))
  ((baz quux mum) (do-the-other-thing))
  (otherwise (ferror nil "Never heard of ~S" x)))

is equivalent to

(cond ((eq x 'foo) (do-this))
      ((eq x 'bar) (do-that))
      ((memq x '(baz quux mum)) (do-the-other-thing))
      (t (ferror nil "Never heard of ~S" x)))

Also see defselect (defselect-fun), a special form for defining a function whose body is like a selectq.

Special Form: select ¶

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

This creates a syntactic ambiguity: if (bar baz) is seen the first element of a clause, is it a list of two forms, or is it one form? select interprets it as a list of two forms. If you want to have a clause whose test is a single form, and that form is a list, you have to write it as a list of one form.

Example:

(select (frob x)
   (foo 1)
   ((bar baz) 2)
   (((current-frob)) 4)
   (otherwise 3))

is equivalent to

(let ((var (frob x)))
  (cond ((eq var foo) 1)
	((or (eq var bar) (eq var baz)) 2)
	((eq var (current-frob)) 4)
	(t 3)))

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

is equivalent to

(let ((var (frob x)))
  (cond ((equal var '(one . two)) (frob-one x))
	((equal var '(three . four)) (frob-three x))
	(t (frob-any x))))

Special Form: dispatch ¶

(dispatch byte-specifier number clauses...) is the same as select (not selectq), but the key is obtained by evaluating (ldb byte-specifier number). byte-specifier and number are both evaluated. Byte specifiers and ldb are explained on ldb-fun.

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.

Special Form: selectq-every ¶

selectq-every has the same syntax as selectq, but, like cond-every, executes every selected clause instead of just the first one. If an otherwise clause is present, it is selected if and only if no preceding clause is selected. The value returned is the value of the last form in the last selected clause. Multiple values are not returned. Example:

(selectq-every animal
  ((cat dog) (setq legs 4))
  ((bird man) (setq legs 2))
  ((cat bird) (put-in-oven animal))
  ((cat dog man) (beware-of animal)))

Special Form: caseq ¶

The caseq special form is provided for Maclisp compatibility. It is exactly the same as selectq. This is not perfectly compatible with Maclisp, because selectq accepts otherwise as well as t where caseq would not accept otherwise, and because Maclisp does some error-checking that selectq does not. Maclisp programs that use caseq will work correctly so long as they don’t use the symbol otherwise as the key.

4.2 Iteration

Special Form: do ¶

The do special form provides a simple 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, ie 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 more general, so-called "new-style" 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 form init, which defaults to nil if it is omitted, and a repeat value form repeat. If repeat is omitted, the var is not changed between repetitions. If init is omitted, the var is initialized to nil.

An index variable specifier can also be just the name of a variable, rather than a list. 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 init forms are evaluated, then the vars are bound to the values of the init forms, their old values being saved in the usual way. Note that the init forms are evaluated before the vars are bound, ie lexically outside of the do. At the beginning of each succeeding iteration those vars that have repeat forms get set to the values of their respective repeat forms. Note that all the repeat forms are evaluated before any of the vars is set.

The second element of the do-form is a list of an end-testing predicate form end-test, and zero or more forms, called the exit-forms. This resembles a cond clause. At the beginning of each iteration, after processing of the variable specifiers, 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 if there were no exit-forms (not the value of the end-test as you might expect by analogy with cond).

Note that the end-test gets evaluated before the first time the body is evaluated. do first initializes the variables from the init forms, then it checks the end-test, then it processes the body, then it deals with the repeat forms, then it tests the end-test again, and so on. If the end-test returns a non-nil value the first time, then the body will never be processed.

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 no more powerful than let; it is obsolete and provided only for Maclisp compatibility.

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.

If a return special form is evaluated inside the body of a do, then the do immediately stops, unbinds its variables, and returns the values given to return. See return-fun for more details about return and its variants. go special forms (see go-fun) and prog-tags can also be used inside the body of a do and they mean the same thing that they do inside prog forms, but we discourage their use since they complicate the control structure in a hard-to-understand way.

The other, so-called "old-style" do looks like:

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

The first time through the loop var gets the value of the init form; the remaining times through the loop it gets the value of the repeat form, which is re-evaluated each time. Note that the init form is evaluated before var is bound, ie 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. As with the new-style do, return and go may be used in the body, and they have the same meaning.

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))	; Note how the setq is avoided.

(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.
     w) 	      ; w starts as nil and is not changed by the do.
    (nil)	      ; The end-test is nil, so this is an infinite loop.
  body)           ; Presumably the body uses return somewhere.

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 assignment.
    ((or (null x) (null y))
     (nreverse z))             ;typical use of nreverse.
    )                          ;no do-body required.

is like (maplist 'f x y) (see maplist-fun).

Also see loop (loop-fun), a general iteration facility based on a keyword syntax rather than a list-structure syntax.

Special Form: do* ¶

In a word, do* is to do as prog* is to prog.

do* works like do but binds and steps the variables sequentially instead of in parallel. This means that the init form for one variable can use the values previous variables. The repeat forms refer to the new values of previous variables instead of their old values. Here is an example:

(do* ((x xlist (cdr x))
      (y (car x) (car x)))
  (print (list x y)))

On each iteration, y’s value will be the car of x. By comparison, with do, this would get an error on entry since x would not have an old value yet.

Special Form: do-named ¶

Sometimes one do is contained inside the body of an outer do. The return function always returns from the innermost surrounding do, but sometimes you want to return from an outer do while within an inner do. You can do this by giving the outer do a name. You use do-named instead of do for the outer do, and use return-from (see return-from-fun), specifying that name, to return from the do-named.

The syntax of do-named is like do except that the symbol do is immediately followed by the name, which should be a symbol.

Example:

(do-named george ((a 1 (1+ a))
		  (d 'foo))
		 ((> a 4) 7)
  (do ((c b (cdr c)))
      ((null c))
    ...
    (return-from george (cons b d))
    ...))

If the symbol t is used as the name, then it will be made "invisible" to returns; that is, returns inside that do-named will return to the next outermost level whose name is not t. (return-from t ...) will return from a do-named named t. This feature is not intended to be used by user-written code; it is for macros to expand into.

If the symbol nil is used as the name, it is as if this were a regular do. Not having a name is the same as being named nil.

progs and loops can have names just as dos can. Since the same functions are used to return from all of these forms, all of these names are in the same name-space; a return returns from the innermost enclosing iteration form, no matter which of these it is, and so you need to use names if you nest any of them within any other and want to return to an outer one from inside an inner one.

Special Form: do*-named ¶

This special form offers a combination of the features of do* and those of do-named.

Special Form: dotimes (index count) body... ¶

dotimes is a convenient abbreviation for the most common integer iteration. dotimes 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. Note that i takes on values starting at zero rather than one, and that it stops before taking the value (// m n) rather than after. You can use return and go and prog-tags inside the body, as with do. dotimes forms return nil unless returned from explicitly with return. For example:

(dotimes (i 5)
  (if (eq (aref a i) 'foo)
      (return i)))

This form searches the array that is the value of a, looking for the symbol foo. It returns the fixnum index of the first element of a that is foo, or else nil if none of the elements are foo.

Special Form: dolist (item list) body... ¶

dolist is a convenient abbreviation for the most common list iteration. dolist 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. You can use return and go and prog-tags inside the body, as with do. dolist forms return nil unless returned from explicitly with return.

Special Form: keyword-extract ¶

keyword-extract is an aid to writing functions which take keyword arguments in the standard fashion. The form

(keyword-extract key-list iteration-var
	keywords flags other-clauses...)

will parse the keywords out into local variables of the function. key-list is a form which evaluates to the list of keyword arguments; it is generally the function’s &rest argument. iteration-var is a variable used to iterate over the list; sometimes other-clauses will use the form

(car (setq iteration-var (cdr iteration-var)))

to extract the next element of the list. (Note that this is not the same as pop, because it does the car after the cdr, not before.)

keywords defines the symbols which are keywords to be followed by an argument. Each element of keywords is either the name of a local variable which receives the argument and is also the keyword, or a list of the keyword and the variable, for use when they are different or the keyword is not to go in the keyword package. Thus if keywords is (foo (ugh bletch) bar) then the keywords recognized will be :foo, ugh, and :bar. If :foo is specified its argument will be stored into foo. If :bar is specified its argument will be stored into bar. If ugh is specified its argument will be stored into bletch.

Note that keyword-extract does not bind these local variables; it assumes you will have done that somewhere else in the code that contains the keyword-extract form.

flags defines the symbols which are keywords not followed by an argument. If a flag is seen its corresponding variable is set to t. (You are assumed to have initialized it to nil when you bound it with let or &aux.) As in keywords, an element of flags may be either a variable from which the keyword is deduced, or a list of the keyword and the variable.

If there are any other-clauses, they are selectq clauses selecting on the keyword being processed. These clauses are for handling any keywords that are not handled by the keywords and flags elements. These can be used to do special processing of certain keywords for which simply storing the argument into a variable is not good enough. After the other-clauses there will be an otherwise clause to complain about any undefined keywords found in key-list.

You can also use the &key lambda-list keyword to create functions that take keyword arguments; see &key.

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

The first subform of a prog is a list of variables, each of which may optionally have an initialization form. The first thing evaluation of a prog form does is to evaluate all of the init forms. Then each variable that had an init form is bound to its value, and the variables that did not have an init form are bound 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. prog* (see prog*-fun) is the same as prog except that this initialization is sequential rather than parallel.

The part of a prog after the variable list is called the body. Each element of the body is either a symbol, in which case it is called a tag, or anything else (almost always a list), in which case it is called a statement.

After prog binds the 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, where processing of the body is continued. tag is not evaluated. return and go and their variants are explained fully below.

The compiler requires that go and return forms be lexically within the scope of the prog; it is not possible for a function called from inside a prog body to return to the prog. That is, the return or go must be inside the prog itself, not inside a function called by the prog. (This restriction happens not to be enforced in the interpreter, but since all programs are eventually compiled, the convention should be adhered to. The restriction will be imposed in future implementations of the interpreter.)

See also the do special form, which uses a body similar to prog. The do, *catch, and *throw special forms are included in Zetalisp 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 forms instead of prog wherever reasonable.

If the first subform of a prog is a non-nil symbol (rather than a variable list), it is the name of the prog, and return-from (see return-from-fun) can be used to return from it. See do-named, do-named-fun.

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 (car y)))
  (return x))

returns the car of the value of z.

Special Form: go tag ¶

The go 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.

Example:

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

Special Form: return value... ¶

return is used to exit from a prog-like special form (prog, prog*, do, do-named, dotimes, dolist, loop, etc.) The value forms are evaluated, and the resulting values are returned by the prog as its values.

In addition, break (see break-fun) recognizes the typed-in form (return value) specially. If this form is typed at a break, value will be evaluated and returned as the value of break. If not specially recognized by break, and not inside a prog-like form, 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))))

Note that the return form is very unusual: it does not ever return a value itself, in the conventional sense. It isn’t useful to write (setq a (return 3)), because when the return form is evaluated, the containing do or prog is immediately exited, and the setq never happens. A return 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 return 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 in all cases. The same is true of go.

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

(defun assqn (x table)
  (do ((l table (cdr l))
       (n 0 (1+ n)))
      ((null l) nil)
    (if (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.

However, if you use return with only one subform, then the prog or do will return all of the values returned by that subform. That is, if you do

(prog ()
   ...
   (return (foo 2)))

and the function foo returns many values, then the prog will return all of those values. In fact, this means that

(return (values form1 form2 form3))
is the same as
(return form1 form2 form3)

It is legal to write simply (return), which will return from the prog without returning any values.

See multiple-value for more information.

Special Form: return-from name value... ¶

The value forms are evaluated, and then are returned from the innermost containing prog-like special form whose name is name. See the description of do-named (do-named-fun) in which named dos and progs are explained.

Function: return-list list ¶

This function is like return except that the prog returns all of the elements of list; if list has more than 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 (values-list list)).

Also see defunp (defunp-fun), a variant of defun that incorporates a prog into the function body.

4.3 Non-Local Exits

Special Form: *catch tag body... ¶

*catch is a special form used with the *throw function to do non-local exits. First tag is evaluated; the result is called the "tag" of the *catch. Then the body forms are evaluated sequentially, and the value of the last form is returned. However, if, during the evaluation of the body, the function *throw is called with the same tag as the tag of the *catch, then the evaluation of the body is aborted, and the *catch form immediately returns the value that was the second argument to *throw without further evaluating the current body form or the rest of the body.

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: a *catch whose tag is one of these values will catch throws to any tag. These are only for internal use 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. With nil, the error check isn’t done.

*catch returns up to four values; trailing null values are not returned for reasons of microcode simplicity, but the values not returned will default to nil if they are received with the multiple-value or multiple-value-bind special forms. 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 (see *unwind-stack-fun) if that was used in place of *throw; otherwise these values are 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 that *catch returns its own extra values, and so it does not propagate multiple values back from the last form.

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, nil, and 0 for tag are reserved and used for internal purposes. nil may not be used, because it would cause an ambiguity in the returned values of *catch. t may only be used with *unwind-stack. 0 and nil are used internally when returning out of an unwind-protect.

See the description of *catch for further details.

Macro: catch form tag ¶

Macro: throw form tag ¶

catch and throw are provided only for Maclisp compatibility. (catch form tag) is the same as (*catch 'tag form), and (throw form tag) is the same as (*throw '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.

A tag of t invokes a special feature whereby the entire stack is unwound, and then the function action is called (see below). 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 unwind a stack completely.

active-frame-count, if non-nil, is the number of frames to be unwound. The definition of a "frame" is implementation-dependent. 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 action is called with one argument, value. If tag is t, meaning throw out the whole way, then the function action is not allowed to return. Otherwise the function action may return and its value will be returned instead of value from the *catch–or from an arbitrary function if active-frame-count is in use. In this case the *catch does not return multiple values as it normally does when thrown to. Note that it is often useful for action to be a stack-group.

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

Special Form: unwind-protect protected-form cleanup-form... ¶

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). This is particularly likely if hairy-function gets an error and the user tells the error-handler to give up and flush the computation.

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.

The general form of unwind-protect looks like

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

protected-form is evaluated, and when it returns or when it attempts to quit out of the unwind-protect, the cleanup-forms are evaluated. The value of the unwind-protect is the value of protected-form. Multiple values returned by the protected-form are propagated back through the unwind-protect.

The cleanup forms are run in the variable-binding environment that you would expect: that is, variables bound outside the scope of the unwind-protect special form can be accessed, but variables bound inside the protected-form can’t be. In other words, the stack is unwound to the point just outside the protected-form, then the cleanup handler is run, and then the stack is unwound some more.

Macro: catch-all body... ¶

(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 *unwind-stack with a tag of t. catch-all is a macro which expands into *catch with a tag of nil.

If you think you want this, most likely you are mistaken and you really want unwind-protect.

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. (If there are no lists at all, then there are no lists to be exhausted, so the function will be called repeatedly over and over. This is an obscure way to write an infinite loop. It is supported for consistency.) If you want to call a function of many arguments where one of the arguments successively takes on the values of the elements of a list and the other arguments are constant, you can use a circular list for the other arguments to mapcar. The function circular-list is useful for creating such lists; see circular-list.

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, mapcon could have been defined by

(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 a function, acceptable to apply–it cannot be a macro or the name of a special form.

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

You can also do what the mapping functions do in a different way by using loop. See loop-fun.

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, car and cdr of nil return nil.

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)

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, explained in chapter area-chapter; 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 (see cdr-code).

5.2 Lists

Function: length list ¶

length returns the length of list. The length of a list is the number of elements 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) ))

except that it is an error to take length of a non-nil atom.

Function: first list ¶

Function: second list ¶

Function: third list ¶

Function: fourth list ¶

Function: fifth list ¶

Function: sixth list ¶

Function: seventh list ¶

These functions take a list as an argument, and return the first, second, etc. element of the list. first is identical to car, second is identical to cadr, and so on. The reason these names are provided is that they make more sense when you are thinking of the argument as a list rather than just as a cons.

Function: rest1 list ¶

Function: rest2 list ¶

Function: rest3 list ¶

Function: rest4 list ¶

restn returns the rest of the elements of a list, starting with element n (counting the first element as the zeroth). Thus rest1 is identical to cdr, rest2 is identical to cddr, and so on. The reason these names are provided is that they make more sense when you are thinking of the argument as a list rather than just as a cons.

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

If n is greater than the length of the list, nil is returned.

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. If n is greater than the length of the list, nil is returned.

This is 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 could have been defined by:

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

Function: last list ¶

last returns the last cons of list. If list is nil, it returns nil. Note that last is unfortunately not analogous to first (first returns the first element of a list, but last doesn’t return the last element of a list); this is a historical artifact.

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: 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 (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 one argument.

Example:

(list* 'a 'b 'c 'd) => (a b c . d)

This is like

(cons 'a (cons 'b (cons 'c 'd)))

More examples:

(list* 'a 'b) => (a . b)
(list* 'a) => a

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: 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 length &rest options ¶

This creates and returns a list containing length elements. length should be a fixnum. options are alternating keywords and values. The keywords may be either of the following:

:area

The value specifies in which area (see area) the list should be created. It should be either an area number (a fixnum), or nil to mean the default area.

:initial-value

The elements of the list will all be this value. It defaults to nil.

make-list always creates a cdr-coded list (see cdr-code).

Examples:

(make-list 3) => (nil nil nil)
(make-list 4 ':initial-value 7) => (7 7 7 7)

When make-list was originally implemented, it took exactly two arguments: the area and the length. This obsolete form is still supported so that old programs will continue to work, but the new keyword-argument form is preferred.

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.

circular-list could have been defined by:

(defun circular-list (&rest elements)
  (setq elements (copylist* elements))
  (rplacd (last elements) elements)
  elements)

Function: copylist list &optional area ¶

Returns a list which is equal to list, but not eq. copylist does not copy any elements of the list: only the conses of the list itself. The returned list is fully cdr-coded (see cdr-code) 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 (see cdr-code). This makes for increased efficiency if you nconc something onto the list later.

Function: copyalist list &optional area ¶

copyalist is for copying association lists (see assoc-lists-section). The list is copied, as in copylist. 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: copytree tree ¶

copytree copies all the conses of a tree and makes a new tree with the same fringe.

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. The list created by reverse is not cdr-coded.

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: 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 (see cdr-code) lists, because it just uses rplacd in the straightforward way. This may be fixed someday. In the meantime reverse might be preferable in some cases.

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)

append makes copies of the conses of all the lists it is given, except for the last one. So the new list will share the conses of the last argument to append, but all of the other conses will be newly created. Only the lists are copied, not the elements of the lists.

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 (relying on car of nil being nil):

(defun append (&rest args)
  (if (< (length args) 2) (car 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 (see cdr-code) 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 is nil in which case cdr-nil is used.

To copy a list, use copylist (see copylist-fun); the old practice of using append to copy lists is unclear and obsolete.

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

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: nleft n list &optional tail ¶

Returns a "tail" of list, i.e one of the conses that makes up list, or nil. (nleft n list) returns the last n elements of list. If n is too large, nleft will return list.

(nleft n list tail) takes cdr of list enough times that taking n more cdrs would yield tail, and returns that. You can see that when tail is nil this is the same as the two-argument case. If tail is not eq to any tail of list, nleft will return nil.

Function: ldiff list sublist ¶

list should be a list, and sublist should be 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.

Function: rplaca x y ¶

(rplaca x y) changes the car of x to y and returns (the modified) x. x must be a cons or a locative. 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 must be a cons or a locative. y may be any Lisp object.

Example:

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

Function: subst new old tree ¶

(subst new old tree) substitutes new for all occurrences of old in tree, and returns the modified copy of tree. The original tree is unchanged, as subst recursively copies all of tree replacing elements equal to old as it goes.

Example:

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

subst could have been defined by:

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

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

To copy a tree, use copytree (see copytree-fun); the old practice of using subst to copy trees is unclear and obsolete.

Note: certain details of subst may be changed in the future. It may possibly be changed to use eq rather than equal for the comparison, and possibly may substitute only in cars, not in cdrs. This is still being discussed.

Function: nsubst new old tree ¶

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

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

Function: sublis alist tree ¶

sublis makes substitutions for symbols in a tree. The first argument to sublis is an association list (see assoc-lists-section). The second argument is the tree in which substitutions are to be made. sublis looks at all symbols in the fringe of the tree; 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 tree shares as much of its substructure as possible with the old. For example, if no substitutions are made, the result is just the old tree.

Example:

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

sublis could have been defined by:

(defun sublis (alist sexp)
  (cond ((atom sexp)
	 (let ((tem (assq sexp alist)))
	   (if tem (cdr tem) sexp)))
	((let ((car (sublis alist (car sexp)))
	       (cdr (sublis alist (cdr sexp))))
	   (if (and (eq (car sexp) car) (eq (cdr sexp) cdr))
	       sexp
	       (cons car cdr))))))

Function: nsublis alist tree ¶

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

nsublis could have been defined by:

(defun nsublis (alist tree)
  (cond ((atom tree)
	 (let ((tem (assq tree alist)))
	   (if tem (cdr tem) tree)))
	(t (rplaca tree (nsublis alist (car tree)))
	   (rplacd tree (nsublis alist (cdr tree)))
	   tree)))

5.4 Cdr-Coding

This section explains the internal data format used to store conses inside the Lisp Machine. Casual users don’t have to worry about this; you can skip this section if you want. It is only important to read this section if you require extra storage efficiency in your program.

The usual and obvious internal representation of conses in any implementation of Lisp is as a pair of pointers, contiguous in memory. If we call the amount of storage that it takes to store a Lisp pointer a "word", then conses normally occupy two words. One word (say it’s the first) holds the car, and the other word (say it’s the second) holds the cdr. To get the car or cdr of a list, you just reference this memory location, and to change the car or cdr, you just store into this memory location.

Very often, conses are used to store lists. If the above representation is used, a list of n elements requires two times n words of memory: n to hold the pointers to the elements of the list, and n to point to the next cons or to nil. To optimize this particular case of using conses, the Lisp Machine uses a storage representation called "cdr coding" to store lists. The basic goal is to allow a list of n elements to be stored in only n locations, while allowing conses that are not parts of lists to be stored in the usual way.

The way it works is that there is an extra two-bit field in every word of memory, called the "cdr-code" field. There are three meaningful values that this field can have, which are called cdr-normal, cdr-next, and cdr-nil. The regular, non-compact way to store a cons is by two contiguous words, the first of which holds the car and the second of which holds the cdr. In this case, the cdr code of the first word is cdr-normal. (The cdr code of the second word doesn’t matter; as we will see, it is never looked at.) The cons is represented by a pointer to the first of the two words. When a list of n elements is stored in the most compact way, pointers to the n elements occupy n contiguous memory locations. The cdr codes of all these locations are cdr-next, except the last location whose cdr code is cdr-nil. The list is represented as a pointer to the first of the n words.

Now, how are the basic operations on conses defined to work based on this data structure? Finding the car is easy: you just read the contents of the location addressed by the pointer. Finding the cdr is more complex. First you must read the contents of the location addressed by the pointer, and inspect the cdr-code you find there. If the code is cdr-normal, then you add one to the pointer, read the location it addresses, and return the contents of that location; that is, you read the second of the two words. If the code is cdr-next, you add one to the pointer, and simply return that pointer without doing any more reading; that is, you return a pointer to the next word in the n-word block. If the code is cdr-nil, you simply return nil.

If you examine these rules, you will find that they work fine even if you mix the two kinds of storage representation within the same list. There’s no problem with doing that.

How about changing the structure? Like car, rplaca is very easy; you just store into the location addressed by the pointer. To do an rplacd you must read the location addressed by the pointer and examine the cdr code. If the code is cdr-normal, you just store into the location one greater than that addressed by the pointer; that is, you store into the second word of the two words. But if the cdr-code is cdr-next or cdr-nil, there is a problem: there is no memory cell that is storing the cdr of the cons. That is the cell that has been optimized out; it just doesn’t exist.

This problem is dealt with by the use of "invisible pointers". An invisible pointer is a special kind of pointer, recognized by its data type (Lisp Machine pointers include a data type field as well as an address field). The way they work is that when the Lisp Machine reads a word from memory, if that word is an invisible pointer then it proceeds to read the word pointed to by the invisible pointer and use that word instead of the invisible pointer itself. Similarly, when it writes to a location, it first reads the location, and if it contains an invisible pointer then it writes to the location addressed by the invisible pointer instead. (This is a somewhat simplified explanation; actually there are several kinds of invisible pointer that are interpreted in different ways at different times, used for things other than the cdr coding scheme.)

Here’s how to do an rplacd when the cdr code is cdr-next or cdr-nil. Call the location addressed by the first argument to rplacd l. First, you allocate two contiguous words (in the same area that l points to). Then you store the old contents of l (the car of the cons) and the second argument to rplacd (the new cdr of the cons) into these two words. You set the cdr-code of the first of the two words to cdr-normal. Then you write an invisible pointer, pointing at the first of the two words, into location l. (It doesn’t matter what the cdr-code of this word is, since the invisible pointer data type is checked first, as we will see.)

Now, whenever any operation is done to the cons (car, cdr, rplaca, or rplacd), the initial reading of the word pointed to by the Lisp pointer that represents the cons will find an invisible pointer in the addressed cell. When the invisible pointer is seen, the address it contains is used in place of the original address. So the newly-allocated two-word cons will be used for any operation done on the original object.

Why is any of this important to users? In fact, it is all invisible to you; everything works the same way whether or not compact representation is used, from the point of view of the semantics of the language. That is, the only difference that any of this makes is a difference in efficiency. The compact representation is more efficient in most cases. However, if the conses are going to get rplacd’ed, then invisible pointers will be created, extra memory will be allocated, and the compact representation will be seen to degrade storage efficiency rather than improve it. Also, accesses that go through invisible pointers are somewhat slower, since more memory references are needed. So if you care a lot about storage efficiency, you should be careful about which lists get stored in which representations.

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

(copylist x) is a suitable way to copy a list, converting it into compact form (see copylist-fun).

5.5 Tables

Zetalisp includes 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 can be 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. For example,

((tweety . bird) (sylvester . cat))

is an association list with two elements. Given a symbol representing the name of an animal, it can retrieve what kind of animal this is.

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. Zetalisp includes hash table facilities for more efficient but more complex tables (see hash-table), and a hashing function (sxhash) to aid users in constructing their own facilities.

5.6 Lists as Tables

Function: memq item list ¶

(memq item list) returns nil if item is not one of the elements of list. Otherwise, it returns the sublist of list beginning with the first occurrence of item; that is, it returns the first cons of the list whose car is item. The comparison is made by eq. 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 a 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:

(let ((sublist (memq x z)))	;Search for x in the list z.
  (if (not (null sublist))      ;If it is found,
      (rplaca sublist y)))	;Replace it with y.

memq could have been defined by:

(defun memq (item list)
    (cond ((null list) nil)
          ((eq item (car list)) list)
          (t (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)
          (t (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. It can also be used with non-commutative predicates. The predicate is called with item as its first argument and the element of list as its second argument, so

(mem #'< 4 list)

finds the first element in list for which (< 4 x) is true; that is, it finds the first element greater than 4.

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. This function is sort of the complement of nth (see nth-fun); like nth, it is zero-based.

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.

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. Another way to look at this is that tailp returns t if (nthcdr n list) is sublist, for some value of n. tailp could have been defined by:

(defun tailp (sublist list)
    (do list list (cdr list) (null list)
      (if (eq sublist list)
	  (return t))))

Function: delq item list &optional n ¶

(delq item list) returns the list with all 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)

These two are 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 or equal to 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 -1))
    (cond ((or (atom list) (zerop n)) list)
          ((eq item (car list))
	   (delq item (cdr list) (1- n)))
          (t (rplacd list (delq item (cdr list) n)))))

If the third argument (n) is not supplied, it defaults to -1 which is effectively infinity since it can be decremented any number of times without reaching zero.

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). (cf 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). (cf mem, mem-fun)

Function: subset predicate list ¶

Function: rem-if-not predicate list ¶

predicate should be a function of one argument. A new list is made by applying predicate to all of the elements of list and removing the ones for which the predicate returns nil. One of this function’s names (rem-if-not) means "remove if this condition is not true"; i.e it keeps the elements for which predicate is true. The other name (subset) refers to the function’s action if list is considered to represent a mathematical set.

Function: subset-not predicate list ¶

Function: rem-if predicate list ¶

predicate should be a function of one argument. A new list is made by applying predicate to all of the elements of list and removing the ones for which the predicate returns non-nil. One of this function’s names (rem-if) means "remove if this condition is true". The other name (subset-not) refers to the function’s action if list is considered to represent a mathematical set.

Function: del-if predicate list ¶

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

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.

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; cddr is a typical function to use here.

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; cddr is a typical function to use here.

5.7 Association Lists

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)). Since 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). (cf mem, mem-fun) As with mem, you may use non-commutative predicates; the first argument to the predicate is item and the second is the key of the element of alist.

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). (cf mem, mem-fun) As with mem, you may use non-commutative predicates; the first argument to the predicate is item and the second is the key of the element of alist.

Function: rassq item alist ¶

rassq means "reverse assq". It is like assq, but it tries to find an element of alist whose cdr (not car) is eq to item. rassq could have been defined by:

(defun rassq (item in-list) 
    (do l in-list (cdr l) (null l) 
      (and (eq item (cdar l)) 
	   (return (car l)))))

Function: rassoc item alist ¶

rassoc is to rassq as assoc is to assq. That is, it finds an element whose cdr is equal to item.

Function: rass predicate item alist ¶

rass is to rassq as ass is to assq. That is, it takes a predicate to be used instead of eq. (cf mem, mem-fun) As with mem, you may use non-commutative predicates; the first argument to the predicate is item and the second is the cdr of the element of alist.

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

5.8 Property Lists

From time immemorial, Lisp has had a kind of tabular data structure called a property list (plist for short). A property list contains zero or more entries; each entry associates from a keyword symbol (called the indicator) to a Lisp object (called the value or, sometimes, the property). There are no duplications among the indicators; a property-list can only have one property at a time with a given name.

This is very similar to an association list. The difference is that a property list is an object with a unique identity; the operations for adding and removing property-list entries are side-effecting operations which alter the property-list rather than making a new one. An association list with no entries would be the empty list (), i.e the symbol nil. There is only one empty list, so all empty association lists are the same object. Each empty property-list is a separate and distinct object.

The implementation of a property list is a memory cell containing a list with an even number (possibly zero) of elements. Each pair of elements constitutes a property; the first of the pair is the indicator and the second is the value. The memory cell is there to give the property list a unique identity and to provide for side-effecting operations.

The term "property list" is sometimes incorrectly used to refer to the list of entries inside the property list, rather than the property list itself. This is regrettable and confusing.

How do we deal with "memory cells" in Lisp; i.e what kind of Lisp object is a property list? Rather than being a distinct primitive data type, a property list can exist in one of three forms:

1. A property list can be a cons whose cdr is the list of entries and whose car is not used and available to the user to store something.

2. The system associates a property list with every symbol (see symbol-plist-section). A symbol can be used where a property list is expected; the property-list primitives will automatically find the symbol’s property list and use it.

3. A property list can be a memory cell in the middle of some data structure, such as a list, an array, an instance, or a defstruct. An arbitrary memory cell of this kind is named by a locative (see locative). Such locatives are typically created with the locf special form (see locf-fun).

Property lists of the first kind are called "disembodied" property lists because they are not associated with a symbol or other data structure. The way to create a disembodied property list is (ncons nil), or (ncons data) to store data in the car of the property list.

Here is an example of the list of entries inside 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 painted 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.

Function: get plist indicator ¶

get looks up plist’s indicator property. If it finds such a property, it returns the value; otherwise, it returns nil. If plist is a symbol, the symbol’s associated property list is used. For example, if the property list of foo is (baz 3), then

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

Function: getl plist indicator-list ¶

getl is like get, except that the second argument is a list of indicators. getl searches down plist for any of the indicators in indicator-list, until it finds a property whose indicator is one of the elements of indicator-list. If plist is a symbol, the symbol’s associated property list is used. getl returns the portion of the list inside plist beginning with the first such property that 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. For 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)

When more than one of the indicators in indicator-list is present in plist, which one getl returns depends on the order of the properties. This is the only thing that depends on that order. The order maintained by putprop and defprop is not defined (their behavior with respect to order is not guaranteed and may be changed without notice).

Function: putprop plist x indicator ¶

This gives plist an indicator-property of x. After this is done, (get plist indicator) will return x. If plist is a symbol, the symbol’s associated property list is used.

Example:

(putprop 'Nixon 'not 'crook)

Special Form: defprop symbol x indicator ¶

defprop is a form of putprop with "unevaluated arguments", which is sometimes more convenient for typing. Normally it doesn’t make sense to use a property list rather than a symbol as the first (or plist) argument.

Example:

(defprop foo bar next-to)

is the same as

(putprop 'foo 'bar 'next-to)

Function: remprop plist indicator ¶

This removes plist’s indicator property, by splicing it out of the property list. It returns that portion of the list inside plist of which the former indicator-property was the car. car of what remprop returns is what get would have returned with the same arguments. If plist is a symbol, the symbol’s associated property list is used. For 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 plist has no indicator-property, then remprop has no side-effect and returns nil.

There is a mixin flavor, called si:property-list-mixin, that provides messages that do things analogous to what the above functions do. [Currently, the above functions do not work on flavor instances, but this will be fixed.]

5.9 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 (or sequence of values). 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. Hashing is explained in hash-section.

A given hash table stores a fixed number of values for each key; by default, there is only one value. Each time you specify a new value or sequence of values, the old one(s) are lost.

Hash tables come in two kinds, the difference being whether the keys are compared using eq or using equal. In other words, there are hash tables which hash on Lisp objects (using eq) and there are hash tables which hash on trees (using equal). The following discussion refers to the eq kind of hash table; the other kind is described later, and works analogously.

Hash tables of the first kind 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(s), 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 remembers one value for each key, since we did not specify otherwise, and 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.

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.

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 Zetalisp 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. Note, however, that the order of arguments to gethash, puthash, and remhash is not consistent with the Zetalisp’s get, putprop, and remprop, either. This is an unfortunate result of the haphazard historical development of Lisp.

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. Even two processes just doing gethash on the same hash table must synchronize themselves, because gethash may be forced by garbage collection to rehash the table. 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.

Hash tables are implemented with a special kind of array. arrayp of a hash table will return t. However, it is not recommended to use ordinary array operations on a hash table. Hash tables should be manipulated only with the functions described below.

• Hashing on Eq
• Hashing on Equal
• Hash Tables and the Garbage Collector
• Hash Primitive

5.10 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 main sorting functions are not stable; that is, equal items may not stay in their original order. If you want a stable sort, use the stable versions. But if you don’t care about stability, don’t use them since stable algorithms are significantly slower.

After sorting, the argument (be it list or array) has been 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 copylist, as appropriate. Furthermore, sort of a list is like delq in that it should not be used for effect; the result is conceptually the same as the argument but in fact is a different Lisp object.

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 compact lists; it sorts compact sublists as if they were arrays. See cdr-code for an explanation of compact lists, and A. I. Memo 587 by Guy L. Steele Jr. for an explanation of the sorting algorithm.

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

When sort is given a list, it may change the order of the conses of the list (using rplacd), and so it cannot be used merely for side-effect; only the returned value of sort will be the sorted list. This will mess up the original list; if you need both the original list and the sorted list, you must copy the original and sort the copy (see copylist, copylist-fun).

Sorting an array just moves the elements of the array into different places, and so sorting an array for side-effect only is all right.

If the argument to sort is an array with a fill pointer, note that, like most functions, sort considers the active length of the array to be the length, and so only the active part of the array will be sorted (see array-active-length, array-active-length-fun).

Function: sortcar x predicate ¶

sortcar is the same as sort except that the predicate is applied to the cars of the elements of x, instead of directly to the elements of x. Example:

(sortcar '((3 . dog) (1 . cat) (2 . bird)) #'<)
                   =>   ((1 . cat) (2 . bird) (3 . dog))

Remember that sortcar, when given a list, may change the order of the conses of the list (using rplacd), and so it cannot be used merely for side-effect; only the returned value of sortcar will be the sorted list.

Function: stable-sort x predicate ¶

stable-sort is like sort, but if two elements of x are equal, i.e predicate returns nil when applied to them in either order, then those two elements will remain in their original order.

Function: stable-sortcar x predicate ¶

stable-sortcar is like sortcar, but if two elements of x are equal, i.e predicate returns nil when applied to their cars in either order, then those two elements will remain in their original order.

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

5.11 Resources

Storage allocation is handled differently by different computer systems. In many languages, the programmer must spend a lot of time thinking about when variables and storage units are allocated and deallocated. In Lisp, freeing of allocated storage is normally done automatically by the Lisp system; when an object is no longer accessible to the Lisp environment, it is garbage collected. This relieves the programmer of a great burden, and makes writing programs much easier.

However, automatic freeing of storage incurs an expense: more computer resources must be devoted to the garbage collector. If a program is designed to allocate temporary storage, which is then left as garbage, more of the computer must be devoted to the collection of garbage; this expense can be high. In some cases, the programmer may decide that it is worth putting up with the inconvenience of having to free storage under program control, rather than letting the system do it automatically, in order to prevent a great deal of overhead from the garbage collector.

It usually is not worth worrying about freeing of storage when the units of storage are very small things such as conses or small arrays. Numbers are not a problem, either; fixnums and small flonums do not occupy storage, and the system has a special way of garbage-collecting the other kinds of numbers with low overhead. But when a program allocates and then gives up very large objects at a high rate (or large objects at a very high rate), it can be very worthwhile to keep track of that one kind of object manually. Within the Lisp Machine system, there are several programs that are in this position. The Chaosnet software allocates and frees "packets", which are moderately large, at a very high rate. The window system allocates and frees certain kinds of windows, which are very large, moderately often. Both of these programs manage their objects manually, keeping track of when they are no longer used.

When we say that a program "manually frees" storage, it does not really mean that the storage is freed in the same sense that the garbage collector frees storage. Instead, a list of unused objects is kept. When a new object is desired, the program first looks on the list to see if there is one around already, and if there is it uses it. Only if the list is empty does it actually allocate a new one. When the program is finished with the object, it returns it to this list.

The functions and special forms in this section perform the above function. The set of objects forming each such list is called a "resource"; for example, there might be a Chaosnet packet resource. defresource defines a new resource; allocate-resource allocates one of the objects; deallocate-resource frees one of the objects (putting it back on the list); and using-resource temporarily allocates an object and then frees it.

Special Form: defresource ¶

The defresource special form is used to define a new resource. The form looks like this:

(defresource name parameters
   keyword value
   keyword value
   ...)

name should be a symbol; it is the name of the resource and gets a defresource property of the internal data structure representing the resource.

parameters is a lambda-list giving names and default values (if &optional is used) of parameters to an object of this type. For example, if one had a resource of two-dimensional arrays to be used as temporary storage in a calculation, the resource would typically have two parameters, the number of rows and the number of columns. In the simplest case parameters is ().

The keyword options control how the objects of the resource are made and kept track of. The following keywords are allowed:

:constructor

The value is either a form or the name of a function. It is responsible for making an object, and will be used when someone tries to allocate an object from the resource and no suitable free objects exist. If the value is a form, it may access the parameters as variables. If it is a function, it is given the internal data structure for the resource and any supplied parameters as its arguments; it will need to default any unsupplied optional parameters. This keyword is required.

:initial-copies

The value is a number (or nil which means 0). This many objects will be made as part of the evaluation of the defresource; thus is useful to set up a pool of free objects during loading of a program. The default is to make no initial copies.

If initial copies are made and there are parameters, all the parameters must be &optional and the initial copies will have the default values of the parameters.

:finder

The value is a form or a function as with :constructor and sees the same arguments. If this option is specified, the resource system does not keep track of the objects. Instead, the finder must do so. It will be called inside a without-interrupts and must find a usable object somehow and return it.

:matcher

The value is a form or a function as with :constructor. In addition to the parameters, a form here may access the variable object (in the current package). A function gets the object as its second argument, after the data structure and before the parameters. The job of the matcher is to make sure that the object matches the specified parameters. If no matcher is supplied, the system will remember the values of the parameters (including optional ones that defaulted) that were used to construct the object, and will assume that it matches those particular values for all time. The comparison is done with equal (not eq). The matcher is called inside a without-interrupts.

:checker

The value is a form or a function, as above. In addition to the parameters, a form here may access the variables object and in-use-p (in the current package). A function receives these as its second and third arguments, after the data structure and before the parameters. The job of the checker is to determine whether the object is safe to allocate. If no checker is supplied, the default checker looks only at in-use-p; if the object has been allocated and not freed it is not safe to allocate, otherwise it is. The checker is called inside a without-interrupts.

If these options are used with forms (rather than functions), the forms get compiled into functions as part of the expansion of defresource. These functions are given names like (:property resource-name si:resource-constructor); these names are not guaranteed not to change in the future.

Most of the options are not used in typical cases. Here is an example:

(defresource two-dimensional-array (rows columns)
	:constructor (make-array (list rows columns)))

Suppose the array was usually going to be 100 by 100, and you wanted to preallocate one during loading of the program so that the first time you needed an array you wouldn’t have to spend the time to create one. You might simply put

(using-resource (foo two-dimensional-array 100 100)
	)

after your defresource, which would allocate a 100 by 100 array and then immediately free it. Alternatively you could:

(defresource two-dimensional-array
			(&optional (rows 100) (columns 100))
	:constructor (make-array (list rows columns))
	:initial-copies 1)

Here is an example of how you might use the :matcher option. Suppose you wanted to have a resource of two-dimensional arrays, as above, except that when you allocate one you don’t care about the exact size, as long as it is big enough. Furthermore you realize that you are going to have a lot of different sizes and if you always allocated one of exactly the right size, you would allocate a lot of different arrays and would not reuse a pre-existing array very often. So you might:

(defresource sloppy-two-dimensional-array (rows columns)
    :constructor (make-array (list rows columns))
    :matcher (and ( (array-dimension-n 1 object) rows)
		  ( (array-dimension-n 2 object) columns)))

Function: allocate-resource name &rest parameters ¶

Allocate an object from the resource specified by name. The various forms and/or functions given as options to defresource, together with any parameters given to allocate-resource, control how a suitable object is found and whether a new one has to be constructed or an old one can be reused.

Note that the using-resource special form is usually what you want to use, rather than allocate-resource itself; see below.

Function: deallocate-resource name resource ¶

Free the object resource, returning it to the free-object list of the resource specified by name.

Function: clear-resource name ¶

Forget all of the objects being remembered by the resource specified by name. Future calls to allocate-resource will create new objects. This function is useful if something about the resource has been changed incompatibly, such that the old objects are no longer usable. If an object of the resource is in use when clear-resource is called, an error will be signalled when that object is deallocated.

Special Form: using-resource (variable resource parameters...) body... ¶

The body forms are evaluated sequentially with variable bound to an object allocated from the resource named resource, using the given parameters. The parameters (if any) are evaluated, but resource is not.

using-resource is often more convenient than calling allocate-resource and deallocate-resource. Furthermore it is careful to free the object when the body is exited, whether it returns normally or via *throw. This is done by using unwind-protect; see unwind-protect-fun.

Here is an example of the use of resources:

(defresource huge-16b-array (&optional (size 1000))
  :constructor (make-array size ':type 'art-16b))

(defun do-complex-computation (x y)
  (using-resource (temp-array huge-16b-array)
    ...                               ;Within the body, the array can be used.
    (aset 5 temp-array i)
    ...))                             ;The array is returned at the end.

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.

Symbols are often used as special variables. Variables and how they work are described in variable-section. The symbols nil and t are always bound to themselves; they may not be assigned, bound, or otherwise used as variables. Attempting to change the value of nil or t (usually) causes an error.

The functions described here work on symbols, not variables in general. This means that the functions below won’t work if you try to use them on local variables.

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.

Function: symeval sym ¶

symeval is the basic primitive for retrieving a symbol’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 (locative). It is preferable to write

(locf (symeval sym))

instead of calling this function explicitly.

This is actually the internal value cell; there can also be an external value cell. For details, see the section on closures (closure).

Note: the function value-cell-location works on symbols that get converted to local variables (see variable-section); the compiler knows about it specially when its argument is a quoted symbol which is the name of a local variable. It returns a pointer to the cell that holds the value of the local variable.

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 bound or assigned. (However, to bind a function cell you must use the bind subprimitive; see bind-fun.) 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 definition ¶

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

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 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 (locative). It is preferable to write

(locf (fsymeval sym))

rather than calling this function explicitly.

Since functions are the basic building block of Lisp programs, the system provides a variety of facilities for dealing with functions. Refer to chapter function-chapter for details.

6.3 The Property List

Every symbol has an associated property list. See plist for documentation of property lists. When a symbol is created, its property list is initially empty.

The Lisp language itself does not use a symbol’s property list for anything. (This was not true in older Lisp implementations, where the print-name, value-cell, and function-cell of a symbol were kept on its property list.) However, various system programs use the property list to associate information with the symbol. For instance, the editor uses the property list of a symbol which is the name of a function to remember where it has the source code for that function, and the compiler uses the property list of a symbol which is the name of a special form to remember how to compile that special form.

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

Function: plist sym ¶

This returns the list which represents the property list of sym. Note that this is not the property list itself; you cannot do get on it.

Function: setplist sym list ¶

This sets the list which represents the property list of sym to list. setplist is to be used with caution (or not at all), 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. This locative pointer is equally valid as sym itself, as a handle on sym’s property list.

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 sections on the reader (see reader) and printer (see printer).

Function: get-pname sym ¶

This returns the print-name of the symbol sym.

Example:

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

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. samepnamep is useful for determining if two symbols would be the same except that they are in different packages (see package).

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). samepnamep is provided mainly so that you can write programs that will work in Maclisp as well as Zetalisp; in new programs, you should just use string-equal.

6.5 The Package Cell

Every symbol has a package cell which is used, for interned symbols, to point to the package which the symbol belongs to. For an uninterned symbol, the package cell contains nil. For information about packages in general, see the chapter on packages, package. For information about package cells, see symbol-package-cell-discussion.

6.6 Creating Symbols

The functions in this section are primitives for creating symbols. However, before discussing them, it is important to point out that most symbols are created by a higher-level mechanism, namely the reader and the intern function. Nearly all symbols in Lisp are created by virtue of the reader’s having seen a sequence of input characters that looked like the printed representation of a symbol. When the reader sees such a p.r, it calls intern (see intern-fun), which looks up the sequence of characters in a big table and sees whether any symbol with this print-name already exists. If it does, read uses the already-existing symbol. If it does not, then intern creates a new symbol and puts it into the table, and read uses that new symbol.

A symbol that has been put into such a table is called an interned symbol. Interned symbols are normally created automatically; the first time someone (such as the reader) asks for a symbol with a given print-name that symbol is automatically created.

These tables are called packages. In Zetalisp, interned symbols are the province of the package system. Although interned symbols are the most commonly used, they will not be discussed further here. For more information, turn to the chapter on packages (package).

An uninterned symbol is a symbol used simply as a data object, with no special cataloging. An uninterned symbol prints the same as an interned symbol with the same print-name, but cannot be read back in.

The following functions can be used to create uninterned symbols explicitly.

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 and the property list will be empty. If permanent-p is specified, it is assumed that the symbol is going to be interned and probably kept around forever; in this case it and its pname will be put in the proper areas. If permanent-p is nil (the default), the symbol goes in the default area and the pname is not copied. permanent-p is mostly for the use of intern itself.

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-props ¶

This returns a new uninterned symbol with the same print-name as sym. If copy-props is non-nil, then the 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-props is nil, then the new symbol will be unbound and undefined, and its property list will be empty.

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 symbol’s 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 32.) => 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".

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. For flonums, this only returns t for exactly 0.0 or 0.0s0; there is no "fuzz".

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 test x ¶

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 returns t if x is a number which satisfies the test, nil if it is not a number or does not meet the test. 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 ge 12) => t
(signp le 12) => nil
(signp n 0) => nil
(signp g 'foo) => nil

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

7.2 Numeric Comparisons

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 (as opposed to Maclisp in which generally only the spelled-out names work for all kinds of numbers).