Extensible Streams
******************

SBCL supports various extensions of ANSI Common Lisp streams.

Bivalent Streams
     A type of stream that can read and write both character and (unsigned-byte 8) values.

Gray Streams
     User-overloadable CLOS classes whose instances can be used as Lisp streams (e.g. passed as the first argument to format).

Simple Streams
     The bundled contrib module sb-simple-streams implements a subset of the Franz Allegro simple-streams proposal.

Bivalent Streams
================

A bivalent stream can be used to read and write both character and (unsigned-byte 8) values.  A bivalent stream is created by calling open with the argument :element-type :default.  On such a stream, both binary and character data can be read and written with the usual input and output functions.

     Streams are not created bivalent by default for performance reasons.  Bivalent streams are incompatible with fast-read-char, an internal optimization in sbcl's stream machinery that bulk-converts octets to characters and implements a fast path through read-char.

Gray Streams
============

The Gray Streams interface is a widely supported extension that provides for definition of CLOS-extensible stream classes.  Gray stream classes are implemented by adding methods to generic functions analogous to Common Lisp's standard I/O functions.  Instances of Gray stream classes may be used with any I/O operation where a non-Gray stream can, provided that all required methods have been implemented suitably.

Gray Streams classes
--------------------

The defined Gray Stream classes are these:

     [file class-sb-gray-fundamental-stream.texinfo not included]
     [file class-sb-gray-fundamental-input-stream.texinfo not included]

The function input-stream-p will return true of any generalized instance of fundamental-input-stream.

     [file class-sb-gray-fundamental-output-stream.texinfo not included]

The function output-stream-p will return true of any generalized instance of fundamental-output-stream.

     [file class-sb-gray-fundamental-binary-stream.texinfo not included]

Note that instantiable subclasses of fundamental-binary-stream should provide (or inherit) an applicable method for the generic function stream-element-type.

     [file class-sb-gray-fundamental-character-stream.texinfo not included]
     [file class-sb-gray-fundamental-binary-input-stream.texinfo not included]
     [file class-sb-gray-fundamental-binary-output-stream.texinfo not included]
     [file class-sb-gray-fundamental-character-input-stream.texinfo not included]
     [file class-sb-gray-fundamental-character-output-stream.texinfo not included]

Methods common to all streams
-----------------------------

These generic functions can be specialized on any generalized instance of fundamental-stream.

     [file fun-common-lisp-stream-element-type.texinfo not included]
     [file fun-common-lisp-close.texinfo not included]
     [file fun-sb-gray-stream-file-position.texinfo not included]

Input stream methods
--------------------

These generic functions may be specialized on any generalized instance of fundamental-input-stream.

     [file fun-sb-gray-stream-clear-input.texinfo not included]
     [file fun-sb-gray-stream-read-sequence.texinfo not included]

Character input stream methods
------------------------------

These generic functions are used to implement subclasses of fundamental-input-stream:

     [file fun-sb-gray-stream-peek-char.texinfo not included]
     [file fun-sb-gray-stream-read-char-no-hang.texinfo not included]
     [file fun-sb-gray-stream-read-char.texinfo not included]
     [file fun-sb-gray-stream-read-line.texinfo not included]
     [file fun-sb-gray-stream-listen.texinfo not included]
     [file fun-sb-gray-stream-unread-char.texinfo not included]

Output stream methods
---------------------

These generic functions are used to implement subclasses of fundamental-output-stream:

     [file fun-sb-gray-stream-clear-output.texinfo not included]
     [file fun-sb-gray-stream-finish-output.texinfo not included]
     [file fun-sb-gray-stream-force-output.texinfo not included]
     [file fun-sb-gray-stream-write-sequence.texinfo not included]

Binary stream methods
---------------------

The following generic functions are available for subclasses of fundamental-binary-stream:

     [file fun-sb-gray-stream-read-byte.texinfo not included]
     [file fun-sb-gray-stream-write-byte.texinfo not included]

Character output stream methods
-------------------------------

These generic functions are used to implement subclasses of fundamental-character-output-stream:

     [file fun-sb-gray-stream-advance-to-column.texinfo not included]
     [file fun-sb-gray-stream-fresh-line.texinfo not included]
     [file fun-sb-gray-stream-line-column.texinfo not included]
     [file fun-sb-gray-stream-line-length.texinfo not included]
     [file fun-sb-gray-stream-start-line-p.texinfo not included]
     [file fun-sb-gray-stream-terpri.texinfo not included]
     [file fun-sb-gray-stream-write-char.texinfo not included]
     [file fun-sb-gray-stream-write-string.texinfo not included]

     [file gray-streams-examples.texinfo not included]

Simple Streams
==============

     [file sb-simple-streams.texinfo not included]