(lispref.info)Input Streams


Next: Input Functions Prev: Streams Intro Up: Streams

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 want 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' used as a stream means that the value of `standard-input'
     should be used instead; that value is the "default input stream",
     and must be a non-`nil' input stream.

SYMBOL
     A symbol as output stream is equivalent to the symbol's function
     definition (if any).

   Here is an example of reading from a stream which 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 at the beginning of the buffer.
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 delimiter 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,
initialized to point 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 6 in foo>   ;; After 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 characters 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
          => (41)

Note that the close parenthesis remains in the list.  The reader has
read it, discovered that it ended the input, and unread it.  Another
attempt to read from the stream at this point would get an error due to
the unmatched close parenthesis.

 - Function: get-file-char
     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.


automatically generated by info2www