doc/manual/streams.texinfo

   1 @node Streams
   2 @comment  node-name,  next,  previous,  up
   3 @chapter Streams
   4
   5 Streams which read or write Lisp character data from or to the outside
   6 world -- files, sockets or other external entities -- require the
   7 specification of a conversion between the external, binary data and the
   8 Lisp characters.  In ANSI Common Lisp, this is done by specifying the
   9 @code{:external-format} argument when the stream is created.  The major
  10 information required is an @emph{encoding}, specified by a keyword
  11 naming that encoding; however, it is also possible to specify
  12 refinements to that encoding as additional options to the external
  13 format designator.
  14
  15 In addition, SBCL supports various extensions of ANSI Common Lisp
  16 streams:
  17
  18 @table @strong
  19 @item Bivalent Streams
  20 A type of stream that can read and write both @code{character} and
  21 @code{(unsigned-byte 8)} values.
  22
  23 @item Gray Streams
  24 User-overloadable CLOS classes whose instances can be used as Lisp
  25 streams (e.g. passed as the first argument to @code{format}).
  26
  27 @item Simple Streams
  28 The bundled contrib module @dfn{sb-simple-streams} implements a subset
  29 of the Franz Allegro simple-streams proposal.
  30
  31 @end table
  32
  33 @menu
  34 * External Formats::
  35 * Bivalent Streams::
  36 * Gray Streams::
  37 * Simple Streams::
  38 @end menu
  39
  40 @node External Formats
  41 @section External Formats
  42 @cindex External formats
  43
  44 @findex @cl{stream-external-format}
  45 The encodings supported by SBCL as external formats are named by
  46 keyword.  Each encoding has a canonical name, which will be encoding
  47 returned by @code{stream-external-format}, and a number of aliases for
  48 convenience, as shown in the table below:
  49
  50 @include encodings.texi-temp
  51
  52 @findex @cl{open}
  53 @findex @cl{with-open-file}
  54 In situations where an external file format designator is required, such
  55 as the @code{:external-format} argument in calls to @code{open} or
  56 @code{with-open-file}, users may supply the name of an encoding to
  57 denote the external format which is applying that encoding to Lisp
  58 characters.
  59
  60 In addition to the basic encoding for an external format, options
  61 controlling various special cases may be passed, by using a list (whose
  62 first element must be an encoding name and whose rest is a plist) as an
  63 external file format designator.  At present, the only supported key in
  64 the plist is @code{:replacement}, where the corresponding value is a
  65 string designator which is used as a replacement when an encoding or
  66 decoding error happens, handling those errors without user intervention;
  67 for example:
  68 @lisp
  69 (with-open-file (i pathname :external-format '(:utf-8 :replacement #\?))
  70   (read-line i))
  71 @end lisp
  72 will read the first line of @var{pathname}, replacing any invalid utf-8
  73 sequences with question marks.
  74
  75 @node Bivalent Streams
  76 @section Bivalent Streams
  77
  78 A @dfn{bivalent stream} can be used to read and write both
  79 @code{character} and @code{(unsigned-byte 8)} values.  A bivalent
  80 stream is created by calling @code{open} with the argument @code{:element-type
  81 :default}.  On such a stream, both binary and character data can be
  82 read and written with the usual input and output functions.
  83
  84 @c Horrible visual markup
  85 @quotation
  86 Streams are @emph{not} created bivalent by default for performance
  87 reasons.  Bivalent streams are incompatible with
  88 @code{fast-read-char}, an internal optimization in sbcl's stream
  89 machinery that bulk-converts octets to characters and implements a
  90 fast path through @code{read-char}.
  91 @end quotation
  92
  93 @node Gray Streams
  94 @section Gray Streams
  95
  96
  97 The Gray Streams interface is a widely supported extension that
  98 provides for definition of CLOS-extensible stream classes.  Gray
  99 stream classes are implemented by adding methods to generic functions
 100 analogous to Common Lisp's standard I/O functions.  Instances of Gray
 101 stream classes may be used with any I/O operation where a non-Gray
 102 stream can, provided that all required methods have been implemented
 103 suitably.
 104
 105 @menu
 106 * Gray Streams classes::
 107 * Methods common to all streams::
 108 * Input stream methods::
 109 * Output stream methods::
 110 * Binary stream methods::
 111 * Character input stream methods::
 112 * Character output stream methods::
 113 * Gray Streams examples::
 114 @end menu
 115
 116 @node Gray Streams classes
 117 @subsection Gray Streams classes
 118
 119 The defined Gray Stream classes are these:
 120
 121 @include class-sb-gray-fundamental-stream.texinfo
 122 @include class-sb-gray-fundamental-input-stream.texinfo
 123
 124 @noindent
 125 The function input-stream-p will return true of any generalized
 126 instance of fundamental-input-stream.
 127
 128 @include class-sb-gray-fundamental-output-stream.texinfo
 129
 130 @noindent
 131 The function output-stream-p will return true of any generalized
 132 instance of fundamental-output-stream.
 133
 134 @include class-sb-gray-fundamental-binary-stream.texinfo
 135
 136 @noindent
 137 Note that instantiable subclasses of fundamental-binary-stream should
 138 provide (or inherit) an applicable method for the generic function
 139 stream-element-type.
 140
 141 @include class-sb-gray-fundamental-character-stream.texinfo
 142 @include class-sb-gray-fundamental-binary-input-stream.texinfo
 143 @include class-sb-gray-fundamental-binary-output-stream.texinfo
 144 @include class-sb-gray-fundamental-character-input-stream.texinfo
 145 @include class-sb-gray-fundamental-character-output-stream.texinfo
 146
 147 @node Methods common to all streams
 148 @subsection Methods common to all streams
 149
 150 These generic functions can be specialized on any generalized instance
 151 of fundamental-stream.
 152
 153 @include fun-common-lisp-stream-element-type.texinfo
 154 @include fun-common-lisp-close.texinfo
 155 @include fun-sb-gray-stream-file-position.texinfo
 156
 157
 158
 159 @node Input stream methods
 160 @subsection Input stream methods
 161
 162 These generic functions may be specialized on any generalized instance
 163 of fundamental-input-stream.
 164
 165 @include fun-sb-gray-stream-clear-input.texinfo
 166 @include fun-sb-gray-stream-read-sequence.texinfo
 167
 168 @node Character input stream methods
 169 @subsection Character input stream methods
 170
 171 These generic functions are used to implement subclasses of
 172 fundamental-input-stream:
 173
 174 @include fun-sb-gray-stream-peek-char.texinfo
 175 @include fun-sb-gray-stream-read-char-no-hang.texinfo
 176 @include fun-sb-gray-stream-read-char.texinfo
 177 @include fun-sb-gray-stream-read-line.texinfo
 178 @include fun-sb-gray-stream-listen.texinfo
 179 @include fun-sb-gray-stream-unread-char.texinfo
 180
 181 @node Output stream methods
 182 @subsection Output stream methods
 183
 184 These generic functions are used to implement subclasses of
 185 fundamental-output-stream:
 186
 187 @include fun-sb-gray-stream-clear-output.texinfo
 188 @include fun-sb-gray-stream-finish-output.texinfo
 189 @include fun-sb-gray-stream-force-output.texinfo
 190 @include fun-sb-gray-stream-write-sequence.texinfo
 191
 192 @node Binary stream methods
 193 @subsection Binary stream methods
 194
 195 The following generic functions are available for subclasses of
 196 fundamental-binary-stream:
 197
 198 @include fun-sb-gray-stream-read-byte.texinfo
 199 @include fun-sb-gray-stream-write-byte.texinfo
 200
 201 @node Character output stream methods
 202 @subsection Character output stream methods
 203
 204 These generic functions are used to implement subclasses of
 205 fundamental-character-output-stream:
 206
 207 @include fun-sb-gray-stream-advance-to-column.texinfo
 208 @include fun-sb-gray-stream-fresh-line.texinfo
 209 @include fun-sb-gray-stream-line-column.texinfo
 210 @include fun-sb-gray-stream-line-length.texinfo
 211 @include fun-sb-gray-stream-start-line-p.texinfo
 212 @include fun-sb-gray-stream-terpri.texinfo
 213 @include fun-sb-gray-stream-write-char.texinfo
 214 @include fun-sb-gray-stream-write-string.texinfo
 215
 216 @include gray-streams-examples.texinfo
 217
 218 @node Simple Streams
 219 @comment  node-name,  next,  previous,  up
 220 @section Simple Streams
 221 @include sb-simple-streams/sb-simple-streams.texinfo