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 running 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 was originally based on 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, was based on Lisp 1.5.

Common Lisp is a Lisp dialect designed to standardize all the various Lisp systems derived from Maclisp. Zetalisp today is nearly a superset of Common Lisp, but there are a few important incompatibilities between them, in places where Common Lisp involves an incompatible change which is deemed to severe to impose on traditional Zetalisp users. There is a special mode which provides strict Common Lisp compatibility. See common-lisp for more information.

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. The Lisp Machine window system and the major utility programs are, or ought to be, documented in other manuals.

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” or “macrocode”. 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 related 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.

The next few chapters discuss I/O: chapter io-chapter explains I/O streams and character and line level operations; chapter expression-io-chapter explains reading and printing symbolic expressions; chapter pathname-chapter explains naming of files; chapter file-io-chapter explains input and output to files. Chapter chaos-chapter describes the use of the Chaosnet.

Chapter package-chapter describes the package system, which allows many name spaces within a single Lisp environment. Chapter system-chapter documents the “system” facility that helps you create and maintain systems, which are 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. This section explains those conventions.

The symbol ‘=>’ is used to indicate evaluation in examples. Thus, when you see ‘foo => nil’, this means that “the result of evaluating foo is (or would have been) nil”.

The symbol ‘==>’ is used to indicate macro expansion in examples. This, when you see ‘(foo bar) ==> (aref bar 0)’, this means that “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 arg2) ¶

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, as in (+ foo 56), and argument references are italicized, as in arg1 and arg2. A different, fixed-width font, as in function-name, is used for Lisp examples that are set off from the text. Other font conventions are that filenames are in bold-face, all upper case (as in SYS: SYS; SYSDCL LISP) while keys on the keyboard are in bold-face and capitalized (as in Help, Return and Meta).

