@node Reader, System Construction, Printer, Top @chapter Reader @menu * Reader Concepts:: * Reader Dictionary:: @end menu @node Reader Concepts, Reader Dictionary, Reader, Reader @section Reader Concepts @c including concept-reader @menu * Dynamic Control of the Lisp Reader:: * Effect of Readtable Case on the Lisp Reader:: * Argument Conventions of Some Reader Functions:: @end menu @node Dynamic Control of the Lisp Reader, Effect of Readtable Case on the Lisp Reader, Reader Concepts, Reader Concepts @subsection Dynamic Control of the Lisp Reader Various aspects of the @i{Lisp reader} can be controlled dynamically. See @ref{Readtables} and @ref{Variables that affect the Lisp Reader}. @node Effect of Readtable Case on the Lisp Reader, Argument Conventions of Some Reader Functions, Dynamic Control of the Lisp Reader, Reader Concepts @subsection Effect of Readtable Case on the Lisp Reader The @i{readtable case} of the @i{current readtable} affects the @i{Lisp reader} in the following ways: @table @asis @item @t{:upcase} When the @i{readtable case} is @t{:upcase}, unescaped constituent @i{characters} are converted to @i{uppercase}, as specified in @ref{Reader Algorithm}. @item @t{:downcase} When the @i{readtable case} is @t{:downcase}, unescaped constituent @i{characters} are converted to @i{lowercase}. @item @t{:preserve} When the @i{readtable case} is @t{:preserve}, the case of all @i{characters} remains unchanged. @item @t{:invert} When the @i{readtable case} is @t{:invert}, then if all of the unescaped letters in the extended token are of the same @i{case}, those (unescaped) letters are converted to the opposite @i{case}. @end table @menu * Examples of Effect of Readtable Case on the Lisp Reader:: @end menu @node Examples of Effect of Readtable Case on the Lisp Reader, , Effect of Readtable Case on the Lisp Reader, Effect of Readtable Case on the Lisp Reader @subsubsection Examples of Effect of Readtable Case on the Lisp Reader @example (defun test-readtable-case-reading () (let ((*readtable* (copy-readtable nil))) (format t "READTABLE-CASE Input Symbol-name~ ~ ~ (dolist (readtable-case '(:upcase :downcase :preserve :invert)) (setf (readtable-case *readtable*) readtable-case) (dolist (input '("ZEBRA" "Zebra" "zebra")) (format t "~&:~A~16T~A~24T~A" (string-upcase readtable-case) input (symbol-name (read-from-string input))))))) @end example The output from @t{(test-readtable-case-reading)} should be as follows: @example READTABLE-CASE Input Symbol-name ------------------------------------- :UPCASE ZEBRA ZEBRA :UPCASE Zebra ZEBRA :UPCASE zebra ZEBRA :DOWNCASE ZEBRA zebra :DOWNCASE Zebra zebra :DOWNCASE zebra zebra :PRESERVE ZEBRA ZEBRA :PRESERVE Zebra Zebra :PRESERVE zebra zebra :INVERT ZEBRA zebra :INVERT Zebra Zebra :INVERT zebra ZEBRA @end example @node Argument Conventions of Some Reader Functions, , Effect of Readtable Case on the Lisp Reader, Reader Concepts @subsection Argument Conventions of Some Reader Functions @menu * The EOF-ERROR-P argument:: * The RECURSIVE-P argument:: @end menu @node The EOF-ERROR-P argument, The RECURSIVE-P argument, Argument Conventions of Some Reader Functions, Argument Conventions of Some Reader Functions @subsubsection The EOF-ERROR-P argument @i{Eof-error-p} in input function calls controls what happens if input is from a file (or any other input source that has a definite end) and the end of the file is reached. If @i{eof-error-p} is @i{true} (the default), an error of @i{type} @b{end-of-file} is signaled at end of file. If it is @i{false}, then no error is signaled, and instead the function returns @i{eof-value}. Functions such as @b{read} that read the representation of an @i{object} rather than a single character always signals an error, regardless of @i{eof-error-p}, if the file ends in the middle of an object representation. For example, if a file does not contain enough right parentheses to balance the left parentheses in it, @b{read} signals an error. If a file ends in a @i{symbol} or a @i{number} immediately followed by end-of-file, @b{read} reads the @i{symbol} or @i{number} successfully and when called again will act according to @i{eof-error-p}. Similarly, the @i{function} @b{read-line} successfully reads the last line of a file even if that line is terminated by end-of-file rather than the newline character. Ignorable text, such as lines containing only @i{whitespace}_2 or comments, are not considered to begin an @i{object}; if @b{read} begins to read an @i{expression} but sees only such ignorable text, it does not consider the file to end in the middle of an @i{object}. Thus an @i{eof-error-p} argument controls what happens when the file ends between @i{objects}. @node The RECURSIVE-P argument, , The EOF-ERROR-P argument, Argument Conventions of Some Reader Functions @subsubsection The RECURSIVE-P argument If @i{recursive-p} is supplied and not @b{nil}, it specifies that this function call is not an outermost call to @b{read} but an embedded call, typically from a @i{reader macro function}. It is important to distinguish such recursive calls for three reasons. @table @asis @item 1. An outermost call establishes the context within which the @t{#@i{n}=} and @t{#@i{n}#} syntax is scoped. Consider, for example, the expression @example (cons '#3=(p q r) '(x y . #3#)) @end example If the @i{single-quote} @i{reader macro} were defined in this way: @example (set-macro-character #\' ;incorrect #'(lambda (stream char) (declare (ignore char)) (list 'quote (read stream)))) @end example then each call to the @i{single-quote} @i{reader macro function} would establish independent contexts for the scope of @b{read} information, including the scope of identifications between markers like ``@t{#3=}'' and ``@t{#3#}''. However, for this expression, the scope was clearly intended to be determined by the outer set of parentheses, so such a definition would be incorrect. The correct way to define the @i{single-quote} @i{reader macro} uses @i{recursive-p}: @example (set-macro-character #\' ;correct #'(lambda (stream char) (declare (ignore char)) (list 'quote (read stream t nil t)))) @end example @item 2. A recursive call does not alter whether the reading process is to preserve @i{whitespace}_2 or not (as determined by whether the outermost call was to @b{read} or @b{read-preserving-whitespace}). Suppose again that @i{single-quote} were to be defined as shown above in the incorrect definition. Then a call to @b{read-preserving-whitespace} that read the expression @t{'foo<@i{Space}>} would fail to preserve the space character following the symbol @t{foo} because the @i{single-quote} @i{reader macro function} calls @b{read}, not @b{read-preserving-whitespace}, to read the following expression (in this case @t{foo}). The correct definition, which passes the value @i{true} for @i{recursive-p} to @b{read}, allows the outermost call to determine whether @i{whitespace}_2 is preserved. @item 3. When end-of-file is encountered and the @i{eof-error-p} argument is not @b{nil}, the kind of error that is signaled may depend on the value of @i{recursive-p}. If @i{recursive-p} is @i{true}, then the end-of-file is deemed to have occurred within the middle of a printed representation; if @i{recursive-p} is @i{false}, then the end-of-file may be deemed to have occurred between @i{objects} rather than within the middle of one. @end table @c end of including concept-reader @node Reader Dictionary, , Reader Concepts, Reader @section Reader Dictionary @c including dict-reader @menu * readtable:: * copy-readtable:: * make-dispatch-macro-character:: * read:: * read-delimited-list:: * read-from-string:: * readtable-case:: * readtablep:: * set-dispatch-macro-character:: * set-macro-character:: * set-syntax-from-char:: * with-standard-io-syntax:: * *read-base*:: * *read-default-float-format*:: * *read-eval*:: * *read-suppress*:: * *readtable*:: * reader-error:: @end menu @node readtable, copy-readtable, Reader Dictionary, Reader Dictionary @subsection readtable [System Class] @subsubheading Class Precedence List:: @b{readtable}, @b{t} @subsubheading Description:: A @i{readtable} maps @i{characters} into @i{syntax types} for the @i{Lisp reader}; see @ref{Syntax}. A @i{readtable} also contains associations between @i{macro characters} and their @i{reader macro functions}, and records information about the case conversion rules to be used by the @i{Lisp reader} when parsing @i{symbols}. Each @i{simple} @i{character} must be representable in the @i{readtable}. It is @i{implementation-defined} whether @i{non-simple} @i{characters} can have syntax descriptions in the @i{readtable}. @subsubheading See Also:: @ref{Readtables}, @ref{Printing Other Objects} @node copy-readtable, make-dispatch-macro-character, readtable, Reader Dictionary @subsection copy-readtable [Function] @code{copy-readtable} @i{{&optional} from-readtable to-readtable} @result{} @i{readtable} @subsubheading Arguments and Values:: @i{from-readtable}---a @i{readtable designator}. The default is the @i{current readtable}. @i{to-readtable}---a @i{readtable} or @b{nil}. The default is @b{nil}. @i{readtable}---the @i{to-readtable} if it is @i{non-nil}, or else a @i{fresh} @i{readtable}. @subsubheading Description:: @b{copy-readtable} copies @i{from-readtable}. If @i{to-readtable} is @b{nil}, a new @i{readtable} is created and returned. Otherwise the @i{readtable} specified by @i{to-readtable} is modified and returned. @b{copy-readtable} copies the setting of @b{readtable-case}. @subsubheading Examples:: @example (setq zvar 123) @result{} 123 (set-syntax-from-char #\z #\' (setq table2 (copy-readtable))) @result{} T zvar @result{} 123 (copy-readtable table2 *readtable*) @result{} # zvar @result{} VAR (setq *readtable* (copy-readtable)) @result{} # zvar @result{} VAR (setq *readtable* (copy-readtable nil)) @result{} # zvar @result{} 123 @end example @subsubheading See Also:: @b{readtable}, @ref{readtable} @subsubheading Notes:: @example (setq *readtable* (copy-readtable nil)) @end example restores the input syntax to standard @r{Common Lisp} syntax, even if the @i{initial readtable} has been clobbered (assuming it is not so badly clobbered that you cannot type in the above expression). On the other hand, @example (setq *readtable* (copy-readtable)) @end example replaces the current @i{readtable} with a copy of itself. This is useful if you want to save a copy of a readtable for later use, protected from alteration in the meantime. It is also useful if you want to locally bind the readtable to a copy of itself, as in: @example (let ((*readtable* (copy-readtable))) ...) @end example @node make-dispatch-macro-character, read, copy-readtable, Reader Dictionary @subsection make-dispatch-macro-character [Function] @code{make-dispatch-macro-character} @i{char {&optional} non-terminating-p readtable} @result{} @i{@b{t}} @subsubheading Arguments and Values:: @i{char}---a @i{character}. @i{non-terminating-p}---a @i{generalized boolean}. The default is @i{false}. @i{readtable}---a @i{readtable}. The default is the @i{current readtable}. @subsubheading Description:: @b{make-dispatch-macro-character} makes @i{char} be a @i{dispatching macro character} in @i{readtable}. Initially, every @i{character} in the dispatch table associated with the @i{char} has an associated function that signals an error of @i{type} @b{reader-error}. If @i{non-terminating-p} is @i{true}, the @i{dispatching macro character} is made a @i{non-terminating} @i{macro character}; if @i{non-terminating-p} is @i{false}, the @i{dispatching macro character} is made a @i{terminating} @i{macro character}. @subsubheading Examples:: @example (get-macro-character #\@{) @result{} NIL, @i{false} (make-dispatch-macro-character #\@{) @result{} T (not (get-macro-character #\@{)) @result{} @i{false} @end example The @i{readtable} is altered. @subsubheading See Also:: @ref{readtable} , @ref{set-dispatch-macro-character; get-dispatch-macro-character} @node read, read-delimited-list, make-dispatch-macro-character, Reader Dictionary @subsection read, read-preserving-whitespace [Function] @code{read} @i{{&optional} input-stream eof-error-p eof-value recursive-p} @result{} @i{object} @code{read-preserving-whitespace} @i{{&optional} input-stream eof-error-p eof-value recursive-p}@* @result{} @i{object} @subsubheading Arguments and Values:: @i{input-stream}---an @i{input} @i{stream designator}. @i{eof-error-p}---a @i{generalized boolean}. The default is @i{true}. @i{eof-value}---an @i{object}. The default is @b{nil}. @i{recursive-p}---a @i{generalized boolean}. The default is @i{false}. @i{object}---an @i{object} (parsed by the @i{Lisp reader}) or the @i{eof-value}. @subsubheading Description:: @b{read} parses the printed representation of an @i{object} from @i{input-stream} and builds such an @i{object}. @b{read-preserving-whitespace} is like @b{read} but preserves any @i{whitespace}_2 @i{character} that delimits the printed representation of the @i{object}. @b{read-preserving-whitespace} is exactly like @b{read} when the @i{recursive-p} @i{argument} to @b{read-preserving-whitespace} is @i{true}. When @b{*read-suppress*} is @i{false}, @b{read} throws away the delimiting @i{character} required by certain printed representations if it is a @i{whitespace}_2 @i{character}; but @b{read} preserves the character (using @b{unread-char}) if it is syntactically meaningful, because it could be the start of the next expression. If a file ends in a @i{symbol} or a @i{number} immediately followed by an @i{end of file}_1, @b{read} reads the @i{symbol} or @i{number} successfully; when called again, it sees the @i{end of file}_1 and only then acts according to @i{eof-error-p}. If a file contains ignorable text at the end, such as blank lines and comments, @b{read} does not consider it to end in the middle of an @i{object}. If @i{recursive-p} is @i{true}, the call to @b{read} is expected to be made from within some function that itself has been called from @b{read} or from a similar input function, rather than from the top level. Both functions return the @i{object} read from @i{input-stream}. @i{Eof-value} is returned if @i{eof-error-p} is @i{false} and end of file is reached before the beginning of an @i{object}. @subsubheading Examples:: @example (read) @t{ |> } @b{|>>}@t{'a}@b{<<|} @result{} (QUOTE A) (with-input-from-string (is " ") (read is nil 'the-end)) @result{} THE-END (defun skip-then-read-char (s c n) (if (char= c #\@{) (read s t nil t) (read-preserving-whitespace s)) (read-char-no-hang s)) @result{} SKIP-THEN-READ-CHAR (let ((*readtable* (copy-readtable nil))) (set-dispatch-macro-character #\# #\@{ #'skip-then-read-char) (set-dispatch-macro-character #\# #\@} #'skip-then-read-char) (with-input-from-string (is "#@{123 x #@}123 y") (format t "~S ~S" (read is) (read is)))) @result{} #\x, #\Space, NIL @end example As an example, consider this @i{reader macro} definition: @example (defun slash-reader (stream char) (declare (ignore char)) `(path . ,(loop for dir = (read-preserving-whitespace stream t nil t) then (progn (read-char stream t nil t) (read-preserving-whitespace stream t nil t)) collect dir while (eql (peek-char nil stream nil nil t) #\/)))) (set-macro-character #\/ #'slash-reader) @end example Consider now calling @b{read} on this expression: @example (zyedh /usr/games/zork /usr/games/boggle) @end example The @t{/} macro reads objects separated by more @t{/} characters; thus @t{/usr/games/zork} is intended to read as @t{(path usr games zork)}. The entire example expression should therefore be read as @example (zyedh (path usr games zork) (path usr games boggle)) @end example However, if @b{read} had been used instead of @b{read-preserving-whitespace}, then after the reading of the symbol @t{zork}, the following space would be discarded; the next call to @b{peek-char} would see the following @t{/}, and the loop would continue, producing this interpretation: @example (zyedh (path usr games zork usr games boggle)) @end example There are times when @i{whitespace}_2 should be discarded. If a command interpreter takes single-character commands, but occasionally reads an @i{object} then if the @i{whitespace}_2 after a @i{symbol} is not discarded it might be interpreted as a command some time later after the @i{symbol} had been read. @subsubheading Affected By:: @b{*standard-input*}, @b{*terminal-io*}, @b{*readtable*}, @b{*read-default-float-format*}, @b{*read-base*}, @b{*read-suppress*}, @b{*package*}, @b{*read-eval*}. @subsubheading Exceptional Situations:: @b{read} signals an error of @i{type} @b{end-of-file}, regardless of @i{eof-error-p}, if the file ends in the middle of an @i{object} representation. For example, if a file does not contain enough right parentheses to balance the left parentheses in it, @b{read} signals an error. This is detected when @b{read} or @b{read-preserving-whitespace} is called with @i{recursive-p} and @i{eof-error-p} @i{non-nil}, and end-of-file is reached before the beginning of an @i{object}. If @i{eof-error-p} is @i{true}, an error of @i{type} @b{end-of-file} is signaled at the end of file. @subsubheading See Also:: @ref{peek-char} , @ref{read-char} , @ref{unread-char} , @ref{read-from-string} , @ref{read-delimited-list} , @ref{parse-integer} , {@ref{Syntax}}, {@ref{Reader Concepts}} @node read-delimited-list, read-from-string, read, Reader Dictionary @subsection read-delimited-list [Function] @code{read-delimited-list} @i{char {&optional} input-stream recursive-p} @result{} @i{list} @subsubheading Arguments and Values:: @i{char}---a @i{character}. @i{input-stream}---an @i{input} @i{stream designator}. The default is @i{standard input}. @i{recursive-p}---a @i{generalized boolean}. The default is @i{false}. @i{list}---a @i{list} of the @i{objects} read. @subsubheading Description:: @b{read-delimited-list} reads @i{objects} from @i{input-stream} until the next character after an @i{object}'s representation (ignoring @i{whitespace}_2 characters and comments) is @i{char}. @b{read-delimited-list} looks ahead at each step for the next non-@i{whitespace}_2 @i{character} and peeks at it as if with @b{peek-char}. If it is @i{char}, then the @i{character} is consumed and the @i{list} of @i{objects} is returned. If it is a @i{constituent} or @i{escape} @i{character}, then @b{read} is used to read an @i{object}, which is added to the end of the @i{list}. If it is a @i{macro character}, its @i{reader macro function} is called; if the function returns a @i{value}, that @i{value} is added to the @i{list}. The peek-ahead process is then repeated. If @i{recursive-p} is @i{true}, this call is expected to be embedded in a higher-level call to @b{read} or a similar function. It is an error to reach end-of-file during the operation of @b{read-delimited-list}. The consequences are undefined if @i{char} has a @i{syntax type} of @i{whitespace}_2 in the @i{current readtable}. @subsubheading Examples:: @example (read-delimited-list #\{]}) 1 2 3 4 5 6 {]} @result{} (1 2 3 4 5 6) @end example Suppose you wanted @t{#@{{@i{a}} @i{b} @i{c} ... @i{z}@}} to read as a list of all pairs of the elements @i{a}, @i{b}, @i{c}, ..., @i{z}, for example. @example #@{p q z a@} reads as ((p q) (p z) (p a) (q z) (q a) (z a)) @end example This can be done by specifying a macro-character definition for @t{#@{} that does two things: reads in all the items up to the @t{@}}, and constructs the pairs. @b{read-delimited-list} performs the first task. @example (defun |#@{-reader| (stream char arg) (declare (ignore char arg)) (mapcon #'(lambda (x) (mapcar #'(lambda (y) (list (car x) y)) (cdr x))) (read-delimited-list #\@} stream t))) @result{} |#@{-reader| (set-dispatch-macro-character #\# #\@{ #'|#@{-reader|) @result{} T (set-macro-character #\@} (get-macro-character #\) @b{nil})) @end example Note that @i{true} is supplied for the @i{recursive-p} argument. It is necessary here to give a definition to the character @t{@}} as well to prevent it from being a constituent. If the line @example (set-macro-character #\@} (get-macro-character #\) @b{nil})) @end example shown above were not included, then the @t{@}} in @example #@{ p q z a@} @end example would be considered a constituent character, part of the symbol named @t{a@}}. This could be corrected by putting a space before the @t{@}}, but it is better to call @b{set-macro-character}. Giving @t{@}} the same definition as the standard definition of the character @t{)} has the twin benefit of making it terminate tokens for use with @b{read-delimited-list} and also making it invalid for use in any other context. Attempting to read a stray @t{@}} will signal an error. @subsubheading Affected By:: @b{*standard-input*}, @b{*readtable*}, @b{*terminal-io*}. @subsubheading See Also:: @ref{read; read-preserving-whitespace} , @ref{peek-char} , @ref{read-char} , @ref{unread-char} . @subsubheading Notes:: @b{read-delimited-list} is intended for use in implementing @i{reader macros}. Usually it is desirable for @i{char} to be a @i{terminating} @i{macro character} so that it can be used to delimit tokens; however, @b{read-delimited-list} makes no attempt to alter the syntax specified for @i{char} by the current readtable. The caller must make any necessary changes to the readtable syntax explicitly. @node read-from-string, readtable-case, read-delimited-list, Reader Dictionary @subsection read-from-string [Function] @code{read-from-string} @i{string {&optional} eof-error-p eof-value {&key} start end preserve-whitespace}@* @result{} @i{object, position} @subsubheading Arguments and Values:: @i{string}---a @i{string}. @i{eof-error-p}---a @i{generalized boolean}. The default is @i{true}. @i{eof-value}---an @i{object}. The default is @b{nil}. @i{start}, @i{end}---@i{bounding index designators} of @i{string}. The defaults for @i{start} and @i{end} are @t{0} and @b{nil}, respectively. @i{preserve-whitespace}---a @i{generalized boolean}. The default is @i{false}. @i{object}---an @i{object} (parsed by the @i{Lisp reader}) or the @i{eof-value}. @i{position}---an @i{integer} greater than or equal to zero, and less than or equal to one more than the @i{length} of the @i{string}. @subsubheading Description:: Parses the printed representation of an @i{object} from the subsequence of @i{string} @i{bounded} by @i{start} and @i{end}, as if @b{read} had been called on an @i{input} @i{stream} containing those same @i{characters}. If @i{preserve-whitespace} is @i{true}, the operation will preserve @i{whitespace}_2 as @b{read-preserving-whitespace} would do. If an @i{object} is successfully parsed, the @i{primary value}, @i{object}, is the @i{object} that was parsed. If @i{eof-error-p} is @i{false} and if the end of the @i{substring} is reached, @i{eof-value} is returned. The @i{secondary value}, @i{position}, is the index of the first @i{character} in the @i{bounded} @i{string} that was not read. The @i{position} may depend upon the value of @i{preserve-whitespace}. If the entire @i{string} was read, the @i{position} returned is either the @i{length} of the @i{string} or one greater than the @i{length} of the @i{string}. @subsubheading Examples:: @example (read-from-string " 1 3 5" t nil :start 2) @result{} 3, 5 (read-from-string "(a b c)") @result{} (A B C), 7 @end example @subsubheading Exceptional Situations:: If the end of the supplied substring occurs before an @i{object} can be read, an error is signaled if @i{eof-error-p} is @i{true}. An error is signaled if the end of the @i{substring} occurs in the middle of an incomplete @i{object}. @subsubheading See Also:: @ref{read; read-preserving-whitespace} , @b{read-preserving-whitespace} @subsubheading Notes:: The reason that @i{position} is allowed to be beyond the @i{length} of the @i{string} is to permit (but not require) the @i{implementation} to work by simulating the effect of a trailing delimiter at the end of the @i{bounded} @i{string}. When @i{preserve-whitespace} is @i{true}, the @i{position} might count the simulated delimiter. @node readtable-case, readtablep, read-from-string, Reader Dictionary @subsection readtable-case [Accessor] @code{readtable-case} @i{readtable} @result{} @i{mode} (setf (@code{ readtable-case} @i{readtable}) mode)@* @subsubheading Arguments and Values:: @i{readtable}---a @i{readtable}. @i{mode}---a @i{case sensitivity mode}. @subsubheading Description:: @i{Accesses} the @i{readtable case} of @i{readtable}, which affects the way in which the @i{Lisp Reader} reads @i{symbols} and the way in which the @i{Lisp Printer} writes @i{symbols}. @subsubheading Examples:: See @ref{Examples of Effect of Readtable Case on the Lisp Reader} and @ref{Examples of Effect of Readtable Case on the Lisp Printer}. @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if @i{readtable} is not a @i{readtable}. Should signal an error of @i{type} @b{type-error} if @i{mode} is not a @i{case sensitivity mode}. @subsubheading See Also:: @ref{readtable} , @b{*print-escape*}, @ref{Reader Algorithm}, @ref{Effect of Readtable Case on the Lisp Reader}, @ref{Effect of Readtable Case on the Lisp Printer} @subsubheading Notes:: @b{copy-readtable} copies the @i{readtable case} of the @i{readtable}. @node readtablep, set-dispatch-macro-character, readtable-case, Reader Dictionary @subsection readtablep [Function] @code{readtablep} @i{object} @result{} @i{generalized-boolean} @subsubheading Arguments and Values:: @i{object}---an @i{object}. @i{generalized-boolean}---a @i{generalized boolean}. @subsubheading Description:: Returns @i{true} if @i{object} is of @i{type} @b{readtable}; otherwise, returns @i{false}. @subsubheading Examples:: @example (readtablep *readtable*) @result{} @i{true} (readtablep (copy-readtable)) @result{} @i{true} (readtablep '*readtable*) @result{} @i{false} @end example @subsubheading Notes:: @example (readtablep @i{object}) @equiv{} (typep @i{object} 'readtable) @end example @node set-dispatch-macro-character, set-macro-character, readtablep, Reader Dictionary @subsection set-dispatch-macro-character, get-dispatch-macro-character @flushright @i{[Function]} @end flushright @code{get-dispatch-macro-character} @i{disp-char sub-char {&optional} readtable} @result{} @i{function} @code{set-dispatch-macro-character} @i{disp-char sub-char new-function {&optional} readtable} @result{} @i{@b{t}} @subsubheading Arguments and Values:: @i{disp-char}---a @i{character}. @i{sub-char}---a @i{character}. @i{readtable}---a @i{readtable designator}. The default is the @i{current readtable}. @i{function}---a @i{function designator} or @b{nil}. @i{new-function}---a @i{function designator}. @subsubheading Description:: @b{set-dispatch-macro-character} causes @i{new-function} to be called when @i{disp-char} followed by @i{sub-char} is read. If @i{sub-char} is a lowercase letter, it is converted to its uppercase equivalent. It is an error if @i{sub-char} is one of the ten decimal digits. @b{set-dispatch-macro-character} installs a @i{new-function} to be called when a particular @i{dispatching macro character} pair is read. @i{New-function} is installed as the dispatch function to be called when @i{readtable} is in use and when @i{disp-char} is followed by @i{sub-char}. For more information about how the @i{new-function} is invoked, see @ref{Macro Characters}. @b{get-dispatch-macro-character} retrieves the dispatch function associated with @i{disp-char} and @i{sub-char} in @i{readtable}. @b{get-dispatch-macro-character} returns the macro-character function for @i{sub-char} under @i{disp-char}, or @b{nil} if there is no function associated with @i{sub-char}. If @i{sub-char} is a decimal digit, @b{get-dispatch-macro-character} returns @b{nil}. @subsubheading Examples:: @example (get-dispatch-macro-character #\# #\@{) @result{} NIL (set-dispatch-macro-character #\# #\@{ ;dispatch on #@{ #'(lambda(s c n) (let ((list (read s nil (values) t))) ;list is object after #n@{ (when (consp list) ;return nth element of list (unless (and n (< 0 n (length list))) (setq n 0)) (setq list (nth n list))) list))) @result{} T #@{(1 2 3 4) @result{} 1 #3@{(0 1 2 3) @result{} 3 #@{123 @result{} 123 @end example If it is desired that @t{#$@i{foo}} : as if it were @t{(dollars @i{foo})}. @example (defun |#$-reader| (stream subchar arg) (declare (ignore subchar arg)) (list 'dollars (read stream t nil t))) @result{} |#$-reader| (set-dispatch-macro-character #\# #\$ #'|#$-reader|) @result{} T @end example @subsubheading See Also:: @ref{Macro Characters} @subsubheading Side Effects:: The @i{readtable} is modified. @subsubheading Affected By:: @b{*readtable*}. @subsubheading Exceptional Situations:: For either function, an error is signaled if @i{disp-char} is not a @i{dispatching macro character} in @i{readtable}. @subsubheading See Also:: @ref{readtable} @subsubheading Notes:: It is necessary to use @b{make-dispatch-macro-character} to set up the dispatch character before specifying its sub-characters. @node set-macro-character, set-syntax-from-char, set-dispatch-macro-character, Reader Dictionary @subsection set-macro-character, get-macro-character [Function] @code{get-macro-character} @i{char {&optional} readtable} @result{} @i{function, non-terminating-p} @code{set-macro-character} @i{char new-function {&optional} non-terminating-p readtable} @result{} @i{@b{t}} @subsubheading Arguments and Values:: @i{char}---a @i{character}. @i{non-terminating-p}---a @i{generalized boolean}. The default is @i{false}. @i{readtable}---a @i{readtable designator}. The default is the @i{current readtable}. @i{function}---@b{nil}, or a @i{designator} for a @i{function} of two @i{arguments}. @i{new-function}---a @i{function designator}. @subsubheading Description:: @b{get-macro-character} returns as its @i{primary value}, @i{function}, the @i{reader macro function} associated with @i{char} in @i{readtable} (if any), or else @b{nil} if @i{char} is not a @i{macro character} in @i{readtable}. The @i{secondary value}, @i{non-terminating-p}, is @i{true} if @i{char} is a @i{non-terminating} @i{macro character}; otherwise, it is @i{false}. @b{set-macro-character} causes @i{char} to be a @i{macro character} associated with the @i{reader macro function} @i{new-function} (or the @i{designator} for @i{new-function}) in @i{readtable}. If @i{non-terminating-p} is @i{true}, @i{char} becomes a @i{non-terminating} @i{macro character}; otherwise it becomes a @i{terminating} @i{macro character}. @subsubheading Examples:: @example (get-macro-character #\@{) @result{} NIL, @i{false} (not (get-macro-character #\;)) @result{} @i{false} @end example The following is a possible definition for the @i{single-quote} @i{reader macro} in @i{standard syntax}: @example (defun single-quote-reader (stream char) (declare (ignore char)) (list 'quote (read stream t nil t))) @result{} SINGLE-QUOTE-READER (set-macro-character #\' #'single-quote-reader) @result{} T @end example Here @t{single-quote-reader} reads an @i{object} following the @i{single-quote} and returns a @i{list} of @b{quote} and that @i{object}. The @i{char} argument is ignored. The following is a possible definition for the @i{semicolon} @i{reader macro} in @i{standard syntax}: @example (defun semicolon-reader (stream char) (declare (ignore char)) ;; First swallow the rest of the current input line. ;; End-of-file is acceptable for terminating the comment. (do () ((char= (read-char stream nil #\Newline t) #\Newline))) ;; Return zero values. (values)) @result{} SEMICOLON-READER (set-macro-character #\; #'semicolon-reader) @result{} T @end example @subsubheading Side Effects:: The @i{readtable} is modified. @subsubheading See Also:: @ref{readtable} @node set-syntax-from-char, with-standard-io-syntax, set-macro-character, Reader Dictionary @subsection set-syntax-from-char [Function] @code{set-syntax-from-char} @i{to-char from-char {&optional} to-readtable from-readtable} @result{} @i{@b{t}} @subsubheading Arguments and Values:: @i{to-char}---a @i{character}. @i{from-char}---a @i{character}. @i{to-readtable}---a @i{readtable}. The default is the @i{current readtable}. @i{from-readtable}---a @i{readtable designator}. The default is the @i{standard readtable}. @subsubheading Description:: @b{set-syntax-from-char} makes the syntax of @i{to-char} in @i{to-readtable} be the same as the syntax of @i{from-char} in @i{from-readtable}. @b{set-syntax-from-char} copies the @i{syntax types} of @i{from-char}. If @i{from-char} is a @i{macro character}, its @i{reader macro function} is copied also. If the character is a @i{dispatching macro character}, its entire dispatch table of @i{reader macro functions} is copied. The @i{constituent traits} of @i{from-char} are not copied. A macro definition from a character such as @t{"} can be copied to another character; the standard definition for @t{"} looks for another character that is the same as the character that invoked it. The definition of @t{(} can not be meaningfully copied to @t{@{}, on the other hand. The result is that @i{lists} are of the form @t{@{a b c)}, not @t{@{a b c@}}, because the definition always looks for a closing parenthesis, not a closing brace. @subsubheading Examples:: @example (set-syntax-from-char #\7 #\;) @result{} T 123579 @result{} 1235 @end example @subsubheading Side Effects:: The @i{to-readtable} is modified. @subsubheading Affected By:: The existing values in the @i{from-readtable}. @subsubheading See Also:: @ref{set-macro-character; get-macro-character} , @ref{make-dispatch-macro-character} , @ref{Character Syntax Types} @subsubheading Notes:: The @i{constituent traits} of a @i{character} are ``hard wired'' into the parser for extended @i{tokens}. For example, if the definition of @t{S} is copied to @t{*}, then @t{*} will become a @i{constituent} that is @i{alphabetic}_2 but that cannot be used as a @i{short float} @i{exponent marker}. For further information, see @ref{Constituent Traits}. @node with-standard-io-syntax, *read-base*, set-syntax-from-char, Reader Dictionary @subsection with-standard-io-syntax [Macro] @code{with-standard-io-syntax} @i{@{@i{form}@}{*}} @result{} @i{@{@i{result}@}{*}} @subsubheading Arguments and Values:: @i{forms}---an @i{implicit progn}. @i{results}---the @i{values} returned by the @i{forms}. @subsubheading Description:: Within the dynamic extent of the body of @i{forms}, all reader/printer control variables, including any @i{implementation-defined} ones not specified by this standard, are bound to values that produce standard read/print behavior. The values for the variables specified by this standard are listed in Figure 23--1. [Reviewer Note by Barrett: *print-pprint-dispatch* should probably be mentioned here, too.] @group @noindent @w{ Variable Value } @w{ @b{*package*} The @t{CL-USER} @i{package} } @w{ @b{*print-array*} @b{t} } @w{ @b{*print-base*} @t{10} } @w{ @b{*print-case*} @t{:upcase} } @w{ @b{*print-circle*} @b{nil} } @w{ @b{*print-escape*} @b{t} } @w{ @b{*print-gensym*} @b{t} } @w{ @b{*print-length*} @b{nil} } @w{ @b{*print-level*} @b{nil} } @w{ @b{*print-lines*} @b{nil} } @w{ @b{*print-miser-width*} @b{nil} } @w{ @b{*print-pprint-dispatch*} The @i{standard pprint dispatch table} } @w{ @b{*print-pretty*} @b{nil} } @w{ @b{*print-radix*} @b{nil} } @w{ @b{*print-readably*} @b{t} } @w{ @b{*print-right-margin*} @b{nil} } @w{ @b{*read-base*} @t{10} } @w{ @b{*read-default-float-format*} @b{single-float} } @w{ @b{*read-eval*} @b{t} } @w{ @b{*read-suppress*} @b{nil} } @w{ @b{*readtable*} The @i{standard readtable} } @noindent @w{ Figure 23--1: Values of standard control variables } @end group @subsubheading Examples:: @example (with-open-file (file pathname :direction :output) (with-standard-io-syntax (print data file))) ;;; ... Later, in another Lisp: (with-open-file (file pathname :direction :input) (with-standard-io-syntax (setq data (read file)))) @end example @node *read-base*, *read-default-float-format*, with-standard-io-syntax, Reader Dictionary @subsection *read-base* [Variable] @subsubheading Value Type:: a @i{radix}. @subsubheading Initial Value:: @t{10}. @subsubheading Description:: Controls the interpretation of tokens by @b{read} as being @i{integers} or @i{ratios}. The @i{value} of @b{*read-base*}, called the @i{current input base} @IGindex{current input base} , is the radix in which @i{integers} and @i{ratios} are to be read by the @i{Lisp reader}. The parsing of other numeric @i{types} (@i{e.g.}, @i{floats}) is not affected by this option. The effect of @b{*read-base*} on the reading of any particular @i{rational} number can be locally overridden by explicit use of the @t{#O}, @t{#X}, @t{#B}, or @t{#@i{n}R} syntax or by a trailing decimal point. @subsubheading Examples:: @example (dotimes (i 6) (let ((*read-base* (+ 10. i))) (let ((object (read-from-string "(\\DAD DAD |BEE| BEE 123. 123)"))) (print (list *read-base* object))))) @t{ |> } (10 (DAD DAD BEE BEE 123 123)) @t{ |> } (11 (DAD DAD BEE BEE 123 146)) @t{ |> } (12 (DAD DAD BEE BEE 123 171)) @t{ |> } (13 (DAD DAD BEE BEE 123 198)) @t{ |> } (14 (DAD 2701 BEE BEE 123 227)) @t{ |> } (15 (DAD 3088 BEE 2699 123 258)) @result{} NIL @end example @subsubheading Notes:: Altering the input radix can be useful when reading data files in special formats. @node *read-default-float-format*, *read-eval*, *read-base*, Reader Dictionary @subsection *read-default-float-format* [Variable] @subsubheading Value Type:: one of the @i{atomic type specifiers} @b{short-float}, @b{single-float}, @b{double-float}, or @b{long-float}, or else some other @i{type specifier} defined by the @i{implementation} to be acceptable. @subsubheading Initial Value:: The @i{symbol} @b{single-float}. @subsubheading Description:: Controls the floating-point format that is to be used when reading a floating-point number that has no @i{exponent marker} or that has @t{e} or @t{E} for an @i{exponent marker}. Other @i{exponent markers} explicitly prescribe the floating-point format to be used. The printer uses @b{*read-default-float-format*} to guide the choice of @i{exponent markers} when printing floating-point numbers. @subsubheading Examples:: @example (let ((*read-default-float-format* 'double-float)) (read-from-string "(1.0 1.0e0 1.0s0 1.0f0 1.0d0 1.0L0)")) @result{} (1.0 1.0 1.0 1.0 1.0 1.0) ;Implementation has float format F. @result{} (1.0 1.0 1.0s0 1.0 1.0 1.0) ;Implementation has float formats S and F. @result{} (1.0d0 1.0d0 1.0 1.0 1.0d0 1.0d0) ;Implementation has float formats F and D. @result{} (1.0d0 1.0d0 1.0s0 1.0 1.0d0 1.0d0) ;Implementation has float formats S, F, D. @result{} (1.0d0 1.0d0 1.0 1.0 1.0d0 1.0L0) ;Implementation has float formats F, D, L. @result{} (1.0d0 1.0d0 1.0s0 1.0 1.0d0 1.0L0) ;Implementation has formats S, F, D, L. @end example @node *read-eval*, *read-suppress*, *read-default-float-format*, Reader Dictionary @subsection *read-eval* [Variable] @subsubheading Value Type:: a @i{generalized boolean}. @subsubheading Initial Value:: @i{true}. @subsubheading Description:: If it is @i{true}, the @t{#.} @i{reader macro} has its normal effect. Otherwise, that @i{reader macro} signals an error of @i{type} @b{reader-error}. @subsubheading See Also:: @b{*print-readably*} @subsubheading Notes:: If @b{*read-eval*} is @i{false} and @b{*print-readably*} is @i{true}, any @i{method} for @b{print-object} that would output a reference to the @t{#.} @i{reader macro} either outputs something different or signals an error of @i{type} @b{print-not-readable}. @node *read-suppress*, *readtable*, *read-eval*, Reader Dictionary @subsection *read-suppress* [Variable] @subsubheading Value Type:: a @i{generalized boolean}. @subsubheading Initial Value:: @i{false}. @subsubheading Description:: This variable is intended primarily to support the operation of the read-time conditional notations @t{#+} and @t{#-}. It is important for the @i{reader macros} which implement these notations to be able to skip over the printed representation of an @i{expression} despite the possibility that the syntax of the skipped @i{expression} may not be entirely valid for the current implementation, since @t{#+} and @t{#-} exist in order to allow the same program to be shared among several @r{Lisp} implementations (including dialects other than @r{Common Lisp}) despite small incompatibilities of syntax. If it is @i{false}, the @i{Lisp reader} operates normally. If the @i{value} of @b{*read-suppress*} is @i{true}, @b{read}, @b{read-preserving-whitespace}, @b{read-delimited-list}, and @b{read-from-string} all return a @i{primary value} of @b{nil} when they complete successfully; however, they continue to parse the representation of an @i{object} in the normal way, in order to skip over the @i{object}, and continue to indicate @i{end of file} in the normal way. Except as noted below, any @i{standardized} @i{reader macro}_2 that is defined to @i{read}_2 a following @i{object} or @i{token} will do so, but not signal an error if the @i{object} read is not of an appropriate type or syntax. The @i{standard syntax} and its associated @i{reader macros} will not construct any new @i{objects} (@i{e.g.}, when reading the representation of a @i{symbol}, no @i{symbol} will be constructed or interned). @table @asis @item Extended tokens All extended tokens are completely uninterpreted. Errors such as those that might otherwise be signaled due to detection of invalid @i{potential numbers}, invalid patterns of @i{package markers}, and invalid uses of the @i{dot} character are suppressed. @item Dispatching macro characters (including @i{sharpsign}) @i{Dispatching macro characters} continue to parse an infix numerical argument, and invoke the dispatch function. The @i{standardized} @i{sharpsign} @i{reader macros} do not enforce any constraints on either the presence of or the value of the numerical argument. @item #= The @t{#=} notation is totally ignored. It does not read a following @i{object}. It produces no @i{object}, but is treated as @i{whitespace}_2. @item ## The @t{##} notation always produces @b{nil}. @end table No matter what the @i{value} of @b{*read-suppress*}, parentheses still continue to delimit and construct @i{lists}; the @t{#(} notation continues to delimit @i{vectors}; and comments, @i{strings}, and the @i{single-quote} and @i{backquote} notations continue to be interpreted properly. Such situations as @t{')}, @t{#<}, @t{#)}, and @t{#<@i{Space}>} continue to signal errors. @subsubheading Examples:: @example (let ((*read-suppress* t)) (mapcar #'read-from-string '("#(foo bar baz)" "#P(:type :lisp)" "#c1.2" "#.(PRINT 'FOO)" "#3AHELLO" "#S(INTEGER)" "#*ABC" "#\GARBAGE" "#RALPHA" "#3R444"))) @result{} (NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL) @end example @subsubheading See Also:: @ref{read; read-preserving-whitespace} , {@ref{Syntax}} @subsubheading Notes:: @i{Programmers} and @i{implementations} that define additional @i{macro characters} are strongly encouraged to make them respect @b{*read-suppress*} just as @i{standardized} @i{macro characters} do. That is, when the @i{value} of @b{*read-suppress*} is @i{true}, they should ignore type errors when reading a following @i{object} and the @i{functions} that implement @i{dispatching macro characters} should tolerate @b{nil} as their infix @i{parameter} value even if a numeric value would ordinarily be required. @node *readtable*, reader-error, *read-suppress*, Reader Dictionary @subsection *readtable* [Variable] @subsubheading Value Type:: a @i{readtable}. @subsubheading Initial Value:: A @i{readtable} that conforms to the description of @r{Common Lisp} syntax in @ref{Syntax}. @subsubheading Description:: The @i{value} of @b{*readtable*} is called the @i{current readtable}. It controls the parsing behavior of the @i{Lisp reader}, and can also influence the @i{Lisp printer} (@i{e.g.}, see the @i{function} @b{readtable-case}). @subsubheading Examples:: @example (readtablep *readtable*) @result{} @i{true} (setq zvar 123) @result{} 123 (set-syntax-from-char #\z #\' (setq table2 (copy-readtable))) @result{} T zvar @result{} 123 (setq *readtable* table2) @result{} # zvar @result{} VAR (setq *readtable* (copy-readtable nil)) @result{} # zvar @result{} 123 @end example @subsubheading Affected By:: @b{compile-file}, @b{load} @subsubheading See Also:: @ref{compile-file} , @ref{load} , @ref{readtable} , @ref{The Current Readtable} @node reader-error, , *readtable*, Reader Dictionary @subsection reader-error [Condition Type] @subsubheading Class Precedence List:: @b{reader-error}, @b{parse-error}, @b{stream-error}, @b{error}, @b{serious-condition}, @b{condition}, @b{t} @subsubheading Description:: The @i{type} @b{reader-error} consists of error conditions that are related to tokenization and parsing done by the @i{Lisp reader}. @subsubheading See Also:: @ref{read; read-preserving-whitespace} , @ref{stream-error-stream} , @ref{Reader Concepts} @c end of including dict-reader @c %**end of chapter