flexi-streams

API Reference

flexi-streams

Flexible bivalent streams for Common Lisp

FLEXI-STREAMS

  • Type OCTET
    A shortcut for (UNSIGNED-BYTE 8).
  • Variable *DEFAULT-EOL-STYLE*
    :lf
    The end-of-line style used by external formats if none is explicitly given. Depends on the OS the code is compiled on.
  • Variable *DEFAULT-LITTLE-ENDIAN*
    t
    Whether external formats are little-endian by default (i.e. unless explicitly specified). Depends on the platform the code is compiled on.
  • Variable *SUBSTITUTION-CHAR*
    nil
    If this value is not NIL, it should be a character which is used (as if by a USE-VALUE restart) whenever during reading an error of type FLEXI-STREAM-ENCODING-ERROR would have been signalled otherwise.
  • Condition FLEXI-STREAM-ERROR  (STREAM-ERROR)
    Superclass for all errors related to flexi streams.
  • Condition FLEXI-STREAM-ELEMENT-TYPE-ERROR  (FLEXI-STREAM-ERROR)
    Errors of this type are signalled if the flexi stream has a wrong element type.
  • Condition FLEXI-STREAM-OUT-OF-SYNC-ERROR  (FLEXI-STREAM-ERROR)
    This can happen if you're trying to write to an IO stream which had prior to that `looked ahead' while reading and now can't `rewind' to the octet where you /should/ be.
  • Condition IN-MEMORY-STREAM-ERROR  (STREAM-ERROR)
    Superclass for all errors related to IN-MEMORY streams.
  • Condition IN-MEMORY-STREAM-CLOSED-ERROR  (IN-MEMORY-STREAM-ERROR)
    An error that is signalled when someone is trying to read from or write to a closed IN-MEMORY stream.
  • Condition IN-MEMORY-STREAM-POSITION-SPEC-ERROR  (IN-MEMORY-STREAM-SIMPLE-ERROR)
    Errors of this type are signalled if an erroneous position spec is used in conjunction with FILE-POSITION.
  • Condition EXTERNAL-FORMAT-CONDITION  (SIMPLE-CONDITION)
    Superclass for all conditions related to external formats.
  • Condition EXTERNAL-FORMAT-ERROR  (EXTERNAL-FORMAT-CONDITION, ERROR)
    Superclass for all errors related to external formats.
  • Condition EXTERNAL-FORMAT-ENCODING-ERROR  (EXTERNAL-FORMAT-ERROR)
    Errors of this type are signalled if there is an encoding problem.
  • Function MAKE-EXTERNAL-FORMAT (name &rest args &key (little-endian *default-little-endian*) id eol-style)
    Creates and returns an external format object as specified. NAME is a keyword like :LATIN1 or :UTF-8, LITTLE-ENDIAN specifies the `endianess' of the external format and is ignored for 8-bit encodings, EOL-STYLE is one of the keywords :CR, :LF, or :CRLF which denote the end-of-line character (sequence), ID is the ID of a Windows code page (and ignored for other encodings).
  • Function EXTERNAL-FORMAT-EQUAL (ef1 ef2)
    Checks whether two EXTERNAL-FORMAT objects denote the same encoding.
  • Class IN-MEMORY-STREAM  (TRIVIAL-GRAY-STREAM-MIXIN)
    An IN-MEMORY-STREAM is a binary stream that reads octets from or writes octets to a sequence in RAM.
    TRANSFORMER   Accessor: IN-MEMORY-STREAM-TRANSFORMER
    A function used to transform the written/read octet to the value stored/retrieved in/from the underlying vector.
  • Class IN-MEMORY-INPUT-STREAM  (IN-MEMORY-STREAM, FUNDAMENTAL-BINARY-INPUT-STREAM)
    An IN-MEMORY-INPUT-STREAM is a binary stream that reads octets from a sequence in RAM.
    No slots.
  • Class IN-MEMORY-OUTPUT-STREAM  (IN-MEMORY-STREAM, FUNDAMENTAL-BINARY-OUTPUT-STREAM)
    An IN-MEMORY-OUTPUT-STREAM is a binary stream that writes octets to a sequence in RAM.
    No slots.
  • Class LIST-STREAM
    A LIST-STREAM is a mixin for IN-MEMORY streams where the underlying sequence is a list.
    LIST   Accessor: LIST-STREAM-LIST
    The underlying list of the stream.
  • Class VECTOR-STREAM
    A VECTOR-STREAM is a mixin for IN-MEMORY streams where the underlying sequence is a vector.
    VECTOR   Accessor: VECTOR-STREAM-VECTOR
    The underlying vector of the stream which (for output) must always be adjustable and have a fill pointer.
  • Method MAKE-IN-MEMORY-INPUT-STREAM ((vector vector) &key (start 0) (end (length vector)) transformer)
    Returns a binary input stream which will supply, in order, the octets in the subsequence of VECTOR bounded by START and END. Each octet returned will be transformed in turn by the optional TRANSFORMER function.
  • Method MAKE-IN-MEMORY-INPUT-STREAM ((list list) &key (start 0) (end (length list)) transformer)
    Returns a binary input stream which will supply, in order, the octets in the subsequence of LIST bounded by START and END. Each octet returned will be transformed in turn by the optional TRANSFORMER function.
  • Function MAKE-IN-MEMORY-OUTPUT-STREAM (&key (element-type 'octet) transformer)
    Returns a binary output stream which accepts objects of type ELEMENT-TYPE (a subtype of OCTET) and makes available a sequence that contains the octes that were actually output. The octets stored will each be transformed by the optional TRANSFORMER function.
  • Method GET-OUTPUT-STREAM-SEQUENCE ((stream in-memory-output-stream) &key as-list)
    Returns a vector containing, in order, all the octets that have been output to the IN-MEMORY stream STREAM. This operation clears any octets on STREAM, so the vector contains only those octets which have been output since the last call to GET-OUTPUT-STREAM-SEQUENCE or since the creation of the stream, whichever occurred most recently. If AS-LIST is true the return value is coerced to a list.
  • Method OUTPUT-STREAM-SEQUENCE-LENGTH ((stream in-memory-output-stream))
    Returns the current length of the underlying vector of the IN-MEMORY output stream STREAM.
  • Macro WITH-INPUT-FROM-SEQUENCE ((var sequence &key start end transformer) &body body)
    Creates an IN-MEMORY input stream from SEQUENCE using the parameters START and END, binds VAR to this stream and then executes the code in BODY. A function TRANSFORMER may optionally be specified to transform the returned octets. The stream is automatically closed on exit from WITH-INPUT-FROM-SEQUENCE, no matter whether the exit is normal or abnormal. The return value of this macro is the return value of BODY.
  • Macro WITH-OUTPUT-TO-SEQUENCE ((var &key as-list (element-type ''octet) transformer) &body body)
    Creates an IN-MEMORY output stream, binds VAR to this stream and then executes the code in BODY. The stream stores data of type ELEMENT-TYPE (a subtype of OCTET) which is (optionally) transformed by the function TRANSFORMER prior to storage. The stream is automatically closed on exit from WITH-OUTPUT-TO-SEQUENCE, no matter whether the exit is normal or abnormal. The return value of this macro is a vector (or a list if AS-LIST is true) containing the octets that were sent to the stream within BODY.
  • Class FLEXI-STREAM  (TRIVIAL-GRAY-STREAM-MIXIN)
    A FLEXI-STREAM object is a stream that's `layered' atop an existing binary/bivalent stream in order to allow for multi-octet external formats. FLEXI-STREAM itself is a mixin and should not be instantiated.
    STREAM   Reader: FLEXI-STREAM-STREAM
    The actual stream that's used for input and/or output. It must be capable of reading/writing octets with READ-SEQUENCE and/or WRITE-SEQUENCE.
    EXTERNAL-FORMAT   Accessor: FLEXI-STREAM-EXTERNAL-FORMAT
    The encoding currently used by this stream. Can be changed on the fly.
    ELEMENT-TYPE   Accessor: FLEXI-STREAM-ELEMENT-TYPE
    The element type of this stream.
  • Method (setf FLEXI-STREAM-EXTERNAL-FORMAT) (new-value (flexi-stream flexi-stream))
    Converts the new value to an EXTERNAL-FORMAT object if necessary.
  • Method (setf FLEXI-STREAM-ELEMENT-TYPE) (new-value (flexi-stream flexi-stream))
    Checks whether the new value makes sense before it is set.
  • Class FLEXI-OUTPUT-STREAM  (FLEXI-STREAM, FUNDAMENTAL-BINARY-OUTPUT-STREAM, FUNDAMENTAL-CHARACTER-OUTPUT-STREAM)
    A FLEXI-OUTPUT-STREAM is a FLEXI-STREAM that can actually be instatiated and used for output. Don't use MAKE-INSTANCE to create a new FLEXI-OUTPUT-STREAM but use MAKE-FLEXI-STREAM instead.
    COLUMN   Accessor: FLEXI-STREAM-COLUMN
    The current output column. A non-negative integer or NIL.
  • Class FLEXI-INPUT-STREAM  (FLEXI-STREAM, FUNDAMENTAL-BINARY-INPUT-STREAM, FUNDAMENTAL-CHARACTER-INPUT-STREAM)
    A FLEXI-INPUT-STREAM is a FLEXI-STREAM that can actually be instatiated and used for input. Don't use MAKE-INSTANCE to create a new FLEXI-INPUT-STREAM but use MAKE-FLEXI-STREAM instead.
    LAST-CHAR-CODE   Accessor: FLEXI-STREAM-LAST-CHAR-CODE
    This slot either holds NIL or the last character (code) read successfully. This is mainly used for UNREAD-CHAR sanity checks.
    LAST-OCTET   Accessor: FLEXI-STREAM-LAST-OCTET
    This slot either holds NIL or the last octet read successfully from the stream using a `binary' operation such as READ-BYTE. This is mainly used for UNREAD-BYTE sanity checks.
    OCTET-STACK   Accessor: FLEXI-STREAM-OCTET-STACK
    A small buffer which holds octets that were already read from the underlying stream but not yet used to produce characters. This is mainly used if we have to look ahead for a CR/LF line ending.
    POSITION   Accessor: FLEXI-STREAM-POSITION
    The position within the stream where each octet read counts as one.
    BOUND   Accessor: FLEXI-STREAM-BOUND
    When this is not NIL, it must be an integer and the stream will behave as if no more data is available as soon as POSITION is greater or equal than this value.
  • Class FLEXI-IO-STREAM  (FLEXI-INPUT-STREAM, FLEXI-OUTPUT-STREAM)
    A FLEXI-IO-STREAM is a FLEXI-STREAM that can actually be instatiated and used for input and output. Don't use MAKE-INSTANCE to create a new FLEXI-IO-STREAM but use MAKE-FLEXI-STREAM instead.
    No slots.
  • Function MAKE-FLEXI-STREAM (stream &rest args &key (external-format (make-external-format :iso-8859-1)) element-type column position bound)
    Creates and returns a new flexi stream. STREAM must be an open binary or `bivalent' stream, i.e. it must be capable of reading/writing octets with READ-SEQUENCE and/or WRITE-SEQUENCE. The resulting flexi stream is an input stream if and only if STREAM is an input stream. Likewise, it's an output stream if and only if STREAM is an output stream. The default for ELEMENT-TYPE is LW:SIMPLE-CHAR on LispWorks and CHARACTER on other Lisps. EXTERNAL-FORMAT must be an EXTERNAL-FORMAT object or a symbol or a list denoting such an object. COLUMN is the initial column of the stream which is either a non-negative integer or NIL. The COLUMN argument must only be used for output streams. POSITION (only used for input streams) should be an integer and it denotes the position the stream is in - it will be increased by one for each octet read. BOUND (only used for input streams) should be NIL or an integer. If BOUND is not NIL and POSITION has gone beyond BOUND, then the stream will behave as if no more input is available.
  • Method UNREAD-BYTE (byte (flexi-input-stream flexi-input-stream))
    Similar to UNREAD-CHAR in that it `unreads' the last octet from STREAM. Note that you can only call UNREAD-BYTE after a corresponding READ-BYTE.
  • Method PEEK-BYTE ((flexi-input-stream flexi-input-stream) &optional peek-type (eof-error-p t) eof-value)
    PEEK-BYTE is like PEEK-CHAR, i.e. it returns an octet from FLEXI-INPUT-STREAM without actually removing it. If PEEK-TYPE is NIL the next octet is returned, if PEEK-TYPE is T, the next octet which is not 0 is returned, if PEEK-TYPE is an octet, the next octet which equals PEEK-TYPE is returned. EOF-ERROR-P and EOF-VALUE are interpreted as usual.
  • Method UNREAD-BYTE (byte (stream flexi-io-stream))
  • Function STRING-TO-OCTETS (string &key (external-format :latin1) (start 0) (end (length string)))
    Converts the Lisp string STRING from START to END to an array of octets corresponding to the external format designated by EXTERNAL-FORMAT. In spite of the name, STRING can be any sequence of characters, but the function is optimized for strings.
  • Function OCTETS-TO-STRING (sequence &key (external-format :latin1) (start 0) (end (length sequence)))
    Converts the Lisp sequence SEQUENCE of octets from START to END to a string using the external format designated by EXTERNAL-FORMAT. This function is optimized for the case of SEQUENCE being a vector. Don't use lists if you're in a hurry.
  • Function OCTET-LENGTH (string &key (external-format :latin1) (start 0) (end (length string)))
    Returns the length of the substring of STRING from START to END in octets if encoded using the external format EXTERNAL-FORMAT. In spite of the name, STRING can be any sequence of characters, but the function is optimized for strings.
  • Function CHAR-LENGTH (sequence &key (external-format :latin1) (start 0) (end (length sequence)))
    Kind of the inverse of OCTET-LENGTH. Returns the length of the subsequence (of octets) of SEQUENCE from START to END in characters if decoded using the external format EXTERNAL-FORMAT. Note that this function doesn't check for the validity of the data in SEQUENCE. This function is optimized for the case of SEQUENCE being a vector. Don't use lists if you're in a hurry.