Sharpsign is a non-terminating dispatching macro character. It reads an optional sequence of digits and then one more character, and uses that character to select a function to run as a reader macro function.
The standard syntax includes constructs introduced by the # character.
The syntax of these constructs is as follows:
a character that identifies the type of construct is
followed by arguments in some form.
If the character is a letter, its case is not important;
#O and #o are considered to be equivalent, for example.
Certain # constructs allow an unsigned decimal number to appear
between the # and the character.
The reader macros associated with the dispatching macro character #
are described later in this section and summarized in the next figure.
|
Figure 2.19: Standard # Dispatching Macro Character Syntax
The combinations marked by an asterisk (*) are explicitly reserved to the user. No conforming implementation defines them.
Note also that digits do not appear in the preceding table. This is
because the notations #0, #1, ..., #9 are
reserved for another purpose which occupies the same syntactic space.
When a digit follows a sharpsign,
it is not treated as a dispatch character.
Instead, an unsigned integer argument is accumulated
and passed as an argument to the reader macro
for the character that follows the digits.
For example,
#2A((1 2) (3 4)) is a use of #A with an argument of 2.
When the token x is a single character long,
this parses as the literal character char.
Uppercase and lowercase letters are distinguished after #\;
#\A and #\a denote different character objects.
Any single character works after #\,
even those that are normally special to read,
such as left-parenthesis and right-parenthesis.
In the single character case,
the x must be followed by a non-constituent character.
After #\ is read,
the reader backs up over the slash and then reads a token,
treating the initial slash as a single escape character
(whether it really is or not in the current readtable).
When the token x is more than one character long,
the x must have the syntax of a symbol
with no embedded package markers.
In this case, the sharpsign backslash notation
parses as the character whose name is (string-upcase x);
see Section 13.1.7 (Character Names).
For information about how the Lisp printer prints character objects, see Section 22.1.3.2 (Printing Characters).
Any expression preceded by #'
(sharpsign followed by single-quote),
as in #'expression,
is treated by the Lisp reader as an abbreviation for and parsed identically
to the expression (function expression).
See function. For example,
(apply #'+ l) ≡ (apply (function +) l)
#( and ) are used to notate a simple vector.
If an unsigned decimal integer
appears between the # and (,
it specifies explicitly the length of the vector.
The consequences are undefined if the number of objects
specified before the closing )
exceeds the unsigned decimal integer.
If the number of objects supplied before the closing )
is less than the unsigned decimal integer but greater than zero,
the last object
is used to fill all
remaining elements of the vector.
The consequences are undefined if the unsigned decimal integer is non-zero and
number of objects supplied before the closing )
is zero.
For example,
#(a b c c c c) #6(a b c c c c) #6(a b c) #6(a b c c)
all mean the same thing: a vector of length 6
with elements a, b, and four occurrences of c.
Other examples follow:
#(a b c) ;A vector of length 3
#(2 3 5 7 11 13 17 19 23 29 31 37 41 43 47)
;A vector containing the primes below 50
#() ;An empty vector
The notation #() denotes an empty vector, as does #0().
For information on how the Lisp printer prints vectors, see Section 22.1.3.4 (Printing Strings), Section 22.1.3.6 (Printing Bit Vectors), or Section 22.1.3.7 (Printing Other Vectors).
A simple bit vector is constructed containing the indicated bits
(0's and 1's), where the leftmost bit has index zero
and the subsequent bits have increasing indices.
Syntax: #«n»*«bits»
With an argument n, the vector to be created is of length n. If the number of bits is less than n but greater than zero, the last bit is used to fill all remaining bits of the bit vector.
The notations #* and #0* each denote an empty bit vector.
Regardless of whether the optional numeric argument n is provided,
the token that follows the asterisk is delimited by
a normal token delimiter.
However, (unless the value of *read-suppress* is true)
an error of type reader-error is signaled
if that token is not composed entirely of 0's and 1's,
or if n was supplied
and the token is composed of more than n bits,
or if n is greater than one, but no bits were specified.
Neither a single escape nor a multiple escape is permitted in this token.
For information on how the Lisp printer prints bit vectors, see Section 22.1.3.6 (Printing Bit Vectors).
For example,
#*101111 #6*101111 #6*101 #6*1011
all mean the same thing: a vector of length 6
with elements 1, 0, 1, 1, 1, and 1.
For example:
#* ;An empty bit-vector
#: introduces an uninterned symbol whose name
is symbol-name. Every time this syntax is encountered,
a distinct uninterned symbol is created.
The symbol-name must have the syntax of a symbol
with no package prefix.
For information on how the Lisp reader prints uninterned symbols, see Section 22.1.3.3 (Printing Symbols).
#.foo is read as the object resulting from the evaluation
of the object represented by foo.
The evaluation is done during the read process,
when the #. notation is encountered.
The #. syntax therefore performs a read-time evaluation of foo.
The normal effect of #. is inhibited when the value of *read-eval* is false.
In that situation, an error of type reader-error is signaled.
For an object
that does not have a convenient printed
representation, a form that computes the object can be given using
the #. notation.
#Brational reads rational in binary (radix 2).
For example,
#B1101 ≡ 13 ;11012 #b101/11 ≡ 5/3
The consequences are undefined if the token immediately following
the #B does not have the syntax of a binary (i.e., radix 2) rational.
#Orational reads rational in octal (radix 8).
For example,
#o37/15 ≡ 31/13 #o777 ≡ 511 #o105 ≡ 69 ;1058
The consequences are undefined if the token immediately following
the #O does not have the syntax of an octal (i.e., radix 8) rational.
#Xrational reads rational in hexadecimal (radix 16).
The digits above 9 are the letters A through F (the lowercase
letters a through f are also acceptable). For example,
#xF00 ≡ 3840 #x105 ≡ 261 ;10516
The consequences are undefined if the token immediately following
the #X does not have the syntax of a hexadecimal (i.e., radix 16) rational.
#radixRrational reads rational in radix radix.
radix must consist of only digits
that are interpreted as an integer
in decimal radix; its value must be between 2 and 36 (inclusive).
Only valid digits
for the specified radix may be used.
For example, #3r102 is another way of writing 11 (decimal),
and #11R32
is another way of writing 35 (decimal).
For radices larger than 10, letters of
the alphabet are used in order for the digits after 9.
No alternate # notation exists for the decimal radix since a
decimal point suffices.
The next figure contains examples of the use of #B,
#O, #X, and #R.
|
Figure 2.20: Radix Indicator Example
The consequences are undefined if the token immediately following
the #nR does not have the syntax of a rational in radix n.
#C reads a following object, which must be a list of
length two whose elements are both reals.
These reals denote, respectively,
the real and imaginary parts of a complex number.
If the two parts as notated are not of the same data type,
then they are converted
according to the rules of floating-point contagion
described in Section 12.1.1.2 (Contagion in Numeric Operations).
#C(real imag) is equivalent to
#.(complex (quote real) (quote imag)),
except that #C is not affected by *read-eval*.
See the function complex (Function).
The next figure contains examples of the use of #C.
|
Figure 2.21: Complex Number Example
For further information, see Section 22.1.3.1.4 (Printing Complexes) and Section 2.3.2.3 (Syntax of a Complex).
#nAobject constructs an n-dimensional array,
using object as the value of the :initial-contents argument
to make-array.
For example, #2A((0 1 5) (foo 2 (hot dog))) represents a 2-by-3 matrix:
0 1 5 foo 2 (hot dog)
In contrast, #1A((0 1 5) (foo 2 (hot dog)))
represents a vector of length 2
whose elements are lists:
(0 1 5) (foo 2 (hot dog))
#0A((0 1 5) (foo 2 (hot dog))) represents a zero-dimensional
array whose sole element is a list:
((0 1 5) (foo 2 (hot dog)))
#0A foo represents
a zero-dimensional array whose sole element is the
symbol foo.
The notation #1A foo is not valid because foo is
not a sequence.
If some dimension of the array
whose representation is being parsed is found to be 0,
all dimensions to the right
(i.e., the higher numbered dimensions)
are also considered to be 0.
For information on how the Lisp printer prints arrays, see Section 22.1.3.4 (Printing Strings), Section 22.1.3.6 (Printing Bit Vectors), Section 22.1.3.7 (Printing Other Vectors), or Section 22.1.3.8 (Printing Other Arrays).
#s(name slot1 value1 slot2 value2 ...)
denotes a structure. This is valid only if name is the name
of a structure type already defined by defstruct
and if the structure type has a standard constructor function.
Let cm stand for the name of this constructor function;
then this syntax is equivalent to
#.(cm keyword1 'value1 keyword2 'value2 ...)
where each keywordj is the result of computing
(intern (string slotj) (find-package 'keyword))
The net effect is that the constructor function is called with the specified
slots having the specified values.
(This coercion feature is deprecated; in the future, keyword names will
be taken in the package they are read in, so symbols that are
actually in the KEYWORD package should be used if that is what is desired.)
Whatever object the constructor function returns
is returned by the #S syntax.
For information on how the Lisp printer prints structures, see Section 22.1.3.12 (Printing Structures).
#P reads a following object, which must be a string.
#P«expression» is equivalent to
#.(parse-namestring '«expression»),
except that #P is not affected by *read-eval*.
For information on how the Lisp printer prints pathnames, see Section 22.1.3.11 (Printing Pathnames).
#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.
#n#, where n is a required unsigned decimal
integer,
provides a reference to some object labeled by #n=;
that is, #n# represents a pointer to the same
(eq) object labeled by #n=.
For example, a structure created in the variable y by this code:
(setq x (list 'p 'q)) (setq y (list (list 'a 'b) x 'foo x)) (rplacd (last y) (cdr y))
could be represented in this way:
((a b) . #1=(#2=(p q) foo #2# . #1#))
Without this notation, but with *print-length* set to 10
and *print-circle* set to nil,
the structure would print in this way:
((a b) (p q) foo (p q) (p q) foo (p q) (p q) foo (p q) ...)
A reference #n# may only occur after a label #n=;
forward references are not permitted. The reference
may not appear as the labeled object itself (that is,
#n=#n#) may not be written
because the object
labeled by #n= is not well defined in this case.
#+ provides a read-time conditionalization facility;
the syntax is #+test expression.
If the feature expression test succeeds,
then this textual notation represents an object
whose printed representation is expression.
If the feature expression test fails,
then this textual notation is treated as whitespace2;
that is, it is as if the “#+ test expression”
did not appear and only a space appeared in its place.
For a detailed description of success and failure in feature expressions, see Section 24.1.2.1 (Feature Expressions).
#+ operates by first reading the feature expression
and then skipping over the form if the feature expression fails.
While reading the test, the current package is the KEYWORD package.
Skipping over the form is accomplished by binding
*read-suppress* to true and then calling read.
For examples, see Section 24.1.2.1.1 (Examples of Feature Expressions).
#- is like #+
except that it skips the expression if the test succeeds;
that is,
#-test expression ≡ #+(not test) expression
For examples, see Section 24.1.2.1.1 (Examples of Feature Expressions).
#|...|# is treated as a comment by the reader.
It must be balanced with respect to other occurrences of #| and |#,
but otherwise may contain any characters whatsoever.
The following are some examples that exploit the #|...|# notation:
;;; In this example, some debugging code is commented out with #|...|# ;;; Note that this kind of comment can occur in the middle of a line ;;; (because a delimiter marks where the end of the comment occurs) ;;; where a semicolon comment can only occur at the end of a line ;;; (because it comments out the rest of the line). (defun add3 (n) #|(format t "~&Adding 3 to ~D." n)|# (+ n 3)) ;;; The examples that follow show issues related to #| ... |# nesting. ;;; In this first example, #| and |# always occur properly paired, ;;; so nesting works naturally. (defun mention-fun-fact-1a () (format t "CL uses ; and #|...|# in comments.")) → MENTION-FUN-FACT-1A (mention-fun-fact-1a) ▷ CL uses ; and #|...|# in comments. → NIL #| (defun mention-fun-fact-1b () (format t "CL uses ; and #|...|# in comments.")) |# (fboundp 'mention-fun-fact-1b) → NIL ;;; In this example, vertical-bar followed by sharpsign needed to appear ;;; in a string without any matching sharpsign followed by vertical-bar ;;; having preceded this. To compensate, the programmer has included a ;;; slash separating the two characters. In case 2a, the slash is ;;; unnecessary but harmless, but in case 2b, the slash is critical to ;;; allowing the outer #| ... |# pair match. If the slash were not present, ;;; the outer comment would terminate prematurely. (defun mention-fun-fact-2a () (format t "Don't use |\# unmatched or you'll get in trouble!")) → MENTION-FUN-FACT-2A (mention-fun-fact-2a) ▷ Don't use |# unmatched or you'll get in trouble! → NIL #| (defun mention-fun-fact-2b () (format t "Don't use |\# unmatched or you'll get in trouble!") |# (fboundp 'mention-fun-fact-2b) → NIL ;;; In this example, the programmer attacks the mismatch problem in a ;;; different way. The sharpsign vertical bar in the comment is not needed ;;; for the correct parsing of the program normally (as in case 3a), but ;;; becomes important to avoid premature termination of a comment when such ;;; a program is commented out (as in case 3b). (defun mention-fun-fact-3a () ; #| (format t "Don't use |# unmatched or you'll get in trouble!")) → MENTION-FUN-FACT-3A (mention-fun-fact-3a) ▷ Don't use |# unmatched or you'll get in trouble! → NIL #| (defun mention-fun-fact-3b () ; #| (format t "Don't use |# unmatched or you'll get in trouble!")) |# (fboundp 'mention-fun-fact-3b) → NIL
Some text editors that purport to understand Lisp syntax treat any |...|
as balanced pairs that cannot nest (as if they were just balanced pairs of
the multiple escapes used in notating certain symbols). To compensate for
this deficiency, some programmers use the notation #||...#||...||#...||#
instead of #|...#|...|#...|#. Note that this alternate usage is not
a different reader macro; it merely exploits the fact that the additional
vertical-bars occur within the comment in a way that tricks certain text editor
into better supporting nested comments. As such, one might sometimes see code
like:
#|| (+ #|| 3 ||# 4 5) ||#
Such code is equivalent to:
#| (+ #| 3 |# 4 5) |#
#< is not valid reader syntax.
The Lisp reader will signal an error
of type reader-error
on encountering #<.
This syntax is typically used in the printed representation
of objects that cannot be read back in.
# followed immediately by whitespace1 is not valid reader syntax.
The Lisp reader will signal an error of type reader-error if it
encounters the reader macro notation #<Newline> or #<Space>.
This is not valid reader syntax.
The Lisp reader will signal an error
of type reader-error
upon encountering #).