‘Car’, ‘cdr’ and ‘cons’ are in bold-face when the actual Lisp objects are being mentioned, but in the normal text font when used as words.

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’ and ‘&key’ to indicate rest and keyword arguments.

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 (‘(’ and ‘)’) stand for themselves. Square brackets (‘[’ and `]’) indicate that what they enclose is optional. Ellipses (‘...’) indicate that the subform (italicized word or parenthesized list) that precedes them may be repeated any number of times (possibly no times at all). Curly brackets followed by ellipses (‘{’ and ‘}...’) 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 that 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 that 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 signaled if any safety checks are violated.

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

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

This is the documentation of the effect of performing operation :operation-name (or, sending a message named :operation-name), with arguments arg1, arg2, and arg3, on an instance of flavor flavor-name.

Descriptions of variables (“globally special” variables) look like this:

Variable: typical-variable ¶

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

If the description says ‘Constant’ rather than ‘Variable’, it means that the value is never set by the system and should not be set by you. In some cases the value is an array or other structure whose contents may be changed by the system or by you.

Most numbers in this manual are decimal; octal numbers are labelled as such, using #o if they appear in examples. Currently the default radix for the Lisp Machine system is eight, but this will be changed in the near future. If you wish to change to base ten now, see the documentation on the variables *read-base* and *print-base* (*read-base*-var).

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

There are several terms that 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 preceded by a ‘/’ it is said to be escaped. Escaping also turns off the effects of macro characters such as "'" and ‘;’. If you select Common Lisp syntax, escaping is done with ‘\’ instead, and ‘/’ has no special syntactic significance. The manual uses traditional syntax throughout, however. The following characters also have special meanings and may not be used in symbols without escaping. These characters are explained in detail in the section on printed representation (reader).

"

Double-quote delimits character strings.

#

Sharp-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 escaped.

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. The colon and the characters preceding it are not actually part of the symbol name, but in early stages of learning the system you can pretend that they are. Actually they are a package prefix. See chapter package-chapter for an explanation of packages and what package prefixes really do.

Symbols whose names start with si: are internal to the system. These functions and variables are documented here because they are things you sometimes need to know about. However, they are subject to change with little concern for compatibility for users.

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 in character-set. 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 Control key on the keyboard (either of the two keys labeled ‘CTRL’), 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 Control and Meta. Unlike ASCII, the Lisp machine character set does not simply label a few of the characters as “control characters”; Control and Meta (and Super and Hyper) are modifiers that can be attached to any character and are represented as separate bits. These modifier bits are not present in characters in strings or files.

Many of the functions refer to “areas”. The area feature is of interest only to writers of large systems and can be safely disregarded by the casual user. It is described in chapter area-chapter.

1.4 Common Lisp Support

Common Lisp is the name of a standardization project whose goal was to establish a compatible subset for Lisp systems descended from Maclisp.

Originally it was hoped that Zetalisp and the Lisp Machine system could be changed to become a superset of Common Lisp; but this proved impossible because the final Common Lisp design includes several incompatible changes to widely used functions, which, while of no fundamental importance, would make most user programs fail to work. Therefore it was necessary to make Common Lisp a separate mode of operation. The incompatibilities fall into two classes:

*

Read syntax: Common Lisp specifies ‘\’ as the single-character escape character rather than the traditional ‘/’. A few other constructs, such as character objects and complex numbers, are also written incompatibly.

*

Specific functions: many Lisp functions of ancient pedigree, including member, assoc, subst, union, terpri, close and // are specified to be incompatible with their traditional behavior.

The read syntax incompatibilities have been dealt with by having separate readtables for traditional and Common Lisp syntax. The incompatibilities in functions have been dealt with by means of reader symbol substitutions. For each function changed incompatibly, such as member, a new, distinct symbol exists in a package called cli (“Common Lisp Incompatible”); for example, cli:member. The function definition of the symbol member is the traditional definition, while that of cli:member is the Common Lisp definition. In Common Lisp programs, the reader is directed to replace member with cli:member wherever it is seen. So traditional and Common Lisp programs both get the member functions they expect. Programs written in traditional syntax can refer to the new cli functions with explicit cli: package prefixes. Programs written in Common Lisp syntax can refer to the traditional symbols with explicit global: package prefixes, but this is not expected to be necessary in code.

The symbol replacements are under control of the current readtable, so that the Common Lisp readtable is responsible for causing cli:close to replace close and so on.

In this manual, the incompatible Common Lisp functions are documented under names starting with cli:, the names by which a traditional program could refer to them. Keep in mind that, in Common Lisp programs, the cli: would be omitted. A list of symbols which have incompatible Common Lisp substitutes can be found by looking up cli: in the function and variable indices.

Traditional read syntax is used nearly everywhere in the manual. This includes the use of ‘/’ as an escape character, the escaping of ‘/’ itself, and not escaping the character ‘\’, which in traditional syntax is not special. It is up to the user to make appropriate modifications to express the same Lisp object in Common Lisp syntax when necessary.

The majority of Common Lisp changes, those that are upward compatible, have been incorporated directly into Zetalisp and are documented in this manual with no special notice.

Common Lisp read syntax and function definitions may be used either in files or interactively.

For listen loops, including Lisp Listener windows, break loops and the debugger, the choice of syntax and function semantics is made by setting the variable readtable to the appropriate readtable (see si:common-lisp-readtable-var) or most simply by calling the function common-lisp.

Function: common-lisp flag ¶

If flag is t, selects Common Lisp syntax and function definitions. If flag is nil, selects traditional syntax and function definitions.

In either case, this controls the reading of the following expressions that you type in the same process. It works by setting readtable.

In a file, Common Lisp is requested by writing the attribute Readtable: Common-Lisp; in the -*- file’s line. This controls both loading or compiling the file and evaluation or compilation in the editor while visiting the file. Readtable: Traditional; specifies the use of traditional syntax and function definitions. If neither attribute is present, the file is processed using whatever syntax is selected in the process that loads it. See file-attribute-list.

Reading and printing done by programs are controlled by the same things that control reading of programs. They can also be controlled explicitly by binding the variable readtable.

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.

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

The print name is a string, which may be obtained by the function symbol-name (symbol-name-fun). This string serves as the printed representation (see printer) of the symbol.

Each symbol has a value, which may be any Lisp object. This is the value of the symbol when regarded as a dynamic variable. 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 value. 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 value is, and use set to change its value.)

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^24 to 2^24-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. Floats are floating-point numbers. Short floats are another kind of floating-point numbers, with less range and precision, but less computational overhead. Ratios are exact rational numbers that are represented with a numerator and a denominator, which are integers. Complexnums are numbers that have explicitly represented real and imaginary parts, which can be any real numbers of the same type. See number for full details of these types and the conversions between them.

A character object is much like a fixnum except that its type is distinguishable. Common Lisp programs use character objects to represent characters. Traditional programs usually use fixnums to represent characters, although they can create an manipulate character objects when they desire. Character objects behave like fixnums when used in arithmetic; only a few operations make any distinction. They do, however, print distinctively. See characters for more information.

The usual form of compiled, executable code is a Lisp object, called a “Function Entry Frame” or “FEF” for historical reasons. 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 kind of Lisp object that represents executable code is a “microcode entry”. These are the microcoded primitive functions of the Lisp system, and any 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 that may contain any object, while others (numeric arrays) may only contain small positive numbers. Strings are a type of array; the elements are character objects.

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 Data Type Predicates

A predicate is a function that 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. The following predicates are for testing what data type an object has.

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

t if object is a symbol, otherwise nil.

Function: nsymbolp object ¶

nil if object is a symbol, otherwise t.

Function: listp object ¶

t if object 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 to work like cli:listp. Since the current definition of listp is identical to that of consp, all uses of listp should be changed to consp unless the treatment of nil is not of concern.]

Function: cli:listp object ¶

The Common Lisp version of listp returns t if object is nil or a cons.

Function: nlistp object ¶

t if object is anything besides a cons, otherwise nil. (nlistp nil) returns t.

[This may be changed in the future, if and when listp is changed. Since the current definition of nlistp is identical to that of atom, all uses of nlistp should be changed to atom unless the treatment of nil is not of concern.]

Function: atom object ¶

t if object is not a cons, otherwise nil. This is the same as (not (consp object)).

Function: consp object ¶

t if object is a cons, otherwise nil. At the moment, this is the same as listp; but while listp may be changed, consp will never be true of nil.

Function: numberp object ¶

t if object is any kind of number, otherwise nil.

Function: integerp object ¶

Function: fixp object ¶

Return t if object is a representation of an integer, i.e a fixnum or a bignum, otherwise nil.

Function: floatp object ¶

t if object is a floating-point number, i.e a full-size or short float, otherwise nil.

Function: fixnump object ¶

t if object is a fixnum, otherwise nil.

Function: bigp object ¶

t if object is a bignum, otherwise nil.

Function: flonump object ¶

t if object is a full-size float, otherwise nil.

Function: small-floatp object ¶

t if object is a short float, otherwise nil.

Function: rationalp object ¶

t if object is an exact representation of a rational number; that is, if it is a fixnum, a bignum or a ratio. Otherwise nil.

Function: complexp object ¶

t if object is a complexnum, a number explicitly represented as complex. Otherwise nil.

Function: realp object ¶

t if object is a number whose value is real, otherwise nil. Any fixnum, bignum, float (of either format) or ratio satisfies this predicate. So does a complexnum whose imaginary part is zero.

Function: characterp object ¶

t if object is a character object, otherwise nil.

Function: stringp object ¶

t if object is a string, otherwise nil.

Function: arrayp object ¶

t if object is an array, otherwise nil. Note that strings are arrays.

Function: vectorp object ¶

t if object is an array of rank 1.

Function: bit-vector-p object ¶

t if object is an array of rank 1 that allows only 0 and 1 as elements.

Function: simple-vector-p object ¶

t if object is an array of rank 1, with no fill pointer and not displaced, that can have any Lisp object as an element.

Function: simple-bit-vector-p object ¶

t if object is an array of rank 1, with no fill pointer and not displaced, that allows only 0 and 1 as elements.

Function: simple-string-p object ¶

t if object is a string with no fill pointer and not displaced.

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

t if object is a function (essentially, something that is acceptable as the first argument to apply), otherwise 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 that can be called as functions but are not normally thought of as functions: arrays, stack groups, entities, and instances. 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.

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.

Function: compiled-function-p object ¶

Function: subrp object ¶

t if object is any compiled code object, otherwise nil. The name subrp is for Maclisp compatibility.

Function: special-form-p symbol ¶

t if symbol is defined as a function that takes some unevaluated args. Macros do not count as special forms.

macro-function can be used to test whether a symbol is defined as a macro, but you must be careful because it also returns a non-nil value for certain special forms. See the definition macro-function (macro-function-fun) to find out how to do this properly.

Function: closurep object ¶

t if object is a closure, otherwise nil.

Function: entityp object ¶

t if object is an entity, otherwise nil. See entity for information about entities.

Function: locativep object ¶

t if object is a locative, otherwise nil.

Function: commonp object ¶

t if object is of a type that Common Lisp defines operations on. See the type specifier common (common-type-spec).

Other standard type predicates include packagep (see packagep-fun), random-state-p (see random-state-p-fun), hash-table-p (hash-table-p-fun), pathnamep (pathnamep-fun), streamp (streamp-fun) and readtablep (readtablep-fun). defstruct can define additional type predicates automatically (defstruct-predicates).

2.3 Type Specifiers

Data types can be represented symbolically by Lisp objects called type specifiers. A type specifier describes a class of possible Lisp objects; the function typep tells whether a given object matches a given type specifier.

Built-in type specifiers exist for the actual Lisp Machine data types. The user can define additional type specifiers to represent arbitrary classifications of data. Type specifiers can also be combined into specifiers for more complex types.

Some type specifiers are symbols: for example, number, cons, symbol, integer, character, compiled-function, array, vector. Their meanings are mostly obvious, but a table follows below. Type specifiers that are symbols are called simple type specifiers.

Lists can also be type specifiers. They are usually combinations or restrictions of other type specifiers. The car of the list is the key to understanding what it means. An example of a combination is (or array symbol), which matches any array or any symbol. An example of a restriction type is (integer 0 6), which matches only integers between 0 and 6 (inclusive).

• Standard Type Specifiers
• User-Defined Type Specifiers
• Testing Types with Type Specifiers
• Coercion with Type Specifiers
• Comparing Type Specifiers

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 a symbol is evaluated, its value as a variable is taken.

• Variables and Bindings
• Setting Variables
• Variable Binding Constructs
• Defining Global Variables
• The Global Binding

(let ((a 5))
  (print a)         ;prints 5
  (let ((a "foo"))
    (print a)       ;prints "foo"
    (setq a "bar")
    (print a))      ;prints "bar"
  (print a))        ;prints 5

(defvar a 5)   ;sets the global binding

(let ((a t))
  (print a))   ;prints t

a => 5         ;the global binding is visible again

(defun foo ()
  (print a))

(let ((a 5))
  (foo))

>>Error: the variable A is used free but not special.

(defvar a)

(defun foo () (print a))

(let ((a 5))
  (foo))

(defun foo ()
  (declare (special a))
  (print a))

(let ((a 5))
  (declare (special a))
  (foo))

(let ((a 5))             ;this binding is dynamic
  (declare (special a))
  (let ((a "foo"))       ;this binding is lexical
    no declaration here
    ... a ...            ;this reference is lexical since
    ...                  ; the innermost binding is lexical
    (let ()
      (declare (special a))
      ... a ...          ;this reference is dynamic, and sees value 5
    ...))

(let ((*read-base* 16.))
  (read))

(let ((a nil))
  (mapatoms (function (lambda (symbol) (push symbol a))))
  a)

(defun mycons (a d)
  (function (lambda (x)
	      (cond ((eq x 'car) a)
		    ((eq x 'cdr) d)))))

(defun mycar (x) (funcall x 'car))
(defun mycdr (x) (funcall x 'cdr))

(setq mc (mycons 4 t))

(mycar mc)  =>  4
(mycdr mc)  =>  t

3.2 Generalized Variables

In Lisp, a variable is something that can remember one piece of data. The primary conceptual operations on a variable are to recover that piece of data and to change it. These might be called access and update. The concept of variables named by symbols, explained above, can be generalized to any storage location that can remember one piece of data, no matter how that location is named.

For each kind of generalized variable, there are typically three functions which implement the conceptual access, update and locate operations. For example, symeval accesses a symbol’s value cell, set updates it, and value-cell-location returns the value cell’s location. array-leader accesses the contents of an array leader element, store-array-leader updates it, and ap-leader returns the location of the leader element. car accesses the car of a cons, rplaca updates it, and car-location returns the location of the car.

Rather than thinking of this as two functions, which operate on a storage location somehow deduced from their arguments, we can shift our point of view and think of the access function as a name for the storage location. Thus (symeval 'foo) is a name for the value of foo, and (aref a 105) is a name for the 105th element of the array a. Rather than having to remember the update function associated with each access function, we adopt a uniform way of updating storage locations named in this way, using the setf special form. This is analogous to the way we use the setq special form to convert the name of a variable (which is also a form which accesses it) into a form that updates it. In fact, setf is an upward compatible generalization of setq. Similarly, the location of the generalized variable can be obtained using the locf construct.

• setf
• locf

(setf (car x) y)

3.3 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 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 signaled. 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 get an error because 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 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, more readable styles of call.

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 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; all keyword parameters are optional.

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 is 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 algorithm used to match up the arguments with the parameters:

Required positional parameters:

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 which have not been bound yet, it is an error (“too few arguments”).

Optional positional parameters:

After all required parameters are handled, apply continues with the optional positional parameters, if any. It binds each 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.

After the positional parameters:

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 signaled (“too many arguments”). If parameters remain, all the remaining arguments are used for both the rest parameter, if any, and the keyword parameters.

Rest parameter:

If there is a rest parameter, it is bound to a list of all the remaining arguments. If there are no remaining arguments, it is bound to nil.

Keyword parameters:

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 eq against the allowed parameter keywords, which have by default the same names as the parameters but in the keyword package. (You can specify the keyword symbol explicitly in the lambda list if you must; see below.) Often the symbol arguments are constants in the program, and it is convenient for this usage that keywords all evaluate to themselves, but it is permissible for them to be computed by expressions. If any keyword parameter has not received a value when all the arguments have been processed, the default-form for the parameter is evaluated and the parameter is bound to its value. All keyword parameters are optional. There may be a keyword symbol among the arguments which does not match any keyword parameter name. By default this is an error, but the lambda list can specify that there should be no error using &allow-other-keys. Also, if one of the keyword symbols among the arguments is :allow-other-keys and the value that follows it is non-nil then there is no error. When there is no error, for either reason, the non-matching symbols and their associated values are simply 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 apply; that function will check for the keywords that concern it.

The way you express which parameters are required, optional, rest and keyword 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 zero, one, two or three arguments.

(&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 keyword parameters. A typical call would look like

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

or

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

or

(foo :a '(some elements))

This illustrates that the parameters can be matched in either order, or omitted. If a keyword is specified twice, the first value is used.

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

x is required positional, y is optional positional, z is rest, and a and b are 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 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 were called on no arguments, a would be bound to the symbol foo, and c would be bound to the value 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.

Occasionally it is important to know whether a certain optional parameter was defaulted or not. Just by looking at the value one cannot distinguish between omitting it and passing the default value explicitly as an argument. 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 is bound to 3 and c is bound to nil. If the function is called with two arguments, b is bound to the value that was passed by the caller (which might be 3), and c is 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)) ((:b b) t))

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

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

This defines an argument which callers specify with the keyword :base, but which within the function is referred to as the variable base-value so as to avoid binding the value of base, which is a synonym for *print-base* and controls how numbers are printed.

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

You could, equivalently, use (a &optional b &rest c) as the lamda list and write (let* (d (e 5) (f (cons a e))) ...) around the body of the function.

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 a stack list (see stack-list) 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, copylist-fun), as you must always assume that it is one of these special lists. The system does 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 may 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 is unsafe in this case, while in the first case it would cause an error, since lists in the stack are impossible to rplacd.

Constant: lambda-parameters-limit ¶

Has as its value the limit on the number of parameters that a lambda list may have. The implementation limit on the number of parameters allowed is at least this many. There is no promise that this many is forbidden, but it is a promise that any number less than this many is permitted.

• Lambda-List Keywords
• Local Functions

3.4 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 form &optional nohook ¶

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

Example:

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

The dynamic bindings available at the time eval is called are visible for dynamic variables within the expression x. No lexical bindings are available for the evaluation of x.

It is unusual to call eval explicitly, 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, mathematics or games.

Also, if you are only interested in getting at the dynamic 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).

If the argument nohook is non-nil, execution of the evalhook is inhibited for form, but not for evaluation of the subforms of form. See evalhook, evalhook-fun. evalhook is also the way to evaluate in a specified lexical environment if you happen to have got your hands on one.

Note: in Maclisp, the second argument to eval is a “binding context pointer”. There is no such thing in Zetalisp; closures are used instead (see closure).

Function: si:eval1 form &optional nohook ¶

Within the definition of a special form, evaluates form in the current lexical environment.

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.

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: apply f &rest args ¶

Function: lexpr-funcall f &rest args ¶

apply is like funcall except that the last of args is really a list of arguments to give to f rather than a single argument. lexpr-funcall is a synonym for apply; formerly, apply was limited to the two argument case.

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

If there is more than one element of args, then all but the last of them are individual arguments to pass to f, while the last one is a list of arguments as above.

Examples:

(apply 'plus 1 1 1 '(1 1 1)) => 6

(defun report-error (&rest args)
   (apply 'format *error-output* args))

apply can also be used with a single argument. Then this argument is a list of a function and some arguments to pass it.

Example:

(apply '(car (a))) => a
      ;Not the same as (eval '(car (a)))

Note: in Maclisp, apply takes two or three arguments, and the third argument, when passed, is interpreted as a “binding context pointer”. So the second argument always provides all the args to pass to the function. There are no binding context pointers in Zetalisp; true lexical scoping exists and is interfaced in other ways.

Constant: call-arguments-limit ¶

Has as its value the limit on the number of arguments that can be dealt with in a function call. There is no promise that this many is forbidden, but it is a promise that any smaller number is acceptable.

Note that if apply is used with exactly two arguments, the first one being a function that takes a rest argument, there is no limit except the size of memory on the number of elements in the second argument to apply.

Function: call function &rest argument-specifications ¶

Offers a very general way of controlling what arguments you pass to a function. You can provide either individual arguments as in funcall or lists of arguments as in 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 object) simply returns object. quote is used to include constants in a form. It is useful specifically because object is not evaluated; the quote is how you make a form that returns an arbitrary Lisp object.

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 ¶

function has two distinct, though related, meanings.

If f is a symbol or any other function spec (see function-spec), (function f) refers to the function definition of f. For example, in (mapcar (function car) x), the function definition of car is passed as the first argument to mapcar. function used this way is like fdefinition except that its argument is unevaluated, and so

(function fred)  is like  (fdefinition 'fred)

f can also be an explicit function, or lambda-expression, a list such as (lambda (x) (* x x)) such as could be the function definition of a symbol. Then (function f) represents that function, suitably interfaced to execute in the lexical environment where it appears. To explain:

(let (a)
  (mapcar (lambda (x) (push x a)) l))

attempts to call the function lambda and evaluate (x) for its first argument. That is no way to refer to the function expressed by (lambda (x) (push x a)).

(let (a)
  (mapcar (quote (lambda (x) (push x a))) l))

passes to mapcar the list (lambda (x) (push x a)). This list does not in any way record the lexical environment where the quote form appeared, so it is impossible to make this environment, with its binding of a, available for the execution of (push x a). Therefore, the reference to a does not work properly.

(let (a)
  (mapcar (function (lambda (x) (push x a))) l))

passes mapcar a specially designed closure made from the function represented by (lambda (x) (push x a)). When mapcar calls this closure, the lexical environment of the function form is put again into effect, and the a in (push x a) refers properly to the binding made by this let.

In addition, the compiler knows that the argument to function should be compiled. The argument of quote cannot be compiled since it may be intended for other uses.

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. The last example could be written as

(let (a)
  (mapcar #'(lambda (x) (push x a)) l))

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, as that would be difficult to make sense of. Instead, write

(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 test function, there are two things you could say:

(setq x 'test)

or

(setq x #'test)

The former causes the value of x to be the symbol test, whereas the latter causes the value of x to be the function object found in the function cell of test. When the time comes to call the function (the program does (funcall x ...)), either expression works because calling a symbol as a function uses its function definition instead. Using 'test is insignificantly 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). Use of #' picks up the function definition out of the symbol test when the setq is done and does not see any later changes to it. #' should be used only if you wish specifically to prevent redefinition of the function from affecting this closure.

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. It is most useful for commenting out function definitions that are not needed or correct but worth preserving in the source. The #|...|# syntactic construct is an alternative method. For comments within code about the code, it is better to use semicolons.

Example:

(comment
;; This is brain-damaged.  Can someone figure out
;; how to do this right?
(defun foo (x)
  ...)
) ;End comment
;; prevents this definition of foo from being used.

3.5 Declarations

Declarations provide auxiliary information on how to execute a function or expression properly. The most important declarations are special declarations, which control the scope of variable names. Some declarations do not affect execution at all and only provide information about a function, for the sake of arglist, for example.

Declarations may apply to an entire function or to any expression within it. Declarations can be made around any subexpression by writing a local-declare around the subexpression or by writing a declare at the front of the body of certain constructs. Declarations can be made on an entire function by writing a declare at the front of the function’s body.

Special Form: local-declare (declaration...) body... ¶

A local-declare form looks like

(local-declare (decl1 decl2 ...)
   form1
   form2
   ...)

Each decl is in effect for the forms in the body of the local-declare form.

Special Form: declare declaration... ¶

The special form declare is used for writing local declarations within the construct they apply to.

A declare inside a function definition, just after the argument list, is equivalent to putting a local-declare around the function definition. More specifically,

(defun foo (a b)
  (declare (special a b))
  (bar))

is equivalent to

(local-declare ((special a b))
(defun foo (a b)
  (bar)))

Note that

(defun foo (a b)
  (local-declare ((special a b))
    (bar)))

does not do the job, because the declaration is not in effect for the binding of the arguments of foo.

declare is preferable to local-declare in this sort of situation, because it allows the defuns themselves to be the top-level lists in the file. While local-declare might appear to have an advantage in that one local-declare may go around several defuns, it tends to cause trouble to use local-declare in that fashion.

declare has a similar meaning at the front of the body of a progn, prog, let, prog*, let*, or internal lambda. For example,

(prog (x)
      (declare (special x))
      ...)

is equivalent to

(local-declare ((special x))
  (prog (x)
        ...))

At top level in the file, (declare forms...) is equivalent to (eval-when (compile) forms...). This use of declare is nearly obsolete, and should be avoided. In Common Lisp, proclaim (below) is used for such purposes, with a different calling convention.

Elsewhere, declare’s are ignored.

Here is a list of declarations that have system-defined meanings:

(special var1 var2 ...)

The variables var1, var2, etc will be treated as special variables in the scope of the declaration.

(unspecial var1 var2 ...)

The variables var1, var2, etc will be treated as lexical variables in the scope of the declaration, even if they are globally special.

(notinline fun1 fun2 ...)

The functions fun1, fun2 and so on will not be open coded or optimized by the compiler within the scope of the declaration.

(inline fun1 fun2 ...)

The functions fun1, fun2 and so on will be open coded or optimized by the compiler (to whatever extent it knows how) within the scope of the declaration. Merely issuing this declaration does not tell the compiler how to do any useful optimization or open coding of a function.

(ignore var1 var2 ...)

Says that the variables var1, var2, etc, which are bound in the construct in which this declaration is found, are going to be ignored. This is currently significant only in a function being compiled; the compiler issues a warning if the variables are used, and refrains from its usual warning if the variables are ignored.

(declaration decl1 decl2 ...)

Says that declarations decl1, decl2, etc are going to be used, and prevents any warning about an unrecognized type of declaration. For example:

(defun hack ()
  (declare (declaration lose-method)
	   (lose-method foo bar))
  ... (lose foo) ...)

might be useful if (lose foo) is a macro whose expander function does (getdecl 'foo 'lose-method) to see what to do. See getdecl-fun for more information on getdecl and declarations.

(proclaim '(declaration lose-method))

might also be advisable if you expect widespread use of lose-method declarations.

The next two are used by the compiler and generally should not be written by users.

(def name . definition)

name will be defined for the compiler in the scope of the declaration. The compiler uses this automatically to keep track of macros and open-codable functions (defsubsts) defined in the file being compiled. Note that the cddr of this item is a function.

(propname symbol value)

(getdecl symbol propname) will return value in the scope of the declaration. This is how the compiler keeps track of defdecls.

These declarations are significant only when they apply to an entire defun.

(arglist . arglist)

Records arglist as the argument list of the function, to be used instead of its lambda list if anyone asks what its arguments are. This is purely documentation.

(values . values) or (:return-list . values)

Records values as the return values list of the function, to be used if anyone asks what values it returns. This is purely documentation.

(sys:function-parent parent-function-spec)

Records parent-function-spec as the parent of this function. If, in the editor, you ask to see the source of this function, and the editor doesn’t know where it is, the editor will show you the source code for the parent function instead.

For example, the accessor functions generated by defstruct have no defuns of their own in the text of the source file. So defstruct generates them with sys:function-parent declarations giving the defstruct’s name as the parent function spec. Visiting the accessor function with Meta- sees the declaration and therefore visits the text of the defstruct.

(:self-flavor flavorname)

Instance variables of the flavor flavorname, in self, will be accessible in the function.

Macro: locally &body body ¶

Executes the body, recognizing declarations at the front of it. locally is synonymous with progn except that in Common Lisp a declare is allowed at the beginning of a locally and not at the beginning of a progn.

locally does differ from progn in one context: at top level in a file being compiled, progn causes each of its elements (including declarations, therefore) to be treated as if at top level. locally does not receive this treatment. The locally form is simply evaluated when the QFASL file is loaded.

Function: proclaim &rest declarations ¶

Each of declarations is put into effect globally. Currently only special and unspecial declarations mean anything in this way. proclaim’s arguments are evaluated, and the values are expected to be declarations such as you could write in a declare. Thus, you would say (proclaim '(special x)) to make a special declaration globally.

Top-level special declarations are not the recommended way to make a variable special. Use defvar, defconstant or defparameter, so that you can give the variable documentation. Proclaiming the variable special should be done only when the variable is used in a file other than the one which defines it, to enable the file to be compiled without having to load the defining file first.

proclaim is fairly new. Until recently, top-level declare was the preferred way to make global special declarations when defvar, etc, could not be used. Such top-level declare’s are still quite common. In them, the declaration would not be quoted; for example, (declare (special x)).

Special Form: special variables... ¶

Equivalent to (proclaim (special variables...)), this declares each of the variables to be globally special. This function is obsolete.

Special Form: unspecial variables... ¶

Removes any global special declarations of the variables. This function is obsolete.

Macro: the type-specifier value-form ¶

Is a Common Lisp construct effectively the same as value-form. It declares that the value of value-form is an object which of type type-specifier. This is to assist compilers in generating better code for conventional machine architectures. The Lisp Machine does not make use of type declarations so this is the same as writing just value-form. type-specifier is not evaluated.

If you want the type of an object to be checked at run time, with an error if it is not what it is supposed to be, use check-type (check-type-fun).

3.6 Tail Recursion

When one function ends by calling another function (possibly itself), as in

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

it is called tail recursion. In general, 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 we say that X tail-recursively evaluates Y.

In a tail recursive situation, it is not strictly necessary to remember anything about the first call to last when the second one is activated. The stack frame for the first call can be discarded completely, allowing last to use a bounded amount of stack space independent of the length of its argument. A system which does this is called tail recursive.

The Lisp machine system works tail recursively if the variable tail-recursion-flag is non-nil. This is often faster, because it reduces the amount of time spent in refilling the hardware’s pdl buffer. However, you forfeit a certain amount of useful debugging information: once the outer call to last has been removed from the stack, you can no longer see its frame in the debugger.

Variable: tail-recursion-flag ¶

If this variable is non-nil, the calling stack frame is discarded when a tail-recursive call is made in compiled code.

There are many things which a function can do that can make it dangerous to discard its stack frame. For example, it may have done a *catch; it may have bound special variables; it may have a &rest argument on the stack; it may have asked for the location of an argument or local variable. The system detects all of these conditions automatically and retains the stack frame to ensure proper execution. Some of these conditions occur in eval; as a result, interpreted code is never completely tail recursive.

3.7 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 returns three values. Many system functions produce multiple values, but they all do it via values.

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. Equivalent to (apply 'values list).

return and its variants can also be used, within a block, do or prog special form, to return multiple values. They are explained on return-fun.

Here are the special forms for receiving multiple values.

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

Special Form: multiple-value-setq (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, 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 (setting nil is not allowed anyway).

Example:

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

In addition to its first value (the symbol), intern returns a second value, which is non-nil if an existing symbol was found, or else nil if intern had to create one. So if the symbol goo was already known, the variable already-there-p is set non-nil, otherwise it is set to nil. The third value returned by intern is ignored by this form of call since there is no third variable in the multiple-value.

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.

multiple-value-setq is the Common Lisp name for this construct. The two names are equivalent.

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.

Example:

(multiple-value-bind (sym already-there)
    (intern string)
  ;; If an existing symbol was found, deallocate the string.
  (if already-there
      (return-storage (prog1 string (setq string nil))))
  sym)

Special Form: multiple-value-call function argforms... ¶

Evaluates the argforms, saving all of their values, and then calls function with all those values as arguments. This differs from

(funcall function argforms...)

because that would get only one argument for function from each argform, whereas multiple-value-call gets as many args from each argform as the argform cares to return. This works by consing a list of all the values returned, and applying function to it. Example:

(multiple-value-call 'append
      (values '(a b) '(c d))
      '(e f))
   =>  (a b c d e f)

Special Form: multiple-value-prog1 form forms... ¶

Evaluates form, saves its values, evaluates the forms, discards their values, then returns whatever values form produced. This does not cons. Example:

(multiple-value-prog1 (values 1 2)
      (print 'foo))
   =>  1 2

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

This is similar to the example of multiple-value above; a is set to a list of three elements, the three values returned by intern.

Special Form: nth-value n form ¶

Evaluates form and returns its value number n, n = 0 meaning the first value. For example, (nth-value 1 (foo)) returns the second of foo’s values. nth-value operates without consing in compiled code if the first argument’s value is known at compile time.

When one form finished by tail recursively evaluating a subform (see tail-recursion), all of the subform’s multiple values are passed back by the outer form. For example, the value of a cond is the value of the last form in the selected clause. If the last form in that clause produces multiple values, so does the cond. This passing-back of multiple values of course has no effect unless eventually one of the special forms for receiving multiple values is reached.

If the outer form returns a value computed by a subform, but not in a tail recursive fashion (for example, if the value of the subform is examined first), 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 pass multiple values if an optimizing compiler realized that the setq’ing of the variable was unnecessary. Since extra returned values are generally ignored, it is not vital to eliminate them.

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 is still called on only 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. To pass all returned values to another function, use multiple-value-call, above.

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 actually 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 and 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 only from the last subform of an and or an or form, not from previous subforms since the return is conditional. Remember that multiple values are only passed back when the value of a subform 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 is 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, provided that that last form’s value is returned unconditionally. This is true if the clause has two or more forms in it, and is always true for the last clause.

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

If a block form falls through the end, it returns all the values returned by the last expression in it. If return-from or return is used to exit a block form, then the values returned by the block form depend on the kind of return. If return is given two or more subforms, then block returns as many values as the return has subforms. However, if the return has only one subform, then the block returns all of the values returned by that one subform.

prog behaves like block if it is exited with return (or return-from). If control falls through the end of a prog, it returns the single value nil. do also behaves like block with respect to return, but if it is exited through the exit test, all the values of the last exit-form are returned.

unwind-protect passes back multiple values from its protected form. In a sense, this is an exception to the rule; but it is useful, and it makes sense to consider the execution of the unwind forms as a byproduct of unwinding the stack and not as part of sequential execution.

catch passes back multiple values from the last form in its body, if it exits normally. If a throw is done, multiple values are passed back from the value form in the throw.

Constant: multiple-values-limit ¶

The smallest number of values that might possibly fail to work. Returning a number of values less than this many cannot possibly run into trouble with an implementation limit on number of values returned.

3.8 Evaluation and Function Calling Errors

Here is a description of the error conditions that the evaluator can signal. Some can be signaled by calls to compiled functions also. This is for use by those who are writing condition handlers (condition-handlers). The novice should skip this section.

Condition on sys:invalid-function: (error) ¶

This is signaled when an object that is supposed to be applied to arguments is not a valid Lisp function. The condition instance supports the operation :function, which returns the supposed function to be called.

The :new-function proceed type is provided; it expects one argument, a function to call instead.

Condition on sys:invalid-lambda-list: (sys:invalid-function error) ¶

This condition name is present in addition to sys:invalid-function when the function to be called looks like an interpreted function, and the only problem is the syntax of its lambda list.

Condition on sys:too-few-arguments: (error) ¶

This condition is signaled when a function is applied to too few arguments. The condition instance supports the operations :function and :arguments which return the function and the list of the arguments provided.

The proceed types :additional-arguments and :new-argument-list are provided. Both take one argument. In the first case, the argument is a list of arguments to pass in addition to the ones supplied. In the second, it is a list of arguments to replace the ones actually supplied.

Condition on sys:too-many-arguments: (error) ¶

This is similar to sys:too-few-arguments. Instead of the :additional-arguments proceed type, :fewer-arguments is provided. Its argument is a number, which is how many of the originally supplied arguments to use in calling the function again.

Condition on sys:undefined-keyword-argument: (error) ¶

This is signaled when a function that takes keyword arguments is given a keyword that it does not accept, if &allow-other-keys was not used in the function’s definition and :allow-other-keys was not specified by the caller (see allow-other-keys-kwd). The :keyword operation on the condition instance returns the extraneous keyword, and the :value operation returns the value supplied with it.

The proceed type :new-keyword is provided. It expects one argument, which is a keyword to use instead of the one supplied.

Flavor Condition on sys:cell-contents-error: (error) ¶

This condition name categorizes all the errors signaled because of references to void memory locations. It includes “unbound” variables, “undefined” functions, and other things.

:address

A locative pointer to the referenced cell.

:current-address

A locative pointer to the cell which currently contains the contents that were found in the referenced cell when the error happened. This can be different from the original address in the case of dynamic variable bindings, which move between special PDLs and symbol value cells.

:cell-type

A keyword saying what type of cell was referred to: :function, :value, :closure, or nil for a cell that is not one of those.

:containing-structure

The object (list, array, symbol) inside which the referenced memory cell is found.

:data-type

:pointer

The data type and pointer fields of the contents of the memory cell, at the time of the error. Both are fixnums.

The proceed type :no-action takes no argument. If the cell’s contents are now valid, the program proceeds, using them. Otherwise the error happens again.

The proceed type :package-dwim looks for symbols with the same name in other packages; but only if the containing structure is a symbol.

Two other proceed types take one argument: :new-value and :store-new-value. The argument is used as the contents of the memory cell. :store-new-value also permanently stores the argument into the cell.

Condition on sys:unbound-variable: (sys:cell-contents-error error) ¶

This condition name categorizes all errors of variables whose values are void.

Condition on : sys:unbound-special-variable ¶

Condition on : sys:unbound-closure-variable ¶

Condition on : sys:unbound-instance-variable ¶

These condition names appear in addition to sys:unbound-variable to subcategorize the kind of variable reference that the error happened in.

Condition on sys:undefined-function: (sys:cell-contents-error error) ¶

This condition name categorizes errors of function specs that are undefined.

Condition on sys:wrong-type-argument: (error) ¶

This is signaled when a function checks the type of its argument and rejects it; for example, if you do (car 1).

The condition instance supports these extra operations:

:arg-name

The name of the erroneous argument. This may be nil if there is no name, or if the system no longer remembers which argument it was.

:old-value

The value that was supplied for the argument.

:function

The function which received and rejected the argument.

:description

A type specifier which says what sort of object was expected for this argument.

The proceed type :argument-value is provided; it expects one argument, which is a value to use instead of the erroneous value.

4.1 Compound Statements

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

Example:

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

Lambda-expressions, cond forms, do forms, and many other control structure forms use progn implicitly, that is, they allow multiple forms in their bodies.

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.

4.2 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; if the predicate returns nil, they are evaluated sequentially and the result of the last one is returned.

Macro: when condition body... ¶

If condition evaluates to something non-nil, the body is executed and its value(s) returned. Otherwise, the value of the when is nil and the body is not executed.

Macro: unless condition body... ¶

If condition evaluates to nil, the body is executed and its value(s) returned. Otherwise, the value of the unless is nil and the body is not executed.

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 condition, followed by zero or more body forms.

(cond (condition body body...)
      (condition)
      (condition body ...)
      ... )

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

cond processes its clauses in order from left to right. First, the condition of the current clause is evaluated. If the result is nil, cond advances to the next clause. Otherwise, the cdr of the clause is treated as a list of body forms which are evaluated in order from left to right. After evaluating the body forms, cond returns without inspecting any remaining clauses. The value of the cond form is the value of the last body form evaluated, or the value of the condition if there were no body forms in the clause. If cond runs out of clauses, that is, if every condition 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 condition.
                    ; (+ y 3) is the body.
      ((null y)     ;A clause with 2 body forms:
       (setq y 4)   ; this
       (cons x z))  ; and this.
      (z)           ;A clause with no body forms: the condition is 
                    ; just z.  If z is non-nil, it is returned.
      (t            ;A condition of t
       105)         ; is always satisfied.
   )                ;This is the end of the cond.

Macro: cond-every ¶

cond-every has the same syntax as cond, but executes every clause whose condition is satisfied, not just the first. If a condition is the symbol otherwise, it is satisfied if and only if no preceding condition is satisfied. The value returned is the value of the last body form in the last clause whose condition 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:

(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 void.

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

but when is usually preferable.

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)

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

but it is often possible and cleaner to use unless in the latter case.

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

Macro: selectq ¶

Macro: case ¶

Macro: caseq ¶

selectq is a conditional which chooses one of its clauses to execute by comparing the value of a form against various constants using eql. Its form is as follows:

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

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 body of the clause is evaluated, and selectq returns the value of the last body form. If there are no matches, selectq returns nil.

A test may be any of:

1) A symbol

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

2) A number

If the key is eql to the number, it matches. key must have the same type and the same value as the number.

3) A list

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

4) t or otherwise

The symbols t and otherwise are special tests 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.

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

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

case is the Common Lisp name for this construct. caseq is the Maclisp name; it identical to selectq, which is not totally 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 work correctly so long as they don’t use the symbol otherwise as a key.

Macro: ecase key-form clauses... ¶

Like case except that an uncorrectable error is signaled if every clause fails. t or otherwise clauses are not allowed.

Macro: ccase place clauses... ¶

Like ecase except that the error is correctable. The first argument is called place because it must be setf’able. If the user proceeds from the error, a new value is read and stored into place; then the clauses are tested again using the new value. Errors repeat until a value is specified which makes some clause succeed.

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

Macro: select ¶

select is like 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)))

Macro: selector ¶

selector is like 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))))

Macro: select-match ¶

select-match is like select but each clause can specify a pattern to match the key against. The general form of use looks like

(select-match key-form
  (pattern condition body...)
  (pattern condition body...)
  ...
  (otherwise body...))

The value of key-form is matched against the patterns one at a time until a match succeeds and the accompanying condition evaluates to something non-nil. At this point the body of that clause is executed and its value(s) returned. If all the patterns/conditions fail, the body of the otherwise clause (if any) is executed. A pattern can test the shape of the key object, and set variables which the condition form can refer to. All the variables set by the patterns are bound locally to the select-match form.

The patterns are matched using list-match-p (list-match-p-fun).

Example:

(select-match '(a b c) 
  (`(,x b ,x) t (vector x))
  (`((,x ,y) b . ,ignore) t (list x y))
  (`(,x b ,y) (symbolp x) (cons x y))
  (otherwise 'lose-big))

returns (a . c), having checked (symbolp 'a). The first clause matches only if the there are three elements, the first and third elements are equal and the second element is b. The second matches only if the first element is a list of length two and the second element is b. The third clause accepts any list of length three whose second element is b. The fourth clause accepts anything that did not match the previous clauses.

select-match generates highly optimized code using special instructions.

Macro: 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 (byte 2 13) 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 is dispatched on.

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

• Comparison Predicates

4.3 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, new-style and old-style. The old-style do is obsolete and exists for Maclisp compatibility only. The more general, “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 is not executed.

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 resulting infinite loop can be terminated by use of return or throw.

do implicitly creates a block with name nil, so return can be used lexically within a do to exit it immediately. This unbinds the do variables and the do form returns whatever values were specified in the return form. See block-and-return-section for more information on these matters. The body of the do is actually treated as a tagbody, so that it may contain go tags (see go-to), but this usage is discouraged as it is often unclear.

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’d 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.

The body of a do may contains 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. For example,

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

The old-style do exists only for Maclisp compatibility. It 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.

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 let* is to let.

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 of 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 is the car of x. The same construction with do might get an error on entry since x might not be bound yet.

Special Form: do-named ¶

do-named is like do but defines a block with a name explicitly specified by the programmer in addition to the block named nil which every do defines. This makes it possible to use return-from to return from this do-named even from within an inner do. An ordinary return there would return from the inner do instead. do-named is obsolete now that block, which is more general and more coherent, exists. See block-and-return-section for more information on block and return-from.

The syntax of do-named is like do except that the symbol do-named is immediately followed by the block 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))
    ...))

