I've seen this used once, but couldn't understand what it does. The reference says that it is
#n=object
reads as whatever object has object as its printed representation.
However, that object is labeled by n, a required
unsigned decimal integer, for possible reference by the syntax #n#.
The scope of the label is the expression being read by the outermost
call to read; within this expression, the same label may not appear
twice.
Which to me reads as just 56 randomly selected words of English language... Can you, please, show an example of when this may be used?
In Common Lisp it is used by the reader and the printer.
This way you can label an object in some s-expression and refer to it in a different place in the s-expression.
The label is #someinteger=
followed by an s-expression. The integer must be unique. You can't use the label twice within a single s-expression.
The reference to a label is #someinteger#
. The integer identifies the s-expression to reference. The label must be introduced, before it can be referenced. The reference can be used multiple times within an s-expression.
This is for example used in reading and printing circular lists or data structures with shared data objects.
Here a simple example:
? '(#1=(1 . 2) (#1#))
reads as
((1 . 2) ((1 . 2)))
Note also this:
? (eq (first *) (first (second *)))
T
It is one identical cons cell.
Let's try a circular list.
Make sure that the printer deals with circular lists and does not print them forever...
? (setf *print-circle* t)
T
Now we are constructing a list:
? (setf l1 (list 1 2 3))
(1 2 3)
We are setting the last cdr to the first cons:
? (setf (cdr (last l1)) l1)
#1=(1 2 3 . #1#)
As you can see above, the printed list gets a label and the last cdr is a reference to that label.
We can also enter a circular list directly by using the same notation. The reader understands it:
? '#1=(1 2 3 . #1#)
#1=(1 2 3 . #1#)
Since we have told the printer to deal with such constructs, we can try the expression from the first example:
? '(#1=(1 . 2) (#1#))
(#1=(1 . 2) (#1#))
Now the printer detects that there are two references to the same cons object.