A number of special notational conventions are used throughout this book for the sake of conciseness.
All numbers in this book are in decimal notation unless there is an explicit indication to the contrary. (Decimal notation is normally taken for granted, of course. Unfortunately, for certain other dialects of Lisp, MacLisp in particular, the default notation for numbers is octal (base 8) rather than decimal, and so the use of decimal notation for describing Common Lisp is, taken in its historical context, a bit unusual!)
In Common Lisp, as in most Lisp dialects, the symbol nil is used to represent both the empty list and the “false” value for Boolean tests. An empty list may, of course, also be written (); this normally denotes the same object as nil. (It is possible, by extremely perverse manipulation of the package system, to cause the sequence of letters nil to be recognized not as the symbol that represents the empty list but as another symbol with the same name. This obscure possibility will be ignored in this book.) These two notations may be used interchangeably as far as the Lisp system is concerned. However, as a matter of style, this book uses the notation () when it is desirable to emphasize the use of an empty list, and uses the notation nil when it is desirable to emphasize the use of the Boolean “false”. The notation ’nil (note the explicit quotation mark) is used to emphasize the use of a symbol. For example:
Any data object other than nil is construed to be Boolean “not false”, that is, “true”. The symbol t is conventionally used to mean “true” when no other value is more appropriate. When a function is said to “return false” or to “be false” in some circumstance, this means that it returns nil. However, when a function is said to “return true” or to “be true” in some circumstance, this means that it returns some value other than nil, but not necessarily t.
Execution of code in Lisp is called evaluation because executing a piece of code normally results in a data object called the value produced by the code. The symbol ⇒ is used in examples to indicate evaluation. For example,
means “the result of evaluating the code (+ 4 5) is (or would be, or would have been) 9.”
The symbol → is used in examples to indicate macro expansion. For example,
means “the result of expanding the macro-call form (push x v) is (setf v (cons x v)).” This implies that the two pieces of code do the same thing; the second piece of code is the definition of what the first does.
The symbol ≡ is used in examples to indicate code equivalence. For example,
means “the value and effects of evaluating the form (gcd x (gcd y z)) are always the same as the value and effects of (gcd (gcd x y) z) for any values of the variables x, y, and z.” This implies that the two pieces of code do the same thing; however, neither directly defines the other in the way macro expansion does.
When this book specifies that it “is an error” for some situation to occur, this means that:
This is not to say that some particular implementation might not define the effects and results for such a situation; the point is that no program conforming to the Common Lisp specification may correctly depend on such effects or results.
On the other hand, if it is specified in this book that in some situation “an error is signaled,” this means that:
In places where it is stated that so-and-so “must” or “must not” or “may not” be the case, then it “is an error” if the stated requirement is not met. For example, if an argument “must be a symbol,” then it “is an error” if the argument is not a symbol. In all cases where an error is to be signaled, the word “signaled” is always used explicitly in this book.
X3J13 has adopted a more elaborate terminology for errors, and has made some effort to specify the type of error to be signaled in situations where signaling is appropriate. This effort was not complete as of September 1989, and I have made little attempt to incorporate the new error terminology or error type specifications in this book. However, the new terminology is described and used in the specification of the Common Lisp Object System appearing in chapter 28; this gives the flavor of how erroneous situations will be described, and appropriate actions prescribed, in the forthcoming ANSI Common Lisp standard.
In general, (sample-function x y) ≡ (list (+ x y) ’foo).
This evaluates form1, form2, form1, form2, form1, form2 in that order.
Functions, variables, named constants, special operators, and macros are described using a distinctive typographical format. Table 1.1 illustrates the manner in which Common Lisp functions are documented. The first line specifies the name of the function, the manner in which it accepts arguments, and the fact that it is a function. If the function takes many arguments, then the names of the arguments may spill across two or three lines. The paragraphs following this standard header explain the definition and uses of the function and often present examples or related functions.
Sometimes two or more related functions are explained in a single combined description. In this situation the headers for all the functions appear together, followed by the combined description.
In general, actual code (including actual names of functions) appears in this typeface: (cons a b). Names that stand for pieces of code (metavariables) are written in italics. In a function description, the names of the parameters appear in italics for expository purposes. The word &optional in the list of parameters indicates that all arguments past that point are optional; the default values for the parameters are described in the text. Parameter lists may also contain &rest, indicating that an indefinite number of arguments may appear, or &key, indicating that keyword arguments are accepted. (The &optional/&rest/&key syntax is actually used in Common Lisp function definitions for these purposes.)
Table 1.2 illustrates the manner in which a global variable is documented. The first line specifies the name of the variable and the fact that it is a variable. Purely as a matter of convention, all global variables used by Common Lisp have names beginning and ending with an asterisk.
Table 1.3 illustrates the manner in which a named constant is documented. The first line specifies the name of the constant and the fact that it is a constant. (A constant is just like a global variable, except that it is an error ever to alter its value or to bind it to a new value.)
Tables 1.4 and 1.5 illustrate the documentation of special operators and macros, which are closely related in purpose. These are very different from functions. Functions are called according to a single, specific, consistent syntax; the &optional/&rest/&key syntax specifies how the function uses its arguments internally but does not affect the syntax of a call. In contrast, each special operator or macro can have its own idiosyncratic syntax. It is by special operators and macros that the syntax of Common Lisp is defined and extended.
In the description of a special operator or macro, an italicized word names a corresponding part of the form that invokes the special operator or macro. Parentheses stand for themselves and should be written as such when invoking the special operator or macro. Brackets, braces, stars, plus signs, and vertical bars are metasyntactic marks. Brackets, [ and ], indicate that what they enclose is optional (may appear zero times or one time in that place); the square brackets should not be written in code. Braces, { and }, simply parenthesize what they enclose but may be followed by a star, {}*, or a plus sign, {}+; a star indicates that what the braces enclose may appear any number of times (including zero, that is, not at all), whereas a plus sign indicates that what the braces enclose may appear any non-zero number of times (that is, must appear at least once). Within braces or brackets, a vertical bar, |, separates mutually exclusive choices. In summary, the notation {x}* means zero or more occurrences of x, the notation {x}+ means one or more occurrences of x, and the notation [x] means zero or one occurrence of x. These notations are also used for syntactic descriptions expressed as BNF-like productions, as in table 22.3.
Double brackets, [[ and ]], indicate that any number of the alternatives enclosed may be used, and those used may occur in any order, but each alternative may be used at most once unless followed by a star. For example,
A downward arrow, ↓, indicates a form of syntactic indirection that helps to make [[ ]] notation more readable. If X is some non-terminal symbol occurring on the left-hand side of some BNF production, then the right-hand side of that production is to be textually substituted for any occurrence of ↓X. Thus the two fragments
In the last example in table 1.5, notice the use of dot notation. The dot appearing in the expression (sample-macro var . body) means that the name body stands for a list of forms, not just a single form, at the end of a list. This notation is often used in examples.
In the heading line in table 1.5, notice the use of [[ ]] notation to indicate that any number of declarations may appear but at most one documentation string (which may appear before, after, or somewhere in the middle of any declarations).
The term “Lisp reader” refers not to you, the reader of this book, nor to some person reading Lisp code, but specifically to a Lisp procedure, namely the function read, which reads characters from an input stream and interprets them by parsing as representations of Lisp objects.
Certain characters are used in special ways in the syntax of Common Lisp. The complete syntax is explained in detail in chapter 22, but a quick summary here may be useful:
Brackets, braces, question mark, and exclamation point (that is, [, ], {, }, ?, and !) are not used for any purpose in standard Common Lisp syntax. These characters are explicitly reserved to the user, primarily for use as macro characters for user-defined lexical syntax extensions (see section 22.1.3).
All code in this book is written using lowercase letters. Common Lisp is generally insensitive to the case in which code is written. Internally, names of symbols are ordinarily converted to and stored in uppercase form. There are ways to force case conversion on output if desired; see *print-case*. In this book, wherever an interactive exchange between a user and the Lisp system is shown, the input is exhibited with lowercase letters and the output with uppercase letters.
readtable-case settings allow the names of symbols to be case-sensitive. The default behavior, however, is as described in the previous paragraph. In any event, only uppercase letters appear in the internal print names of symbols naming the standard Common Lisp facilities described in this book.