is equivalent to

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

t as the name of a do-named behaves somewhat peculiarly, and therefore should be avoided.

Special Form: do*-named ¶

This special form offers a combination of the features of do* and those of do-named. It is obsolete, as is do-named, since it is cleaner to use block.

Macro: dotimes (index count [value-expression]) 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. When the count is exhausted, the value of value-expression is returned; or nil, if value-expression is missing.

Example:

(dotimes (i (truncate m n))
  (frob i))

is equivalent to:

(do ((i 0 (1+ i))
     (count (truncate 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 (truncate m n) rather than after. You can use return and go and tagbody-tags inside the body, as with do. dotimes forms return the value of value-expression, or 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.

Macro: dolist (item list [value-expression]) 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. If the list is exhausted, the value of value-expression is returned; or nil, if value-expression is missing.

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 tagbody-tags inside the body, as with do.

Macro: do-forever body... ¶

Executes the forms in the body over and over, or until a non-local exit (such as return).

4.4 Static Non-Local Exits

The static non-local exit allows code deep within a construct to jump to the end of that construct instantly, not executing anything except unwind-protect’s on the way. The construct which defines a static level that can be exited non-locally is called block and the construct which exits it is called return-from. The block being exited must be lexically visible from the return-from which says to exit it; this is what ‘static’ means. By contrast, catch and throw provide for dynamic non-local exits; refer to the following section. Here is an example of using a static non-local exit:

(block top
  (let ((v1 (do-1)))
    (when (all-done v1) (return-from top v1))
    (do-2))
  (do-3)
  ...
  (do-last))

If (all-done v1) returns non-nil, the entire block immediately returns the value of v1. Otherwise, the rest of the body of the block is executed sequentially, and ultimately the value or values of (do-last) are returned.

Note that the return-from 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-from foo 3)), because when the return-from form is evaluated, the containing block is immediately exited, and the setq never happens.

The fact that block’s and return-from’s are matched up lexically means you cannot do this:

(defun foo (a)
  (block foo1
    (bar a)))

(defun bar (x)
  (return-from foo1 x))

The (return-from foo1 x) gets an error because there is no lexically visible block named foo1. The suitable block in the caller, foo, is not even noticed.

Static handling allows the compiler to produce good code for return-from. It is also useful with functional arguments:

(defun first-symbol (list)
  (block done
    (mapc #'(lambda (elt)
	      (if (symbolp elt) (return-from done elt)))
	  list)))

The return-from done sees the block done lexically. Even if mapc had a block in it named done it would have no effect on the execution of first-symbol.

When a function is defined with defun with a name which is a symbol, a block whose name is the function name is automatically placed around the body of the function definition. For example,

(defun foo (a)
  (if (evenp a) 
      (return-from foo (list a)))
  (1+ a))

(foo 4) => (4)
(foo 5) => 6

A function written explicitly with lambda does not have a block unless you write one yourself.

A named prog, or a do-named, implicitly defines a block with the specified name. So you can exit those constructs with return-from. In fact, the ability to name prog’s was the original way to define a place for return-from to exit, before block was invented.

Every prog, do or loop, whether named or not, implicitly defines a block named nil. Thus, named prog’s define two block’s, one named nil and one named whatever name you specify. As a result, you can use return (an abbreviation for return-from nil) to return from the innermost lexically containing prog, do or loop (or from a block nil if you happen to write one). This function is like assq, but it returns an additional value which is the index in the table of the entry it found. For example,

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

There is one exception to this: a prog, do or loop with name t defines only the block named t, no block named nil. The compiler used to make use of this feature in expanding certain built-in constructs into others.

Special Form: block name body... ¶

Executes body, returning the values of the last form in body, but permitting non-local exit using return-from forms present lexically within body. name is not evaluated, and is used to match up return-from forms with their block’ss.

(block foo
  (return-from foo 24) t) => 24
(block foo t) => t

Special Form: return-from name values ¶

Performs a non-local exit from the innermost lexically containing block whose name is name. name is not evaluated. When the compiler is used, return-from’s are matched up with block’s at compile time.

values is evaluated and its values become the values of the exited block form.

A return-from form may appear as or inside an argument to a regular function, but if the return-from is executed then the function will never actually be called. For example,

(block done
  (foo (if a (return-from done t) nil)))

foo is actually called only if a’s value is nil. This style of coding is not recommended when foo is actually a function.

return-from can also be used with zero value forms, or with several value forms. Then one value is returned from each value form. Originally return-from always returned only one value from each value form, even when there was only one value form. Passing back all the values when there is a single values form is a later change, which is also the Common Lisp standard. In fact, the single value form case is much more powerful and subsumes all the others. For example,

(return-from foo 1 2)

is equivalent to

(return-from foo (values 1 2))

and

(return-from foo)

is equivalent to

(return-from foo (values))

It is unfortunate that the case of one value form is treated differently from all other cases, but the power of being able to propagate any number of values from a single form is worth it.

To return precisely one value, use (return-from foo (values form)). It is legal to write simply (return-from foo), which returns no values from the block. See multiple-value for more information.

Special Form: return values ¶

Is equivalent to (return-from nil values). It returns from a block whose name is nil.

In addition, break (see break-fun) recognizes the typed-in form (return value) specially. break evaluates value and returns it.

Special Form: return-list list ¶

This function is like return except that each element of list is returned as a separate value from the block that is exited.

return-list is obsolete, since (return (values-list list)) does the same thing.

4.5 Tags and Gotos

Jumping to a label or tag is another kind of static non-local exit. Compared with return-from, it allows more flexibility in choosing where to send control to, but does not allow values to be sent along. This is because the tag does not have any way of saying what to do with any values.

To define a tag, the tagbody special form is used. In the body of a tagbody, all lists are treated as forms to be evaluated (called statements when they occur in this context). If no goto happens, all the forms are evaluated in sequence and then the tagbody form returns nil. Thus, the statements are evaluated only for effect.

An element of the tagbody’s body which is a symbol is not a statement but a tag instead. It identifies a place in the sequence of statements which you can go to. Going to a tag is accomplished by the form (go tag), executed at any point lexically within the tagbody.

go transfers control immediately to the first statement following tag in its tagbody, pausing only to deal with any unwind-protects that are being exited as a result. If there are no more statements after tag in its tagbody, then that tagbody returns nil immediately.

All lexically containing tagbody’s are eligible to contain the specified tag, with the innermost tagbody taking priority. If no suitable tag is found, an error is signaled. The compiler matches go’s with tags at compile time and issues a compiler warning if no tag is found. Example:

(block nil
  (tagbody
    (setq x some frob)
  loop
    do something
    (if some predicate (go endtag))
    do something more
    (if (minusp x) (go loop))
  endtag
    (return z)))

is a kind of iteration made out of go-to’s. This tagbody can never exit normally because the return in the last statement takes control away from it. This use of a return and block is how one encapsulates a tagbody to produce a non-nil value.

It works to go from an internal lambda function to a tag in a lexically containing function, as in

(defun foo (a)
  (tagbody
   t1
    (bar #'(lambda () (go t1)))))

If bar ever invokes its argument, control goes to t1 and bar is invoked anew. Not very useful, but it illustrates the technique.

Special Form: tagbody statements-and-tags... ¶

Executes all the elements of statements-and-tags which are lists (the statements), and then returns nil. But meanwhile, all elements of statements-and-tags which are symbols (the tags) are available for use with go in any of the statements. Atoms other than symbols are meaningless in a tagbody.

The reason that tagbody returns nil rather than the value of the last statement is that the designers of Common Lisp decided that one could not reliably return a value from the tagbody by writing it as the last statement since some of the time the expression for the desired value would be a symbol rather than a list, and then it would be taken as a tag rather than the last statement and it would not work.

Special Form: go tag ¶

The go special form is used to “go-to” a tag defined in a lexically containing tagbody form (or other form which implicitly expands into a tagbody, such as prog, do or loop). tag must be a symbol. It is not evaluated.

Special Form: prog ¶

prog is an archaic special form which provides temporary variables, static non-local exits, and tags for go. These aspects of prog were individually abstracted out to inspire let, block and tagbody. Now prog is obsolete, as it is much cleaner to use let, block, tagbody or all three of them, or do or loop. But prog appears in so many programs that it cannot be eliminated.

A typical prog looks like (prog (variables...) body...), which is equivalent to

(block nil
  (let (variables...)
    (tagbody body...)))

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

(prog name (variables...) body...)

and is equivalent to

(block name
  (block nil
    (let (variables...)
      (tagbody body...))))

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. Thus, the equivalent code would use let* rather than let.

4.6 Dynamic 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 values of the last form are 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 values of 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) catches 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).

Any Lisp object may be used as a catch tag. The values t and nil for tag are special: a catch whose tag is one of these values catches throws regardless of 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. Example:

(catch 'negative
   (values
     (mapcar #'(lambda (x) 
		 (cond ((minusp x)
			(throw 'negative 
			  (values x :negative)))
		       (t (f x)) )))
	     y)
     :positive))

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

