1.0.4.9: writing bignum characters onto a single line
[sbcl.git] / 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