24.4 Reading and Writing of Tokens

replace-input  stream new-input &key start end buffer-start rescan [Generic Function]

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. [annotate]

Note: What is the "current input position" of an input editing stream? Where does it come from? What happens to the scan pointer and the insertion pointer of the stream? Are they updated as appropriate? [edit]-- Gilbert Baumann 2005-11-27 01:11Z
Note: Isn't the "current input position" 'the point in the buffer at which the next user input gesture will be inserted'? See stream-insertion-pointer. [edit]-- JQS 2005-12-12 20:53Z
Note: I would assume that the "current input position" is the same as the insertion pointer, but this is not what McCLIM currently does. Instead, McCLIM interprets it to be where the current input-editing-context was established (mostly the start of the input buffer, but not necessarily, if, for example, command arguments are being read). [edit]-- Troels "Athas" Henriksen 2006-10-15 17:37Z

replace-input must queue a rescan by calling queue-rescan if the new input does not match the old input, or rescan is true. [annotate]

The returned value is the position in the input buffer. [annotate]

Note: Which position? [edit]-- Gilbert Baumann 2005-11-27 01:12Z

All input editing streams must implement a method for this function. [annotate]


presentation-replace-input  stream object type view &key buffer-start rescan query-identifier for-context-type [Generic Function]

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

All input editing streams must implement a method for this function. Typically, this will be implemented by calling present-to-string on object, type, view, and for-context-type, and then calling replace-input on the resulting string. [annotate]

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 that into the input buffer. For the purposes of input editing, "accept results" must be treated as a single input gesture. [annotate]

Note: It would be nice, if it would be mentioned, how exeactly stream-read-gesture should react on hitting such an "accept result". [edit]-- Gilbert Baumann 2005-11-27 01:15Z


Note: Hmm, how can i decide wether something has a readable presentation or not? [edit]-- Gilbert Baumann 2004-11-27 19:36Z

Another note:

It might be good, if something that is half readable and half unreadable is being inserted as such. E.g. a form (:BAZ #<SOME FOO @1234>) could be represented as "(:BAZ " and ")" as regular input, while "#<SOME FOO @1234>" will then be some of these "accept results".

But I guess to do this right, we probably need to extend present to return whether its output is supposed to be readable.

[edit]-- Gilbert Baumann 2004-11-27 19:45Z

read-token  stream &key input-wait-handler pointer-button-press-handler click-only [Function]

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

Note: What about the activation gesture? Will it be left unread too? [edit]-- Gilbert Baumann 2006-03-01 11:13Z

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

If the boolean click-only is true, then no keyboard input is allowed. In this case read-token will simply ignore any typed characters. [annotate]

input-wait-handler and pointer-button-press-handler are as for stream-read-gesture. [annotate]


write-token  token stream &key acceptably [Function]

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

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