Macro: catch-continuation tag throw-cont non-throw-cont body... ¶

Macro: catch-continuation-if cond-form tag throw-cont non-throw-cont body... ¶

The catch-continuation special form makes it convenient to discriminate whether exit is normal or due to a throw.

The body is executed inside a catch on tag (which is evaluated). If body returns normally, the function non-throw-cont is called, passing all the values returned by the last form in body as arguments. This function’s values are returned from the catch-continuation.

If on the other hand a throw to tag occurs, the values thrown are passed to the function throw-cont, and its values are returned.

If a continuation is explicitly written as nil, it is not called at all. The arguments that would have been passed to it are returned instead. This is equivalent to using values as the function; but explicit nil is optimized, so use that.

catch-continuation-if differs only in that the catch is not done if the value of the cond-form is nil. In this case, the non-throw continuation if any is always called.

In the general case, consing is necessary to record the multiple values, but if a continuation is an explicit #'(lambda ...) with a fixed number of arguments, or if a continuation is nil, it is open coded and the consing is avoided.

Special Form: throw tag values-form ¶

throw is the primitive for exiting from a surrounding catch. tag is evaluated, and the result is matched (with eq) against the tags of all active catch’es; the innermost matching one is exited. If no matching catch is dynamically active, an error is signaled.

