Next: The Lisp Reader, Previous: Errors, Up: Introduction [Contents][Index]
are described using a distinctive typographical format.
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.
---------------------------------------------------------------- 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). ----------------------------------------------------------------
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-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). ----------------------------------------------------------------
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-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. ----------------------------------------------------------------
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,
p [[x | {y}* | z]] q
means 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.
p [[?xyz-mixture]] q
xyz-mixture ::= x | {y}* | z
are together equivalent to the previous example.
----------------------------------------------------------------
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)
----------------------------------------------------------------
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).
Next: The Lisp Reader, Previous: Errors, Up: Introduction [Contents][Index]