Notational Conventions (The Universe Known as LISP)

14.1.2.2 Notational Conventions

A number of special notational conventions are used throughout this book for the sake of conciseness.

Decimal Numbers
All numbers in this book are in decimal notation unless there is an explicit indication to the contrary.
Nil - False - Empty List

false

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. 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.

When a function is said to “return false” or to “be false” in some circumstance, this means that it returns nil.

true

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 true” or to “be true” in some circumstance, this means that it returns some value other than nil, but not necessarily t.
Evaluation - Expansion - and Equivalence
Evaluation
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.
```
(+ 4 5) => 9
```
means “the result of evaluating the code (+ 4 5) is (or would be, or would have been) 9.”
Expansion
The symbol -> is used in examples to indicate macro expansion.
```
(push x v) -> (setf v (cons x v))
```
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.
Equivalence
The symbol == is used in examples to indicate code equivalence.
```
(gcd x (gcd y z)) == (gcd (gcd x y) z)
```
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.
Errors
Error
When this book specifies that it “is an error” for some situation to occur, this means that:
- No valid Common Lisp program should cause this situation to occur.
- If this situation occurs, the effects and results are completely undefined as far as adherence to the Common Lisp specification is concerned.
- No Common Lisp implementation is required to detect such an error.
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.
Error Signal
If it is specified in this book that in some situation “an error is signaled,” this means that:
- If this situation occurs, an error will be signaled;
  - see error and
  - cerror
- Valid Common Lisp programs may rely on the fact that an error will be signaled.
- Every Common Lisp implementation is required to detect such an error.
In all cases where an error is to be signaled, the word “signaled” is always used explicitly in this book.
X3J13

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.
Descriptions of Functions and Other Entities
- Functions,
- variables,
- named constants,
- special forms, and
- macros
are described using a distinctive typographical format.
1. Functions
  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.
```
----------------------------------------------------------------
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).

----------------------------------------------------------------
```
2. Global Variables
  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-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).

----------------------------------------------------------------
```
3. Constants
  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-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.

----------------------------------------------------------------
```
4. Special Forms and Macros
  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.
```
----------------------------------------------------------------
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)
----------------------------------------------------------------
```
5. Style Guide for Special Forms and Macros
  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.
      - 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.
      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.