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:
tused 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. If Emacs is running in batch mode, standard input is used instead of the minibuffer. For example,
(message "%s" (read t))
will read a Lisp expression from standard input and print the result
to standard output.
nilsupplied as an input stream means to use the value of
standard-inputinstead; that value is the default input stream, and must be a non-
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.
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
---------- 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
useless-list to a list of characters. Then each call to
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 remain 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
This function is used internally as an input stream to read from the input file opened by the function
load. Don't use this function yourself.