CLHS: Section 1.4.1.3

#

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

Copyright 1996-2001, Xanalys Inc. All rights reserved.