The input functions read characters, lines, or bytes from an input stream. This argument is called stream. If omitted or nil, the current value of *standard-input*. This is the ``default input stream'', which in simple use reads from the terminal keyboard. If the argument is t, the current value of *terminal-io* is used; this is conventionally supposed to access ``the user's terminal'' and nearly always reads from the keyboard in processes belonging to windows.

If the stream is an interactive one, such as the terminal, the input is echoed, and functions which read more than a single character allow editing as well. peek-char echoes all of the characters that were skipped over if read-char would have echoed them; the character not removed from the stream is not echoed either.

When an input stream has no more data to return, it reports end of file. Each stream input operation has a convention for how to do this. The input functions accept an argument eof-option or two arguments eof-error and eof-value to tell them what to do if end of file is encountered instead of any input. The functions that take two eof- arguments are the Common Lisp ones. For them, end of file is an error if eof-error is non-nil or if it is unsupplied. If eof-error is nil, then the function returns eof-value at end of file.

The functions which have one argument called eof-option are from Maclisp. End of file causes an error if the argument is not supplied. Otherwise, end of file causes the function to return the argument's value. Note that an eof-option of nil means to return nil if the end of the file is reached; it is not equivalent to supplying no eof-option.

These functions all take an optional argument called stream, which is where to send the output. If unsupplied stream defaults to the value of *standard-output*. If stream is nil, the value of *standard-output* (i.e. the default) is used. If it is t, the value of *terminal-io* is used (i.e. the interactive terminal). This is all more-or-less compatible with Maclisp, except that instead of the variable *standard-output* Maclisp has several variables and complicated rules. For detailed documentation of streams, refer to .

For print and the other expression output functions, see .

The format function (see ) is very useful for producing nicely formatted text. It can do anything any of the above functions can do, and it makes it easy to produce good looking messages and such. format can generate a string or output to a stream.

The rubout handler is a feature of all interactive streams, that is, streams that connect to terminals. Its purpose is to allow the user to edit minor mistakes made during type-in. At the same time, it is not supposed to get in the way; input is to be seen by Lisp as soon as a syntactically complete form has been typed. The definition of `syntactically complete form' depends on the function that is reading from the stream; for read, it is a Lisp expression.

Some interactive streams (`editing Lisp listeners') have a rubout handler that allows input to be edited with the full power of the ZWEI editor. (ZWEI is the general editor implementation on which Zmacs and ZMail are based.) Most windows have a rubout handler that apes ZWEI, implementing about twenty common ZWEI commands. The cold load stream has a simple rubout handler that allows just rubbing out of single characters, and a few simple commands like clearing the screen and erasing the entire input typed so far. All three kinds of rubout handler use the same protocol, which is described in this section. We also say a little about the most common of the three rubout handlers.

[Eventually some version of ZWEI will be used for all streams except the cold load stream]

The tricky thing about the rubout handler is the need for it to figure out when you are all done. The idea of a rubout handler is that you can type in characters, and they are saved up in a buffer so that if you change your mind, you can rub them out and type different characters. However, at some point, the rubout handler has to decide that the time has come to stop putting characters into the buffer and to let the function parsing the input, such as read, return. This is called activation. The right time to activate depends on the function calling the rubout handler, and may be very complicated (if the function is read, figuring out when one Lisp expression has been typed requires knowledge of all the various printed representations, what all currently-defined reader macros do, and so on). Rubout handlers should not have to know how to parse the characters in the buffer to figure out what the caller is reading and when to activate; only the caller should have to know this. The rubout handler interface is organized so that the calling function can do all the parsing, while the rubout handler does all the handling of editing commands, and the two are kept completely separate.

The basic way that the rubout handler works is as follows. When an input function that reads characters from a stream, such as read or readline (but not tyi), is invoked with a stream which has :rubout-handler in its :which-operations list, that function ``enters'' the rubout handler. It then goes ahead :tyi'ing characters from the stream. Because control is inside the rubout handler, the stream echoes these characters so the user can see what he is typing. (Normally echoing is considered to be a higher-level function outside of the province of streams, but when the higher-level function tells the stream to enter the rubout handler it is also handing it the responsibility for echoing.) The rubout handler is also saving all these characters in a buffer, for reasons disclosed in the following paragraph. When the parsing function decides it has enough input, it returns and control ``leaves'' the rubout handler. This is the easy case.

