23.2 Input Streams

Most of the Lisp functions for reading text take an input stream as an argument. The input stream specifies where or how to get the characters of the text to be read. Here are the possible types of input stream:

buffer

The input characters are read from buffer, starting with the character directly after point. Point advances as characters are read.

marker

The input characters are read from the buffer that marker is in, starting with the character directly after the marker. The marker position advances as characters are read. The value of point in the buffer has no effect when the stream is a marker.

string

The input characters are taken from string, starting at the first character in the string and using as many characters as required.

function

The input characters are generated by function, one character per call. Normally function is called with no arguments, and should return a character.

Occasionally function is called with one argument (always a character). When that happens, function should save the argument and arrange to return it on the next call. This is called unreading the character; it happens when the Lisp reader reads one character too many and wants to “put it back where it came from”.

t

t used as a stream means that the input is read from the minibuffer. In fact, the minibuffer is invoked once and the text given by the user is made into a string that is then used as the input stream.

nil

nil supplied as an input stream means to use the value of standard-input instead; that value is the default input stream, and must be a non-nil input stream.

symbol

A symbol as input stream is equivalent to the symbol’s function definition (if any).

Here is an example of reading from a stream that is a buffer, showing where point is located before and after:

---------- Buffer: foo ----------
This∗ is the contents of foo.
---------- Buffer: foo ----------

(read (get-buffer "foo"))
     ⇒ is

(read (get-buffer "foo"))
     ⇒ the

---------- Buffer: foo ----------
This is the∗ contents of foo.
---------- Buffer: foo ----------

Note that the first read skips a space. Reading skips any amount of whitespace preceding the significant text.

In Emacs 18, reading a symbol discarded the delimiter terminating the symbol. Thus, point would end up at the beginning of ‘contents’ rather than after ‘the’. The Emacs 19 behavior is superior because it correctly handles input such as ‘bar(foo)’, where the open-parenthesis that ends one object is needed as the beginning of another object.

Here is an example of reading from a stream that is a marker, initially positioned at the beginning of the buffer shown. The value read is the symbol This.

---------- Buffer: foo ----------
This is the contents of foo.
---------- Buffer: foo ----------

(setq m (set-marker (make-marker) 1 (get-buffer "foo")))
     ⇒ #<marker at 1 in foo>

(read m)
     ⇒ This

m
     ⇒ #<marker at 5 in foo>   ;; Before the first space.

Here we read from the contents of a string:

(read "(When in) the course")
     ⇒ (When in)

The following example reads from the minibuffer. The prompt is: ‘Lisp expression: ’. (That is always the prompt used when you read from the stream t.) The user’s input is shown following the prompt.

(read t)
     ⇒ 23
---------- Buffer: Minibuffer ----------
Lisp expression: 23 RET
---------- Buffer: Minibuffer ----------

Finally, here is an example of a stream that is a function, named useless-stream. Before we use the stream, we initialize the variable useless-list to a list of characters. Then each call to the function useless-stream obtains the next character in the list or unreads a character by adding it to the front of the list.

(setq useless-list (append "XY()" nil))
     ⇒ (88 89 40 41)

(defun useless-stream (&optional unread)
  (if unread
      (setq useless-list (cons unread useless-list))
    (prog1 (car useless-list)
           (setq useless-list (cdr useless-list)))))
     ⇒ useless-stream

Now we read using the stream thus constructed:

(read 'useless-stream)
     ⇒ XY

useless-list
     ⇒ (40 41)

Note that the open and close parentheses remains in the list. The Lisp reader encountered the open parenthesis, decided that it ended the input, and unread it. Another attempt to read from the stream at this point would read ‘()’ and return nil.