Skip to main content

1.4 Definitions

This section contains notational conventions and definitions of terms used in this manual.

1.4.1 Notational Conventions​

The following notational conventions are used throughout this document.

1.4.1.1 Font Key​

Fonts are used in this document to convey information.

name

Denotes a formal term whose meaning is defined in the Glossary. When this font is used, the Glossary definition takes precedence over normal English usage.

Sometimes a glossary term appears subscripted, as in “whitespace2.” Such a notation selects one particular Glossary definition out of several, in this case the second. The subscript notation for Glossary terms is generally used where the context might be insufficient to disambiguate among the available definitions.

name

Denotes the introduction of a formal term locally to the current text. There is still a corresponding glossary entry, and is formally equivalent to a use of “name,” but the hope is that making such uses conspicuous will save the reader a trip to the glossary in some cases.

name

Denotes a symbol in the COMMON-LISP package. For information about case conventions, see Section 1.4.1.4.1 (Case in Symbols).

name

Denotes a sample name or piece of code that a programmer might write in Common Lisp.

This font is also used for certain standardized names that are not names of external symbols of the COMMON-LISP package, such as keywords1, package names, and loop keywords.

name

Denotes the name of a parameter or value.

In some situations the notation “⟨name⟩” (i.e., the same font, but with surrounding “angle brackets”) is used instead in order to provide better visual separation from surrounding characters. These “angle brackets” are metasyntactic, and never actually appear in program input or output.

1.4.1.2 Modified BNF Syntax​

This specification uses an extended Backus Normal Form (BNF) to describe the syntax of Common Lisp macro forms and special forms. This section discusses the syntax of BNF expressions.

1.4.1.2.1 Splicing in Modified BNF Syntax​

The primary extension used is the following:

[[ O ]]

An expression of this form appears whenever a list of elements is to be spliced into a larger structure and the elements can appear in any order. The symbol O represents a description of the syntax of some number of syntactic elements to be spliced; that description must be of the form

O 1 | . . . | Ol

where each Oi can be of the form S or of the form S* or of the form S1. The expression [[ O ]] means that a list of the form

(Oi1. . . Oij) 1 ≤ j

is spliced into the enclosing expression, such that if n 6= m and 1 ≤ n, m ≤ j, then either Oin6= Oim or Oin = Oim = Qk, where for some 1 ≤ k ≤ n, Ok is of the form Qk*. Furthermore, for each Oin that is of the form Qk1, that element is required to appear somewhere in the list to be spliced.

For example, the expression

(x [[ A | B* | C ]] y)

means that at most one A, any number of B’s, and at most one C can occur in any order. It is a description of any of these:

(x y)

(x B A C y)

(x A B B B B B C y)

(x C B A B B B y)

but not any of these:

(x B B A A C C y)

(x C B C y)

In the first case, both A and C appear too often, and in the second case C appears too often.

The notation [[ O1 | O2 | . . . ]]+adds the additional restriction that at least one item from among the possible choices must be used. For example:

(x [[ A | B* | C ]]+y)

means that at most one A, any number of B’s, and at most one C can occur in any order, but that in any case at least one of these options must be selected. It is a description of any of these:

(x B y)

(x B A C y)

(x A B B B B B C y)

(x C B A B B B y)

but not any of these:

(x y)

(x B B A A C C y)

(x C B C y)

In the first case, no item was used; in the second case, both A and C appear too often; and in the third case C appears too often.

Also, the expression:

(x [[ A1| B1| C ]] y)

can generate exactly these and no others:

(x A B C y)

(x A C B y)

(x A B y)

(x B A C y)

(x B C A y)

(x B A y)

(x C A B y)

(x C B A y)

1.4.1.2.2 Indirection in Modified BNF Syntax​

An indirection extension is introduced in order to make this new syntax more readable: ↓O

If O is a non-terminal symbol, the right-hand side of its definition is substituted for the entire expression ↓O. For example, the following BNF is equivalent to the BNF in the previous example:

(x [[ ↓O ]] y)