All the values of values-form are returned from the exited catch.

catch’es with tag nil always match any throw. They are really catch-all’s. So do catch’es with tag t, which are unwind-protect’s, but if the only matching catch’es are these then an error is signaled anyway. This is because an unwind-protect always throws again after its cleanup forms are finished; if there is nothing to catch after the last unwind-protect, an error will happen then, and it is better to detect the error sooner.

The values t, nil, and 0 for tag are reserved and used for internal purposes. nil may not be used, because it would cause confusion in handling of unwind-protect’s. t may only be used with *unwind-stack. 0 and nil are used internally when returning out of an unwind-protect.

Macro: *catch form tag ¶

Macro: *throw form tag ¶

Old, obsolete names for catch and throw.

Condition on sys:throw-tag-not-seen: (error) ¶

This is signaled when throw (or *unwind-stack) is used and there is no catch for the specified tag. The condition instance supports these extra operations:

:tag

The tag being thrown to.

:value

The value being thrown (the second argument to throw).

:count

:action

The additional two arguments given to *unwind-stack, if that was used.

The error occurs in the environment of the throw; no unwinding has yet taken place.

The proceed type :new-tag expects one argument, a tag to throw to instead.

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

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

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-protect’s receive control, but catch-all’s 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 facilities of Lisp create situations in which the above code won’t work, however: if hairy-function should use throw, return or go to transfer control 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 debugger 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 transfers control out of the evaluation of the unwind-protect, the (turn-off-water-faucet) form is evaluated during the transfer of control, before control arrives at the catch, block or go tag to which it is being transferred.

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 transfer control 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 catches a throw to any tag at all. Since the tag thrown to is one of the returned values, the caller of catch-all may continue throwing to that tag if he wants. The one thing that catch-all does 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.

