doc/manual/streams.texinfo

   1 @node Extensible Streams
   2 @comment  node-name,  next,  previous,  up
   3 @chapter Extensible Streams
   4
   5 SBCL supports various extensions of ANSI Common Lisp streams.
   6
   7 @table @strong
   8 @item Bivalent Streams
   9 A type of stream that can read and write both @code{character} and
  10 @code{(unsigned-byte 8)} values.
  11
  12 @item Gray Streams
  13 User-overloadable CLOS classes whose instances can be used as Lisp
  14 streams (e.g. passed as the first argument to @code{format}).
  15
  16 @item Simple Streams
  17 The bundled contrib module @dfn{sb-simple-streams} implements a subset
  18 of the Franz Allegro simple-streams proposal.
  19
  20 @end table
  21
  22 @menu
  23 * Bivalent Streams::
  24 * Gray Streams::
  25 * Simple Streams::
  26 @end menu
  27
  28 @node Bivalent Streams
  29 @section Bivalent Streams
  30
  31 A @dfn{bivalent stream} can be used to read and write both
  32 @code{character} and @code{(unsigned-byte 8)} values.  A bivalent
  33 stream is created by calling @code{open} with the argument @code{:element-type
  34 :default}.  On such a stream, both binary and character data can be
  35 read and written with the usual input and output functions.
  36
  37 @c Horrible visual markup
  38 @quotation
  39 Streams are @emph{not} created bivalent by default for performance
  40 reasons.  Bivalent streams are incompatible with
  41 @code{fast-read-char}, an internal optimization in sbcl's stream
  42 machinery that bulk-converts octets to characters and implements a
  43 fast path through @code{read-char}.
  44 @end quotation
  45
  46 @node Gray Streams
  47 @section Gray Streams
  48
  49
  50 The Gray Streams interface is a widely supported extension that
  51 provides for definition of CLOS-extensible stream classes.  Gray
  52 stream classes are implemented by adding methods to generic functions
  53 analogous to Common Lisp's standard I/O functions.  Instances of Gray
  54 stream classes may be used with any I/O operation where a non-Gray
  55 stream can, provided that all required methods have been implemented
  56 suitably.
  57
  58 @menu
  59 * Gray Streams classes::
  60 * Methods common to all streams::
  61 * Input stream methods::
  62 * Output stream methods::
  63 * Binary stream methods::
  64 * Character input stream methods::
  65 * Character output stream methods::
  66 * Gray Streams examples::
  67 @end menu
  68
  69 @node Gray Streams classes
  70 @subsection Gray Streams classes
  71
  72 The defined Gray Stream classes are these:
  73
  74 @include class-sb-gray-fundamental-stream.texinfo
  75 @include class-sb-gray-fundamental-input-stream.texinfo
  76
  77 @noindent
  78 The function input-stream-p will return true of any generalized
  79 instance of fundamental-input-stream.
  80
  81 @include class-sb-gray-fundamental-output-stream.texinfo
  82
  83 @noindent
  84 The function output-stream-p will return true of any generalized
  85 instance of fundamental-output-stream.
  86
  87 @include class-sb-gray-fundamental-binary-stream.texinfo
  88
  89 @noindent
  90 Note that instantiable subclasses of fundamental-binary-stream should
  91 provide (or inherit) an applicable method for the generic function
  92 stream-element-type.
  93
  94 @include class-sb-gray-fundamental-character-stream.texinfo
  95 @include class-sb-gray-fundamental-binary-input-stream.texinfo
  96 @include class-sb-gray-fundamental-binary-output-stream.texinfo
  97 @include class-sb-gray-fundamental-character-input-stream.texinfo
  98 @include class-sb-gray-fundamental-character-output-stream.texinfo
  99
 100 @node Methods common to all streams
 101 @subsection Methods common to all streams
 102
 103 These generic functions can be specialized on any generalized instance
 104 of fundamental-stream.
 105
 106 @include fun-common-lisp-stream-element-type.texinfo
 107 @include fun-common-lisp-close.texinfo
 108 @include fun-sb-gray-stream-file-position.texinfo
 109
 110
 111
 112 @node Input stream methods
 113 @subsection Input stream methods
 114
 115 These generic functions may be specialized on any generalized instance
 116 of fundamental-input-stream.
 117
 118 @include fun-sb-gray-stream-clear-input.texinfo
 119 @include fun-sb-gray-stream-read-sequence.texinfo
 120
 121 @node Character input stream methods
 122 @subsection Character input stream methods
 123
 124 These generic functions are used to implement subclasses of
 125 fundamental-input-stream:
 126
 127 @include fun-sb-gray-stream-peek-char.texinfo
 128 @include fun-sb-gray-stream-read-char-no-hang.texinfo
 129 @include fun-sb-gray-stream-read-char.texinfo
 130 @include fun-sb-gray-stream-read-line.texinfo
 131 @include fun-sb-gray-stream-listen.texinfo
 132 @include fun-sb-gray-stream-unread-char.texinfo
 133
 134 @node Output stream methods
 135 @subsection Output stream methods
 136
 137 These generic functions are used to implement subclasses of
 138 fundamental-output-stream:
 139
 140 @include fun-sb-gray-stream-clear-output.texinfo
 141 @include fun-sb-gray-stream-finish-output.texinfo
 142 @include fun-sb-gray-stream-force-output.texinfo
 143 @include fun-sb-gray-stream-write-sequence.texinfo
 144
 145 @node Binary stream methods
 146 @subsection Binary stream methods
 147
 148 The following generic functions are available for subclasses of
 149 fundamental-binary-stream:
 150
 151 @include fun-sb-gray-stream-read-byte.texinfo
 152 @include fun-sb-gray-stream-write-byte.texinfo
 153
 154 @node Character output stream methods
 155 @subsection Character output stream methods
 156
 157 These generic functions are used to implement subclasses of
 158 fundamental-character-output-stream:
 159
 160 @include fun-sb-gray-stream-advance-to-column.texinfo
 161 @include fun-sb-gray-stream-fresh-line.texinfo
 162 @include fun-sb-gray-stream-line-column.texinfo
 163 @include fun-sb-gray-stream-line-length.texinfo
 164 @include fun-sb-gray-stream-start-line-p.texinfo
 165 @include fun-sb-gray-stream-terpri.texinfo
 166 @include fun-sb-gray-stream-write-char.texinfo
 167 @include fun-sb-gray-stream-write-string.texinfo
 168
 169 @include gray-streams-examples.texinfo
 170
 171 @node Simple Streams
 172 @comment  node-name,  next,  previous,  up
 173 @section Simple Streams
 174 @include sb-simple-streams/sb-simple-streams.texinfo