Info Catalog elisp: Streams Intro elisp: Read and Print elisp: Input Functions

elisp: Input Streams

 
 18.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, which must support
      two kinds of calls:
 
         • When it is called with no arguments, it should return the next
           character.
 
         • When it is called with one argument (always a character),
           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.  In this case, it
           makes no difference what value FUNCTION returns.
 
 ‘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.  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.
 
 ‘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.
 
    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 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 ‘nil’.
 

Info Catalog elisp: Streams Intro elisp: Read and Print elisp: Input Functions