catch-all returns all the values thrown to it, or returned by the body, plus three additional values: the tag thrown to, the active-frame-count, and the action. The tag value is nil if the body returned normally. The last two values are the third and fourth arguments to *unwind-stack (see *unwind-stack-fun) if that was used, or nil if an ordinary throw was done or if the body returned normally.

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

4.7 Mapping

Function: map fcn &rest lists ¶

Function: mapl 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 proceeds down the lists x1, x2, ..., xn in parallel. The first argument to f comes 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 f is called repeatedly without end. 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-fun.

There are five other mapping functions besides mapcar. maplist is like mapcar except that the function is applied to the list and successive cdrs of that list rather than to successive elements of the list. map (or mapl) 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 is 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(l)   |     mapc      |
             argument    |              |               |
          ---------------+--------------+---------------+
            list of the  |              |               |
returns      function    |    maplist   |    mapcar     |
              results    |              |               |
          ---------------+--------------+---------------+
            nconc of the |              |               |
              function   |    mapcon    |    mapcan     |
              results    |              |               |
          ---------------+--------------+---------------+

Note that map and mapl are synonymous. map is the traditional name of this function. mapl is the Common Lisp name. In Common Lisp, the function map does something different and incompatible; see cli:map, cli:map-fun. mapl works the same in traditional Zetalisp and Common Lisp.

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. car or cdr of anything else is an error.

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 ¶

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)

