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 ``<NEWLINE>'' might be used.

 (progn (format t "~&Who? ") (read-line))
>>  Who? Fred, Mary, and Sally<NEWLINE>
=>  "Fred, Mary, and Sally", false