X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fstreams.texinfo;h=243ccf445edd1430cd0fe09021b248b9064f2ddd;hb=3cd07d95709e7059ed76076e9978ac21bd5b3629;hp=1cd05954694e2d7fd200ff66e08d3eab23a77e56;hpb=01b53542be411ba6ede003da5e7292e16602ab6e;p=sbcl.git diff --git a/doc/manual/streams.texinfo b/doc/manual/streams.texinfo index 1cd0595..243ccf4 100644 --- a/doc/manual/streams.texinfo +++ b/doc/manual/streams.texinfo @@ -1,41 +1,173 @@ -SBCL supports @dfn{Gray streams}, user-overloadable CLOS classes whose -instances can be used as Lisp streams (e.g. passed as the first -argument to @code{format}). Additionally, the bundled contrib module -@dfn{sb-simple-streams} implements a subset of the Franz Allegro -simple-streams proposal. +@node Extensible Streams +@comment node-name, next, previous, up +@chapter Extensible Streams + +SBCL supports various extensions of ANSI Common Lisp streams. + +@table @strong +@item Bivalent Streams +A type of stream that can read and write both @code{character} and +@code{(unsigned-byte 8)} values. + +@item Gray Streams +User-overloadable CLOS classes whose instances can be used as Lisp +streams (e.g. passed as the first argument to @code{format}). + +@item Simple Streams +The bundled contrib module @dfn{sb-simple-streams} implements a subset +of the Franz Allegro simple-streams proposal. + +@end table @menu -* Gray Streams:: -* Simple Streams:: +* Bivalent Streams:: +* Gray Streams:: +* Simple Streams:: @end menu +@node Bivalent Streams +@section Bivalent Streams + +A @dfn{bivalent stream} can be used to read and write both +@code{character} and @code{(unsigned-byte 8)} values. A bivalent +stream is created by calling @code{open} with the argument @code{:element-type +:default}. On such a stream, both binary and character data can be +read and written with the usual input and output functions. + +@c Horrible visual markup +@quotation +Streams are @emph{not} created bivalent by default for performance +reasons. Bivalent streams are incompatible with +@code{fast-read-char}, an internal optimization in sbcl's stream +machinery that bulk-converts octets to characters and implements a +fast path through @code{read-char}. +@end quotation + @node Gray Streams @section 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. + +@menu +* Gray Streams classes:: +* Methods common to all streams:: +* Input stream methods:: +* Output stream methods:: +* Binary stream methods:: +* Character input stream methods:: +* Character output stream methods:: +* Gray Streams examples:: +@end menu + +@node Gray Streams classes +@subsection Gray Streams classes + +The defined Gray Stream classes are these: + @include class-sb-gray-fundamental-stream.texinfo -@include fun-sb-gray-stream-advance-to-column.texinfo +@include class-sb-gray-fundamental-input-stream.texinfo + +@noindent +The function input-stream-p will return true of any generalized +instance of fundamental-input-stream. + +@include class-sb-gray-fundamental-output-stream.texinfo + +@noindent +The function output-stream-p will return true of any generalized +instance of fundamental-output-stream. + +@include class-sb-gray-fundamental-binary-stream.texinfo + +@noindent +Note that instantiable subclasses of fundamental-binary-stream should +provide (or inherit) an applicable method for the generic function +stream-element-type. + +@include class-sb-gray-fundamental-character-stream.texinfo +@include class-sb-gray-fundamental-binary-input-stream.texinfo +@include class-sb-gray-fundamental-binary-output-stream.texinfo +@include class-sb-gray-fundamental-character-input-stream.texinfo +@include class-sb-gray-fundamental-character-output-stream.texinfo + +@node Methods common to all streams +@subsection Methods common to all streams + +These generic functions can be specialized on any generalized instance +of fundamental-stream. + +@include fun-common-lisp-stream-element-type.texinfo +@include fun-common-lisp-close.texinfo +@include fun-sb-gray-stream-file-position.texinfo + + + +@node Input stream methods +@subsection Input stream methods + +These generic functions may be specialized on any generalized instance +of fundamental-input-stream. + @include fun-sb-gray-stream-clear-input.texinfo +@include fun-sb-gray-stream-read-sequence.texinfo + +@node Character input stream methods +@subsection Character input stream methods + +These generic functions are used to implement subclasses of +fundamental-input-stream: + +@include fun-sb-gray-stream-peek-char.texinfo +@include fun-sb-gray-stream-read-char-no-hang.texinfo +@include fun-sb-gray-stream-read-char.texinfo +@include fun-sb-gray-stream-read-line.texinfo +@include fun-sb-gray-stream-listen.texinfo +@include fun-sb-gray-stream-unread-char.texinfo + +@node Output stream methods +@subsection Output stream methods + +These generic functions are used to implement subclasses of +fundamental-output-stream: + @include fun-sb-gray-stream-clear-output.texinfo @include fun-sb-gray-stream-finish-output.texinfo @include fun-sb-gray-stream-force-output.texinfo +@include fun-sb-gray-stream-write-sequence.texinfo + +@node Binary stream methods +@subsection Binary stream methods + +The following generic functions are available for subclasses of +fundamental-binary-stream: + +@include fun-sb-gray-stream-read-byte.texinfo +@include fun-sb-gray-stream-write-byte.texinfo + +@node Character output stream methods +@subsection Character output stream methods + +These generic functions are used to implement subclasses of +fundamental-character-output-stream: + +@include fun-sb-gray-stream-advance-to-column.texinfo @include fun-sb-gray-stream-fresh-line.texinfo @include fun-sb-gray-stream-line-column.texinfo @include fun-sb-gray-stream-line-length.texinfo -@include fun-sb-gray-stream-listen.texinfo -@include fun-sb-gray-stream-peek-char.texinfo -@include fun-sb-gray-stream-read-byte.texinfo -@include fun-sb-gray-stream-read-char-no-hang.texinfo -@include fun-sb-gray-stream-read-char.texinfo -@include fun-sb-gray-stream-read-line.texinfo -@include fun-sb-gray-stream-read-sequence.texinfo @include fun-sb-gray-stream-start-line-p.texinfo @include fun-sb-gray-stream-terpri.texinfo -@include fun-sb-gray-stream-unread-char.texinfo -@include fun-sb-gray-stream-write-byte.texinfo @include fun-sb-gray-stream-write-char.texinfo -@include fun-sb-gray-stream-write-sequence.texinfo @include fun-sb-gray-stream-write-string.texinfo +@include gray-streams-examples.texinfo + @node Simple Streams @comment node-name, next, previous, up @section Simple Streams