getf: Correct docstring.
[sbcl.git] / 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