Package COM.INFORMATIMAGO.COMMON-LISP.CESARUM.PEEK-STREAM


This package exports a class named PEEK-STREAM that encapsulates a
stream and a buffer in such a way that reading, peeking or unreading
characters can be done in any number and in any order.

We don't use gray stream to keep it pure Common-Lisp.  The I/O methods
are GETCHAR, UNGETCHAR and NEXTCHAR to avoid name clashes with
un-generic READ-CHAR, UNREAD-CHAR and PEEK-CHAR.


License:

    AGPL3
    
    Copyright Pascal J. Bourguignon 2004 - 2015
    
    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU Affero General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.
    
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Affero General Public License for more details.
    
    You should have received a copy of the GNU Affero General Public License
    along with this program.
    If not, see <http://www.gnu.org/licenses/>


(get-future-char peek-stream)
generic-function
DO:             Read a character from the underlying stream and keep
                it in the buffer for GETCHAR.

RETURN:         The character that has been read, or NIL when EOF
                (which doesn't mean GETCHAR would return NIL).

NOTE:           We have:
                    (equalp (loop repeat N collect (nextchar ps))
                            (loop repeat N collect (getchar  ps)))
                but not:
                    (equalp (loop repeat N collect (getchar  ps))
                            (loop repeat N collect (nextchar ps)))
SEE ALSO:       NEXTCHAR.
(getchar peek-stream)
generic-function
RETURN: The next character in the PEEK-STREAM, advancing.
(nextchar peek-stream &optional peek-type)
generic-function
DO:             Just like CL:PEEK-CHAR.

                If peek-type is not supplied or NIL, peek-char returns
                the next character to be read from input-stream,
                without actually removing it from input-stream. The
                next time input is done from input-stream, the
                character will still be there.

                If  peek-type is T, then peek-char skips over
                whitespace[2] characters, but not comments, and then
                performs the peeking operation on the next
                character. The last character examined, the one that
                starts an object, is not removed from  input-stream.

                If peek-type is a CHARACTER, then peek-char skips over
                input characters until a character that is char= to
                that character is found; that character is left in
                input-stream.

RETURN:         The same character that will be returned by the next
                (getchar self).

NOTE:           There's no conforming way to determine whether a
                character has the whitespace[2] syntax in the current
                *readtable*.  Therefore we use instead the
                PEEK-STREAM-SPACES method to get the list of spaces.
peek-stream
class
More than one character may be peeked and unread from this.
Class precedence list: PEEK-STREAM STANDARD-OBJECT T
Class init args: STREAM SPACES
(peek-stream-spaces peek-stream)
generic-function
RETURN:         A sequence of characters to be considered whitespace
                by (nextchar peek-stream T).
(setf (peek-stream-spaces peek-stream) new-whitespaces)
generic-function
DO:             Changes the sequence of characters to be considered
                whitespace by (nextchar peek-stream T).

PEEK-STREAM-STREAM

(readline peek-stream)
generic-function
RETURN: A string containing the read line.
(ungetchar peek-stream ch)
generic-function
DO: Unread the character CH from the PEEK-STREAM.