Streams
*******

Streams which read or write Lisp character data from or to the outside world -- files, sockets or other external entities -- require the specification of a conversion between the external, binary data and the Lisp characters.  In ANSI Common Lisp, this is done by specifying the :external-format argument when the stream is created.  The major information required is an encoding, specified by a keyword naming that encoding; however, it is also possible to specify refinements to that encoding as additional options to the external format designator.

In addition, 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.

External Formats
================

The encodings supported by SBCL as external formats are named by keyword.  Each encoding has a canonical name, which will be encoding returned by stream-external-format, and a number of aliases for convenience, as shown in the table below:

     [file encodings.texi-temp not included]

In situations where an external file format designator is required, such as the :external-format argument in calls to open or with-open-file, users may supply the name of an encoding to denote the external format which is applying that encoding to Lisp characters.

In addition to the basic encoding for an external format, options controlling various special cases may be passed, by using a list (whose first element must be an encoding name and whose rest is a plist) as an external file format designator.  At present, the only supported key in the plist is :replacement, where the corresponding value is a string designator which is used as a replacement when an encoding or decoding error happens, handling those errors without user intervention; for example:

     (with-open-file (i pathname :external-format '(:utf-8 :replacement #\?))
       (read-line i))

will read the first line of PATHNAME, replacing any invalid utf-8 sequences with question marks.

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]