If the user types a rubout, a throw is done out of all recursive levels of read, reader macros, and so forth, back to the point where the rubout handler was entered. Also the rubout is echoed by erasing from the screen the character which was rubbed out. Now the read is tried over again, re-reading all the characters that have not been rubbed out, not echoing them this time. When the saved characters have been exhausted, additional input is read from the user in the usual fashion.

The effect of this is a complete separation of the functions of rubout handling and parsing, while at the same time mingling the execution of these two functions in such a way that input is always activated at just the right time. It does mean that the parsing function (in the usual case, read and all macro-character definitions) must be prepared to be thrown through at any time and should not have non-trivial side-effects, since it may be called multiple times.

If an error occurs while inside the rubout handler, the error message is printed and then additional characters are read. When the user types a rubout, it rubs out the error message as well as the character that caused the error. The user can then proceed to type the corrected expression; the input will be reparsed from the beginning in the usual fashion.

The rubout handler based on the ZWEI editor interprets control characters in the usual ZWEI way: as editing commands, allowing you to edit your buffered input.

The common rubout handler also recognizes a subset of the editor commands, including Rubout, Control-F and Meta-F and others. Typing Help while in the rubout handler displays a list of the commands. The kill and yank commands in the rubout handler use the same kill ring as the editor, so you can kill an expression in the editor and yank it back into a rubout handler with Control-Y, or kill an expression in the rubout handler with Control-K or Clear-input and yank it back in the editor. The rubout processor also keeps a ring buffer of most recent input strings (a separate ring for each stream), and the commands Control-C and Meta-C retrieve from this ring just as Control-Y and Meta-Y do from the kill ring.

When not inside the rubout handler, and when typing at a program that uses control characters for its own purposes, control characters are treated the same as ordinary characters.

Some programs such as the debugger allow the user to type either a control character or an expression. In such programs, you are really not inside the rubout handler unless you have typed the beginning of an expression. When the input buffer is empty, a control character is treated as a command for the program (such as, Control-C to continue in the debugger); when there is text in the rubout handler buffer, the same character is treated as a rubout handler command. Another consequence of this is that the message you get by typing Help varies, being either the rubout handler's documentation or the debugger's documentation.

To write a parsing function that reads with rubout handling, use with-input-editing.

Each option in the list of rubout handler options consists of a list whose first element is a keyword and whose remaining elements are the arguments of that keyword. Note that this is not the same format as the arguments to a typical function that takes keyword arguments; rather this is an alist of options. The standard options are:

