Next: The Lisp Reader Up: Notational Conventions Previous: Errors
Common Lisp the Language, 2nd Edition
Next: The Lisp Reader
Up: Notational Conventions
Previous: Errors
Functions, variables, named constants, special forms, 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-1: Sample Function Description
[Function]
sample-function arg1 arg2 &optional arg3 arg4
The function sample-function adds together arg1 and arg2,
and then multiplies the result by arg3. If arg3 is not
provided or is nil, the multiplication isn't done.
sample-function then returns a list whose first element is
this result and whose section element is arg4 (which
defaults to the symbol foo). For example:
(sample-function 3 4) => (7 foo)
(sample-function 1 2 2 'bar) => (6 bar)
In general, (sample-function x y) == (list (+ x y) 'foo).
----------------------------------------------------------------
----------------------------------------------------------------
Table 1-2: Sample Variable Description
[Variable]
*sample-variable*
The variable *sample-variable* specifies how many times the
special form sample-special-form should iterate. The value
should always be a non-negative integer or nil (which means
iterate indefinitely many times). The initial value is 0
(meaning no iterations).
----------------------------------------------------------------
----------------------------------------------------------------
Table 1-3: Sample Constant Description
[Constant]
sample-constant
The named constant sample-constant has as its value the
height of the terminal screen in furlongs times the base-2
logarithm of the implementation's total disk capacity in
bytes, as a floating-point number.
----------------------------------------------------------------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.)
----------------------------------------------------------------
Table 1-4: Sample Special Form Description
[Special Form]
sample-special-form [name] ({var}*) {form}+
This evaluates each form in sequence as an implicit progn,
and does this as many times as specified by the global
variable *sample-variable*. Each variable var is
bound and initialized to 43 before the first iteration, and
unbound after the last iteration. The name name, if
supplied, may be used in a return-from form to exit from the
loop prematurely. If the loop ends normally,
sample-special-form returns nil. For example:
(setq *sample-variable* 3)
(sample-special-form () form1 form2)
This evaluates form1, form2, form1, form2, form1, form2,
in that order.
----------------------------------------------------------------
----------------------------------------------------------------
Table 1-5: Sample Macro Description
[Macro]
sample-macro var [[ declaration* | doc-string ]] {tag | statement}*
This evaluates the statements as a prog body, with the
variable var bound to 43.
(sample-macro x (return (+ x x))) => 86
(sample-macro var . body) -> (prog ((var 43)) . body)
----------------------------------------------------------------Tables 1-4 and
1-5 illustrate the
documentation of special forms 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 form or macro
can have its own idiosyncratic syntax. It is by special forms and macros
that the syntax of Common Lisp is defined and extended.
In the description of a special form or macro, an italicized word names a corresponding part of the form that invokes the special form or macro. Parentheses stand for themselves and should be written as such when invoking the special form 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-2.
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,
p [[x | {y}* | z]] qmeans that at most one x, any number of y’s, and at most one z may appear between the mandatory occurrences of p and q, and those that appear may be in any order.
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
p [[xyz-mixture]] q
xyz-mixture ::= x | {y}* | zare together equivalent to the previous example.
HTML Note: In the WWW version of this book, we have
substituted a question mark (?) for the downward arrow ().
In the last example in table 1-5, notice the use of dot
notation. The dot appearing in the expression
(sample-macrovar.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).
Next: The Lisp Reader
Up: Notational Conventions
Previous: Errors
AI.Repository@cs.cmu.edu