O::=A | B* | C

1.4.1.2.3 Additional Uses for Indirect Definitions in Modified BNF Syntax​

In some cases, an auxiliary definition in the BNF might appear to be unused within the BNF, but might still be useful elsewhere. For example, consider the following definitions:

case keyform {↓normal-clause}* [↓otherwise-clause] → {result}*

ccase keyplace {↓normal-clause}* → {result}*

ecase keyform {↓normal-clause}* → {result}*

normal-clause::=(keys {form}*)

otherwise-clause::=({otherwise | t} {form}*)

clause::=normal-clause | otherwise-clause

Here the term “clause” might appear to be “dead” in that it is not used in the BNF. However, the purpose of the BNF is not just to guide parsing, but also to define useful terms for reference in the descriptive text which follows. As such, the term “clause” might appear in text that follows, as shorthand for “normal-clause or otherwise-clause.”

1.4.1.3 Special Symbols​

The special symbols described here are used as a notational convenience within this document, and are part of neither the Common Lisp language nor its environment.

→

This indicates evaluation. For example:

(+ 4 5) → 9

This means that the result of evaluating the form (+ 4 5) is 9.

If a form returns multiple values, those values might be shown separated by spaces, line breaks, or commas. For example:

(truncate 7 5)

→ 1 2

(truncate 7 5)

→ 1

2

(truncate 7 5)

→ 1, 2

Each of the above three examples is equivalent, and specifies that (truncate 7 5) returns two values, which are 1 and 2.

Some conforming implementations actually type an arrow (or some other indicator) before showing return values, while others do not.

or→

The notation “ or→” is used to denote one of several possible alternate results. The example