Macro: push item place ¶

Adds an element item to the front of a list that is stored in place. A new cons is allocated whose car is item and whose cdr is the old contents of place. This cons is stored into place.

The form

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

replaces the commonly-used construct

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

and is intended to be more explicit and esthetic.

place can be any form that setf can store into. For example,

(push x (get y z))
 ==> (putprop y (cons x (get y z)) z)

The returned value of push is not defined.

Macro: pop place ¶

Removes an element from the front of the list that is stored in place. It finds the cons in place, stores the cdr of the cons back into place, and returns the car of that cons. place can be any form that setf can store into.

Example:

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

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). Instead, the cons itself serves as a kind of locative to its cdr (see contents-fun).

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 altered rather than copied. Exercise caution when using these functions, as strange side-effects can occur if they are used to modify portions of list structure which have become shared unbeknownst to the programmer. The nconc, nreverse, nreconc, nbutlast and delq functions and others, described below, have the same property, because they call rplaca or rplacd.

Function: 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 ¶

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)

(setf (car x) y) and (setf (car x) y) are much like rplaca and rplacd, but they return y rather than x.

5.2 Lists

Function: list &rest args ¶

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: length list-or-array ¶

Returns the length of list-or-array. The length of a list is the number of elements in it; the number of times you can cdr it before you get a non-cons.

Examples:

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

length could have been defined by:

(defun length (x)
  (if (arrayp x) (array-active-length x)
    (do ((n 0 (1+ n))
         (y x (cdr y)))
        ((null y) n))))

Function: list-length list ¶

Returns the length of list, or nil if list is circular. (The function length would loop forever if given a circular list.)

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.