(:activation fn args...)	Activate if certain characters are typed in. When the user types an activation character, the rubout handler moves the editing pointer immediately to the end of the buffer and inserts the activation character. This immediately causes the parsing function to begin rescanning the input. fn is used to test characters for being activators. It is called with an input character as the first arg (possibly a fixnum, possibly a character object) and args as additional args. If fn returns non-nil, the character is an activation. fn is not called for blips. After the parsing function has read the entire contents of the buffer, it sees the activation character as a blip (:activation char numeric-arg) where char is the character that activated and numeric-arg is the numeric arg that was pending for the next rubout handler command. Normally the parsing function will return at this point. Then the activation character does not echo. But if the parsing function continues to read input, the activation character echoes and is inserted in the buffer.
(:do-not-echo chars...)	Poor man's activation characters. Like :activation except that the characters that should activate are listed explicitly, and the character itself is returned to the parsing function rather than a blip.
(:full-rubout val)	If the user rubs out all the characters he typed, then control is returned from the rubout handler immediately. Two values are returned; the first is nil and the second is val. (If the user doesn't rub out all the characters, then the rubout handler propagates multiple values back from the function that it calls, as usual.) In the absence of this option, the rubout handler would simply wait for more characters to be typed in and would ignore any additional rubouts. This is how the debugger knows to remove Eval: from the screen if you type the beginning of a form and rub it all out.
(:pass-through char1 char2...)	The characters char1, char2, etc. are not to be treated as special by the rubout handler. They are read as input by the parsing function. If the parsing function does not return, they can be rubbed out. This works only for characters with no modifier bits.
(:preemptable value)	Makes all blips read as input by the rubout handler act as preemptive commands. If this option is specified, the rubout handler returns immediately when it reads a blip. It returns two values: the blip that was read, and value. The parsing function is not allowed to finish parsing up to a delimiter; instead, any buffered input remains in the buffer for the next time input is done. In the mean time, the preemptive command character can be processed by the command loop. While this applies to all blips, the blips which it is probably intended for are mouse blips.
(:command fn args...)	Makes certain characters preemptive commands. A preemptive command returns instantly to the caller of the :rubout-handler operation, regardless of the input in the buffer. It returns two values: a list (:command char numeric-arg) and the keyword :command. The parsing function is not allowed to finish parsing up to a delimiter; instead, any buffered input remains in the buffer for the next time input is done. In the mean time, the preemptive command character can be processed by the command loop. The test for whether a character should be a preemptive command is done using fn and args just as in :activation.
(:editing-command (char doc)...)	Defines editing commands to be executed by the parsing function itself. This is how qsend implements the Control-Meta-Y command. Each char is such a command, and doc says what it does. (doc is printed out by the rubout handler's Help command.) If any of these characters is read by the rubout handler, it is returned immediately to the parsing function regardless of where the editing pointer is in the buffer. (Normal inserted text is not returned immediately when read unless the editing pointer is at the end of the buffer.) The parsing function should not regard these characters as part of the input. There are two reasonable things that the parsing function can do when it receives one of the editing command characters: print some output, or force some input. If it prints output, it should invoke the :refresh-rubout-handler operation afterward before the next :tyi. This causes the rubout handler to redisplay so that the input being edited appears after the output that was done. If the parsing function forces input, the input is read by the rubout handler. This can be used to modify the buffered input. qsend's Control-Meta-Y command works by forcing the yanked text as input. There is no way to act directly on the buffered input because different implementations of the rubout handler store it in different ways.
(:prompt function)
(:reprompt function)	When it is time for the user to be prompted, function is called with two arguments. The first is a stream it may print on; the second is the character which caused the need for prompting, e.g. #\clear-input or #\clear-screen, or nil if the rubout handler was just entered. The difference between :prompt and :reprompt is that the latter does not call the prompt function when the rubout handler is first entered, but only when the input is redisplayed (e.g. after a screen clear). If both options are specified then :reprompt overrides :prompt except when the rubout handler is first entered. function may also be a string. Then it is simply printed. If the rubout handler is exited with an empty buffer due to the :full-rubout option, whatever prompt was printed is erased.
(:initial-input string)	Pretends that the user typed string. When the rubout handler is entered, string is typed out. The user can input more characters or rub out characters from it.
(:initial-input-index index)	Positions the editing pointer initially index characters into the initial input string. Used only in company with with :initial-input.
(:no-input-save t)	Don't save this batch of input in the input history when it is done. For example, yes-or-no-p specifies this option.
(:norecursive t)	If this invocation of the rubout handler is within another one, the options specified in the previous call should be completely ignored during this one. Normally, individual options specified this time override the previous settings for the same options, but any of the previous options not individually overridden are still in effect.

Rubout handlers handle the condition sys:parse-error if it is signaled by the parsing function. The handling consists of printing the error message, waiting for the user to rub out, erasing the error message, and parsing the input again. All errors signaled by a parsing function that signify that the user's input was syntactically invalid should have this condition name. For example, the errors read signals have condition name sys:parse-error since it is is a consequence of sys:read-error.

The compiler handles sys:parse-error by proceeding with proceed-type :no-action. All signalers of sys:parse-error should offer this proceed type, and respond to its use by continuing to parse, ignoring the invalid input.