16.4 Reading and Writing Tokens

Sometimes after an
accept
method has read some input from the user, it may be necessary to insert a modified version of that input back into the input buffer. The following two functions can be used to modify the input buffer:

replace-input[Generic Function]

Arguments: stream new-input
&key
start end buffer-start rescan

Summary: Replaces the part of the input editing stream
stream
's input buffer that extends from
buffer-start
to its scan pointer with the string
new-input
.
buffer-start
defaults to the current input position of stream.
start
and
end
can be supplied to specify a subsequence of
new-input
;
start
defaults to 0 and
end
defaults to the length of
new-input
.

replace-input
queues a rescan by calling
queue-rescan
if the new input does not match the old output, or if
rescan
is
t
.

Summary: Like
replace-input
, except that the new input to insert into the input buffer is obtained by presenting the object object with the presentation type
type
and view view. buffer-start and rescan are as for
replace-input
, query-identifier is as for
accept
, and for-context-type is as for
present
.

If the object does not have a readable representation (in the Lisp sense),
presentation-replace-input
may create an "accept result" to represent the object and insert it into the input buffer. For the purposes of input editing, "accept results" must be treated as a single input gesture.

The following two functions are used to read or write a token (that is, a string):

Summary: Reads characters from the interactive steam stream until it encounters a delimiter, activation, or pointer gesture. Returns the accumulated string that was delimited by the delimiter or activation gesture, leaving the delimiter unread.

If the first character of typed input is a quotation mark (
#\"
), then
read-token
will ignore delimiter gestures until another quotation mark is seen. When the closing quotation mark is seen,
read-token
will proceed as discussed previously.

If the boolean
click-only
is
t
, then no keyboard input is allowed. In that case,
read-token
will simply ignore any typed characters.

Summary:
write-token
is the opposite of
read-token
; given the string token, it writes it to the interactive stream stream. If
acceptably
is
t
and there are any characters in the token that are delimiter gestures (see
with-delimiter-gestures
), then
write-token
will surround the token with quotation marks (
#\"
).

Typically, present methods will use
write-token
instead of
write-string
.