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.
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.
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.
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.
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.
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.
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.
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.
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).
This information describes type information for the structures defined in the “Compound Type Specifier Syntax” section.
This information describes the meaning of the structures defined in the “Compound Type Specifier Syntax” section.
This information describes the unchanging type and value of a constant variable.
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.)
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).
Three kinds of information may appear here:
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.
This information describes the initial value of a dynamic variable. Since this variable might change, see type restrictions in the “Value Type” section.
This information describes the argument precedence order. If it is omitted, the argument precedence order is the default (left to right).
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).
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:
This is an accessor function.
This is a class.
This is a subtype of type condition.
This is a constant variable.
This is a declaration identifier.
This is a function.
This is a function that is defined only lexically within the scope of some
other macro form.
This is a macro that is defined only lexically within the scope of some
other macro form.
This is a macro.
This is a restart.
This is a special operator.
This is a standard generic function.
This is a symbol that is specially recognized in some particular situation,
such as the syntax of a macro.
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.)
This is an atomic type specifier,
and depending on information for each particular entry,
may subject to form other type specifiers.
This is a defined name that is not an atomic type specifier,
but that can be used in constructing valid type specifiers.
This is a dynamic variable.
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.
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.
List of references to other parts of this standard that offer information relevant to this operator. This list is not part of the standard.
Anything that is changed as a result of the evaluation of the form containing this operator.
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.
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:
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.
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:
is operationally equivalent to this line:
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).
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:
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.
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,
means the same as
but introduces the additional requirement that there be at least one argument.
An evaluation arrow “→” precedes a list of values to be returned. For example:
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:
If no arguments are permitted, or no values are returned, a special notation is used to make this more visually apparent. For example,
indicates that F is an operator that accepts no arguments and returns
no values.
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:
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.
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.