index.html - clic - Clic is an command line interactive client for gopher writt… | |
git clone git://bitreich.org/clic/ git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws65… | |
Log | |
Files | |
Refs | |
Tags | |
README | |
LICENSE | |
--- | |
index.html (62454B) | |
--- | |
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> | |
2 <html> | |
3 | |
4 <head> | |
5 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1… | |
6 <title>FLEXI-STREAMS - Flexible bivalent streams for Common Lisp</titl… | |
7 <style type="text/css"> | |
8 pre { padding:5px; background-color:#e0e0e0 } | |
9 h3, h4 { text-decoration: underline; } | |
10 a { text-decoration: none; padding: 1px 2px 1px 2px; } | |
11 a:visited { text-decoration: none; padding: 1px 2px 1px 2px; } | |
12 a:hover { text-decoration: none; padding: 1px 1px 1px 1px; border: 1px… | |
13 a:focus { text-decoration: none; padding: 1px 2px 1px 2px; border: non… | |
14 a.none { text-decoration: none; padding: 0; } | |
15 a.none:visited { text-decoration: none; padding: 0; } | |
16 a.none:hover { text-decoration: none; border: none; padding: 0; } | |
17 a.none:focus { text-decoration: none; border: none; padding: 0; } | |
18 a.noborder { text-decoration: none; padding: 0; } | |
19 a.noborder:visited { text-decoration: none; padding: 0; } | |
20 a.noborder:hover { text-decoration: none; border: none; padding: 0; } | |
21 a.noborder:focus { text-decoration: none; border: none; padding: 0; } | |
22 </style> | |
23 </head> | |
24 | |
25 <body bgcolor=white> | |
26 | |
27 <h2>FLEXI-STREAMS - Flexible bivalent streams for Common Lisp</h2> | |
28 | |
29 <blockquote> | |
30 <br> <br><h3><a name=abstract class=none>Abstract</a></h3> | |
31 | |
32 FLEXI-STREAMS implements "virtual" bivalent streams that can be | |
33 layered atop real binary or bivalent streams and that can be used to | |
34 read and write character data in various single- or multi-octet | |
35 encodings which can be changed on the fly. It also supplies | |
36 <em>in-memory</em> binary streams which are similar to string streams. | |
37 <p> | |
38 The library needs a Common Lisp implementation that | |
39 supports <a | |
40 href="http://www.nhplace.com/kent/CL/Issues/stream-definition-by-user.ht… | |
41 streams</em></a> and relies on David | |
42 Lichteblau's <a | |
43 href="http://www.cliki.net/trivial-gray-streams">trivial-gray-streams</a> | |
44 to offer portability between different Lisps. | |
45 <p> | |
46 The code comes with | |
47 a <a | |
48 href="http://www.opensource.org/licenses/bsd-license.php">BSD-style | |
49 license</a> so you can basically do with it whatever you want. | |
50 | |
51 <p> | |
52 <font color=red>Download shortcut:</font> <a | |
53 href="https://github.com/edicl/flexi-streams/releases/latest">https://gi… | |
54 </blockquote> | |
55 | |
56 <br> <br><h3><a class=none name="contents">Contents</a></h3> | |
57 <ol> | |
58 <li><a href="#example">Example usage</a> | |
59 <li><a href="#install">Download and installation</a> | |
60 <li><a href="#support">Support</a> | |
61 <li><a href="#dictionary">The FLEXI-STREAMS dictionary</a> | |
62 <ol> | |
63 <li><a href="#external-formats">External formats</a> | |
64 <ol> | |
65 <li><a href="#make-external-format"><code>make-external-format</co… | |
66 <li><a href="#external-format-name"><code>external-format-name</co… | |
67 <li><a href="#external-format-eol-style"><code>external-format-eol… | |
68 <li><a href="#external-format-little-endian"><code>external-format… | |
69 <li><a href="#external-format-id"><code>external-format-id</code><… | |
70 <li><a href="#external-format-equal"><code>external-format-equal</… | |
71 <li><a href="#*default-eol-style*"><code>*default-eol-style*</code… | |
72 <li><a href="#*default-little-endian*"><code>*default-little-endia… | |
73 <li><a href="#external-format-condition"><code>external-format-con… | |
74 <li><a href="#external-format-condition-external-format"><code>ext… | |
75 <li><a href="#external-format-error"><code>external-format-error</… | |
76 <li><a href="#external-format-encoding-error"><code>external-forma… | |
77 <li><a href="#*substitution-char*"><code>*substitution-char*</code… | |
78 <li><a href="#accept-overlong-sequence"><code>accept-overlong-sequ… | |
79 </ol> | |
80 <li><a href="#flexi-streams">Flexi streams</a> | |
81 <ol> | |
82 <li><a href="#flexi-stream"><code>flexi-stream</code></a> | |
83 <li><a href="#flexi-input-stream"><code>flexi-input-stream</code><… | |
84 <li><a href="#flexi-output-stream"><code>flexi-output-stream</code… | |
85 <li><a href="#flexi-io-stream"><code>flexi-io-stream</code></a> | |
86 <li><a href="#make-flexi-stream"><code>make-flexi-stream</code></a> | |
87 <li><a href="#flexi-stream-external-format"><code>flexi-stream-ext… | |
88 <li><a href="#flexi-stream-element-type"><code>flexi-stream-elemen… | |
89 <li><a href="#flexi-stream-column"><code>flexi-stream-column</code… | |
90 <li><a href="#flexi-stream-position"><code>flexi-stream-position</… | |
91 <li><a href="#flexi-stream-bound"><code>flexi-stream-bound</code><… | |
92 <li><a href="#flexi-stream-stream"><code>flexi-stream-stream</code… | |
93 <li><a href="#unread-byte"><code>unread-byte</code></a> | |
94 <li><a href="#peek-byte"><code>peek-byte</code></a> | |
95 <li><a href="#octet"><code>octet</code></a> | |
96 <li><a href="#flexi-stream-error"><code>flexi-stream-error</code><… | |
97 <li><a href="#flexi-stream-out-of-sync-error"><code>flexi-stream-o… | |
98 <li><a href="#flexi-stream-element-type-error"><code>flexi-stream-… | |
99 <li><a href="#flexi-stream-element-type-error-element-type"><code>… | |
100 </ol> | |
101 <li><a href="#in-memory">In-memory streams</a> | |
102 <ol> | |
103 <li><a href="#in-memory-stream"><code>in-memory-stream</code></a> | |
104 <li><a href="#in-memory-input-stream"><code>in-memory-input-stream… | |
105 <li><a href="#in-memory-output-stream"><code>in-memory-output-stre… | |
106 <li><a href="#list-stream"><code>list-stream</code></a> | |
107 <li><a href="#vector-stream"><code>vector-stream</code></a> | |
108 <li><a href="#make-in-memory-input-stream"><code>make-in-memory-in… | |
109 <li><a href="#make-in-memory-output-stream"><code>make-in-memory-o… | |
110 <li><a href="#get-output-stream-sequence"><code>get-output-stream-… | |
111 <li><a href="#output-stream-sequence-length"><code>output-stream-s… | |
112 <li><a href="#with-input-from-sequence"><code>with-input-from-sequ… | |
113 <li><a href="#with-output-to-sequence"><code>with-output-to-sequen… | |
114 <li><a href="#in-memory-stream-error"><code>in-memory-stream-error… | |
115 <li><a href="#in-memory-stream-closed-error"><code>in-memory-strea… | |
116 <li><a href="#in-memory-stream-position-spec-error"><code>in-memor… | |
117 <li><a href="#in-memory-stream-position-spec-error-position-spec">… | |
118 </ol> | |
119 <li><a href="#strings">Strings</a> | |
120 <ol> | |
121 <li><a href="#string-to-octets"><code>string-to-octets</code></a> | |
122 <li><a href="#octets-to-string"><code>octets-to-string</code></a> | |
123 <li><a href="#octet-length"><code>octet-length</code></a> | |
124 <li><a href="#char-length"><code>char-length</code></a> | |
125 </ol> | |
126 </ol> | |
127 <li><a href="#position">File positions</a> | |
128 <li><a href="#ack">Acknowledgements</a> | |
129 </ol> | |
130 | |
131 <br> <br><h3><a name="example" class=none>Example usage</a></h3> | |
132 | |
133 The examples were created with <a href="http://www.lispworks.com/">LispW… | |
134 | |
135 <pre> | |
136 (defun foo (pathspec) | |
137 "With standard LispWorks streams." | |
138 (with-open-file (out pathspec | |
139 :direction :output | |
140 :if-exists :supersede | |
141 :external-format '(:utf-8 :eol-style :crlf)) | |
142 (write-line "ÄÖÜ1" out)) | |
143 (with-open-file (out pathspec | |
144 :direction :output | |
145 :if-exists :append | |
146 :external-format '(:latin-1 :eol-style :lf)) | |
147 (write-line "ÄÖÜ2" out)) | |
148 (with-open-file (out pathspec | |
149 :direction :output | |
150 :if-exists :append | |
151 :element-type 'octet) | |
152 (write-byte #xeb out) | |
153 (write-sequence #(#xa3 #xa4 #xa5) out)) | |
154 (with-open-file (out pathspec | |
155 :direction :output | |
156 :if-exists :append | |
157 :external-format '(:unicode :little-endian nil :e… | |
158 (write-line "ÄÖÜ3" out))) | |
159 | |
160 (defun bar (pathspec) | |
161 "With a <a href="#flexi-streams" class=noborder>flexi stream</a>.… | |
162 (with-open-file (out pathspec | |
163 :direction :output | |
164 :if-exists :supersede | |
165 :external-format '(:latin-1 :eol-style :lf)) | |
166 (setq out (<a href="#make-flexi-stream" class=noborder>make-flexi-st… | |
167 (write-line "ÄÖÜ1" out) | |
168 (setf (<a href="#flexi-stream-external-format" class=noborder>flexi-… | |
169 (write-line "ÄÖÜ2" out) | |
170 (write-byte #xeb out) | |
171 (write-sequence #(#xa3 #xa4 #xa5) out) | |
172 (setf (flexi-stream-external-format out) :ucs-2be) | |
173 (write-line "ÄÖÜ3" out))) | |
174 </pre> | |
175 | |
176 <p> | |
177 And applying this function | |
178 <pre> | |
179 (defun baz (pathspec) | |
180 (let (result) | |
181 (with-open-file (in pathspec :element-type '<a href="#octet" class=n… | |
182 (setq in (<a href="#make-flexi-stream" class=noborder>make-flexi-s… | |
183 (push (read-line in) result) | |
184 (push (read-byte in) result) | |
185 (setf (<a href="#flexi-stream-external-format" class=noborder>flex… | |
186 (push (read-line in) result) | |
187 (setf (flexi-stream-external-format in) :greek) | |
188 (push (read-char in) result) | |
189 (setf (flexi-stream-external-format in) :latin0) | |
190 (let ((string (make-string 3 :element-type 'character))) | |
191 (read-sequence string in) | |
192 (push string result)) | |
193 (let ((octets (make-array 2 :element-type 'octet))) | |
194 (read-sequence octets in) | |
195 (push octets result)) | |
196 (setf (flexi-stream-external-format in) :ucs-2be) | |
197 (push (read-line in) result)) | |
198 (nreverse result))) | |
199 </pre> | |
200 to the file created above will yield the list | |
201 <pre> | |
202 ("ÄÖÜ1" 196 "ÖÜ2" #\λ&nbs… | |
203 </pre> | |
204 | |
205 <p> | |
206 For more examples see the source code | |
207 of | |
208 <a href="http://mr-co.de/projects/cl-rfc2047/">CL-RFC2047</a>, | |
209 <a | |
210 href="http://weitz.de/drakma/">Drakma</a>, <a | |
211 href="http://weitz.de/chunga/">Chunga</a>, | |
212 or <a href="http://weitz.de/cl-wbxml/">CL-WBXML</a>. | |
213 | |
214 <br> <br><h3><a name="install" class=none>Download and installation… | |
215 | |
216 Before you try to install FLEXI-STREAMS, first check that in your Lisp | |
217 each <a | |
218 href="http://www.lispworks.com/documentation/HyperSpec/Body/13_.htm">cha… | |
219 <a | |
220 href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm… | |
221 code</a> is equal to | |
222 its <a | |
223 href="http://en.wikipedia.org/wiki/Unicode">Unicode</a> <a | |
224 href="http://unicode.org/glossary/">code point</a> and | |
225 that <code>(CHAR-CODE #\Newline)</code> | |
226 and <code>(CHAR-CODE #\Linefeed)</code> have the same | |
227 value (10). (This is the case for all relevant CL | |
228 implementations which were in use when this library was written. It | |
229 is <em>not</em> mandated by the ANSI standard, though.) | |
230 <p> | |
231 FLEXI-STREAMS together with this documentation can be downloaded from <a | |
232 href="https://github.com/edicl/flexi-streams/releases/latest">https://gi… | |
233 <p> | |
234 Before you install FLEXI-STREAMS you first need to | |
235 install the <a | |
236 href="http://www.cliki.net/trivial-gray-streams">trivial-gray-streams</a… | |
237 unless you already have it. | |
238 <p> | |
239 FLEXI-STREAMS comes with a system definition for <a | |
240 href="http://www.cliki.net/asdf">ASDF</a> so you can install the library… | |
241 <pre> | |
242 (asdf:oos 'asdf:load-op :flexi-streams) | |
243 </pre> | |
244 if you've unpacked it in a place where ASDF can find it. Installation | |
245 via <a href="http://www.cliki.net/asdf-install">asdf-install</a> | |
246 should also be possible, and there's a port | |
247 to <a href="http://www.cliki.net/Gentoo">Gentoo Lisp</a> thanks to | |
248 Matthew Kennedy. | |
249 <p> | |
250 You can run a test suite which tests <em>some</em> (but | |
251 not <em>all</em>) aspects of the library with | |
252 <pre> | |
253 (asdf:oos 'asdf:test-op :flexi-streams) | |
254 </pre> | |
255 This might take a while... | |
256 <p> | |
257 The current development version of FLEXI-STREAMS can be found | |
258 at <a href="http://bknr.net/trac/browser/trunk/thirdparty">http://bknr.n… | |
259 This is the one to send <a href="#mail">patches</a> against. Use at | |
260 your own risk. | |
261 <p> | |
262 Luís Oliveira maintains a <a href="http://darcs.net/">darcs</a> | |
263 repository of FLEXI-STREAMS | |
264 at <a href="http://common-lisp.net/%7Eloliveira/ediware/">http://common-… | |
265 <p> | |
266 A <a href="http://www.selenic.com/mercurial/wiki/">Mercurial</a> | |
267 repository of older versions is available | |
268 at <a | |
269 href="http://arcanes.fr.eu.org/~pierre/2007/02/weitz/">http://arcanes.fr… | |
270 thanks to Pierre Thierry. | |
271 | |
272 <br> <br><h3><a name="support" class=none>Support</a></h3> | |
273 | |
274 The development version of flexi-streams can be | |
275 found <a href="https://github.com/edicl/flexi-streams" target="_new">on | |
276 github</a>. Please use the github issue tracking system to submit bug | |
277 reports. Patches are welcome, please | |
278 use <a href="https://github.com/edicl/flexi-streams/pulls">GitHub pull | |
279 requests</a>. If you want to make a change, | |
280 please <a href="http://weitz.de/patches.html" target="_new">read this | |
281 first</a>. | |
282 | |
283 <br> <br><h3><a class=none name="dictionary">The FLEXI-STREAMS dict… | |
284 | |
285 <h4><a name="external-formats" class=none>External formats</a></h4> | |
286 | |
287 <code>EXTERNAL-FORMAT</code> objects are used to denote the external | |
288 formats of <a href="#flexi-streams">flexi streams</a>. These objects ar… | |
289 the <a | |
290 href="#make-external-format"><code>MAKE-EXTERNAL-FORMAT</code></a> | |
291 function, and there are <a href="#external-format-name">various | |
292 readers</a> to query their attributes. Once such an object is | |
293 created it can't be changed. | |
294 <p> | |
295 An external format consists of a basic encoding | |
296 (like <a | |
297 href="http://en.wikipedia.org/wiki/Iso-8859-1">ISO 8859-1</a> | |
298 or <a href="http://en.wikipedia.org/wiki/UTF-8">UTF-8</a>), a | |
299 definition how line endings are denoted - by a carriage return | |
300 character (ASCII 13), by a line feed character (ASCII 10), | |
301 or by both of these characters in a row -, and optionally (for | |
302 encodings that use units larger than 8 bits) information | |
303 about the <a href="http://en.wikipedia.org/wiki/Endian">endianess</a> | |
304 of the encoding. | |
305 <p> | |
306 The following encodings are currently supported by FLEXI-STREAMS: | |
307 <ul> | |
308 <li><a href="http://en.wikipedia.org/wiki/UTF-8">UTF-8</a> (denoted by t… | |
309 <li><a href="http://en.wikipedia.org/wiki/UTF-16">UTF-16</a> (denoted by… | |
310 <li><a href="http://en.wikipedia.org/wiki/UTF-32">UTF-32</a> (denoted by… | |
311 <li>all <a href="http://czyborra.com/charsets/iso8859.html">ISO 8859</a>… | |
312 <li><a href="http://en.wikipedia.org/wiki/KOI8-R">KOI8-R</a> (denoted by… | |
313 <li>a couple | |
314 of <a href="http://czyborra.com/charsets/codepages.html">Windows code | |
315 pages</a> (denoted by the keyword <code>:CODE-PAGE</code> and an | |
316 obligatory <code>:ID</code> argument), and | |
317 <li><a href="http://en.wikipedia.org/wiki/ASCII">US-ASCII</a>. | |
318 </ul> | |
319 <p> | |
320 A couple of alternative names are allowed that are listed below: | |
321 <p> | |
322 <table border=1> | |
323 <tr><td><code>:UTF-8</code></td><td><code>:UTF8</code></td></tr> | |
324 <tr><td rowspan=4 valign=top><code>:UTF-16</code></td><td><code>:UTF16</… | |
325 <tr><td><code>:UCS-2</code></td></tr> | |
326 <tr><td><code>:UCS2</code></td></tr> | |
327 <tr><td><code>:UNICODE</code></td></tr> | |
328 <tr><td rowspan=3 valign=top><code>:UTF-32</code></td><td><code>:UTF32</… | |
329 <tr><td><code>:UCS-4</code></td></tr> | |
330 <tr><td><code>:UCS4</code></td></tr> | |
331 <tr><td rowspan=2 valign=top><code>:ISO-8859-1</code></td><td><code>:LAT… | |
332 <tr><td><code>:LATIN1</code></td></tr> | |
333 <tr><td rowspan=2 valign=top><code>:ISO-8859-2</code></td><td><code>:LAT… | |
334 <tr><td><code>:LATIN2</code></td></tr> | |
335 <tr><td rowspan=2 valign=top><code>:ISO-8859-3</code></td><td><code>:LAT… | |
336 <tr><td><code>:LATIN3</code></td></tr> | |
337 <tr><td rowspan=2 valign=top><code>:ISO-8859-4</code></td><td><code>:LAT… | |
338 <tr><td><code>:LATIN4</code></td></tr> | |
339 <tr><td><code>:ISO-8859-5</code></td><td><code>:CYRILLIC</code></td></tr> | |
340 <tr><td><code>:ISO-8859-6</code></td><td><code>:ARABIC</code></td></tr> | |
341 <tr><td><code>:ISO-8859-7</code></td><td><code>:GREEK</code></td></tr> | |
342 <tr><td><code>:ISO-8859-8</code></td><td><code>:HEBREW</code></td></tr> | |
343 <tr><td rowspan=2 valign=top><code>:ISO-8859-9</code></td><td><code>:LAT… | |
344 <tr><td><code>:LATIN5</code></td></tr> | |
345 <tr><td rowspan=2 valign=top><code>:ISO-8859-10</code></td><td><code>:LA… | |
346 <tr><td><code>:LATIN6</code></td></tr> | |
347 <tr><td><code>:ISO-8859-11</code></td><td><code>:THAI</code></td></tr> | |
348 <tr><td rowspan=2 valign=top><code>:ISO-8859-13</code></td><td><code>:LA… | |
349 <tr><td><code>:LATIN7</code></td></tr> | |
350 <tr><td rowspan=2 valign=top><code>:ISO-8859-14</code></td><td><code>:LA… | |
351 <tr><td><code>:LATIN8</code></td></tr> | |
352 <tr><td rowspan=4 valign=top><code>:ISO-8859-15</code></td><td><code>:LA… | |
353 <tr><td><code>:LATIN9</code></td></tr> | |
354 <tr><td><code>:LATIN-0</code></td></tr> | |
355 <tr><td><code>:LATIN0</code></td></tr> | |
356 <tr><td rowspan=2 valign=top><code>:ISO-8859-16</code></td><td><code>:LA… | |
357 <tr><td><code>:LATIN10</code></td></tr> | |
358 <tr><td rowspan=2 valign=top><code>:CODE-PAGE</code></td><td><code>:CODE… | |
359 <tr><td><code>WIN32:CODE-PAGE<br>(only on <a href="http://www.lispworks.… | |
360 <tr><td><code>:KOI8-R</code></td><td><code>:KOI8R</code></td></tr> | |
361 <tr><td><code>:US-ASCII</code></td><td><code>:ASCII</code></td></tr> | |
362 </table> | |
363 <p> | |
364 (Note that we treat UCS-2 exactly like UTF-16 although there | |
365 are <a href="http://en.wikipedia.org/wiki/UTF-16">subtle | |
366 differences</a>. Also note that even though we support encodings like | |
367 UTF-32 some Lisps only supports characters contained within | |
368 the <a | |
369 href="http://en.wikipedia.org/wiki/Basic_Multilingual_Plane">Basic | |
370 Multilingual Plane</a> (like LispWorks) or even less (like CMUCL), so | |
371 if other characters are read from a | |
372 <a href="#flexi-streams">flexi | |
373 stream</a>, <a | |
374 href="http://www.lispworks.com/documentation/HyperSpec/Body/f_rd_cha.htm… | |
375 will try to be helpful and return the corresponding Unicode code point - | |
376 an integer - instead. This might lead to an error if you're using | |
377 functions | |
378 like <a | |
379 href="http://www.lispworks.com/documentation/HyperSpec/Body/f_rd_lin.htm… | |
380 | |
381 <p> | |
382 Whenever a FLEXI-STREAMS function accepts an external format as one of | |
383 its arguments, you can provide either an <code>EXTERNAL-FORMAT</code> | |
384 object or a shortcut which can be a list or a symbol. The list | |
385 shortcuts have a syntax similar | |
386 to <a | |
387 href="http://www.lispworks.com/documentation/lw50/LWUG/html/lwuser-360.h… | |
388 one used by LispWorks</a> - the cars are the names of and encoding | |
389 and the cdrs of these lists correspond to the keyword arguments | |
390 to <a | |
391 href="#make-external-format"><code>MAKE-EXTERNAL-FORMAT</code></a>, so | |
392 for example | |
393 <pre>(:latin-1 :eol-style :crlf)</pre> | |
394 is equivalent to | |
395 <pre>(<a class=noborder href="#make-external-format">make-external-forma… | |
396 symbol shortcuts are equivalent to | |
397 calling <a | |
398 href="#make-external-format"><code>MAKE-EXTERNAL-FORMAT</code></a> | |
399 without keyword arguments, i.e. | |
400 <pre>:thai</pre> | |
401 behaves like | |
402 <pre>(<a class=noborder href="#make-external-format">make-external-forma… | |
403 Finally, the following expansions are | |
404 available: | |
405 <p> | |
406 <table border=1> | |
407 <tr><td><code>:UCS-2LE</code></td><td><code>(:UCS-2 :LITTLE-ENDIAN&… | |
408 <tr><td><code>:UCS-2BE</code></td><td><code>(:UCS-2 :LITTLE-ENDIAN&… | |
409 <tr><td><code>:UCS-4LE</code></td><td><code>(:UCS-4 :LITTLE-ENDIAN&… | |
410 <tr><td><code>:UCS-4BE</code></td><td><code>(:UCS-4 :LITTLE-ENDIAN&… | |
411 <tr><td><code>:UTF-16LE</code></td><td><code>(:UTF-16 :LITTLE-ENDIA… | |
412 <tr><td><code>:UTF-16BE</code></td><td><code>(:UTF-16 :LITTLE-ENDIA… | |
413 <tr><td><code>:UTF-32LE</code></td><td><code>(:UTF-32 :LITTLE-ENDIA… | |
414 <tr><td><code>:UTF-32BE</code></td><td><code>(:UTF-32 :LITTLE-ENDIA… | |
415 <tr><td><code>:IBM437</code></td><td><code>(:CODE-PAGE :ID 437… | |
416 <tr><td><code>:IBM850</code></td><td><code>(:CODE-PAGE :ID 850… | |
417 <tr><td><code>:IBM852</code></td><td><code>(:CODE-PAGE :ID 852… | |
418 <tr><td><code>:IBM855</code></td><td><code>(:CODE-PAGE :ID 855… | |
419 <tr><td><code>:IBM857</code></td><td><code>(:CODE-PAGE :ID 857… | |
420 <tr><td><code>:IBM860</code></td><td><code>(:CODE-PAGE :ID 860… | |
421 <tr><td><code>:IBM861</code></td><td><code>(:CODE-PAGE :ID 861… | |
422 <tr><td><code>:IBM862</code></td><td><code>(:CODE-PAGE :ID 862… | |
423 <tr><td><code>:IBM863</code></td><td><code>(:CODE-PAGE :ID 863… | |
424 <tr><td><code>:IBM864</code></td><td><code>(:CODE-PAGE :ID 864… | |
425 <tr><td><code>:IBM865</code></td><td><code>(:CODE-PAGE :ID 865… | |
426 <tr><td><code>:IBM866</code></td><td><code>(:CODE-PAGE :ID 866… | |
427 <tr><td><code>:IBM869</code></td><td><code>(:CODE-PAGE :ID 869… | |
428 <tr><td><code>:WINDOWS-1250</code></td><td><code>(:CODE-PAGE :ID&nb… | |
429 <tr><td><code>:WINDOWS-1251</code></td><td><code>(:CODE-PAGE :ID&nb… | |
430 <tr><td><code>:WINDOWS-1252</code></td><td><code>(:CODE-PAGE :ID&nb… | |
431 <tr><td><code>:WINDOWS-1253</code></td><td><code>(:CODE-PAGE :ID&nb… | |
432 <tr><td><code>:WINDOWS-1254</code></td><td><code>(:CODE-PAGE :ID&nb… | |
433 <tr><td><code>:WINDOWS-1255</code></td><td><code>(:CODE-PAGE :ID&nb… | |
434 <tr><td><code>:WINDOWS-1256</code></td><td><code>(:CODE-PAGE :ID&nb… | |
435 <tr><td><code>:WINDOWS-1257</code></td><td><code>(:CODE-PAGE :ID&nb… | |
436 <tr><td><code>:WINDOWS-1258</code></td><td><code>(:CODE-PAGE :ID&nb… | |
437 </table> | |
438 <p> | |
439 Note that if you provide a shortcut, it | |
440 will be converted to an <code>EXTERNAL-FORMAT</code> object first. | |
441 So, if you're concerned about efficiency, create these objects once and | |
442 re-use them. | |
443 | |
444 <p><br>[Function] | |
445 <br><a class=none name="make-external-format"><b>make-external-format</b… | |
446 | |
447 <blockquote><br> Creates and returns | |
448 an <a href="#external-formats"><code>EXTERNAL-FORMAT</code> | |
449 object</a>. <code><i>name</i></code> is a | |
450 symbol, <code><i>eol-style</i></code> is one of the | |
451 keywords <code>:CR</code>, <code>:LF</code>, or <code>:CRLF</code>, | |
452 and <code><i>little-endian</i></code> is | |
453 a <a | |
454 href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_g.htm… | |
455 boolean</a>. The default value for <code><i>eol-style</i></code> is the… | |
456 for <code><i>little-endian</i></code> is the value of <a href="#*default… | |
457 <code><i>id</i></code> must be an integer denoting a Windows code page | |
458 known by FLEXI-STREAMS if <code><i>name</i></code> | |
459 is <code>:CODE-PAGE</code> or <code>WIN32:CODE-PAGE</code>, otherwise | |
460 the value is ignored. See <a href="#external-formats">the section | |
461 about external formats</a> for more info. | |
462 <p> | |
463 Examples (run on Windows): | |
464 | |
465 <pre> | |
466 CL-USER 1 > (make-external-format :latin-1) | |
467 #<FLEXI-STREAMS::EXTERNAL-FORMAT (:ISO-8859-1 :EOL-STYLE :CRLF) 2067D… | |
468 | |
469 CL-USER 2 > (make-external-format :latin-1 :eol-style :lf) | |
470 #<FLEXI-STREAMS::EXTERNAL-FORMAT (:ISO-8859-1 :EOL-STYLE :LF) 2068B4D… | |
471 | |
472 CL-USER 3 > (make-external-format :ibm437) | |
473 #<FLEXI-STREAMS::EXTERNAL-FORMAT (:CODE-PAGE :ID 437 :EOL-STYLE :CRLF… | |
474 | |
475 CL-USER 4 > (make-external-format :ucs-2) | |
476 #<FLEXI-STREAMS::EXTERNAL-FORMAT (:UTF-16 :EOL-STYLE :CRLF :LITTLE-EN… | |
477 | |
478 CL-USER 5 > (make-external-format :ucs-2be) | |
479 #<FLEXI-STREAMS::EXTERNAL-FORMAT (:UTF-16 :EOL-STYLE :CRLF :LITTLE-EN… | |
480 | |
481 CL-USER 6 > (make-external-format :ucs-2be :eol-style :cr) | |
482 #<FLEXI-STREAMS::EXTERNAL-FORMAT (:UTF-16 :EOL-STYLE :CR :LITTLE-ENDI… | |
483 </pre> | |
484 </blockquote> | |
485 | |
486 <p><br>[Readers] | |
487 <br><a class=none name="external-format-name"><b>external-format-name</b… | |
488 <br><a class=none name="external-format-eol-style"><b>external-format-eo… | |
489 <br><a class=none name="external-format-little-endian"><b>external-forma… | |
490 <br><a class=none name="external-format-id"><b>external-format-id</b> <i… | |
491 | |
492 <blockquote><br> | |
493 These methods can be used to query an <a href="#external-formats"><code>… | |
494 </blockquote> | |
495 | |
496 <p><br>[Functions] | |
497 <br><a class=none name="external-format-equal"><b>external-format-equal<… | |
498 | |
499 <blockquote><br> | |
500 Checks whether the two <a href="#external-formats">external formats</a> … | |
501 <p> | |
502 Examples (run on Windows): | |
503 | |
504 <pre> | |
505 CL-USER 1 > (<a href="#make-external-format" class=noborder>make-exte… | |
506 #<FLEXI-STREAMS::EXTERNAL-FORMAT (:UTF-32 :EOL-STYLE :CRLF :LITTLE-EN… | |
507 | |
508 CL-USER 2 > (external-format-equal <a href="http://www.lispworks.com/… | |
509 T | |
510 | |
511 CL-USER 3 > (make-external-format :code-page :id 437) | |
512 #<FLEXI-STREAMS::EXTERNAL-FORMAT (:CODE-PAGE :ID 437 :EOL-STYLE :CRLF… | |
513 | |
514 CL-USER 4 > (external-format-equal * (make-external-format :ibm437)) | |
515 T | |
516 </pre> | |
517 | |
518 </blockquote> | |
519 | |
520 <p><br>[Special variable] | |
521 <br><a class=none name="*default-eol-style*"><b>*default-eol-style*</b><… | |
522 | |
523 <blockquote><br> | |
524 The default value for the <code><i>eol-style</i></code> keyword argument… | |
525 </blockquote> | |
526 | |
527 <p><br>[Special variable] | |
528 <br><a class=none name="*default-little-endian*"><b>*default-little-endi… | |
529 | |
530 <blockquote><br> | |
531 The default value for the <code><i>little-endian</i></code> keyword argu… | |
532 </blockquote> | |
533 | |
534 <p><br>[Condition] | |
535 <br><a class=none name="external-format-condition"><b>external-format-co… | |
536 | |
537 <blockquote><br> | |
538 All conditions related to <a href="#external-formats">external formats</… | |
539 There's a slot for the external format which can be accessed with <a hre… | |
540 </blockquote> | |
541 | |
542 <p><br>[Reader] | |
543 <br><a class=none name="external-format-condition-external-format"><b>ex… | |
544 | |
545 <blockquote><br> If <code><i>condition</i></code> is of | |
546 type <a href="#external-format-condition"><code>EXTERNAL-FORMAT-CONDITIO… | |
547 this function will return the associated external format. Note that | |
548 there are situation which happen during the creation of external | |
549 formats where this method returns <code>NIL</code>. | |
550 </blockquote> | |
551 | |
552 <p><br>[Condition] | |
553 <br><a class=none name="external-format-error"><b>external-format-error<… | |
554 | |
555 <blockquote><br> | |
556 All errors related to <a href="#external-formats">external formats</a> a… | |
557 This is a subtype of <a href="#external-format-condition"><code>EXTERNAL… | |
558 </blockquote> | |
559 | |
560 <p><br>[Condition] | |
561 <br><a class=none name="external-format-encoding-error"><b>external-form… | |
562 | |
563 <blockquote><br> | |
564 All errors related to encoding problems with <a href="#external-formats"… | |
565 restart</a> is provided. See also <a href="#*substitution-char*"><code>*… | |
566 </blockquote> | |
567 | |
568 <p><br>[Special variable] | |
569 <br><a class=none name="*substitution-char*"><b>*substitution-char*</b><… | |
570 | |
571 <blockquote><br> | |
572 If this value is not NIL, it should be a character which is used | |
573 (as if by a <a href="http://www.lispworks.com/documentation/HyperSpec/Bo… | |
574 type <a href="#external-format-encoding-error"><code>EXTERNAL-FORMAT-ENC… | |
575 | |
576 <pre> | |
577 CL-USER 1 > (defun foo () | |
578 <font color=orange>;; not a valid UTF-8 sequence</font> | |
579 (<a href="#with-input-from-sequence" class=noborder>with-i… | |
580 (setq in (<a href="#make-flexi-stream" class=noborder>ma… | |
581 (read-line in))) | |
582 FOO | |
583 | |
584 CL-USER 2 > (foo) | |
585 | |
586 Error: Unexpected value #xF6 in UTF-8 sequence. | |
587 1 (continue) Specify a character to be used instead. | |
588 2 (abort) Return to level 0. | |
589 3 Return to top loop level 0. | |
590 | |
591 Type :b for backtrace, :c <option number> to proceed, or :? for o… | |
592 | |
593 CL-USER 3 : 1 > :c | |
594 Type a character: x | |
595 | |
596 Error: End of file while in UTF-8 sequence. | |
597 1 (continue) Specify a character to be used instead. | |
598 2 (abort) Return to level 0. | |
599 3 Return to top loop level 0. | |
600 | |
601 Type :b for backtrace, :c <option number> to proceed, or :? for o… | |
602 | |
603 CL-USER 4 : 1 > :c | |
604 Type a character: y | |
605 "xy" | |
606 T | |
607 | |
608 CL-USER 5 > (<a href="http://www.lispworks.com/documentation/HyperSpe… | |
609 (<a href="http… | |
610 (foo)) | |
611 "--" | |
612 T | |
613 | |
614 CL-USER 6 > (let ((<a href="#*SUBSTITUTION-CHAR*" class=noborder>*sub… | |
615 (foo)) | |
616 "??" | |
617 T | |
618 </pre> | |
619 </blockquote> | |
620 | |
621 <p><br>[Restart] | |
622 <br><a class=none name="accept-overlong-sequence"><b>accept-overlong-seq… | |
623 | |
624 <blockquote><br> This is | |
625 a <a href="http://www.lispworks.com/documentation/HyperSpec/Body/09_adb.… | |
626 which is established whenever a UTF-8 "overlong" sequence is | |
627 encountered. If | |
628 you <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_inv… | |
629 this restart, the corresponding code point will be accepted although | |
630 it was encoded in an illegal way. | |
631 </blockquote> | |
632 | |
633 <h4><a name="flexi-streams" class=none>Flexi streams</a></h4> | |
634 | |
635 <em>Flexi streams</em> are the core of the FLEXI-STREAMS library. You | |
636 create them using the | |
637 function <a | |
638 href="#make-flexi-stream"><code>MAKE-FLEXI-STREAM</code></a> which | |
639 takes an open binary stream (called the <em>underlying</em> stream) as i… | |
640 A <em>binary</em> stream in this context means that if it's an <a href="… | |
641 stream</a>, you can read from it with | |
642 <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_rd_by.h… | |
643 (or, as a workaround for LispWorks, you can at least apply | |
644 <a | |
645 href="http://www.lispworks.com/documentation/HyperSpec/Body/f_rd_seq.htm… | |
646 to it where the sequence is an array of element | |
647 type <a href="#octet"><code>OCTET</code></a>), and similarly for | |
648 <a | |
649 href="http://www.lispworks.com/documentation/HyperSpec/Body/f_wr_by.htm#… | |
650 (<a | |
651 href="http://www.lispworks.com/documentation/HyperSpec/Body/f_wr_seq.htm… | |
652 for LispWorks) | |
653 and <a | |
654 href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_o.htm… | |
655 streams</a>. (Note that this specifically holds | |
656 for <a | |
657 href="http://www.lispworks.com/documentation/lw50/LWRM/html/lwref-91.htm… | |
658 streams</a> like socket streams.) | |
659 <p> | |
660 A flexi stream behaves like an ordinary Lisp stream. It is an input | |
661 stream if the underlying binary stream is an input stream, and it is | |
662 an output stream when the underlying binary stream is an output | |
663 stream. You can write characters as well | |
664 as <a href="#octet">octets</a> to an output flexi stream and similarly | |
665 you can read characters and octets from an input flexi stream. | |
666 <p> | |
667 A flexi stream always has an <a href="#external-formats">external | |
668 format</a> associated with it which is deployed whenever you read | |
669 characters from the stream or write characters to it. You | |
670 can <a href="#flexi-stream-external-format">change</a> the external | |
671 format while you use the stream. | |
672 <p> | |
673 Once you're using a flexi stream you should <em>not</em> read from or | |
674 write to the underlying stream directly anymore. | |
675 <p> | |
676 If | |
677 you <a | |
678 href="http://www.lispworks.com/documentation/HyperSpec/Body/f_close.htm"… | |
679 a flexi stream, the underlying stream will also be closed. However, it | |
680 also suffices to close the underlying stream directly should you not | |
681 want to use the flexi stream anymore. So, the following usage | |
682 (where <code>IN</code> is implicitly closed at the end) is OK: | |
683 <pre> | |
684 (with-open-file (in "/foo/bar/baz.txt") | |
685 (let ((flexi (<a href="#make-flexi-stream" class=noborder>make-flexi-s… | |
686 (read-line flexi))) | |
687 </pre> | |
688 <p> | |
689 Output flexi streams will try to keep track of | |
690 the <a | |
691 href="http://www.lispworks.com/documentation/lw50/LWRM/html/lwref-591.ht… | |
692 they're in but you can also <a href="#flexi-stream-column">set</a> the | |
693 column directly. This value will be incremented by one for each | |
694 character written to the stream and it will be set to <code>0</code> | |
695 if you send a <code>#\Newline</code> character. The column will be | |
696 set to <code>NIL</code> if an <a href="#octet"><code>OCTET</code></a> | |
697 is sent to the stream. Once the column is <code>NIL</code> it'll stay | |
698 like that unless it is explicitly set to another value. | |
699 <p> | |
700 Input flexi streams keep track of | |
701 their <a href="#flexi-stream-position">position</a> within the stream. | |
702 This value is incremented by one for | |
703 each <a href="#octet"><code>OCTET</code></a> read from the stream, and | |
704 it is incremented by the number of octets actually read for each | |
705 character read from the stream. So, if the encoding is UTF-8, reading | |
706 the character <code>#\ä</code> (a-umlaut) will advance the position… | |
707 If the encoding is UTF-32 and the end-of-line style | |
708 is <code>:CRLF</code>, reading a <code>#\Newline</code> will advance | |
709 the position by eight. | |
710 <p> | |
711 You can also set the <a href="#flexi-stream-bound">bound</a> of an | |
712 input flexi stream. Initially it is <code>NIL</code>, but when it's | |
713 an integer and the | |
714 stream's <a href="#flexi-stream-position">position</a> has gone beyond | |
715 this bound, the stream will behave as if no more input is available. | |
716 <p> | |
717 Caveat: You can | |
718 only <a | |
719 href="http://www.lispworks.com/documentation/HyperSpec/Body/f_unrd_c.htm… | |
720 a character from a flexi stream if you haven't changed the external form… | |
721 <p> | |
722 Caveat: The <em>underlying</em> stream should either be a <a href="http:… | |
723 | |
724 <p><br>[Standard class] | |
725 <br><a class=none name="flexi-stream"><b>flexi-stream</b></a> | |
726 | |
727 <blockquote><br> | |
728 Every <a href="#flexi-streams"><em>flexi stream</em></a> returned by <a … | |
729 </blockquote> | |
730 | |
731 <p><br>[Standard class] | |
732 <br><a class=none name="flexi-input-stream"><b>flexi-input-stream</b></a> | |
733 | |
734 <blockquote><br> | |
735 A <a href="#flexi-streams"><em>flexi stream</em></a> is of this type if … | |
736 </blockquote> | |
737 | |
738 <p><br>[Standard class] | |
739 <br><a class=none name="flexi-output-stream"><b>flexi-output-stream</b><… | |
740 | |
741 <blockquote><br> | |
742 A <a href="#flexi-streams"><em>flexi stream</em></a> is of this type if … | |
743 </blockquote> | |
744 | |
745 <p><br>[Standard class] | |
746 <br><a class=none name="flexi-io-stream"><b>flexi-io-stream</b></a> | |
747 | |
748 <blockquote><br> | |
749 A <a href="#flexi-streams"><em>flexi stream</em></a> is of this type if … | |
750 </blockquote> | |
751 | |
752 <p><br>[Function] | |
753 <br><a class=none name="make-flexi-stream"><b>make-flexi-stream</b> <i>s… | |
754 | |
755 <blockquote><br> | |
756 Creates and returns a <a href="#flexi-streams"><em>flexi stream</em></a>… | |
757 </blockquote> | |
758 | |
759 <p><br>[Accessors] | |
760 <br><a class=none name="flexi-stream-external-format"><b>flexi-stream-ex… | |
761 <br><tt>(setf (</tt><b>flexi-stream-external-format</b> <i>flexi-stream<… | |
762 <br><a class=none name="flexi-stream-element-type"><b>flexi-stream-eleme… | |
763 <br><tt>(setf (</tt><b>flexi-stream-element-type</b> <i>flexi-stream</i>… | |
764 <br><a class=none name="flexi-stream-column"><b>flexi-stream-column</b> … | |
765 <br><tt>(setf (</tt><b>flexi-stream-column</b> <i>flexi-output-stream</i… | |
766 <br><a class=none name="flexi-stream-position"><b>flexi-stream-position<… | |
767 <br><tt>(setf (</tt><b>flexi-stream-position</b> <i>flexi-input-stream</… | |
768 <br><a class=none name="flexi-stream-bound"><b>flexi-stream-bound</b> <i… | |
769 <br><tt>(setf (</tt><b>flexi-stream-bound</b> <i>flexi-input-stream</i>)… | |
770 | |
771 <blockquote><br> | |
772 These methods can be used to get and set the corresponding attributes of… | |
773 <p> | |
774 <a href="#flexi-stream-external-format"><code>(SETF | |
775 FLEXI-STREAM-EXTERNAL-FORMAT)</code></a> accepts keyword symbols | |
776 (<a href="#external-formats">names of external formats</a>), lists | |
777 (which should be valid lists of parameters | |
778 to <a | |
779 href="#make-external-format"><code>MAKE-EXTERNAL-FORMAT</code></a>), or … | |
780 <pre> | |
781 CL-USER 1 > (setf (flexi-stream-external-format *my-stream*) :ucs-4le) | |
782 #<FLEXI-STREAMS::EXTERNAL-FORMAT (:UTF-32 :EOL-STYLE :CRLF :LITTLE-EN… | |
783 | |
784 CL-USER 2 > (setf (flexi-stream-external-format *my-stream*) '(:ucs-2… | |
785 #<FLEXI-STREAMS::EXTERNAL-FORMAT (:UTF-16 :EOL-STYLE :BR :LITTLE-ENDI… | |
786 | |
787 CL-USER 3 > (setf (flexi-stream-external-format *my-stream*) (make-ex… | |
788 #<FLEXI-STREAMS::EXTERNAL-FORMAT (:CODE-PAGE :ID 437 :EOL-STYLE :CRLF… | |
789 </pre> | |
790 </blockquote> | |
791 | |
792 <p><br>[Reader] | |
793 <br><a class=none name="flexi-stream-stream"><b>flexi-stream-stream</b> … | |
794 | |
795 <blockquote><br> | |
796 This method returns the underlying stream of a <a href="#flexi-streams">… | |
797 </blockquote> | |
798 | |
799 <p><br>[Generic function] | |
800 <br><a class=none name="unread-byte"><b>unread-byte</b> <i>byte stream</… | |
801 | |
802 <blockquote><br> | |
803 Similar to <a href="http://www.lispworks.com/documentation/HyperSpec/Bod… | |
804 <code><i>stream</i></code> which must be a <a href="#flexi-streams">flex… | |
805 <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_rd_by.h… | |
806 </blockquote> | |
807 | |
808 <p><br>[Generic function] | |
809 <br><a class=none name="peek-byte"><b>peek-byte</b> <i>stream <tt>&o… | |
810 | |
811 <blockquote><br> | |
812 <code>PEEK-BYTE</code> is like <a href="http://www.lispworks.com/documen… | |
813 without actually removing it. If <code><i>peek-type</i></code> is <code… | |
814 returned, if <code><i>peek-type</i></code> is <code>T</code>, the next o… | |
815 returned, if <code><i>peek-type</i></code> is an octet, the next octet w… | |
816 <code><i>peek-type</i></code> is returned. <code><i>eof-error-p</i></co… | |
817 <p> | |
818 Note that the parameters aren't in the same order as with <a href="http:… | |
819 </blockquote> | |
820 | |
821 <p><br>[Type] | |
822 <br><a class=none name="octet"><b>octet</b></a> | |
823 | |
824 <blockquote><br> | |
825 Just a shortcut for <code>(UNSIGNED-BYTE 8)</code>. | |
826 </blockquote> | |
827 | |
828 <p><br>[Condition] | |
829 <br><a class=none name="flexi-stream-error"><b>flexi-stream-error</b></a> | |
830 | |
831 <blockquote><br> | |
832 All errors related to <a href="#flexi-streams">flexi streams</a> are of … | |
833 </blockquote> | |
834 | |
835 <p><br>[Condition] | |
836 <br><a class=none name="flexi-stream-out-of-sync-error"><b>flexi-stream-… | |
837 | |
838 <blockquote><br> This can happen if you're trying to write to | |
839 an <a href="#flexi-io-stream">IO stream</a> which had prior to that | |
840 "looked ahead" while reading and now can't "rewind" to the octet where | |
841 you <em>should</em> be. | |
842 </blockquote> | |
843 | |
844 <p><br>[Condition] | |
845 <br><a class=none name="flexi-stream-element-type-error"><b>flexi-stream… | |
846 | |
847 <blockquote><br> | |
848 All errors related to problems with the element type of <a href="#flexi-… | |
849 </blockquote> | |
850 | |
851 <p><br>[Reader] | |
852 <br><a class=none name="flexi-stream-element-type-error-element-type"><b… | |
853 | |
854 <blockquote><br> | |
855 If <code><i>condition</i></code> is of type <a href="#flexi-stream-eleme… | |
856 </blockquote> | |
857 | |
858 <h4><a name="in-memory" class=none>In-memory streams</a></h4> | |
859 | |
860 The library also provides <em>in-memory</em> binary streams which are mo… | |
861 | |
862 <p><br>[Standard class] | |
863 <br><a class=none name="in-memory-stream"><b>in-memory-stream</b></a> | |
864 | |
865 <blockquote><br> | |
866 Every <a href="#in-memory"><em>in-memory stream</em></a> returned by <a … | |
867 </blockquote> | |
868 | |
869 <p><br>[Standard class] | |
870 <br><a class=none name="in-memory-input-stream"><b>in-memory-input-strea… | |
871 | |
872 <blockquote><br> | |
873 Every <a href="#in-memory"><em>in-memory stream</em></a> returned by <a … | |
874 </blockquote> | |
875 | |
876 <p><br>[Standard class] | |
877 <br><a class=none name="in-memory-output-stream"><b>in-memory-output-str… | |
878 | |
879 <blockquote><br> | |
880 Every <a href="#in-memory"><em>in-memory stream</em></a> returned by <a … | |
881 </blockquote> | |
882 | |
883 <p><br>[Standard class] | |
884 <br><a class=none name="list-stream"><b>list-stream</b></a> | |
885 | |
886 <blockquote><br> | |
887 Every <a href="#in-memory"><em>in-memory input stream</em></a> is of thi… | |
888 </blockquote> | |
889 | |
890 <p><br>[Standard class] | |
891 <br><a class=none name="vector-stream"><b>vector-stream</b></a> | |
892 | |
893 <blockquote><br> | |
894 Every <a href="#in-memory"><em>in-memory stream</em></a> is of this type… | |
895 </blockquote> | |
896 | |
897 <p><br>[Generic function] | |
898 <br><a class=none name="make-in-memory-input-stream"><b>make-in-memory-i… | |
899 | |
900 <blockquote><br> | |
901 Returns a <a href="http://www.lispworks.com/documentation/HyperSpec/Body… | |
902 octets in the subsequence of <code><i>sequence</i></code> bounded by <co… | |
903 Each octet returned will be transformed in turn by the optional | |
904 <code><i>transformer</i></code> function. | |
905 </blockquote> | |
906 | |
907 <p><br>[Function] | |
908 <br><a class=none name="make-in-memory-output-stream"><b>make-in-memory-… | |
909 | |
910 <blockquote><br> | |
911 Returns a <a href="http://www.lispworks.com/documentation/HyperSpec/Body… | |
912 available a sequence (see <a href="#get-output-stream-sequence"><code>GE… | |
913 output. The octets stored will each be transformed by the optional <cod… | |
914 </blockquote> | |
915 | |
916 <p><br>[Generic function] | |
917 <br><a class=none name="get-output-stream-sequence"><b>get-output-stream… | |
918 | |
919 <blockquote><br> | |
920 Returns a vector containing, in order, all the octets that have | |
921 been output to the <a href="#in-memory">in-memory output stream</a> <cod… | |
922 octets on <code><i>stream</i></code>, so the vector contains only those … | |
923 been output since the last call to <a href="#get-output-stream-sequence"… | |
924 the creation of the stream, whichever occurred most recently. If | |
925 <code><i>as-list</i></code> is true the return value is coerced to a lis… | |
926 </blockquote> | |
927 | |
928 <p><br>[Generic function] | |
929 <br><a class=none name="output-stream-sequence-length"><b>output-stream-… | |
930 | |
931 <blockquote><br> Returns the current length of the underlying vector | |
932 of the <a href="#in-memory">in-memory output | |
933 stream</a> <code><i>stream</i></code>, i.e. this is the length of the | |
934 sequence that <a href="#get-output-stream-sequence"><code>GET-OUTPUT-STR… | |
935 this very moment. | |
936 </blockquote> | |
937 | |
938 <p><br>[Macro] | |
939 <br><a class=none name="with-input-from-sequence"><b>with-input-from-seq… | |
940 | |
941 <blockquote><br> Creates an <a href="#in-memory">in-memory input | |
942 stream</a> from the sequence <code><i>sequence</i></code> using the | |
943 parameters <code><i>start</i></code> and <code><i>end</i></code> | |
944 (see <a | |
945 href="#make-in-memory-input-stream"><code>MAKE-IN-MEMORY-INPUT-STREAM</c… | |
946 binds <code><i>var</i></code> to this stream and then executes | |
947 the <code><i>statement*</i></code> forms. A | |
948 function <code><i>transformer</i></code> may optionally be specified | |
949 to transform the returned octets. The stream is automatically closed | |
950 on exit from | |
951 <a href="#with-output-to-sequence"><code>WITH-OUTPUT-TO-SEQUENCE</code><… | |
952 abnormal. The return value of this macro is the return value of | |
953 the last statement of <code><i>statement*</i></code>. | |
954 </blockquote> | |
955 | |
956 <p><br>[Macro] | |
957 <br><a class=none name="with-output-to-sequence"><b>with-output-to-seque… | |
958 | |
959 <blockquote><br> | |
960 Creates an <a href="#in-memory">in-memory output stream</a>, binds <code… | |
961 then executes the <code><i>statement*</i></code> forms. The stream stor… | |
962 data of type <code><i>element-type</i></code> (a subtype of <a href="#oc… | |
963 function <code><i>transformer</i></code> prior to storage. The stream is… | |
964 exit from <a href="#with-output-to-sequence"><code>WITH-OUTPUT-TO-SEQUEN… | |
965 normal or abnormal. The return value of this macro is a vector (or a | |
966 list if <code><i>as-list</i></code> is true) containing the octets that … | |
967 stream within the body of the macro. | |
968 </blockquote> | |
969 | |
970 <p><br>[Condition] | |
971 <br><a class=none name="in-memory-stream-error"><b>in-memory-stream-erro… | |
972 | |
973 <blockquote><br> | |
974 All errors related to <a href="#in-memory">in-memory streams</a> are of … | |
975 </blockquote> | |
976 | |
977 <p><br>[Condition] | |
978 <br><a class=none name="in-memory-stream-closed-error"><b>in-memory-stre… | |
979 | |
980 <blockquote><br> | |
981 An error of this type is signalled if one tries to read from or write to… | |
982 </blockquote> | |
983 | |
984 <p><br>[Condition] | |
985 <br><a class=none name="in-memory-stream-position-spec-error"><b>in-memo… | |
986 | |
987 <blockquote><br> Errors of this type are signalled if an erroneous | |
988 position spec is used in conjunction | |
989 with <a href="#position"><code>FILE-POSITION</code></a>. This is a | |
990 subtype | |
991 of <a href="#in-memory-stream-error"><code>IN-MEMORY-STREAM-ERROR</code>… | |
992 and has an additional slot for the position spec which can be accessed | |
993 with <a href="#in-memory-stream-position-spec-error-position-spec"><code… | |
994 </blockquote> | |
995 | |
996 <p><br>[Reader] | |
997 <br><a class=none name="in-memory-stream-position-spec-error-position-sp… | |
998 | |
999 <blockquote><br> | |
1000 If <code><i>condition</i></code> is of type <a href="#in-memory-stream-p… | |
1001 </blockquote> | |
1002 | |
1003 <h4><a name="strings" class=none>Strings</a></h4> | |
1004 | |
1005 This section collects a few convenience functions for strings conversion… | |
1006 | |
1007 <p><br>[Function] | |
1008 <br><a class=none name="string-to-octets"><b>string-to-octets</b> <i>str… | |
1009 | |
1010 <blockquote><br> | |
1011 | |
1012 Converts the Lisp string <code><i>string</i></code> from <code><i>start<… | |
1013 <a href="#octet">octets</a> corresponding to the <a href="#external-form… | |
1014 format</a> designated by <code><i>external-format</i></code>. The defaul… | |
1015 <code><i>start</i></code> and <code><i>end</i></code> | |
1016 are <code>0</code> and the length of the string. The default | |
1017 for <code><i>external-format</i></code> is <code>:LATIN1</code>. | |
1018 <p> | |
1019 In spite of the name, <code><i>string</i></code> can be any sequence of … | |
1020 the function is optimized for strings. | |
1021 </blockquote> | |
1022 | |
1023 <p><br>[Function] | |
1024 <br><a class=none name="octets-to-string"><b>octets-to-string</b> <i>seq… | |
1025 | |
1026 <blockquote><br> Converts the Lisp | |
1027 sequence <code><i>sequence</i></code> of <a href="#octet">octets</a> | |
1028 from <code><i>start</i></code> to <code><i>end</i></code> to a string | |
1029 using the <a href="#external-formats">external format</a> designated | |
1030 by <code><i>external-format</i></code>. The defaults for | |
1031 <code><i>start</i></code> and <code><i>end</i></code> | |
1032 are <code>0</code> and the length of the sequence. The default | |
1033 for <code><i>external-format</i></code> is <code>:LATIN1</code>. | |
1034 <p> | |
1035 This function is optimized for the case | |
1036 of <code><i>sequence</i></code> being | |
1037 a <a href="http://www.lispworks.com/documentation/HyperSpec/Body/t_vecto… | |
1038 Don't use lists if you are in hurry. | |
1039 </blockquote> | |
1040 | |
1041 <p><br>[Function] | |
1042 <br><a class=none name="octet-length"><b>octet-length</b> <i>string <tt>… | |
1043 | |
1044 <blockquote><br> | |
1045 | |
1046 Returns the length of the subsequence of <code><i>string</i></code> from… | |
1047 <a href="#octet">octets</a> if encoded using | |
1048 the <a href="#external-formats">external format</a> designated | |
1049 by <code><i>external-format</i></code>. | |
1050 The defaults for | |
1051 <code><i>start</i></code> and <code><i>end</i></code> | |
1052 are <code>0</code> and the length of <code><i>string</i></code>. The de… | |
1053 for <code><i>external-format</i></code> is <code>:LATIN1</code>. | |
1054 <p> | |
1055 In spite of the name, <code><i>string</i></code> can be any sequence of … | |
1056 the function is optimized for strings. | |
1057 </blockquote> | |
1058 | |
1059 <p><br>[Function] | |
1060 <br><a class=none name="char-length"><b>char-length</b> <i>sequence <tt>… | |
1061 | |
1062 <blockquote><br> | |
1063 | |
1064 Kind of the inverse of <a href="#octet-length"><code>OCTET-LENGTH</code>… | |
1065 Returns the length of the subsequence (of <a href="#octet">octets</a>) o… | |
1066 characters if decoded using | |
1067 the <a href="#external-formats">external format</a> designated | |
1068 by <code><i>external-format</i></code>. | |
1069 The defaults for | |
1070 <code><i>start</i></code> and <code><i>end</i></code> | |
1071 are <code>0</code> and the length of the sequence. The default | |
1072 for <code><i>external-format</i></code> is <code>:LATIN1</code>. Note t… | |
1073 <p> | |
1074 This function is optimized for the case | |
1075 of <code><i>sequence</i></code> being | |
1076 a <a href="http://www.lispworks.com/documentation/HyperSpec/Body/t_vecto… | |
1077 Don't use lists if you are in hurry. | |
1078 </blockquote> | |
1079 | |
1080 <br> <br><h3><a class=none name="position">File positions</a></h3> | |
1081 | |
1082 For <a href="#flexi-streams">flexi streams</a> as well | |
1083 as for <a href="#input-memory">in-memory | |
1084 streams</a>, <a | |
1085 href="http://www.lispworks.com/documentation/HyperSpec/Body/f_file_p.htm… | |
1086 will usually return <code>NIL</code> and do nothing when a second | |
1087 argument is supplied. This is correct | |
1088 w.r.t. the <a | |
1089 href="http://www.lispworks.com/documentation/HyperSpec/">ANSI | |
1090 standard</a>, but not very helpful. However, even | |
1091 with <a | |
1092 href="http://www.nhplace.com/kent/CL/Issues/stream-definition-by-user.ht… | |
1093 streams</a> there is no <em>portable</em> way to implement a better | |
1094 behaviour. | |
1095 <p> | |
1096 For <a href="http://www.lispworks.com/">LispWorks</a> | |
1097 and <a href="http://clisp.sf.net/">CLISP</a>, | |
1098 <a | |
1099 href="http://www.lispworks.com/documentation/HyperSpec/Body/f_file_p.htm… | |
1100 for <a href="#flexi-streams">flexi streams</a> will work as if the | |
1101 function had been applied to the underlying stream, and | |
1102 for <a href="#input-memory">in-memory streams</a> it will try to do | |
1103 something sensible if the underlying data structure is a vector | |
1104 (i.e. <em>not</em> a list). Patches for other Common Lisp | |
1105 implementations should be sent to | |
1106 the <a | |
1107 href="http://common-lisp.net/project/cl-plus-ssl/#trivial-gray-streams">… | |
1108 maintainers. | |
1109 | |
1110 <br> <br><h3><a class=none name="ack">Acknowledgements</a></h3> | |
1111 | |
1112 Thanks to David Lichteblau for numerous portability patches. Thanks | |
1113 to Igor Plekhov for the KOI8-R code. Thanks to Anton Vodonosov for | |
1114 numerous patches and additions. Thanks | |
1115 to <a href="http://netzhansa.blogspot.com/">Hans Hübner</a> for | |
1116 his work on making FLEXI-STREAMS faster. | |
1117 | |
1118 </body> | |
1119 </html> |