(char-name #\a)

→ NIL

or→ "LOWERCASE-a"

or→ "Small-A"

or→ "LA01"

indicates that nil, "LOWERCASE-a", "Small-A", "LA01" are among the possible results of (char-name #\a)—each with equal preference. Unless explicitly specified otherwise, it should not be assumed that the set of possible results shown is exhaustive. Formally, the above example is equivalent to

(char-name #\a) → implementation-dependent

but it is intended to provide additional information to illustrate some of the ways in which it is permitted for implementations to diverge.

not →

The notation “not →” is used to denote a result which is not possible. This might be used, for example, in order to emphasize a situation where some anticipated misconception might lead the reader to falsely believe that the result might be possible. For example,

(function-lambda-expression

(funcall #’(lambda (x) #’(lambda () x)) nil))

→ NIL, true, NIL

or→ (LAMBDA () X), true, NIL

not → NIL, false, NIL

not → (LAMBDA () X), false, NIL

≡

This indicates code equivalence. For example:

(gcd x (gcd y z)) ≡ (gcd (gcd x y) z)

This means that the results and observable side-effects of evaluating the form

(gcd x (gcd y z)) are always the same as the results and observable side-effects of (gcd (gcd x y) z) for any x, y, and z.

▷

Common Lisp specifies input and output with respect to a non-interactive stream model. The specific details of how interactive input and output are mapped onto that non-interactive model are implementation-defined.

For example, conforming implementations are permitted to differ in issues of how interactive input is terminated. For example, the function read terminates when the final delimiter is typed on a non-interactive stream. In some implementations, an interactive call to read returns as soon as the final delimiter is typed, even if that delimiter is not a newline. In other implementations, a final newline is always required. In still other implementations, there might be a command which “activates” a buffer full of input without the command itself being visible on the program’s input stream.

In the examples in this document, the notation “▷” precedes lines where interactive input and output occurs. Within such a scenario, “this notation” notates user input.

For example, the notation

(+ 1 (print (+ (sqrt (read)) (sqrt (read)))))

▷ 9 16

▷ 7

→ 8

shows an interaction in which “(+ 1 (print (+ (sqrt (read)) (sqrt (read)))))” is a form to be evaluated, “9 16 ” is interactive input, “7” is interactive output, and “8” is the value yielded from the evaluation.

The use of this notation is intended to disguise small differences in interactive input and output behavior between implementations.

Sometimes, the non-interactive stream model calls for a newline. How that newline character is interactively entered is an implementation-defined detail of the user interface, but in that case, either the notation “⟨Newline⟩” or “←” might be used.

(progn (format t "~&Who? ") (read-line))

▷ Who? Fred, Mary, and Sally←

→ "Fred, Mary, and Sally", ~~fal~~se

1.4.1.4 Objects with Multiple Notations​

Some objects in Common Lisp can be notated in more than one way. In such situations, the choice of which notation to use is technically arbitrary, but conventions may exist which convey a “point of view” or “sense of intent.”

1.4.1.4.1 Case in Symbols​

While case is significant in the process of interning a symbol, the Lisp reader , by default, attempts to canonicalize the case of a symbol prior to interning; see Section 23.1.2 (Effect of Readtable Case on the Lisp Reader). As such, case in symbols is not, by default, significant. Throughout

this document, except as explicitly noted otherwise, the case in which a symbol appears is not significant; that is, HELLO, Hello, hElLo, and hello are all equivalent ways to denote a symbol whose name is "HELLO".

The characters backslash and vertical-bar are used to explicitly quote the case and other parsing related aspects of characters. As such, the notations |hello| and \h\e\l\l\o are equivalent ways to refer to a symbol whose name is "hello", and which is distinct from any symbol whose name is "HELLO".

The symbols that correspond to Common Lisp defined names have uppercase names even though their names generally appear in lowercase in this document.

1.4.1.4.2 Numbers​

Although Common Lisp provides a variety of ways for programs to manipulate the input and output radix for rational numbers, all numbers in this document are in decimal notation unless explicitly noted otherwise.

1.4.1.4.3 Use of the Dot Character​

The dot appearing by itself in an expression such as

(item1 item2 . tail)

means that tail represents a list of objects at the end of a list. For example,

(A B C . (D E F))

is notationally equivalent to:

(A B C D E F)

Although dot is a valid constituent character in a symbol, no standardized symbols contain the character dot, so a period that follows a reference to a symbol at the end of a sentence in this document should always be interpreted as a period and never as part of the symbol’s name. For example, within this document, a sentence such as “This sample sentence refers to the symbol car.” refers to a symbol whose name is "CAR" (with three letters), and never to a four-letter symbol "CAR."

1.4.1.4.4 NIL​

nil has a variety of meanings. It is a symbol in the COMMON-LISP package with the name "NIL", it is boolean (and generalized boolean) false, it is the empty list, and it is the name of the empty type (a subtype of all types).

Within Common Lisp, nil can be notated interchangeably as either NIL or (). By convention, the choice of notation offers a hint as to which of its many roles it is playing.

|For Evaluation? Notation Typically Implied Role|

| :- |

|

Yes nil use as a boolean.

Yes ’nil use as a symbol.

Yes ’() use as an empty list

No nil use as a symbol or boolean. No () use as an empty list.

|

Figure 1–1. Notations for NIL

Within this document only, nil is also sometimes notated as false to emphasize its role as a boolean. For example:

(print ()) ;avoided

(defun three nil 3) ;avoided

’(nil nil) ;list of two symbols

’(() ()) ;list of empty lists

(defun three () 3) ;Emphasize empty parameter list.

(append ’() ’()) → () ;Emphasize use of empty lists

(not nil) → true ;Emphasize use as Boolean false

(get ’nil ’color) ;Emphasize use as a symbol

A function is sometimes said to “be false” or “be true” in some circumstance. Since no function object can be the same as nil and all function objects represent true when viewed as booleans, it would be meaningless to say that the function was literally false and uninteresting to say that it was literally true. Instead, these phrases are just traditional alternative ways of saying that the

function “returns false” or “returns true,” respectively.

1.4.1.5 Designators​

A designator is an object that denotes another object.

Where a parameter of an operator is described as a designator , the description of the operator is written in a way that assumes that the value of the parameter is the denoted object; that is, that the parameter is already of the denoted type. (The specific nature of the object denoted by a “⟨typeii designator*” or a “designator for a ⟨type⟩” can be found in the Glossary entry for “⟨typeii designator* .”)

For example, “nil” and “the value of *standard-output*” are operationally indistinguishable as stream designators. Similarly, the symbol foo and the string "FOO" are operationally indistinguishable as string designators.

Except as otherwise noted, in a situation where the denoted object might be used multiple times, it is implementation-dependent whether the object is coerced only once or whether the coercion occurs each time the object must be used.

For example, mapcar receives a function designator as an argument, and its description is written as if this were simply a function. In fact, it is implementation-dependent whether the function designator is coerced right away or whether it is carried around internally in the form that it was given as an argument and re-coerced each time it is needed. In most cases, conforming programs cannot detect the distinction, but there are some pathological situations (particularly those involving self-redefining or mutually-redefining functions) which do conform and which can detect this difference. The following program is a conforming program, but might or might not have portably correct results, depending on whether its correctness depends on one or the other of the results:

(defun add-some (x)

(defun add-some (x) (+ x 2))

(+ x 1)) → ADD-SOME

(mapcar ’add-some ’(1 2 3 4))

→ (2 3 4 5)

or→ (2 4 5 6)

In a few rare situations, there may be a need in a dictionary entry to refer to the object that was the original designator for a parameter . Since naming the parameter would refer to the denoted object, the phrase “the ⟨parameter-nameii designator*” can be used to refer to the designator which was the argument from which the value of ⟨parameter-name⟩ was computed.

1.4.1.6 Nonsense Words​

When a word having no pre-attached semantics is required (e.g., in an example), it is common in the Lisp community to use one of the words “foo,” “bar,” “baz,” and “quux.” For example, in

(defun foo (x) (+ x 1))

the use of the name foo is just a shorthand way of saying “please substitute your favorite name here.”

These nonsense words have gained such prevalance of usage, that it is commonplace for newcomers to the community to begin to wonder if there is an attached semantics which they are overlooking—there is not.

1.4.2 Error Terminology​

Situations in which errors might, should, or must be signaled are described in the standard. The wording used to describe such situations is intended to have precise meaning. The following list is a glossary of those meanings.

Safe code

This is code processed with the safety optimization at its highest setting (3). safety is a lexical property of code. The phrase “the function F should signal an error” means that if F is invoked from code processed with the highest safety optimization, an error is signaled. It is implementation-dependent whether F or the calling code signals the error.

Unsafe code

This is code processed with lower safety levels.

Unsafe code might do error checking. Implementations are permitted to treat all code as safe code all the time.

An error is signaled

This means that an error is signaled in both safe and unsafe code. Conforming code may rely on the fact that the error is signaled in both safe and unsafe code. Every implementation is required to detect the error in both safe and unsafe code. For example, “an error is signaled if unexport is given a symbol not accessible in the current package.”

If an explicit error type is not specified, the default is error.

An error should be signaled

This means that an error is signaled in safe code, and an error might be signaled in unsafe code. Conforming code may rely on the fact that the error is signaled in safe code. Every implementation is required to detect the error at least in safe code. When the error is not signaled, the “consequences are undefined” (see below). For example, “+ should signal an error of type type-error if any argument is not of type number.”

Should be prepared to signal an error

This is similar to “should be signaled” except that it does not imply that ‘extra effort’ has to be taken on the part of an operator to discover an erroneous situation if the normal action of that operator can be performed successfully with only ‘lazy’ checking. An implementation is always permitted to signal an error, but even in safe code, it is only required to signal the error when failing to signal it might lead to incorrect results. In unsafe code, the consequences are undefined.

For example, defining that “find should be prepared to signal an error of type type-error if its second argument is not a proper list” does not imply that an error is always signaled. The form

(find ’a ’(a b . c))

must either signal an error of type type-error in safe code, else return A. In unsafe code, the consequences are undefined. By contrast,

(find ’d ’(a b . c))

must signal an error of type type-error in safe code. In unsafe code, the consequences are undefined. Also,

(find ’d ’#1=(a b . #1#))

in safe code might return nil (as an implementation-defined extension), might never return, or might signal an error of type type-error. In unsafe code, the consequences are undefined.

Typically, the “should be prepared to signal” terminology is used in type checking situations where there are efficiency considerations that make it impractical to detect errors that are not relevant to the correct operation of the operator .

The consequences are unspecified

This means that the consequences are unpredictable but harmless. Implementations are permitted to specify the consequences of this situation. No conforming code may depend on the results or effects of this situation, and all conforming code is required to treat the

results and effects of this situation as unpredictable but harmless. For example, “if the second argument to shared-initialize specifies a name that does not correspond to any slots accessible in the object, the results are unspecified.”

The consequences are undefined

This means that the consequences are unpredictable. The consequences may range from harmless to fatal. No conforming code may depend on the results or effects. Conforming code must treat the consequences as unpredictable. In places where the words “must,” “must not,” or “may not” are used, then “the consequences are undefined” if the stated requirement is not met and no specific consequence is explicitly stated. An implementation is permitted to signal an error in this case.

For example: “Once a name has been declared by defconstant to be constant, any further assignment or binding of that variable has undefined consequences.”

An error might be signaled

This means that the situation has undefined consequences; however, if an error is signaled, it is of the specified type. For example, “open might signal an error of type file-error.”

The return values are unspecified

This means that only the number and nature of the return values of a form are not specified. However, the issue of whether or not any side-effects or transfer of control occurs is still well-specified.

A program can be well-specified even if it uses a function whose returns values are unspecified. For example, even if the return values of some function F are unspecified, an expression such as (length (list (F))) is still well-specified because it does not rely on any particular aspect of the value or values returned by F.

Implementations may be extended to cover this situation

This means that the situation has undefined consequences; however, a conforming

implementation is free to treat the situation in a more specific way. For example, an implementation might define that an error is signaled, or that an error should be signaled, or even that a certain well-defined non-error behavior occurs.

No conforming code may depend on the consequences of such a situation; all conforming code must treat the consequences of the situation as undefined. Implementations are required to document how the situation is treated.

For example, “implementations may be extended to define other type specifiers to have a corresponding class.”

Implementations are free to extend the syntax

This means that in this situation implementations are permitted to define unambiguous extensions to the syntax of the form being described. No conforming code may depend on this extension. Implementations are required to document each such extension. All

conforming code is required to treat the syntax as meaningless. The standard might disallow certain extensions while allowing others. For example, “no implementation is free to extend the syntax of defclass.”

A warning might be issued

This means that implementations are encouraged to issue a warning if the context is appropriate (e.g., when compiling). However, a conforming implementation is not required to issue a warning.

1.4.3 Sections Not Formally Part Of This Standard​

Front matter and back matter, such as the “Table of Contents,” “Index,” “Figures,” “Credits,” and “Appendix” are not considered formally part of this standard, so that we retain the flexibility needed to update these sections even at the last minute without fear of needing a formal vote to change those parts of the document. These items are quite short and very useful, however, and it is not recommended that they be removed even in an abridged version of this document.

Within the concept sections, subsections whose names begin with the words “Note” or “Notes” or “Example” or “Examples” are provided for illustration purposes only, and are not considered part of the standard.

An attempt has been made to place these sections last in their parent section, so that they could be removed without disturbing the contiguous numbering of the surrounding sections in order to produce a document of smaller size.

Likewise, the “Examples” and “Notes” sections in a dictionary entry are not considered part of the standard and could be removed if necessary.

Nevertheless, the examples provide important clarifications and consistency checks for the rest of the material, and such abridging is not recommended unless absolutely unavoidable.

1.4.4 Interpreting Dictionary Entries​

The dictionary entry for each defined name is partitioned into sections. Except as explicitly indicated otherwise below, each section is introduced by a label identifying that section. The omission of a section implies that the section is either not applicable, or would provide no interesting information.

This section defines the significance of each potential section in a dictionary entry.

1.4.4.1 The “Affected By” Section of a Dictionary Entry​

For an operator , anything that can affect the side effects of or values returned by the operator .

For a variable, anything that can affect the value of the variable including functions that bind or assign it.

1.4.4.2 The “Arguments” Section of a Dictionary Entry​

This information describes the syntax information of entries such as those for declarations and special expressions which are never evaluated as forms, and so do not return values.

1.4.4.3 The “Arguments and Values” Section of a Dictionary Entry​

An English language description of what arguments the operator accepts and what values it returns, including information about defaults for parameters corresponding to omittable arguments (such as optional parameters and keyword parameters). For special operators and macros, their arguments are not evaluated unless it is explicitly stated in their descriptions that they are evaluated.

Except as explicitly specified otherwise, the consequences are undefined if these type restrictions are violated.

1.4.4.4 The “Binding Types Affected” Section of a Dictionary Entry​

This information alerts the reader to the kinds of bindings that might potentially be affected by a declaration. Whether in fact any particular such binding is actually affected is dependent on additional factors as well. See the “Description” section of the declaration in question for details.

1.4.4.5 The “Class Precedence List” Section of a Dictionary Entry​

This appears in the dictionary entry for a class, and contains an ordered list of the classes defined by Common Lisp that must be in the class precedence list of this class.

It is permissible for other (implementation-defined) classes to appear in the implementation’s class precedence list for the class.

It is permissible for either standard-object or structure-object to appear in the implementation’s class precedence list; for details, see Section 4.2.2 (Type Relationships).

Except as explicitly indicated otherwise somewhere in this specification, no additional standardized classes may appear in the implementation’s class precedence list.

By definition of the relationship between classes and types, the classes listed in this section are also supertypes of the type denoted by the class.

1.4.4.6 Dictionary Entries for Type Specifiers​

The atomic type specifiers are those defined names listed in Figure 4–2. Such dictionary entries are of kind “Class,” “Condition Type,” “System Class,” or “Type.” A description of how to interpret a symbol naming one of these types or classes as an atomic type specifier is found in the “Description” section of such dictionary entries.

The compound type specifiers are those defined names listed in Figure 4–3. Such dictionary entries are of kind “Class,” “System Class,” “Type,” or “Type Specifier.” A description of how to interpret as a compound type specifier a list whose car is such a symbol is found in the “Compound Type Specifier Kind,” “Compound Type Specifier Syntax,” “Compound Type Specifier Arguments,” and “Compound Type Specifier Description” sections of such dictionary entries.

1.4.4.6.1 The “Compound Type Specifier Kind” Section of a Dictionary Entry​

An “abbreviating” type specifier is one that describes a subtype for which it is in principle possible to enumerate the elements, but for which in practice it is impractical to do so.

A “specializing” type specifier is one that describes a subtype by restricting the type of one or more components of the type, such as element type or complex part type.

A “predicating” type specifier is one that describes a subtype containing only those objects that satisfy a given predicate.

A “combining” type specifier is one that describes a subtype in a compositional way, using combining operations (such as “and,” “or,” and “not”) on other types.

1.4.4.6.2 The “Compound Type Specifier Syntax” Section of a Dictionary Entry​

This information about a type describes the syntax of a compound type specifier for that type.

Whether or not the type is acceptable as an atomic type specifier is not represented here; see Section 1.4.4.6 (Dictionary Entries for Type Specifiers).

1.4.4.6.3 The “Compound Type Specifier Arguments” Section of a Dictionary Entry​

This information describes type information for the structures defined in the “Compound Type Specifier Syntax” section.

1.4.4.6.4 The “Compound Type Specifier Description” Section of a Dictionary Entry​

This information describes the meaning of the structures defined in the “Compound Type Specifier Syntax” section.

1.4.4.7 The “Constant Value” Section of a Dictionary Entry​

This information describes the unchanging type and value of a constant variable.

1.4.4.8 The “Description” Section of a Dictionary Entry​

A summary of the operator and all intended aspects of the operator , but does not necessarily include all the fields referenced below it (“Side Effects,” “Exceptional Situations,” etc.)

1.4.4.9 The “Examples” Section of a Dictionary Entry​

Examples of use of the *operator* . These examples are not considered part of the standard; see Section 1.4.3 (Sections Not Formally Part Of This Standard).

1.4.4.10 The “Exceptional Situations” Section of a Dictionary Entry​

Three kinds of information may appear here:

• Situations that are detected by the function and formally signaled.

• Situations that are handled by the function.

• Situations that may be detected by the function.

This field does not include conditions that could be signaled by functions passed to and called by this operator as arguments or through dynamic variables, nor by executing subforms of this operator if it is a macro or special operator .

1.4.4.11 The “Initial Value” Section of a Dictionary Entry​

This information describes the initial value of a dynamic variable. Since this variable might change, see type restrictions in the “Value Type” section.

1.4.4.12 The “Argument Precedence Order” Section of a Dictionary Entry​

This information describes the argument precedence order . If it is omitted, the argument precedence order is the default (left to right).

1.4.4.13 The “Method Signature” Section of a Dictionary Entry​

The description of a generic function includes descriptions of the methods that are defined on that generic function by the standard. A method signature is used to describe the parameters and parameter specializers for each method. Methods defined for the generic function must be of the form described by the method signature.

F (x class) (y t) &optional z &key k

This signature indicates that this method on the generic function F has two required parameters: x, which must be a generalized instance of the class class; and y, which can be any object (i.e., a generalized instance of the class t). In addition, there is an optional parameter z and a keyword parameter k. This signature also indicates that this method on F is a primary method and has no qualifiers.

For each parameter , the argument supplied must be in the intersection of the type specified in the description of the corresponding generic function and the type given in the signature of some method (including not only those methods defined in this specification, but also implementation-defined or user-defined methods in situations where the definition of such methods is permitted).

1.4.4.14 The “Name” Section of a Dictionary Entry​

This section introduces the dictionary entry. It is not explicitly labeled. It appears preceded and followed by a horizontal bar.

In large print at left, the defined name appears; if more than one defined name is to be described by the entry, all such names are shown separated by commas.

In somewhat smaller italic print at right is an indication of what kind of dictionary entry this is. Possible values are:

Accessor

This is an accessor function.

Class

This is a class.

Condition Type

This is a subtype of type condition.

Constant Variable

This is a constant variable.

Declaration

This is a declaration identifier .

Function

This is a function.

Local Function

This is a function that is defined only lexically within the scope of some other macro form.

Local Macro

This is a macro that is defined only lexically within the scope of some other macro form.

Macro

This is a macro.

Restart

This is a restart.

Special Operator

This is a special operator .

Standard Generic Function

This is a standard generic function.

Symbol

This is a symbol that is specially recognized in some particular situation, such as the syntax of a macro.

System Class

This is like class, but it identifies a class that is potentially a built-in class. (No class is actually required to be a built-in class.)

Type

This is an atomic type specifier , and depending on information for each particular entry, may subject to form other type specifiers.

Type Specifier

This is a defined name that is not an atomic type specifier , but that can be used in constructing valid type specifiers.

Variable

This is a dynamic variable.

1.4.4.15 The “Notes” Section of a Dictionary Entry​

Information not found elsewhere in this description which pertains to this operator . Among other things, this might include cross reference information, code equivalences, stylistic hints, implementation hints, typical uses. This information is not considered part of the standard; any conforming implementation or conforming program is permitted to ignore the presence of this information.

1.4.4.16 The “Pronunciation” Section of a Dictionary Entry​

This offers a suggested pronunciation for defined names so that people not in verbal communication with the original designers can figure out how to pronounce words that are not in normal English usage. This information is advisory only, and is not considered part of the standard. For brevity, it is only provided for entries with names that are specific to Common Lisp and would not be found in Webster’s Third New International Dictionary the English Language, Unabridged.

1.4.4.17 The “See Also” Section of a Dictionary Entry​

List of references to other parts of this standard that offer information relevant to this operator . This list is not part of the standard.

1.4.4.18 The “Side Effects” Section of a Dictionary Entry​

Anything that is changed as a result of the evaluation of the form containing this operator .

1.4.4.19 The “Supertypes” Section of a Dictionary Entry​

This appears in the dictionary entry for a type, and contains a list of the standardized types that must be supertypes of this type.

In implementations where there is a corresponding class, the order of the classes in the class precedence list is consistent with the order presented in this section.

1.4.4.20 The “Syntax” Section of a Dictionary Entry​

This section describes how to use the defined name in code. The “Syntax” description for a generic function describes the lambda list of the generic function itself, while the “Method Signatures” describe the lambda lists of the defined methods. The “Syntax” description for an ordinary function, a macro, or a special operator describes its parameters.

For example, an operator description might say:

F x y &optional z &key k

This description indicates that the function F has two required parameters, x and y. In addition, there is an optional parameter z and a keyword parameter k.

For macros and special operators, syntax is given in modified BNF notation; see Section 1.4.1.2 (Modified BNF Syntax). For functions a lambda list is given. In both cases, however, the outermost parentheses are omitted, and default value information is omitted.

1.4.4.20.1 Special “Syntax” Notations for Overloaded Operators​

If two descriptions exist for the same operation but with different numbers of arguments, then the extra arguments are to be treated as optional. For example, this pair of lines:

file-position stream → position

file-position stream position-spec → success-p

is operationally equivalent to this line:

file-position stream &optional position-spec → result

and differs only in that it provides on opportunity to introduce different names for parameter and values for each case. The separated (multi-line) notation is used when an operator is overloaded in such a way that the parameters are used in different ways depending on how many arguments are supplied (e.g., for the function /) or the return values are different in the two cases (e.g., for the

function file-position).

1.4.4.20.2 Naming Conventions for Rest Parameters​

Within this specification, if the name of a rest parameter is chosen to be a plural noun, use of that name in parameter font refers to the list to which the rest parameter is bound. Use of the singular form of that name in parameter font refers to an element of that list.

For example, given a syntax description such as:

F &rest arguments

it is appropriate to refer either to the rest parameter named arguments by name, or to one of its elements by speaking of “an argument,” “some argument,” “each argument” etc.

1.4.4.20.3 Requiring Non​

In some cases it is useful to refer to all arguments equally as a single aggregation using a rest parameter while at the same time requiring at least one argument. A variety of imperative and declarative means are available in code for expressing such a restriction, however they generally do not manifest themselves in a lambda list. For descriptive purposes within this specification,

F &rest arguments+

means the same as

F &rest arguments

but introduces the additional requirement that there be at least one argument.

1.4.4.20.4 Return values in the “Syntax” Section​

An evaluation arrow “→” precedes a list of values to be returned. For example:

F a b c → x

indicates that F is an operator that has three required parameters (i.e., a, b, and c) and that returns one value (i.e., x). If more than one value is returned by an operator, the names of the values are separated by commas, as in:

F a b c → x, y, z

1.4.4.20.4.1 No Arguments or Values in the “Syntax” Section​

If no arguments are permitted, or no values are returned, a special notation is used to make this more visually apparent. For example,

F ⟨no arguments⟩ → ⟨no values⟩

indicates that F is an operator that accepts no arguments and returns no values.

1.4.4.20.4.2 Unconditional Transfer of Control in the “Syntax” Section​

Some operators perform an unconditional transfer of control, and so never have any return values. Such operators are notated using a notation such as the following:

F a b c →

1.4.4.21 The “Valid Context” Section of a Dictionary Entry​

This information is used by dictionary entries such as “Declarations” in order to restrict the context in which the declaration may appear.

A given “Declaration” might appear in a declaration (i.e., a declare expression), a proclamation (i.e., a declaim or proclaim form), or both.

1.4.4.22 The “Value Type” Section of a Dictionary Entry​

This information describes any type restrictions on a dynamic variable.

Except as explicitly specified otherwise, the consequences are undefined if this type restriction is violated.