Commit | Line | Data |
---|---|---|
07d83abe MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
c62da8f8 LC |
3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2009, |
4 | @c 2010, 2011 Free Software Foundation, Inc. | |
07d83abe MV |
5 | @c See the file guile.texi for copying conditions. |
6 | ||
07d83abe MV |
7 | @node Input and Output |
8 | @section Input and Output | |
9 | ||
10 | @menu | |
11 | * Ports:: The idea of the port abstraction. | |
12 | * Reading:: Procedures for reading from a port. | |
13 | * Writing:: Procedures for writing to a port. | |
14 | * Closing:: Procedures to close a port. | |
15 | * Random Access:: Moving around a random access port. | |
16 | * Line/Delimited:: Read and write lines or delimited text. | |
17 | * Block Reading and Writing:: Reading and writing blocks of text. | |
18 | * Default Ports:: Defaults for input, output and errors. | |
19 | * Port Types:: Types of port and how to make them. | |
b242715b | 20 | * R6RS I/O Ports:: The R6RS port API. |
07d83abe MV |
21 | * I/O Extensions:: Using and extending ports in C. |
22 | @end menu | |
23 | ||
24 | ||
25 | @node Ports | |
26 | @subsection Ports | |
bf5df489 | 27 | @cindex Port |
07d83abe MV |
28 | |
29 | Sequential input/output in Scheme is represented by operations on a | |
30 | @dfn{port}. This chapter explains the operations that Guile provides | |
31 | for working with ports. | |
32 | ||
33 | Ports are created by opening, for instance @code{open-file} for a file | |
34 | (@pxref{File Ports}). Characters can be read from an input port and | |
35 | written to an output port, or both on an input/output port. A port | |
36 | can be closed (@pxref{Closing}) when no longer required, after which | |
37 | any attempt to read or write is an error. | |
38 | ||
39 | The formal definition of a port is very generic: an input port is | |
40 | simply ``an object which can deliver characters on demand,'' and an | |
41 | output port is ``an object which can accept characters.'' Because | |
42 | this definition is so loose, it is easy to write functions that | |
43 | simulate ports in software. @dfn{Soft ports} and @dfn{string ports} | |
44 | are two interesting and powerful examples of this technique. | |
45 | (@pxref{Soft Ports}, and @ref{String Ports}.) | |
46 | ||
47 | Ports are garbage collected in the usual way (@pxref{Memory | |
48 | Management}), and will be closed at that time if not already closed. | |
28cc8dac | 49 | In this case any errors occurring in the close will not be reported. |
07d83abe MV |
50 | Usually a program will want to explicitly close so as to be sure all |
51 | its operations have been successful. Of course if a program has | |
52 | abandoned something due to an error or other condition then closing | |
53 | problems are probably not of interest. | |
54 | ||
55 | It is strongly recommended that file ports be closed explicitly when | |
56 | no longer required. Most systems have limits on how many files can be | |
57 | open, both on a per-process and a system-wide basis. A program that | |
58 | uses many files should take care not to hit those limits. The same | |
59 | applies to similar system resources such as pipes and sockets. | |
60 | ||
61 | Note that automatic garbage collection is triggered only by memory | |
62 | consumption, not by file or other resource usage, so a program cannot | |
63 | rely on that to keep it away from system limits. An explicit call to | |
64 | @code{gc} can of course be relied on to pick up unreferenced ports. | |
65 | If program flow makes it hard to be certain when to close then this | |
66 | may be an acceptable way to control resource usage. | |
67 | ||
40296bab KR |
68 | All file access uses the ``LFS'' large file support functions when |
69 | available, so files bigger than 2 Gbytes (@math{2^31} bytes) can be | |
70 | read and written on a 32-bit system. | |
71 | ||
28cc8dac MG |
72 | Each port has an associated character encoding that controls how bytes |
73 | read from the port are converted to characters and string and controls | |
74 | how characters and strings written to the port are converted to bytes. | |
75 | When ports are created, they inherit their character encoding from the | |
76 | current locale, but, that can be modified after the port is created. | |
77 | ||
912a8702 MG |
78 | Currently, the ports only work with @emph{non-modal} encodings. Most |
79 | encodings are non-modal, meaning that the conversion of bytes to a | |
80 | string doesn't depend on its context: the same byte sequence will always | |
81 | return the same string. A couple of modal encodings are in common use, | |
82 | like ISO-2022-JP and ISO-2022-KR, and they are not yet supported. | |
83 | ||
28cc8dac MG |
84 | Each port also has an associated conversion strategy: what to do when |
85 | a Guile character can't be converted to the port's encoded character | |
86 | representation for output. There are three possible strategies: to | |
87 | raise an error, to replace the character with a hex escape, or to | |
88 | replace the character with a substitute character. | |
89 | ||
07d83abe MV |
90 | @rnindex input-port? |
91 | @deffn {Scheme Procedure} input-port? x | |
92 | @deffnx {C Function} scm_input_port_p (x) | |
93 | Return @code{#t} if @var{x} is an input port, otherwise return | |
94 | @code{#f}. Any object satisfying this predicate also satisfies | |
95 | @code{port?}. | |
96 | @end deffn | |
97 | ||
98 | @rnindex output-port? | |
99 | @deffn {Scheme Procedure} output-port? x | |
100 | @deffnx {C Function} scm_output_port_p (x) | |
101 | Return @code{#t} if @var{x} is an output port, otherwise return | |
102 | @code{#f}. Any object satisfying this predicate also satisfies | |
103 | @code{port?}. | |
104 | @end deffn | |
105 | ||
106 | @deffn {Scheme Procedure} port? x | |
107 | @deffnx {C Function} scm_port_p (x) | |
108 | Return a boolean indicating whether @var{x} is a port. | |
109 | Equivalent to @code{(or (input-port? @var{x}) (output-port? | |
110 | @var{x}))}. | |
111 | @end deffn | |
112 | ||
28cc8dac MG |
113 | @deffn {Scheme Procedure} set-port-encoding! port enc |
114 | @deffnx {C Function} scm_set_port_encoding_x (port, enc) | |
4c7b9975 LC |
115 | Sets the character encoding that will be used to interpret all port I/O. |
116 | @var{enc} is a string containing the name of an encoding. Valid | |
117 | encoding names are those | |
118 | @url{http://www.iana.org/assignments/character-sets, defined by IANA}. | |
28cc8dac | 119 | @end deffn |
d6a6989e LC |
120 | |
121 | @defvr {Scheme Variable} %default-port-encoding | |
72b3aa56 | 122 | A fluid containing @code{#f} or the name of the encoding to |
d6a6989e LC |
123 | be used by default for newly created ports (@pxref{Fluids and Dynamic |
124 | States}). The value @code{#f} is equivalent to @code{"ISO-8859-1"}. | |
28cc8dac MG |
125 | |
126 | New ports are created with the encoding appropriate for the current | |
4c7b9975 LC |
127 | locale if @code{setlocale} has been called or the value specified by |
128 | this fluid otherwise. | |
129 | @end defvr | |
28cc8dac MG |
130 | |
131 | @deffn {Scheme Procedure} port-encoding port | |
132 | @deffnx {C Function} scm_port_encoding | |
211683cc MG |
133 | Returns, as a string, the character encoding that @var{port} uses to interpret |
134 | its input and output. The value @code{#f} is equivalent to @code{"ISO-8859-1"}. | |
28cc8dac MG |
135 | @end deffn |
136 | ||
137 | @deffn {Scheme Procedure} set-port-conversion-strategy! port sym | |
138 | @deffnx {C Function} scm_set_port_conversion_strategy_x (port, sym) | |
139 | Sets the behavior of the interpreter when outputting a character that | |
140 | is not representable in the port's current encoding. @var{sym} can be | |
141 | either @code{'error}, @code{'substitute}, or @code{'escape}. If it is | |
142 | @code{'error}, an error will be thrown when an nonconvertible character | |
143 | is encountered. If it is @code{'substitute}, then nonconvertible | |
144 | characters will be replaced with approximate characters, or with | |
145 | question marks if no approximately correct character is available. If | |
146 | it is @code{'escape}, it will appear as a hex escape when output. | |
147 | ||
148 | If @var{port} is an open port, the conversion error behavior | |
149 | is set for that port. If it is @code{#f}, it is set as the | |
150 | default behavior for any future ports that get created in | |
151 | this thread. | |
152 | @end deffn | |
153 | ||
154 | @deffn {Scheme Procedure} port-conversion-strategy port | |
155 | @deffnx {C Function} scm_port_conversion_strategy (port) | |
156 | Returns the behavior of the port when outputting a character that is | |
157 | not representable in the port's current encoding. It returns the | |
158 | symbol @code{error} if unrepresentable characters should cause | |
159 | exceptions, @code{substitute} if the port should try to replace | |
160 | unrepresentable characters with question marks or approximate | |
161 | characters, or @code{escape} if unrepresentable characters should be | |
162 | converted to string escapes. | |
163 | ||
164 | If @var{port} is @code{#f}, then the current default behavior will be | |
165 | returned. New ports will have this default behavior when they are | |
166 | created. | |
167 | @end deffn | |
168 | ||
169 | ||
07d83abe MV |
170 | |
171 | @node Reading | |
172 | @subsection Reading | |
bf5df489 | 173 | @cindex Reading |
07d83abe MV |
174 | |
175 | [Generic procedures for reading from ports.] | |
176 | ||
1518f649 AW |
177 | These procedures pertain to reading characters and strings from |
178 | ports. To read general S-expressions from ports, @xref{Scheme Read}. | |
179 | ||
07d83abe | 180 | @rnindex eof-object? |
bf5df489 | 181 | @cindex End of file object |
07d83abe MV |
182 | @deffn {Scheme Procedure} eof-object? x |
183 | @deffnx {C Function} scm_eof_object_p (x) | |
184 | Return @code{#t} if @var{x} is an end-of-file object; otherwise | |
185 | return @code{#f}. | |
186 | @end deffn | |
187 | ||
188 | @rnindex char-ready? | |
189 | @deffn {Scheme Procedure} char-ready? [port] | |
190 | @deffnx {C Function} scm_char_ready_p (port) | |
191 | Return @code{#t} if a character is ready on input @var{port} | |
192 | and return @code{#f} otherwise. If @code{char-ready?} returns | |
193 | @code{#t} then the next @code{read-char} operation on | |
194 | @var{port} is guaranteed not to hang. If @var{port} is a file | |
195 | port at end of file then @code{char-ready?} returns @code{#t}. | |
cdf1ad3b MV |
196 | |
197 | @code{char-ready?} exists to make it possible for a | |
07d83abe MV |
198 | program to accept characters from interactive ports without |
199 | getting stuck waiting for input. Any input editors associated | |
200 | with such ports must make sure that characters whose existence | |
201 | has been asserted by @code{char-ready?} cannot be rubbed out. | |
202 | If @code{char-ready?} were to return @code{#f} at end of file, | |
203 | a port at end of file would be indistinguishable from an | |
cdf1ad3b | 204 | interactive port that has no ready characters. |
07d83abe MV |
205 | @end deffn |
206 | ||
207 | @rnindex read-char | |
208 | @deffn {Scheme Procedure} read-char [port] | |
209 | @deffnx {C Function} scm_read_char (port) | |
210 | Return the next character available from @var{port}, updating | |
211 | @var{port} to point to the following character. If no more | |
212 | characters are available, the end-of-file object is returned. | |
c62da8f8 LC |
213 | |
214 | When @var{port}'s data cannot be decoded according to its | |
215 | character encoding, a @code{decoding-error} is raised and | |
216 | @var{port} points past the erroneous byte sequence. | |
07d83abe MV |
217 | @end deffn |
218 | ||
219 | @deftypefn {C Function} size_t scm_c_read (SCM port, void *buffer, size_t size) | |
220 | Read up to @var{size} bytes from @var{port} and store them in | |
221 | @var{buffer}. The return value is the number of bytes actually read, | |
222 | which can be less than @var{size} if end-of-file has been reached. | |
223 | ||
224 | Note that this function does not update @code{port-line} and | |
225 | @code{port-column} below. | |
226 | @end deftypefn | |
227 | ||
228 | @rnindex peek-char | |
229 | @deffn {Scheme Procedure} peek-char [port] | |
230 | @deffnx {C Function} scm_peek_char (port) | |
231 | Return the next character available from @var{port}, | |
232 | @emph{without} updating @var{port} to point to the following | |
233 | character. If no more characters are available, the | |
cdf1ad3b MV |
234 | end-of-file object is returned. |
235 | ||
236 | The value returned by | |
07d83abe MV |
237 | a call to @code{peek-char} is the same as the value that would |
238 | have been returned by a call to @code{read-char} on the same | |
239 | port. The only difference is that the very next call to | |
240 | @code{read-char} or @code{peek-char} on that @var{port} will | |
241 | return the value returned by the preceding call to | |
242 | @code{peek-char}. In particular, a call to @code{peek-char} on | |
243 | an interactive port will hang waiting for input whenever a call | |
cdf1ad3b | 244 | to @code{read-char} would have hung. |
c62da8f8 LC |
245 | |
246 | As for @code{read-char}, a @code{decoding-error} may be raised | |
247 | if such a situation occurs. However, unlike with @code{read-char}, | |
248 | @var{port} still points at the beginning of the erroneous byte | |
249 | sequence when the error is raised. | |
07d83abe MV |
250 | @end deffn |
251 | ||
252 | @deffn {Scheme Procedure} unread-char cobj [port] | |
253 | @deffnx {C Function} scm_unread_char (cobj, port) | |
254 | Place @var{char} in @var{port} so that it will be read by the | |
255 | next read operation. If called multiple times, the unread characters | |
256 | will be read again in last-in first-out order. If @var{port} is | |
257 | not supplied, the current input port is used. | |
258 | @end deffn | |
259 | ||
260 | @deffn {Scheme Procedure} unread-string str port | |
261 | @deffnx {C Function} scm_unread_string (str, port) | |
262 | Place the string @var{str} in @var{port} so that its characters will | |
263 | be read from left-to-right as the next characters from @var{port} | |
264 | during subsequent read operations. If called multiple times, the | |
265 | unread characters will be read again in last-in first-out order. If | |
9782da8a | 266 | @var{port} is not supplied, the @code{current-input-port} is used. |
07d83abe MV |
267 | @end deffn |
268 | ||
269 | @deffn {Scheme Procedure} drain-input port | |
270 | @deffnx {C Function} scm_drain_input (port) | |
271 | This procedure clears a port's input buffers, similar | |
272 | to the way that force-output clears the output buffer. The | |
273 | contents of the buffers are returned as a single string, e.g., | |
274 | ||
275 | @lisp | |
276 | (define p (open-input-file ...)) | |
277 | (drain-input p) => empty string, nothing buffered yet. | |
278 | (unread-char (read-char p) p) | |
279 | (drain-input p) => initial chars from p, up to the buffer size. | |
280 | @end lisp | |
281 | ||
282 | Draining the buffers may be useful for cleanly finishing | |
283 | buffered I/O so that the file descriptor can be used directly | |
284 | for further input. | |
285 | @end deffn | |
286 | ||
287 | @deffn {Scheme Procedure} port-column port | |
288 | @deffnx {Scheme Procedure} port-line port | |
289 | @deffnx {C Function} scm_port_column (port) | |
290 | @deffnx {C Function} scm_port_line (port) | |
291 | Return the current column number or line number of @var{port}. | |
292 | If the number is | |
293 | unknown, the result is #f. Otherwise, the result is a 0-origin integer | |
294 | - i.e.@: the first character of the first line is line 0, column 0. | |
295 | (However, when you display a file position, for example in an error | |
296 | message, we recommend you add 1 to get 1-origin integers. This is | |
297 | because lines and column numbers traditionally start with 1, and that is | |
298 | what non-programmers will find most natural.) | |
299 | @end deffn | |
300 | ||
301 | @deffn {Scheme Procedure} set-port-column! port column | |
302 | @deffnx {Scheme Procedure} set-port-line! port line | |
303 | @deffnx {C Function} scm_set_port_column_x (port, column) | |
304 | @deffnx {C Function} scm_set_port_line_x (port, line) | |
305 | Set the current column or line number of @var{port}. | |
306 | @end deffn | |
307 | ||
308 | @node Writing | |
309 | @subsection Writing | |
bf5df489 | 310 | @cindex Writing |
07d83abe MV |
311 | |
312 | [Generic procedures for writing to ports.] | |
313 | ||
1518f649 AW |
314 | These procedures are for writing characters and strings to |
315 | ports. For more information on writing arbitrary Scheme objects to | |
316 | ports, @xref{Scheme Write}. | |
317 | ||
07d83abe MV |
318 | @deffn {Scheme Procedure} get-print-state port |
319 | @deffnx {C Function} scm_get_print_state (port) | |
320 | Return the print state of the port @var{port}. If @var{port} | |
321 | has no associated print state, @code{#f} is returned. | |
322 | @end deffn | |
323 | ||
07d83abe MV |
324 | @rnindex newline |
325 | @deffn {Scheme Procedure} newline [port] | |
326 | @deffnx {C Function} scm_newline (port) | |
327 | Send a newline to @var{port}. | |
328 | If @var{port} is omitted, send to the current output port. | |
329 | @end deffn | |
330 | ||
cdf1ad3b | 331 | @deffn {Scheme Procedure} port-with-print-state port [pstate] |
07d83abe MV |
332 | @deffnx {C Function} scm_port_with_print_state (port, pstate) |
333 | Create a new port which behaves like @var{port}, but with an | |
cdf1ad3b MV |
334 | included print state @var{pstate}. @var{pstate} is optional. |
335 | If @var{pstate} isn't supplied and @var{port} already has | |
336 | a print state, the old print state is reused. | |
07d83abe MV |
337 | @end deffn |
338 | ||
07d83abe MV |
339 | @deffn {Scheme Procedure} simple-format destination message . args |
340 | @deffnx {C Function} scm_simple_format (destination, message, args) | |
341 | Write @var{message} to @var{destination}, defaulting to | |
342 | the current output port. | |
343 | @var{message} can contain @code{~A} (was @code{%s}) and | |
344 | @code{~S} (was @code{%S}) escapes. When printed, | |
345 | the escapes are replaced with corresponding members of | |
346 | @var{ARGS}: | |
347 | @code{~A} formats using @code{display} and @code{~S} formats | |
348 | using @code{write}. | |
349 | If @var{destination} is @code{#t}, then use the current output | |
350 | port, if @var{destination} is @code{#f}, then return a string | |
351 | containing the formatted text. Does not add a trailing newline. | |
352 | @end deffn | |
353 | ||
354 | @rnindex write-char | |
355 | @deffn {Scheme Procedure} write-char chr [port] | |
356 | @deffnx {C Function} scm_write_char (chr, port) | |
357 | Send character @var{chr} to @var{port}. | |
358 | @end deffn | |
359 | ||
360 | @deftypefn {C Function} void scm_c_write (SCM port, const void *buffer, size_t size) | |
361 | Write @var{size} bytes at @var{buffer} to @var{port}. | |
362 | ||
363 | Note that this function does not update @code{port-line} and | |
364 | @code{port-column} (@pxref{Reading}). | |
365 | @end deftypefn | |
366 | ||
367 | @findex fflush | |
368 | @deffn {Scheme Procedure} force-output [port] | |
369 | @deffnx {C Function} scm_force_output (port) | |
370 | Flush the specified output port, or the current output port if @var{port} | |
371 | is omitted. The current output buffer contents are passed to the | |
372 | underlying port implementation (e.g., in the case of fports, the | |
373 | data will be written to the file and the output buffer will be cleared.) | |
374 | It has no effect on an unbuffered port. | |
375 | ||
376 | The return value is unspecified. | |
377 | @end deffn | |
378 | ||
379 | @deffn {Scheme Procedure} flush-all-ports | |
380 | @deffnx {C Function} scm_flush_all_ports () | |
381 | Equivalent to calling @code{force-output} on | |
382 | all open output ports. The return value is unspecified. | |
383 | @end deffn | |
384 | ||
385 | ||
386 | @node Closing | |
387 | @subsection Closing | |
bf5df489 KR |
388 | @cindex Closing ports |
389 | @cindex Port, close | |
07d83abe MV |
390 | |
391 | @deffn {Scheme Procedure} close-port port | |
392 | @deffnx {C Function} scm_close_port (port) | |
393 | Close the specified port object. Return @code{#t} if it | |
394 | successfully closes a port or @code{#f} if it was already | |
395 | closed. An exception may be raised if an error occurs, for | |
396 | example when flushing buffered output. See also @ref{Ports and | |
397 | File Descriptors, close}, for a procedure which can close file | |
398 | descriptors. | |
399 | @end deffn | |
400 | ||
401 | @deffn {Scheme Procedure} close-input-port port | |
402 | @deffnx {Scheme Procedure} close-output-port port | |
403 | @deffnx {C Function} scm_close_input_port (port) | |
404 | @deffnx {C Function} scm_close_output_port (port) | |
405 | @rnindex close-input-port | |
406 | @rnindex close-output-port | |
407 | Close the specified input or output @var{port}. An exception may be | |
408 | raised if an error occurs while closing. If @var{port} is already | |
409 | closed, nothing is done. The return value is unspecified. | |
410 | ||
411 | See also @ref{Ports and File Descriptors, close}, for a procedure | |
412 | which can close file descriptors. | |
413 | @end deffn | |
414 | ||
415 | @deffn {Scheme Procedure} port-closed? port | |
416 | @deffnx {C Function} scm_port_closed_p (port) | |
417 | Return @code{#t} if @var{port} is closed or @code{#f} if it is | |
418 | open. | |
419 | @end deffn | |
420 | ||
421 | ||
422 | @node Random Access | |
423 | @subsection Random Access | |
bf5df489 KR |
424 | @cindex Random access, ports |
425 | @cindex Port, random access | |
07d83abe MV |
426 | |
427 | @deffn {Scheme Procedure} seek fd_port offset whence | |
428 | @deffnx {C Function} scm_seek (fd_port, offset, whence) | |
429 | Sets the current position of @var{fd/port} to the integer | |
430 | @var{offset}, which is interpreted according to the value of | |
431 | @var{whence}. | |
432 | ||
433 | One of the following variables should be supplied for | |
434 | @var{whence}: | |
435 | @defvar SEEK_SET | |
436 | Seek from the beginning of the file. | |
437 | @end defvar | |
438 | @defvar SEEK_CUR | |
439 | Seek from the current position. | |
440 | @end defvar | |
441 | @defvar SEEK_END | |
442 | Seek from the end of the file. | |
443 | @end defvar | |
444 | If @var{fd/port} is a file descriptor, the underlying system | |
445 | call is @code{lseek}. @var{port} may be a string port. | |
446 | ||
447 | The value returned is the new position in the file. This means | |
448 | that the current position of a port can be obtained using: | |
449 | @lisp | |
450 | (seek port 0 SEEK_CUR) | |
451 | @end lisp | |
452 | @end deffn | |
453 | ||
454 | @deffn {Scheme Procedure} ftell fd_port | |
455 | @deffnx {C Function} scm_ftell (fd_port) | |
456 | Return an integer representing the current position of | |
457 | @var{fd/port}, measured from the beginning. Equivalent to: | |
458 | ||
459 | @lisp | |
460 | (seek port 0 SEEK_CUR) | |
461 | @end lisp | |
462 | @end deffn | |
463 | ||
464 | @findex truncate | |
465 | @findex ftruncate | |
40296bab KR |
466 | @deffn {Scheme Procedure} truncate-file file [length] |
467 | @deffnx {C Function} scm_truncate_file (file, length) | |
468 | Truncate @var{file} to @var{length} bytes. @var{file} can be a | |
469 | filename string, a port object, or an integer file descriptor. The | |
470 | return value is unspecified. | |
471 | ||
472 | For a port or file descriptor @var{length} can be omitted, in which | |
473 | case the file is truncated at the current position (per @code{ftell} | |
474 | above). | |
475 | ||
476 | On most systems a file can be extended by giving a length greater than | |
477 | the current size, but this is not mandatory in the POSIX standard. | |
07d83abe MV |
478 | @end deffn |
479 | ||
480 | @node Line/Delimited | |
481 | @subsection Line Oriented and Delimited Text | |
bf5df489 KR |
482 | @cindex Line input/output |
483 | @cindex Port, line input/output | |
07d83abe MV |
484 | |
485 | The delimited-I/O module can be accessed with: | |
486 | ||
aba0dff5 | 487 | @lisp |
07d83abe | 488 | (use-modules (ice-9 rdelim)) |
aba0dff5 | 489 | @end lisp |
07d83abe MV |
490 | |
491 | It can be used to read or write lines of text, or read text delimited by | |
492 | a specified set of characters. It's similar to the @code{(scsh rdelim)} | |
493 | module from guile-scsh, but does not use multiple values or character | |
494 | sets and has an extra procedure @code{write-line}. | |
495 | ||
496 | @c begin (scm-doc-string "rdelim.scm" "read-line") | |
497 | @deffn {Scheme Procedure} read-line [port] [handle-delim] | |
498 | Return a line of text from @var{port} if specified, otherwise from the | |
499 | value returned by @code{(current-input-port)}. Under Unix, a line of text | |
500 | is terminated by the first end-of-line character or by end-of-file. | |
501 | ||
502 | If @var{handle-delim} is specified, it should be one of the following | |
503 | symbols: | |
504 | @table @code | |
505 | @item trim | |
506 | Discard the terminating delimiter. This is the default, but it will | |
507 | be impossible to tell whether the read terminated with a delimiter or | |
508 | end-of-file. | |
509 | @item concat | |
510 | Append the terminating delimiter (if any) to the returned string. | |
511 | @item peek | |
512 | Push the terminating delimiter (if any) back on to the port. | |
513 | @item split | |
514 | Return a pair containing the string read from the port and the | |
515 | terminating delimiter or end-of-file object. | |
516 | @end table | |
c62da8f8 LC |
517 | |
518 | Like @code{read-char}, this procedure can throw to @code{decoding-error} | |
519 | (@pxref{Reading, @code{read-char}}). | |
07d83abe MV |
520 | @end deffn |
521 | ||
522 | @c begin (scm-doc-string "rdelim.scm" "read-line!") | |
523 | @deffn {Scheme Procedure} read-line! buf [port] | |
524 | Read a line of text into the supplied string @var{buf} and return the | |
525 | number of characters added to @var{buf}. If @var{buf} is filled, then | |
526 | @code{#f} is returned. | |
527 | Read from @var{port} if | |
528 | specified, otherwise from the value returned by @code{(current-input-port)}. | |
529 | @end deffn | |
530 | ||
531 | @c begin (scm-doc-string "rdelim.scm" "read-delimited") | |
532 | @deffn {Scheme Procedure} read-delimited delims [port] [handle-delim] | |
533 | Read text until one of the characters in the string @var{delims} is found | |
534 | or end-of-file is reached. Read from @var{port} if supplied, otherwise | |
535 | from the value returned by @code{(current-input-port)}. | |
536 | @var{handle-delim} takes the same values as described for @code{read-line}. | |
537 | @end deffn | |
538 | ||
539 | @c begin (scm-doc-string "rdelim.scm" "read-delimited!") | |
540 | @deffn {Scheme Procedure} read-delimited! delims buf [port] [handle-delim] [start] [end] | |
e7fb779f AW |
541 | Read text into the supplied string @var{buf}. |
542 | ||
543 | If a delimiter was found, return the number of characters written, | |
544 | except if @var{handle-delim} is @code{split}, in which case the return | |
545 | value is a pair, as noted above. | |
546 | ||
547 | As a special case, if @var{port} was already at end-of-stream, the EOF | |
548 | object is returned. Also, if no characters were written because the | |
549 | buffer was full, @code{#f} is returned. | |
550 | ||
551 | It's something of a wacky interface, to be honest. | |
07d83abe MV |
552 | @end deffn |
553 | ||
554 | @deffn {Scheme Procedure} write-line obj [port] | |
555 | @deffnx {C Function} scm_write_line (obj, port) | |
556 | Display @var{obj} and a newline character to @var{port}. If | |
557 | @var{port} is not specified, @code{(current-output-port)} is | |
558 | used. This function is equivalent to: | |
559 | @lisp | |
560 | (display obj [port]) | |
561 | (newline [port]) | |
562 | @end lisp | |
563 | @end deffn | |
564 | ||
28cc8dac | 565 | Some of the aforementioned I/O functions rely on the following C |
07d83abe MV |
566 | primitives. These will mainly be of interest to people hacking Guile |
567 | internals. | |
568 | ||
569 | @deffn {Scheme Procedure} %read-delimited! delims str gobble [port [start [end]]] | |
570 | @deffnx {C Function} scm_read_delimited_x (delims, str, gobble, port, start, end) | |
571 | Read characters from @var{port} into @var{str} until one of the | |
572 | characters in the @var{delims} string is encountered. If | |
573 | @var{gobble} is true, discard the delimiter character; | |
574 | otherwise, leave it in the input stream for the next read. If | |
575 | @var{port} is not specified, use the value of | |
576 | @code{(current-input-port)}. If @var{start} or @var{end} are | |
577 | specified, store data only into the substring of @var{str} | |
578 | bounded by @var{start} and @var{end} (which default to the | |
579 | beginning and end of the string, respectively). | |
580 | ||
581 | Return a pair consisting of the delimiter that terminated the | |
582 | string and the number of characters read. If reading stopped | |
583 | at the end of file, the delimiter returned is the | |
584 | @var{eof-object}; if the string was filled without encountering | |
585 | a delimiter, this value is @code{#f}. | |
586 | @end deffn | |
587 | ||
588 | @deffn {Scheme Procedure} %read-line [port] | |
589 | @deffnx {C Function} scm_read_line (port) | |
590 | Read a newline-terminated line from @var{port}, allocating storage as | |
591 | necessary. The newline terminator (if any) is removed from the string, | |
592 | and a pair consisting of the line and its delimiter is returned. The | |
593 | delimiter may be either a newline or the @var{eof-object}; if | |
594 | @code{%read-line} is called at the end of file, it returns the pair | |
595 | @code{(#<eof> . #<eof>)}. | |
596 | @end deffn | |
597 | ||
598 | @node Block Reading and Writing | |
599 | @subsection Block reading and writing | |
bf5df489 KR |
600 | @cindex Block read/write |
601 | @cindex Port, block read/write | |
07d83abe MV |
602 | |
603 | The Block-string-I/O module can be accessed with: | |
604 | ||
aba0dff5 | 605 | @lisp |
07d83abe | 606 | (use-modules (ice-9 rw)) |
aba0dff5 | 607 | @end lisp |
07d83abe MV |
608 | |
609 | It currently contains procedures that help to implement the | |
610 | @code{(scsh rw)} module in guile-scsh. | |
611 | ||
612 | @deffn {Scheme Procedure} read-string!/partial str [port_or_fdes [start [end]]] | |
613 | @deffnx {C Function} scm_read_string_x_partial (str, port_or_fdes, start, end) | |
614 | Read characters from a port or file descriptor into a | |
615 | string @var{str}. A port must have an underlying file | |
616 | descriptor --- a so-called fport. This procedure is | |
617 | scsh-compatible and can efficiently read large strings. | |
618 | It will: | |
619 | ||
620 | @itemize | |
621 | @item | |
622 | attempt to fill the entire string, unless the @var{start} | |
623 | and/or @var{end} arguments are supplied. i.e., @var{start} | |
624 | defaults to 0 and @var{end} defaults to | |
625 | @code{(string-length str)} | |
626 | @item | |
627 | use the current input port if @var{port_or_fdes} is not | |
628 | supplied. | |
629 | @item | |
630 | return fewer than the requested number of characters in some | |
631 | cases, e.g., on end of file, if interrupted by a signal, or if | |
632 | not all the characters are immediately available. | |
633 | @item | |
634 | wait indefinitely for some input if no characters are | |
635 | currently available, | |
636 | unless the port is in non-blocking mode. | |
637 | @item | |
638 | read characters from the port's input buffers if available, | |
639 | instead from the underlying file descriptor. | |
640 | @item | |
641 | return @code{#f} if end-of-file is encountered before reading | |
642 | any characters, otherwise return the number of characters | |
643 | read. | |
644 | @item | |
645 | return 0 if the port is in non-blocking mode and no characters | |
646 | are immediately available. | |
647 | @item | |
648 | return 0 if the request is for 0 bytes, with no | |
649 | end-of-file check. | |
650 | @end itemize | |
651 | @end deffn | |
652 | ||
653 | @deffn {Scheme Procedure} write-string/partial str [port_or_fdes [start [end]]] | |
654 | @deffnx {C Function} scm_write_string_partial (str, port_or_fdes, start, end) | |
655 | Write characters from a string @var{str} to a port or file | |
656 | descriptor. A port must have an underlying file descriptor | |
657 | --- a so-called fport. This procedure is | |
658 | scsh-compatible and can efficiently write large strings. | |
659 | It will: | |
660 | ||
661 | @itemize | |
662 | @item | |
663 | attempt to write the entire string, unless the @var{start} | |
664 | and/or @var{end} arguments are supplied. i.e., @var{start} | |
665 | defaults to 0 and @var{end} defaults to | |
666 | @code{(string-length str)} | |
667 | @item | |
668 | use the current output port if @var{port_of_fdes} is not | |
669 | supplied. | |
670 | @item | |
671 | in the case of a buffered port, store the characters in the | |
672 | port's output buffer, if all will fit. If they will not fit | |
673 | then any existing buffered characters will be flushed | |
674 | before attempting | |
675 | to write the new characters directly to the underlying file | |
676 | descriptor. If the port is in non-blocking mode and | |
677 | buffered characters can not be flushed immediately, then an | |
678 | @code{EAGAIN} system-error exception will be raised (Note: | |
679 | scsh does not support the use of non-blocking buffered ports.) | |
680 | @item | |
681 | write fewer than the requested number of | |
682 | characters in some cases, e.g., if interrupted by a signal or | |
683 | if not all of the output can be accepted immediately. | |
684 | @item | |
685 | wait indefinitely for at least one character | |
686 | from @var{str} to be accepted by the port, unless the port is | |
687 | in non-blocking mode. | |
688 | @item | |
689 | return the number of characters accepted by the port. | |
690 | @item | |
691 | return 0 if the port is in non-blocking mode and can not accept | |
692 | at least one character from @var{str} immediately | |
693 | @item | |
694 | return 0 immediately if the request size is 0 bytes. | |
695 | @end itemize | |
696 | @end deffn | |
697 | ||
698 | @node Default Ports | |
699 | @subsection Default Ports for Input, Output and Errors | |
bf5df489 KR |
700 | @cindex Default ports |
701 | @cindex Port, default | |
07d83abe MV |
702 | |
703 | @rnindex current-input-port | |
704 | @deffn {Scheme Procedure} current-input-port | |
705 | @deffnx {C Function} scm_current_input_port () | |
34846414 | 706 | @cindex standard input |
07d83abe | 707 | Return the current input port. This is the default port used |
3fa0a042 KR |
708 | by many input procedures. |
709 | ||
710 | Initially this is the @dfn{standard input} in Unix and C terminology. | |
711 | When the standard input is a tty the port is unbuffered, otherwise | |
712 | it's fully buffered. | |
713 | ||
714 | Unbuffered input is good if an application runs an interactive | |
715 | subprocess, since any type-ahead input won't go into Guile's buffer | |
9782da8a | 716 | and be unavailable to the subprocess. |
3fa0a042 KR |
717 | |
718 | Note that Guile buffering is completely separate from the tty ``line | |
9782da8a KR |
719 | discipline''. In the usual cooked mode on a tty Guile only sees a |
720 | line of input once the user presses @key{Return}. | |
07d83abe MV |
721 | @end deffn |
722 | ||
723 | @rnindex current-output-port | |
724 | @deffn {Scheme Procedure} current-output-port | |
725 | @deffnx {C Function} scm_current_output_port () | |
34846414 | 726 | @cindex standard output |
07d83abe | 727 | Return the current output port. This is the default port used |
3fa0a042 KR |
728 | by many output procedures. |
729 | ||
730 | Initially this is the @dfn{standard output} in Unix and C terminology. | |
731 | When the standard output is a tty this port is unbuffered, otherwise | |
732 | it's fully buffered. | |
733 | ||
734 | Unbuffered output to a tty is good for ensuring progress output or a | |
735 | prompt is seen. But an application which always prints whole lines | |
736 | could change to line buffered, or an application with a lot of output | |
737 | could go fully buffered and perhaps make explicit @code{force-output} | |
738 | calls (@pxref{Writing}) at selected points. | |
07d83abe MV |
739 | @end deffn |
740 | ||
741 | @deffn {Scheme Procedure} current-error-port | |
742 | @deffnx {C Function} scm_current_error_port () | |
34846414 | 743 | @cindex standard error output |
3fa0a042 KR |
744 | Return the port to which errors and warnings should be sent. |
745 | ||
746 | Initially this is the @dfn{standard error} in Unix and C terminology. | |
747 | When the standard error is a tty this port is unbuffered, otherwise | |
748 | it's fully buffered. | |
07d83abe MV |
749 | @end deffn |
750 | ||
751 | @deffn {Scheme Procedure} set-current-input-port port | |
752 | @deffnx {Scheme Procedure} set-current-output-port port | |
753 | @deffnx {Scheme Procedure} set-current-error-port port | |
754 | @deffnx {C Function} scm_set_current_input_port (port) | |
755 | @deffnx {C Function} scm_set_current_output_port (port) | |
756 | @deffnx {C Function} scm_set_current_error_port (port) | |
757 | Change the ports returned by @code{current-input-port}, | |
758 | @code{current-output-port} and @code{current-error-port}, respectively, | |
759 | so that they use the supplied @var{port} for input or output. | |
760 | @end deffn | |
761 | ||
661ae7ab MV |
762 | @deftypefn {C Function} void scm_dynwind_current_input_port (SCM port) |
763 | @deftypefnx {C Function} void scm_dynwind_current_output_port (SCM port) | |
764 | @deftypefnx {C Function} void scm_dynwind_current_error_port (SCM port) | |
07d83abe | 765 | These functions must be used inside a pair of calls to |
661ae7ab MV |
766 | @code{scm_dynwind_begin} and @code{scm_dynwind_end} (@pxref{Dynamic |
767 | Wind}). During the dynwind context, the indicated port is set to | |
07d83abe MV |
768 | @var{port}. |
769 | ||
770 | More precisely, the current port is swapped with a `backup' value | |
661ae7ab | 771 | whenever the dynwind context is entered or left. The backup value is |
07d83abe MV |
772 | initialized with the @var{port} argument. |
773 | @end deftypefn | |
774 | ||
775 | @node Port Types | |
776 | @subsection Types of Port | |
bf5df489 KR |
777 | @cindex Types of ports |
778 | @cindex Port, types | |
07d83abe MV |
779 | |
780 | [Types of port; how to make them.] | |
781 | ||
782 | @menu | |
783 | * File Ports:: Ports on an operating system file. | |
784 | * String Ports:: Ports on a Scheme string. | |
785 | * Soft Ports:: Ports on arbitrary Scheme procedures. | |
786 | * Void Ports:: Ports on nothing at all. | |
787 | @end menu | |
788 | ||
789 | ||
790 | @node File Ports | |
791 | @subsubsection File Ports | |
bf5df489 KR |
792 | @cindex File port |
793 | @cindex Port, file | |
07d83abe MV |
794 | |
795 | The following procedures are used to open file ports. | |
796 | See also @ref{Ports and File Descriptors, open}, for an interface | |
797 | to the Unix @code{open} system call. | |
798 | ||
799 | Most systems have limits on how many files can be open, so it's | |
800 | strongly recommended that file ports be closed explicitly when no | |
801 | longer required (@pxref{Ports}). | |
802 | ||
803 | @deffn {Scheme Procedure} open-file filename mode | |
804 | @deffnx {C Function} scm_open_file (filename, mode) | |
805 | Open the file whose name is @var{filename}, and return a port | |
806 | representing that file. The attributes of the port are | |
807 | determined by the @var{mode} string. The way in which this is | |
808 | interpreted is similar to C stdio. The first character must be | |
809 | one of the following: | |
c755b861 | 810 | |
07d83abe MV |
811 | @table @samp |
812 | @item r | |
813 | Open an existing file for input. | |
814 | @item w | |
815 | Open a file for output, creating it if it doesn't already exist | |
816 | or removing its contents if it does. | |
817 | @item a | |
818 | Open a file for output, creating it if it doesn't already | |
819 | exist. All writes to the port will go to the end of the file. | |
820 | The "append mode" can be turned off while the port is in use | |
821 | @pxref{Ports and File Descriptors, fcntl} | |
822 | @end table | |
c755b861 | 823 | |
07d83abe | 824 | The following additional characters can be appended: |
c755b861 | 825 | |
07d83abe MV |
826 | @table @samp |
827 | @item + | |
828 | Open the port for both input and output. E.g., @code{r+}: open | |
829 | an existing file for both input and output. | |
830 | @item 0 | |
831 | Create an "unbuffered" port. In this case input and output | |
832 | operations are passed directly to the underlying port | |
833 | implementation without additional buffering. This is likely to | |
834 | slow down I/O operations. The buffering mode can be changed | |
835 | while a port is in use @pxref{Ports and File Descriptors, | |
836 | setvbuf} | |
837 | @item l | |
838 | Add line-buffering to the port. The port output buffer will be | |
839 | automatically flushed whenever a newline character is written. | |
c755b861 | 840 | @item b |
5261e742 AW |
841 | Use binary mode, ensuring that each byte in the file will be read as one |
842 | Scheme character. | |
843 | ||
844 | To provide this property, the file will be opened with the 8-bit | |
845 | character encoding "ISO-8859-1", ignoring any coding declaration or port | |
846 | encoding. @xref{Ports}, for more information on port encodings. | |
847 | ||
848 | Note that while it is possible to read and write binary data as | |
849 | characters or strings, it is usually better to treat bytes as octets, | |
850 | and byte sequences as bytevectors. @xref{R6RS Binary Input}, and | |
851 | @ref{R6RS Binary Output}, for more. | |
852 | ||
853 | This option had another historical meaning, for DOS compatibility: in | |
854 | the default (textual) mode, DOS reads a CR-LF sequence as one LF byte. | |
855 | The @code{b} flag prevents this from happening, adding @code{O_BINARY} | |
856 | to the underlying @code{open} call. Still, the flag is generally useful | |
857 | because of its port encoding ramifications. | |
07d83abe | 858 | @end table |
c755b861 | 859 | |
092bdcc4 KR |
860 | If a file cannot be opened with the access |
861 | requested, @code{open-file} throws an exception. | |
862 | ||
211683cc | 863 | When the file is opened, this procedure will scan for a coding |
5261e742 AW |
864 | declaration (@pxref{Character Encoding of Source Files}). If a coding |
865 | declaration is found, it will be used to interpret the file. Otherwise, | |
866 | the port's encoding will be used. To suppress this behavior, open the | |
867 | file in binary mode and then set the port encoding explicitly using | |
868 | @code{set-port-encoding!}. | |
211683cc | 869 | |
07d83abe MV |
870 | In theory we could create read/write ports which were buffered |
871 | in one direction only. However this isn't included in the | |
092bdcc4 | 872 | current interfaces. |
07d83abe MV |
873 | @end deffn |
874 | ||
875 | @rnindex open-input-file | |
876 | @deffn {Scheme Procedure} open-input-file filename | |
877 | Open @var{filename} for input. Equivalent to | |
aba0dff5 | 878 | @lisp |
07d83abe | 879 | (open-file @var{filename} "r") |
aba0dff5 | 880 | @end lisp |
07d83abe MV |
881 | @end deffn |
882 | ||
883 | @rnindex open-output-file | |
884 | @deffn {Scheme Procedure} open-output-file filename | |
885 | Open @var{filename} for output. Equivalent to | |
aba0dff5 | 886 | @lisp |
07d83abe | 887 | (open-file @var{filename} "w") |
aba0dff5 | 888 | @end lisp |
07d83abe MV |
889 | @end deffn |
890 | ||
891 | @deffn {Scheme Procedure} call-with-input-file filename proc | |
892 | @deffnx {Scheme Procedure} call-with-output-file filename proc | |
893 | @rnindex call-with-input-file | |
894 | @rnindex call-with-output-file | |
895 | Open @var{filename} for input or output, and call @code{(@var{proc} | |
896 | port)} with the resulting port. Return the value returned by | |
897 | @var{proc}. @var{filename} is opened as per @code{open-input-file} or | |
28cc8dac | 898 | @code{open-output-file} respectively, and an error is signaled if it |
07d83abe MV |
899 | cannot be opened. |
900 | ||
901 | When @var{proc} returns, the port is closed. If @var{proc} does not | |
28cc8dac | 902 | return (e.g.@: if it throws an error), then the port might not be |
07d83abe MV |
903 | closed automatically, though it will be garbage collected in the usual |
904 | way if not otherwise referenced. | |
905 | @end deffn | |
906 | ||
907 | @deffn {Scheme Procedure} with-input-from-file filename thunk | |
908 | @deffnx {Scheme Procedure} with-output-to-file filename thunk | |
909 | @deffnx {Scheme Procedure} with-error-to-file filename thunk | |
910 | @rnindex with-input-from-file | |
911 | @rnindex with-output-to-file | |
912 | Open @var{filename} and call @code{(@var{thunk})} with the new port | |
913 | setup as respectively the @code{current-input-port}, | |
914 | @code{current-output-port}, or @code{current-error-port}. Return the | |
915 | value returned by @var{thunk}. @var{filename} is opened as per | |
916 | @code{open-input-file} or @code{open-output-file} respectively, and an | |
28cc8dac | 917 | error is signaled if it cannot be opened. |
07d83abe MV |
918 | |
919 | When @var{thunk} returns, the port is closed and the previous setting | |
920 | of the respective current port is restored. | |
921 | ||
922 | The current port setting is managed with @code{dynamic-wind}, so the | |
923 | previous value is restored no matter how @var{thunk} exits (eg.@: an | |
924 | exception), and if @var{thunk} is re-entered (via a captured | |
925 | continuation) then it's set again to the @var{FILENAME} port. | |
926 | ||
927 | The port is closed when @var{thunk} returns normally, but not when | |
928 | exited via an exception or new continuation. This ensures it's still | |
929 | ready for use if @var{thunk} is re-entered by a captured continuation. | |
930 | Of course the port is always garbage collected and closed in the usual | |
931 | way when no longer referenced anywhere. | |
932 | @end deffn | |
933 | ||
934 | @deffn {Scheme Procedure} port-mode port | |
935 | @deffnx {C Function} scm_port_mode (port) | |
936 | Return the port modes associated with the open port @var{port}. | |
937 | These will not necessarily be identical to the modes used when | |
938 | the port was opened, since modes such as "append" which are | |
939 | used only during port creation are not retained. | |
940 | @end deffn | |
941 | ||
942 | @deffn {Scheme Procedure} port-filename port | |
943 | @deffnx {C Function} scm_port_filename (port) | |
ac012a27 AW |
944 | Return the filename associated with @var{port}, or @code{#f} if no |
945 | filename is associated with the port. | |
e55abf41 KR |
946 | |
947 | @var{port} must be open, @code{port-filename} cannot be used once the | |
948 | port is closed. | |
07d83abe MV |
949 | @end deffn |
950 | ||
951 | @deffn {Scheme Procedure} set-port-filename! port filename | |
952 | @deffnx {C Function} scm_set_port_filename_x (port, filename) | |
953 | Change the filename associated with @var{port}, using the current input | |
954 | port if none is specified. Note that this does not change the port's | |
955 | source of data, but only the value that is returned by | |
956 | @code{port-filename} and reported in diagnostic output. | |
957 | @end deffn | |
958 | ||
959 | @deffn {Scheme Procedure} file-port? obj | |
960 | @deffnx {C Function} scm_file_port_p (obj) | |
961 | Determine whether @var{obj} is a port that is related to a file. | |
962 | @end deffn | |
963 | ||
964 | ||
965 | @node String Ports | |
966 | @subsubsection String Ports | |
bf5df489 KR |
967 | @cindex String port |
968 | @cindex Port, string | |
07d83abe | 969 | |
ecb87335 | 970 | The following allow string ports to be opened by analogy to R4RS |
07d83abe MV |
971 | file port facilities: |
972 | ||
28cc8dac MG |
973 | With string ports, the port-encoding is treated differently than other |
974 | types of ports. When string ports are created, they do not inherit a | |
975 | character encoding from the current locale. They are given a | |
976 | default locale that allows them to handle all valid string characters. | |
977 | Typically one should not modify a string port's character encoding | |
978 | away from its default. | |
979 | ||
07d83abe MV |
980 | @deffn {Scheme Procedure} call-with-output-string proc |
981 | @deffnx {C Function} scm_call_with_output_string (proc) | |
982 | Calls the one-argument procedure @var{proc} with a newly created output | |
983 | port. When the function returns, the string composed of the characters | |
984 | written into the port is returned. @var{proc} should not close the port. | |
7b041912 LC |
985 | |
986 | Note that which characters can be written to a string port depend on the port's | |
987 | encoding. The default encoding of string ports is specified by the | |
988 | @code{%default-port-encoding} fluid (@pxref{Ports, | |
989 | @code{%default-port-encoding}}). For instance, it is an error to write Greek | |
990 | letter alpha to an ISO-8859-1-encoded string port since this character cannot be | |
991 | represented with ISO-8859-1: | |
992 | ||
993 | @example | |
994 | (define alpha (integer->char #x03b1)) ; GREEK SMALL LETTER ALPHA | |
995 | ||
996 | (with-fluids ((%default-port-encoding "ISO-8859-1")) | |
997 | (call-with-output-string | |
998 | (lambda (p) | |
999 | (display alpha p)))) | |
1000 | ||
1001 | @result{} | |
1002 | Throw to key `encoding-error' | |
1003 | @end example | |
1004 | ||
1005 | Changing the string port's encoding to a Unicode-capable encoding such as UTF-8 | |
1006 | solves the problem. | |
07d83abe MV |
1007 | @end deffn |
1008 | ||
1009 | @deffn {Scheme Procedure} call-with-input-string string proc | |
1010 | @deffnx {C Function} scm_call_with_input_string (string, proc) | |
1011 | Calls the one-argument procedure @var{proc} with a newly | |
1012 | created input port from which @var{string}'s contents may be | |
1013 | read. The value yielded by the @var{proc} is returned. | |
1014 | @end deffn | |
1015 | ||
1016 | @deffn {Scheme Procedure} with-output-to-string thunk | |
1017 | Calls the zero-argument procedure @var{thunk} with the current output | |
1018 | port set temporarily to a new string port. It returns a string | |
1019 | composed of the characters written to the current output. | |
7b041912 LC |
1020 | |
1021 | See @code{call-with-output-string} above for character encoding considerations. | |
07d83abe MV |
1022 | @end deffn |
1023 | ||
1024 | @deffn {Scheme Procedure} with-input-from-string string thunk | |
1025 | Calls the zero-argument procedure @var{thunk} with the current input | |
1026 | port set temporarily to a string port opened on the specified | |
1027 | @var{string}. The value yielded by @var{thunk} is returned. | |
1028 | @end deffn | |
1029 | ||
1030 | @deffn {Scheme Procedure} open-input-string str | |
1031 | @deffnx {C Function} scm_open_input_string (str) | |
1032 | Take a string and return an input port that delivers characters | |
1033 | from the string. The port can be closed by | |
1034 | @code{close-input-port}, though its storage will be reclaimed | |
1035 | by the garbage collector if it becomes inaccessible. | |
1036 | @end deffn | |
1037 | ||
1038 | @deffn {Scheme Procedure} open-output-string | |
1039 | @deffnx {C Function} scm_open_output_string () | |
1040 | Return an output port that will accumulate characters for | |
1041 | retrieval by @code{get-output-string}. The port can be closed | |
1042 | by the procedure @code{close-output-port}, though its storage | |
1043 | will be reclaimed by the garbage collector if it becomes | |
1044 | inaccessible. | |
1045 | @end deffn | |
1046 | ||
1047 | @deffn {Scheme Procedure} get-output-string port | |
1048 | @deffnx {C Function} scm_get_output_string (port) | |
1049 | Given an output port created by @code{open-output-string}, | |
1050 | return a string consisting of the characters that have been | |
1051 | output to the port so far. | |
1052 | ||
1053 | @code{get-output-string} must be used before closing @var{port}, once | |
1054 | closed the string cannot be obtained. | |
1055 | @end deffn | |
1056 | ||
1057 | A string port can be used in many procedures which accept a port | |
1058 | but which are not dependent on implementation details of fports. | |
1059 | E.g., seeking and truncating will work on a string port, | |
1060 | but trying to extract the file descriptor number will fail. | |
1061 | ||
1062 | ||
1063 | @node Soft Ports | |
1064 | @subsubsection Soft Ports | |
bf5df489 KR |
1065 | @cindex Soft port |
1066 | @cindex Port, soft | |
07d83abe MV |
1067 | |
1068 | A @dfn{soft-port} is a port based on a vector of procedures capable of | |
1069 | accepting or delivering characters. It allows emulation of I/O ports. | |
1070 | ||
1071 | @deffn {Scheme Procedure} make-soft-port pv modes | |
1072 | @deffnx {C Function} scm_make_soft_port (pv, modes) | |
1073 | Return a port capable of receiving or delivering characters as | |
1074 | specified by the @var{modes} string (@pxref{File Ports, | |
1075 | open-file}). @var{pv} must be a vector of length 5 or 6. Its | |
1076 | components are as follows: | |
1077 | ||
1078 | @enumerate 0 | |
1079 | @item | |
1080 | procedure accepting one character for output | |
1081 | @item | |
1082 | procedure accepting a string for output | |
1083 | @item | |
1084 | thunk for flushing output | |
1085 | @item | |
1086 | thunk for getting one character | |
1087 | @item | |
1088 | thunk for closing port (not by garbage collection) | |
1089 | @item | |
1090 | (if present and not @code{#f}) thunk for computing the number of | |
1091 | characters that can be read from the port without blocking. | |
1092 | @end enumerate | |
1093 | ||
1094 | For an output-only port only elements 0, 1, 2, and 4 need be | |
1095 | procedures. For an input-only port only elements 3 and 4 need | |
1096 | be procedures. Thunks 2 and 4 can instead be @code{#f} if | |
1097 | there is no useful operation for them to perform. | |
1098 | ||
1099 | If thunk 3 returns @code{#f} or an @code{eof-object} | |
1100 | (@pxref{Input, eof-object?, ,r5rs, The Revised^5 Report on | |
1101 | Scheme}) it indicates that the port has reached end-of-file. | |
1102 | For example: | |
1103 | ||
1104 | @lisp | |
1105 | (define stdout (current-output-port)) | |
1106 | (define p (make-soft-port | |
1107 | (vector | |
1108 | (lambda (c) (write c stdout)) | |
1109 | (lambda (s) (display s stdout)) | |
1110 | (lambda () (display "." stdout)) | |
1111 | (lambda () (char-upcase (read-char))) | |
1112 | (lambda () (display "@@" stdout))) | |
1113 | "rw")) | |
1114 | ||
1115 | (write p p) @result{} #<input-output: soft 8081e20> | |
1116 | @end lisp | |
1117 | @end deffn | |
1118 | ||
1119 | ||
1120 | @node Void Ports | |
1121 | @subsubsection Void Ports | |
bf5df489 KR |
1122 | @cindex Void port |
1123 | @cindex Port, void | |
07d83abe MV |
1124 | |
1125 | This kind of port causes any data to be discarded when written to, and | |
1126 | always returns the end-of-file object when read from. | |
1127 | ||
1128 | @deffn {Scheme Procedure} %make-void-port mode | |
1129 | @deffnx {C Function} scm_sys_make_void_port (mode) | |
1130 | Create and return a new void port. A void port acts like | |
1131 | @file{/dev/null}. The @var{mode} argument | |
1132 | specifies the input/output modes for this port: see the | |
1133 | documentation for @code{open-file} in @ref{File Ports}. | |
1134 | @end deffn | |
1135 | ||
1136 | ||
b242715b LC |
1137 | @node R6RS I/O Ports |
1138 | @subsection R6RS I/O Ports | |
1139 | ||
1140 | @cindex R6RS | |
1141 | @cindex R6RS ports | |
1142 | ||
1143 | The I/O port API of the @uref{http://www.r6rs.org/, Revised Report^6 on | |
1144 | the Algorithmic Language Scheme (R6RS)} is provided by the @code{(rnrs | |
1145 | io ports)} module. It provides features, such as binary I/O and Unicode | |
1146 | string I/O, that complement or refine Guile's historical port API | |
040dfa6f AR |
1147 | presented above (@pxref{Input and Output}). Note that R6RS ports are not |
1148 | disjoint from Guile's native ports, so Guile-specific procedures will | |
1149 | work on ports created using the R6RS API, and vice versa. | |
1150 | ||
1151 | The text in this section is taken from the R6RS standard libraries | |
1152 | document, with only minor adaptions for inclusion in this manual. The | |
1153 | Guile developers offer their thanks to the R6RS editors for having | |
1154 | provided the report's text under permissive conditions making this | |
1155 | possible. | |
b242715b LC |
1156 | |
1157 | @c FIXME: Update description when implemented. | |
958173e4 | 1158 | @emph{Note}: The implementation of this R6RS API is not complete yet. |
b242715b LC |
1159 | |
1160 | @menu | |
040dfa6f AR |
1161 | * R6RS File Names:: File names. |
1162 | * R6RS File Options:: Options for opening files. | |
1163 | * R6RS Buffer Modes:: Influencing buffering behavior. | |
1164 | * R6RS Transcoders:: Influencing port encoding. | |
b242715b LC |
1165 | * R6RS End-of-File:: The end-of-file object. |
1166 | * R6RS Port Manipulation:: Manipulating R6RS ports. | |
040dfa6f | 1167 | * R6RS Input Ports:: Input Ports. |
b242715b | 1168 | * R6RS Binary Input:: Binary input. |
040dfa6f AR |
1169 | * R6RS Textual Input:: Textual input. |
1170 | * R6RS Output Ports:: Output Ports. | |
b242715b | 1171 | * R6RS Binary Output:: Binary output. |
040dfa6f | 1172 | * R6RS Textual Output:: Textual output. |
b242715b LC |
1173 | @end menu |
1174 | ||
de424d95 LC |
1175 | A subset of the @code{(rnrs io ports)} module is provided by the |
1176 | @code{(ice-9 binary-ports)} module. It contains binary input/output | |
1177 | procedures and does not rely on R6RS support. | |
1178 | ||
040dfa6f AR |
1179 | @node R6RS File Names |
1180 | @subsubsection File Names | |
1181 | ||
1182 | Some of the procedures described in this chapter accept a file name as an | |
1183 | argument. Valid values for such a file name include strings that name a file | |
1184 | using the native notation of filesystem paths on an implementation's | |
1185 | underlying operating system, and may include implementation-dependent | |
1186 | values as well. | |
1187 | ||
1188 | A @var{filename} parameter name means that the | |
1189 | corresponding argument must be a file name. | |
1190 | ||
1191 | @node R6RS File Options | |
1192 | @subsubsection File Options | |
1193 | @cindex file options | |
1194 | ||
1195 | When opening a file, the various procedures in this library accept a | |
1196 | @code{file-options} object that encapsulates flags to specify how the | |
1197 | file is to be opened. A @code{file-options} object is an enum-set | |
1198 | (@pxref{rnrs enums}) over the symbols constituting valid file options. | |
1199 | ||
1200 | A @var{file-options} parameter name means that the corresponding | |
1201 | argument must be a file-options object. | |
1202 | ||
1203 | @deffn {Scheme Syntax} file-options @var{file-options-symbol} ... | |
1204 | ||
1205 | Each @var{file-options-symbol} must be a symbol. | |
1206 | ||
1207 | The @code{file-options} syntax returns a file-options object that | |
1208 | encapsulates the specified options. | |
1209 | ||
1210 | When supplied to an operation that opens a file for output, the | |
1211 | file-options object returned by @code{(file-options)} specifies that the | |
1212 | file is created if it does not exist and an exception with condition | |
1213 | type @code{&i/o-file-already-exists} is raised if it does exist. The | |
1214 | following standard options can be included to modify the default | |
1215 | behavior. | |
1216 | ||
1217 | @table @code | |
1218 | @item no-create | |
1219 | If the file does not already exist, it is not created; | |
1220 | instead, an exception with condition type @code{&i/o-file-does-not-exist} | |
1221 | is raised. | |
1222 | If the file already exists, the exception with condition type | |
1223 | @code{&i/o-file-already-exists} is not raised | |
1224 | and the file is truncated to zero length. | |
1225 | @item no-fail | |
1226 | If the file already exists, the exception with condition type | |
1227 | @code{&i/o-file-already-exists} is not raised, | |
1228 | even if @code{no-create} is not included, | |
1229 | and the file is truncated to zero length. | |
1230 | @item no-truncate | |
1231 | If the file already exists and the exception with condition type | |
1232 | @code{&i/o-file-already-exists} has been inhibited by inclusion of | |
1233 | @code{no-create} or @code{no-fail}, the file is not truncated, but | |
1234 | the port's current position is still set to the beginning of the | |
1235 | file. | |
1236 | @end table | |
1237 | ||
1238 | These options have no effect when a file is opened only for input. | |
1239 | Symbols other than those listed above may be used as | |
1240 | @var{file-options-symbol}s; they have implementation-specific meaning, | |
1241 | if any. | |
1242 | ||
1243 | @quotation Note | |
1244 | Only the name of @var{file-options-symbol} is significant. | |
1245 | @end quotation | |
1246 | @end deffn | |
1247 | ||
1248 | @node R6RS Buffer Modes | |
1249 | @subsubsection Buffer Modes | |
1250 | ||
1251 | Each port has an associated buffer mode. For an output port, the | |
1252 | buffer mode defines when an output operation flushes the buffer | |
1253 | associated with the output port. For an input port, the buffer mode | |
1254 | defines how much data will be read to satisfy read operations. The | |
1255 | possible buffer modes are the symbols @code{none} for no buffering, | |
1256 | @code{line} for flushing upon line endings and reading up to line | |
1257 | endings, or other implementation-dependent behavior, | |
1258 | and @code{block} for arbitrary buffering. This section uses | |
1259 | the parameter name @var{buffer-mode} for arguments that must be | |
1260 | buffer-mode symbols. | |
1261 | ||
1262 | If two ports are connected to the same mutable source, both ports | |
1263 | are unbuffered, and reading a byte or character from that shared | |
1264 | source via one of the two ports would change the bytes or characters | |
1265 | seen via the other port, a lookahead operation on one port will | |
1266 | render the peeked byte or character inaccessible via the other port, | |
1267 | while a subsequent read operation on the peeked port will see the | |
1268 | peeked byte or character even though the port is otherwise unbuffered. | |
1269 | ||
1270 | In other words, the semantics of buffering is defined in terms of side | |
1271 | effects on shared mutable sources, and a lookahead operation has the | |
1272 | same side effect on the shared source as a read operation. | |
1273 | ||
1274 | @deffn {Scheme Syntax} buffer-mode @var{buffer-mode-symbol} | |
1275 | ||
1276 | @var{buffer-mode-symbol} must be a symbol whose name is one of | |
1277 | @code{none}, @code{line}, and @code{block}. The result is the | |
1278 | corresponding symbol, and specifies the associated buffer mode. | |
1279 | ||
1280 | @quotation Note | |
1281 | Only the name of @var{buffer-mode-symbol} is significant. | |
1282 | @end quotation | |
1283 | @end deffn | |
1284 | ||
1285 | @deffn {Scheme Procedure} buffer-mode? obj | |
1286 | Returns @code{#t} if the argument is a valid buffer-mode symbol, and | |
1287 | returns @code{#f} otherwise. | |
1288 | @end deffn | |
1289 | ||
1290 | @node R6RS Transcoders | |
1291 | @subsubsection Transcoders | |
1292 | @cindex codec | |
1293 | @cindex end-of-line style | |
1294 | @cindex transcoder | |
1295 | @cindex binary port | |
1296 | @cindex textual port | |
1297 | ||
1298 | Several different Unicode encoding schemes describe standard ways to | |
1299 | encode characters and strings as byte sequences and to decode those | |
1300 | sequences. Within this document, a @dfn{codec} is an immutable Scheme | |
1301 | object that represents a Unicode or similar encoding scheme. | |
1302 | ||
1303 | An @dfn{end-of-line style} is a symbol that, if it is not @code{none}, | |
1304 | describes how a textual port transcodes representations of line endings. | |
1305 | ||
1306 | A @dfn{transcoder} is an immutable Scheme object that combines a codec | |
1307 | with an end-of-line style and a method for handling decoding errors. | |
1308 | Each transcoder represents some specific bidirectional (but not | |
1309 | necessarily lossless), possibly stateful translation between byte | |
1310 | sequences and Unicode characters and strings. Every transcoder can | |
1311 | operate in the input direction (bytes to characters) or in the output | |
1312 | direction (characters to bytes). A @var{transcoder} parameter name | |
1313 | means that the corresponding argument must be a transcoder. | |
1314 | ||
1315 | A @dfn{binary port} is a port that supports binary I/O, does not have an | |
1316 | associated transcoder and does not support textual I/O. A @dfn{textual | |
1317 | port} is a port that supports textual I/O, and does not support binary | |
1318 | I/O. A textual port may or may not have an associated transcoder. | |
1319 | ||
1320 | @deffn {Scheme Procedure} latin-1-codec | |
1321 | @deffnx {Scheme Procedure} utf-8-codec | |
1322 | @deffnx {Scheme Procedure} utf-16-codec | |
1323 | ||
1324 | These are predefined codecs for the ISO 8859-1, UTF-8, and UTF-16 | |
1325 | encoding schemes. | |
1326 | ||
1327 | A call to any of these procedures returns a value that is equal in the | |
1328 | sense of @code{eqv?} to the result of any other call to the same | |
1329 | procedure. | |
1330 | @end deffn | |
1331 | ||
1332 | @deffn {Scheme Syntax} eol-style @var{eol-style-symbol} | |
1333 | ||
1334 | @var{eol-style-symbol} should be a symbol whose name is one of | |
1335 | @code{lf}, @code{cr}, @code{crlf}, @code{nel}, @code{crnel}, @code{ls}, | |
1336 | and @code{none}. | |
1337 | ||
1338 | The form evaluates to the corresponding symbol. If the name of | |
1339 | @var{eol-style-symbol} is not one of these symbols, the effect and | |
1340 | result are implementation-dependent; in particular, the result may be an | |
1341 | eol-style symbol acceptable as an @var{eol-style} argument to | |
1342 | @code{make-transcoder}. Otherwise, an exception is raised. | |
1343 | ||
1344 | All eol-style symbols except @code{none} describe a specific | |
1345 | line-ending encoding: | |
1346 | ||
1347 | @table @code | |
1348 | @item lf | |
1349 | linefeed | |
1350 | @item cr | |
1351 | carriage return | |
1352 | @item crlf | |
1353 | carriage return, linefeed | |
1354 | @item nel | |
1355 | next line | |
1356 | @item crnel | |
1357 | carriage return, next line | |
1358 | @item ls | |
1359 | line separator | |
1360 | @end table | |
1361 | ||
1362 | For a textual port with a transcoder, and whose transcoder has an | |
1363 | eol-style symbol @code{none}, no conversion occurs. For a textual input | |
1364 | port, any eol-style symbol other than @code{none} means that all of the | |
1365 | above line-ending encodings are recognized and are translated into a | |
1366 | single linefeed. For a textual output port, @code{none} and @code{lf} | |
1367 | are equivalent. Linefeed characters are encoded according to the | |
1368 | specified eol-style symbol, and all other characters that participate in | |
1369 | possible line endings are encoded as is. | |
1370 | ||
1371 | @quotation Note | |
1372 | Only the name of @var{eol-style-symbol} is significant. | |
1373 | @end quotation | |
1374 | @end deffn | |
1375 | ||
1376 | @deffn {Scheme Procedure} native-eol-style | |
1377 | Returns the default end-of-line style of the underlying platform, e.g., | |
1378 | @code{lf} on Unix and @code{crlf} on Windows. | |
1379 | @end deffn | |
1380 | ||
1381 | @deffn {Condition Type} &i/o-decoding | |
1382 | @deffnx {Scheme Procedure} make-i/o-decoding-error port | |
1383 | @deffnx {Scheme Procedure} i/o-decoding-error? obj | |
1384 | ||
1385 | This condition type could be defined by | |
1386 | ||
1387 | @lisp | |
1388 | (define-condition-type &i/o-decoding &i/o-port | |
1389 | make-i/o-decoding-error i/o-decoding-error?) | |
1390 | @end lisp | |
1391 | ||
1392 | An exception with this type is raised when one of the operations for | |
1393 | textual input from a port encounters a sequence of bytes that cannot be | |
1394 | translated into a character or string by the input direction of the | |
1395 | port's transcoder. | |
1396 | ||
1397 | When such an exception is raised, the port's position is past the | |
1398 | invalid encoding. | |
1399 | @end deffn | |
1400 | ||
1401 | @deffn {Condition Type} &i/o-encoding | |
1402 | @deffnx {Scheme Procedure} make-i/o-encoding-error port char | |
1403 | @deffnx {Scheme Procedure} i/o-encoding-error? obj | |
1404 | @deffnx {Scheme Procedure} i/o-encoding-error-char condition | |
1405 | ||
1406 | This condition type could be defined by | |
1407 | ||
1408 | @lisp | |
1409 | (define-condition-type &i/o-encoding &i/o-port | |
1410 | make-i/o-encoding-error i/o-encoding-error? | |
1411 | (char i/o-encoding-error-char)) | |
1412 | @end lisp | |
1413 | ||
1414 | An exception with this type is raised when one of the operations for | |
1415 | textual output to a port encounters a character that cannot be | |
1416 | translated into bytes by the output direction of the port's transcoder. | |
1417 | @var{Char} is the character that could not be encoded. | |
1418 | @end deffn | |
1419 | ||
1420 | @deffn {Scheme Syntax} error-handling-mode @var{error-handling-mode-symbol} | |
1421 | ||
1422 | @var{error-handling-mode-symbol} should be a symbol whose name is one of | |
1423 | @code{ignore}, @code{raise}, and @code{replace}. The form evaluates to | |
1424 | the corresponding symbol. If @var{error-handling-mode-symbol} is not | |
1425 | one of these identifiers, effect and result are | |
1426 | implementation-dependent: The result may be an error-handling-mode | |
1427 | symbol acceptable as a @var{handling-mode} argument to | |
1428 | @code{make-transcoder}. If it is not acceptable as a | |
1429 | @var{handling-mode} argument to @code{make-transcoder}, an exception is | |
1430 | raised. | |
1431 | ||
1432 | @quotation Note | |
1433 | Only the name of @var{error-handling-style-symbol} is significant. | |
1434 | @end quotation | |
1435 | ||
1436 | The error-handling mode of a transcoder specifies the behavior | |
1437 | of textual I/O operations in the presence of encoding or decoding | |
1438 | errors. | |
1439 | ||
1440 | If a textual input operation encounters an invalid or incomplete | |
1441 | character encoding, and the error-handling mode is @code{ignore}, an | |
1442 | appropriate number of bytes of the invalid encoding are ignored and | |
1443 | decoding continues with the following bytes. | |
1444 | ||
1445 | If the error-handling mode is @code{replace}, the replacement | |
1446 | character U+FFFD is injected into the data stream, an appropriate | |
1447 | number of bytes are ignored, and decoding | |
1448 | continues with the following bytes. | |
1449 | ||
1450 | If the error-handling mode is @code{raise}, an exception with condition | |
1451 | type @code{&i/o-decoding} is raised. | |
1452 | ||
1453 | If a textual output operation encounters a character it cannot encode, | |
1454 | and the error-handling mode is @code{ignore}, the character is ignored | |
1455 | and encoding continues with the next character. If the error-handling | |
1456 | mode is @code{replace}, a codec-specific replacement character is | |
1457 | emitted by the transcoder, and encoding continues with the next | |
1458 | character. The replacement character is U+FFFD for transcoders whose | |
1459 | codec is one of the Unicode encodings, but is the @code{?} character | |
1460 | for the Latin-1 encoding. If the error-handling mode is @code{raise}, | |
1461 | an exception with condition type @code{&i/o-encoding} is raised. | |
1462 | @end deffn | |
1463 | ||
1464 | @deffn {Scheme Procedure} make-transcoder codec | |
1465 | @deffnx {Scheme Procedure} make-transcoder codec eol-style | |
1466 | @deffnx {Scheme Procedure} make-transcoder codec eol-style handling-mode | |
1467 | ||
1468 | @var{codec} must be a codec; @var{eol-style}, if present, an eol-style | |
1469 | symbol; and @var{handling-mode}, if present, an error-handling-mode | |
1470 | symbol. | |
1471 | ||
1472 | @var{eol-style} may be omitted, in which case it defaults to the native | |
1473 | end-of-line style of the underlying platform. @var{Handling-mode} may | |
1474 | be omitted, in which case it defaults to @code{replace}. The result is | |
1475 | a transcoder with the behavior specified by its arguments. | |
1476 | @end deffn | |
1477 | ||
1478 | @deffn {Scheme procedure} native-transcoder | |
1479 | Returns an implementation-dependent transcoder that represents a | |
1480 | possibly locale-dependent ``native'' transcoding. | |
1481 | @end deffn | |
1482 | ||
1483 | @deffn {Scheme Procedure} transcoder-codec transcoder | |
1484 | @deffnx {Scheme Procedure} transcoder-eol-style transcoder | |
1485 | @deffnx {Scheme Procedure} transcoder-error-handling-mode transcoder | |
1486 | ||
1487 | These are accessors for transcoder objects; when applied to a | |
1488 | transcoder returned by @code{make-transcoder}, they return the | |
1489 | @var{codec}, @var{eol-style}, and @var{handling-mode} arguments, | |
1490 | respectively. | |
1491 | @end deffn | |
1492 | ||
1493 | @deffn {Scheme Procedure} bytevector->string bytevector transcoder | |
1494 | ||
1495 | Returns the string that results from transcoding the | |
1496 | @var{bytevector} according to the input direction of the transcoder. | |
1497 | @end deffn | |
1498 | ||
1499 | @deffn {Scheme Procedure} string->bytevector string transcoder | |
1500 | ||
1501 | Returns the bytevector that results from transcoding the | |
1502 | @var{string} according to the output direction of the transcoder. | |
1503 | @end deffn | |
1504 | ||
b242715b LC |
1505 | @node R6RS End-of-File |
1506 | @subsubsection The End-of-File Object | |
1507 | ||
1508 | @cindex EOF | |
1509 | @cindex end-of-file | |
1510 | ||
1511 | R5RS' @code{eof-object?} procedure is provided by the @code{(rnrs io | |
1512 | ports)} module: | |
1513 | ||
1514 | @deffn {Scheme Procedure} eof-object? obj | |
1515 | @deffnx {C Function} scm_eof_object_p (obj) | |
1516 | Return true if @var{obj} is the end-of-file (EOF) object. | |
1517 | @end deffn | |
1518 | ||
1519 | In addition, the following procedure is provided: | |
1520 | ||
1521 | @deffn {Scheme Procedure} eof-object | |
1522 | @deffnx {C Function} scm_eof_object () | |
1523 | Return the end-of-file (EOF) object. | |
1524 | ||
1525 | @lisp | |
1526 | (eof-object? (eof-object)) | |
1527 | @result{} #t | |
1528 | @end lisp | |
1529 | @end deffn | |
1530 | ||
1531 | ||
1532 | @node R6RS Port Manipulation | |
1533 | @subsubsection Port Manipulation | |
1534 | ||
1535 | The procedures listed below operate on any kind of R6RS I/O port. | |
1536 | ||
040dfa6f AR |
1537 | @deffn {Scheme Procedure} port? obj |
1538 | Returns @code{#t} if the argument is a port, and returns @code{#f} | |
1539 | otherwise. | |
1540 | @end deffn | |
1541 | ||
1542 | @deffn {Scheme Procedure} port-transcoder port | |
1543 | Returns the transcoder associated with @var{port} if @var{port} is | |
1544 | textual and has an associated transcoder, and returns @code{#f} if | |
1545 | @var{port} is binary or does not have an associated transcoder. | |
1546 | @end deffn | |
1547 | ||
1548 | @deffn {Scheme Procedure} binary-port? port | |
1549 | Return @code{#t} if @var{port} is a @dfn{binary port}, suitable for | |
1550 | binary data input/output. | |
1551 | ||
1552 | Note that internally Guile does not differentiate between binary and | |
1553 | textual ports, unlike the R6RS. Thus, this procedure returns true when | |
1554 | @var{port} does not have an associated encoding---i.e., when | |
1555 | @code{(port-encoding @var{port})} is @code{#f} (@pxref{Ports, | |
1556 | port-encoding}). This is the case for ports returned by R6RS procedures | |
1557 | such as @code{open-bytevector-input-port} and | |
1558 | @code{make-custom-binary-output-port}. | |
1559 | ||
1560 | However, Guile currently does not prevent use of textual I/O procedures | |
1561 | such as @code{display} or @code{read-char} with binary ports. Doing so | |
1562 | ``upgrades'' the port from binary to textual, under the ISO-8859-1 | |
1563 | encoding. Likewise, Guile does not prevent use of | |
1564 | @code{set-port-encoding!} on a binary port, which also turns it into a | |
1565 | ``textual'' port. | |
1566 | @end deffn | |
1567 | ||
1568 | @deffn {Scheme Procedure} textual-port? port | |
1569 | Always return @var{#t}, as all ports can be used for textual I/O in | |
1570 | Guile. | |
1571 | @end deffn | |
1572 | ||
1573 | @deffn {Scheme Procedure} transcoded-port obj | |
1574 | The @code{transcoded-port} procedure | |
1575 | returns a new textual port with the specified @var{transcoder}. | |
1576 | Otherwise the new textual port's state is largely the same as | |
1577 | that of @var{binary-port}. | |
1578 | If @var{binary-port} is an input port, the new textual | |
1579 | port will be an input port and | |
1580 | will transcode the bytes that have not yet been read from | |
1581 | @var{binary-port}. | |
1582 | If @var{binary-port} is an output port, the new textual | |
1583 | port will be an output port and | |
1584 | will transcode output characters into bytes that are | |
1585 | written to the byte sink represented by @var{binary-port}. | |
1586 | ||
1587 | As a side effect, however, @code{transcoded-port} | |
1588 | closes @var{binary-port} in | |
1589 | a special way that allows the new textual port to continue to | |
1590 | use the byte source or sink represented by @var{binary-port}, | |
1591 | even though @var{binary-port} itself is closed and cannot | |
1592 | be used by the input and output operations described in this | |
1593 | chapter. | |
1594 | @end deffn | |
1595 | ||
b242715b LC |
1596 | @deffn {Scheme Procedure} port-position port |
1597 | If @var{port} supports it (see below), return the offset (an integer) | |
1598 | indicating where the next octet will be read from/written to in | |
1599 | @var{port}. If @var{port} does not support this operation, an error | |
1600 | condition is raised. | |
1601 | ||
1602 | This is similar to Guile's @code{seek} procedure with the | |
1603 | @code{SEEK_CUR} argument (@pxref{Random Access}). | |
1604 | @end deffn | |
1605 | ||
1606 | @deffn {Scheme Procedure} port-has-port-position? port | |
1607 | Return @code{#t} is @var{port} supports @code{port-position}. | |
1608 | @end deffn | |
1609 | ||
1610 | @deffn {Scheme Procedure} set-port-position! port offset | |
1611 | If @var{port} supports it (see below), set the position where the next | |
1612 | octet will be read from/written to @var{port} to @var{offset} (an | |
1613 | integer). If @var{port} does not support this operation, an error | |
1614 | condition is raised. | |
1615 | ||
1616 | This is similar to Guile's @code{seek} procedure with the | |
1617 | @code{SEEK_SET} argument (@pxref{Random Access}). | |
1618 | @end deffn | |
1619 | ||
1620 | @deffn {Scheme Procedure} port-has-set-port-position!? port | |
1621 | Return @code{#t} is @var{port} supports @code{set-port-position!}. | |
1622 | @end deffn | |
1623 | ||
1624 | @deffn {Scheme Procedure} call-with-port port proc | |
1625 | Call @var{proc}, passing it @var{port} and closing @var{port} upon exit | |
1626 | of @var{proc}. Return the return values of @var{proc}. | |
1627 | @end deffn | |
1628 | ||
040dfa6f AR |
1629 | @node R6RS Input Ports |
1630 | @subsubsection Input Ports | |
96128014 | 1631 | |
040dfa6f AR |
1632 | @deffn {Scheme Procedure} input-port? obj@ |
1633 | Returns @code{#t} if the argument is an input port (or a combined input | |
1634 | and output port), and returns @code{#f} otherwise. | |
1635 | @end deffn | |
96128014 | 1636 | |
040dfa6f AR |
1637 | @deffn {Scheme Procedure} port-eof? port |
1638 | Returns @code{#t} | |
1639 | if the @code{lookahead-u8} procedure (if @var{input-port} is a binary port) | |
1640 | or the @code{lookahead-char} procedure (if @var{input-port} is a textual port) | |
1641 | would return | |
1642 | the end-of-file object, and @code{#f} otherwise. | |
1643 | The operation may block indefinitely if no data is available | |
1644 | but the port cannot be determined to be at end of file. | |
96128014 LC |
1645 | @end deffn |
1646 | ||
040dfa6f AR |
1647 | @deffn {Scheme Procedure} open-file-input-port filename |
1648 | @deffnx {Scheme Procedure} open-file-input-port filename file-options | |
1649 | @deffnx {Scheme Procedure} open-file-input-port filename file-options buffer-mode | |
1650 | @deffnx {Scheme Procedure} open-file-input-port filename file-options buffer-mode maybe-transcoder | |
1651 | @var{Maybe-transcoder} must be either a transcoder or @code{#f}. | |
1652 | ||
1653 | The @code{open-file-input-port} procedure returns an | |
1654 | input port for the named file. The @var{file-options} and | |
1655 | @var{maybe-transcoder} arguments are optional. | |
1656 | ||
1657 | The @var{file-options} argument, which may determine | |
1658 | various aspects of the returned port (@pxref{R6RS File Options}), | |
1659 | defaults to the value of @code{(file-options)}. | |
1660 | ||
1661 | The @var{buffer-mode} argument, if supplied, | |
1662 | must be one of the symbols that name a buffer mode. | |
1663 | The @var{buffer-mode} argument defaults to @code{block}. | |
1664 | ||
1665 | If @var{maybe-transcoder} is a transcoder, it becomes the transcoder associated | |
1666 | with the returned port. | |
1667 | ||
1668 | If @var{maybe-transcoder} is @code{#f} or absent, | |
1669 | the port will be a binary port and will support the | |
1670 | @code{port-position} and @code{set-port-position!} operations. | |
1671 | Otherwise the port will be a textual port, and whether it supports | |
1672 | the @code{port-position} and @code{set-port-position!} operations | |
1673 | is implementation-dependent (and possibly transcoder-dependent). | |
96128014 LC |
1674 | @end deffn |
1675 | ||
040dfa6f AR |
1676 | @deffn {Scheme Procedure} standard-input-port |
1677 | Returns a fresh binary input port connected to standard input. Whether | |
1678 | the port supports the @code{port-position} and @code{set-port-position!} | |
1679 | operations is implementation-dependent. | |
1680 | @end deffn | |
1681 | ||
1682 | @deffn {Scheme Procedure} current-input-port | |
1683 | This returns a default textual port for input. Normally, this default | |
1684 | port is associated with standard input, but can be dynamically | |
1685 | re-assigned using the @code{with-input-from-file} procedure from the | |
1686 | @code{io simple (6)} library (@pxref{rnrs io simple}). The port may or | |
1687 | may not have an associated transcoder; if it does, the transcoder is | |
1688 | implementation-dependent. | |
1689 | @end deffn | |
b242715b LC |
1690 | |
1691 | @node R6RS Binary Input | |
1692 | @subsubsection Binary Input | |
1693 | ||
1694 | @cindex binary input | |
1695 | ||
1696 | R6RS binary input ports can be created with the procedures described | |
1697 | below. | |
1698 | ||
1699 | @deffn {Scheme Procedure} open-bytevector-input-port bv [transcoder] | |
1700 | @deffnx {C Function} scm_open_bytevector_input_port (bv, transcoder) | |
1701 | Return an input port whose contents are drawn from bytevector @var{bv} | |
1702 | (@pxref{Bytevectors}). | |
1703 | ||
1704 | @c FIXME: Update description when implemented. | |
1705 | The @var{transcoder} argument is currently not supported. | |
1706 | @end deffn | |
1707 | ||
1708 | @cindex custom binary input ports | |
1709 | ||
1710 | @deffn {Scheme Procedure} make-custom-binary-input-port id read! get-position set-position! close | |
1711 | @deffnx {C Function} scm_make_custom_binary_input_port (id, read!, get-position, set-position!, close) | |
1712 | Return a new custom binary input port@footnote{This is similar in spirit | |
1713 | to Guile's @dfn{soft ports} (@pxref{Soft Ports}).} named @var{id} (a | |
1714 | string) whose input is drained by invoking @var{read!} and passing it a | |
1715 | bytevector, an index where bytes should be written, and the number of | |
1716 | bytes to read. The @code{read!} procedure must return an integer | |
1717 | indicating the number of bytes read, or @code{0} to indicate the | |
1718 | end-of-file. | |
1719 | ||
1720 | Optionally, if @var{get-position} is not @code{#f}, it must be a thunk | |
1721 | that will be called when @var{port-position} is invoked on the custom | |
1722 | binary port and should return an integer indicating the position within | |
1723 | the underlying data stream; if @var{get-position} was not supplied, the | |
1724 | returned port does not support @var{port-position}. | |
1725 | ||
1726 | Likewise, if @var{set-position!} is not @code{#f}, it should be a | |
1727 | one-argument procedure. When @var{set-port-position!} is invoked on the | |
1728 | custom binary input port, @var{set-position!} is passed an integer | |
1729 | indicating the position of the next byte is to read. | |
1730 | ||
1731 | Finally, if @var{close} is not @code{#f}, it must be a thunk. It is | |
1732 | invoked when the custom binary input port is closed. | |
1733 | ||
1734 | Using a custom binary input port, the @code{open-bytevector-input-port} | |
1735 | procedure could be implemented as follows: | |
1736 | ||
1737 | @lisp | |
1738 | (define (open-bytevector-input-port source) | |
1739 | (define position 0) | |
1740 | (define length (bytevector-length source)) | |
1741 | ||
1742 | (define (read! bv start count) | |
1743 | (let ((count (min count (- length position)))) | |
1744 | (bytevector-copy! source position | |
1745 | bv start count) | |
1746 | (set! position (+ position count)) | |
1747 | count)) | |
1748 | ||
1749 | (define (get-position) position) | |
1750 | ||
1751 | (define (set-position! new-position) | |
1752 | (set! position new-position)) | |
1753 | ||
1754 | (make-custom-binary-input-port "the port" read! | |
1755 | get-position | |
1756 | set-position!)) | |
1757 | ||
1758 | (read (open-bytevector-input-port (string->utf8 "hello"))) | |
1759 | @result{} hello | |
1760 | @end lisp | |
1761 | @end deffn | |
1762 | ||
1763 | @cindex binary input | |
1764 | Binary input is achieved using the procedures below: | |
1765 | ||
1766 | @deffn {Scheme Procedure} get-u8 port | |
1767 | @deffnx {C Function} scm_get_u8 (port) | |
1768 | Return an octet read from @var{port}, a binary input port, blocking as | |
1769 | necessary, or the end-of-file object. | |
1770 | @end deffn | |
1771 | ||
1772 | @deffn {Scheme Procedure} lookahead-u8 port | |
1773 | @deffnx {C Function} scm_lookahead_u8 (port) | |
1774 | Like @code{get-u8} but does not update @var{port}'s position to point | |
1775 | past the octet. | |
1776 | @end deffn | |
1777 | ||
1778 | @deffn {Scheme Procedure} get-bytevector-n port count | |
1779 | @deffnx {C Function} scm_get_bytevector_n (port, count) | |
1780 | Read @var{count} octets from @var{port}, blocking as necessary and | |
1781 | return a bytevector containing the octets read. If fewer bytes are | |
1782 | available, a bytevector smaller than @var{count} is returned. | |
1783 | @end deffn | |
1784 | ||
1785 | @deffn {Scheme Procedure} get-bytevector-n! port bv start count | |
1786 | @deffnx {C Function} scm_get_bytevector_n_x (port, bv, start, count) | |
1787 | Read @var{count} bytes from @var{port} and store them in @var{bv} | |
1788 | starting at index @var{start}. Return either the number of bytes | |
1789 | actually read or the end-of-file object. | |
1790 | @end deffn | |
1791 | ||
1792 | @deffn {Scheme Procedure} get-bytevector-some port | |
1793 | @deffnx {C Function} scm_get_bytevector_some (port) | |
1794 | Read from @var{port}, blocking as necessary, until data are available or | |
1795 | and end-of-file is reached. Return either a new bytevector containing | |
1796 | the data read or the end-of-file object. | |
1797 | @end deffn | |
1798 | ||
1799 | @deffn {Scheme Procedure} get-bytevector-all port | |
1800 | @deffnx {C Function} scm_get_bytevector_all (port) | |
1801 | Read from @var{port}, blocking as necessary, until the end-of-file is | |
1802 | reached. Return either a new bytevector containing the data read or the | |
1803 | end-of-file object (if no data were available). | |
1804 | @end deffn | |
1805 | ||
040dfa6f AR |
1806 | @node R6RS Textual Input |
1807 | @subsubsection Textual Input | |
1808 | ||
1809 | @deffn {Scheme Procedure} get-char port | |
1810 | Reads from @var{textual-input-port}, blocking as necessary, until a | |
1811 | complete character is available from @var{textual-input-port}, | |
1812 | or until an end of file is reached. | |
1813 | ||
1814 | If a complete character is available before the next end of file, | |
1815 | @code{get-char} returns that character and updates the input port to | |
1816 | point past the character. If an end of file is reached before any | |
1817 | character is read, @code{get-char} returns the end-of-file object. | |
1818 | @end deffn | |
1819 | ||
1820 | @deffn {Scheme Procedure} lookahead-char port | |
1821 | The @code{lookahead-char} procedure is like @code{get-char}, but it does | |
1822 | not update @var{textual-input-port} to point past the character. | |
1823 | @end deffn | |
1824 | ||
1825 | @deffn {Scheme Procedure} get-string-n port count | |
1826 | ||
1827 | @var{Count} must be an exact, non-negative integer object, representing | |
1828 | the number of characters to be read. | |
1829 | ||
1830 | The @code{get-string-n} procedure reads from @var{textual-input-port}, | |
1831 | blocking as necessary, until @var{count} characters are available, or | |
1832 | until an end of file is reached. | |
1833 | ||
1834 | If @var{count} characters are available before end of file, | |
1835 | @code{get-string-n} returns a string consisting of those @var{count} | |
1836 | characters. If fewer characters are available before an end of file, but | |
1837 | one or more characters can be read, @code{get-string-n} returns a string | |
1838 | containing those characters. In either case, the input port is updated | |
1839 | to point just past the characters read. If no characters can be read | |
1840 | before an end of file, the end-of-file object is returned. | |
1841 | @end deffn | |
1842 | ||
1843 | @deffn {Scheme Procedure} get-string-n! port string start count | |
1844 | ||
1845 | @var{Start} and @var{count} must be exact, non-negative integer objects, | |
1846 | with @var{count} representing the number of characters to be read. | |
1847 | @var{String} must be a string with at least $@var{start} + @var{count}$ | |
1848 | characters. | |
1849 | ||
1850 | The @code{get-string-n!} procedure reads from @var{textual-input-port} | |
1851 | in the same manner as @code{get-string-n}. If @var{count} characters | |
1852 | are available before an end of file, they are written into @var{string} | |
1853 | starting at index @var{start}, and @var{count} is returned. If fewer | |
1854 | characters are available before an end of file, but one or more can be | |
1855 | read, those characters are written into @var{string} starting at index | |
1856 | @var{start} and the number of characters actually read is returned as an | |
1857 | exact integer object. If no characters can be read before an end of | |
1858 | file, the end-of-file object is returned. | |
1859 | @end deffn | |
1860 | ||
1861 | @deffn {Scheme Procedure} get-string-all port count | |
1862 | Reads from @var{textual-input-port} until an end of file, decoding | |
1863 | characters in the same manner as @code{get-string-n} and | |
1864 | @code{get-string-n!}. | |
1865 | ||
1866 | If characters are available before the end of file, a string containing | |
1867 | all the characters decoded from that data are returned. If no character | |
1868 | precedes the end of file, the end-of-file object is returned. | |
1869 | @end deffn | |
1870 | ||
1871 | @deffn {Scheme Procedure} get-line port | |
1872 | Reads from @var{textual-input-port} up to and including the linefeed | |
1873 | character or end of file, decoding characters in the same manner as | |
1874 | @code{get-string-n} and @code{get-string-n!}. | |
1875 | ||
1876 | If a linefeed character is read, a string containing all of the text up | |
1877 | to (but not including) the linefeed character is returned, and the port | |
1878 | is updated to point just past the linefeed character. If an end of file | |
1879 | is encountered before any linefeed character is read, but some | |
1880 | characters have been read and decoded as characters, a string containing | |
1881 | those characters is returned. If an end of file is encountered before | |
1882 | any characters are read, the end-of-file object is returned. | |
1883 | ||
1884 | @quotation Note | |
1885 | The end-of-line style, if not @code{none}, will cause all line endings | |
1886 | to be read as linefeed characters. @xref{R6RS Transcoders}. | |
1887 | @end quotation | |
1888 | @end deffn | |
1889 | ||
1890 | @deffn {Scheme Procedure} get-datum port count | |
1891 | Reads an external representation from @var{textual-input-port} and returns the | |
1892 | datum it represents. The @code{get-datum} procedure returns the next | |
1893 | datum that can be parsed from the given @var{textual-input-port}, updating | |
1894 | @var{textual-input-port} to point exactly past the end of the external | |
1895 | representation of the object. | |
1896 | ||
1897 | Any @emph{interlexeme space} (comment or whitespace, @pxref{Scheme | |
1898 | Syntax}) in the input is first skipped. If an end of file occurs after | |
1899 | the interlexeme space, the end-of-file object (@pxref{R6RS End-of-File}) | |
1900 | is returned. | |
1901 | ||
1902 | If a character inconsistent with an external representation is | |
1903 | encountered in the input, an exception with condition types | |
1904 | @code{&lexical} and @code{&i/o-read} is raised. Also, if the end of | |
1905 | file is encountered after the beginning of an external representation, | |
1906 | but the external representation is incomplete and therefore cannot be | |
1907 | parsed, an exception with condition types @code{&lexical} and | |
1908 | @code{&i/o-read} is raised. | |
1909 | @end deffn | |
1910 | ||
1911 | @node R6RS Output Ports | |
1912 | @subsubsection Output Ports | |
1913 | ||
1914 | @deffn {Scheme Procedure} output-port? obj | |
1915 | Returns @code{#t} if the argument is an output port (or a | |
1916 | combined input and output port), @code{#f} otherwise. | |
1917 | @end deffn | |
1918 | ||
1919 | @deffn {Scheme Procedure} flush-output-port port | |
1920 | Flushes any buffered output from the buffer of @var{output-port} to the | |
1921 | underlying file, device, or object. The @code{flush-output-port} | |
1922 | procedure returns an unspecified values. | |
1923 | @end deffn | |
1924 | ||
1925 | @deffn {Scheme Procedure} open-file-output-port filename | |
1926 | @deffnx {Scheme Procedure} open-file-output-port filename file-options | |
1927 | @deffnx {Scheme Procedure} open-file-output-port filename file-options buffer-mode | |
1928 | @deffnx {Scheme Procedure} open-file-output-port filename file-options buffer-mode maybe-transcoder | |
1929 | ||
1930 | @var{maybe-transcoder} must be either a transcoder or @code{#f}. | |
1931 | ||
1932 | The @code{open-file-output-port} procedure returns an output port for the named file. | |
1933 | ||
1934 | The @var{file-options} argument, which may determine various aspects of | |
1935 | the returned port (@pxref{R6RS File Options}), defaults to the value of | |
1936 | @code{(file-options)}. | |
1937 | ||
1938 | The @var{buffer-mode} argument, if supplied, | |
1939 | must be one of the symbols that name a buffer mode. | |
1940 | The @var{buffer-mode} argument defaults to @code{block}. | |
1941 | ||
1942 | If @var{maybe-transcoder} is a transcoder, it becomes the transcoder | |
1943 | associated with the port. | |
1944 | ||
1945 | If @var{maybe-transcoder} is @code{#f} or absent, | |
1946 | the port will be a binary port and will support the | |
1947 | @code{port-position} and @code{set-port-position!} operations. | |
1948 | Otherwise the port will be a textual port, and whether it supports | |
1949 | the @code{port-position} and @code{set-port-position!} operations | |
1950 | is implementation-dependent (and possibly transcoder-dependent). | |
1951 | @end deffn | |
1952 | ||
1953 | @deffn {Scheme Procedure} standard-output-port | |
1954 | @deffnx {Scheme Procedure} standard-error-port | |
1955 | Returns a fresh binary output port connected to the standard output or | |
1956 | standard error respectively. Whether the port supports the | |
1957 | @code{port-position} and @code{set-port-position!} operations is | |
1958 | implementation-dependent. | |
1959 | @end deffn | |
1960 | ||
1961 | @deffn {Scheme Procedure} current-output-port | |
1962 | @deffnx {Scheme Procedure} current-error-port | |
1963 | These return default textual ports for regular output and error output. | |
1964 | Normally, these default ports are associated with standard output, and | |
1965 | standard error, respectively. The return value of | |
1966 | @code{current-output-port} can be dynamically re-assigned using the | |
1967 | @code{with-output-to-file} procedure from the @code{io simple (6)} | |
1968 | library (@pxref{rnrs io simple}). A port returned by one of these | |
1969 | procedures may or may not have an associated transcoder; if it does, the | |
1970 | transcoder is implementation-dependent. | |
1971 | @end deffn | |
1972 | ||
b242715b LC |
1973 | @node R6RS Binary Output |
1974 | @subsubsection Binary Output | |
1975 | ||
1976 | Binary output ports can be created with the procedures below. | |
1977 | ||
1978 | @deffn {Scheme Procedure} open-bytevector-output-port [transcoder] | |
1979 | @deffnx {C Function} scm_open_bytevector_output_port (transcoder) | |
1980 | Return two values: a binary output port and a procedure. The latter | |
1981 | should be called with zero arguments to obtain a bytevector containing | |
1982 | the data accumulated by the port, as illustrated below. | |
1983 | ||
1984 | @lisp | |
1985 | (call-with-values | |
1986 | (lambda () | |
1987 | (open-bytevector-output-port)) | |
1988 | (lambda (port get-bytevector) | |
1989 | (display "hello" port) | |
1990 | (get-bytevector))) | |
1991 | ||
1992 | @result{} #vu8(104 101 108 108 111) | |
1993 | @end lisp | |
1994 | ||
1995 | @c FIXME: Update description when implemented. | |
1996 | The @var{transcoder} argument is currently not supported. | |
1997 | @end deffn | |
1998 | ||
1999 | @cindex custom binary output ports | |
2000 | ||
2001 | @deffn {Scheme Procedure} make-custom-binary-output-port id write! get-position set-position! close | |
2002 | @deffnx {C Function} scm_make_custom_binary_output_port (id, write!, get-position, set-position!, close) | |
2003 | Return a new custom binary output port named @var{id} (a string) whose | |
2004 | output is sunk by invoking @var{write!} and passing it a bytevector, an | |
2005 | index where bytes should be read from this bytevector, and the number of | |
2006 | bytes to be ``written''. The @code{write!} procedure must return an | |
2007 | integer indicating the number of bytes actually written; when it is | |
2008 | passed @code{0} as the number of bytes to write, it should behave as | |
2009 | though an end-of-file was sent to the byte sink. | |
2010 | ||
2011 | The other arguments are as for @code{make-custom-binary-input-port} | |
2012 | (@pxref{R6RS Binary Input, @code{make-custom-binary-input-port}}). | |
2013 | @end deffn | |
2014 | ||
2015 | @cindex binary output | |
2016 | Writing to a binary output port can be done using the following | |
2017 | procedures: | |
2018 | ||
2019 | @deffn {Scheme Procedure} put-u8 port octet | |
2020 | @deffnx {C Function} scm_put_u8 (port, octet) | |
2021 | Write @var{octet}, an integer in the 0--255 range, to @var{port}, a | |
2022 | binary output port. | |
2023 | @end deffn | |
2024 | ||
2025 | @deffn {Scheme Procedure} put-bytevector port bv [start [count]] | |
2026 | @deffnx {C Function} scm_put_bytevector (port, bv, start, count) | |
2027 | Write the contents of @var{bv} to @var{port}, optionally starting at | |
2028 | index @var{start} and limiting to @var{count} octets. | |
2029 | @end deffn | |
2030 | ||
040dfa6f AR |
2031 | @node R6RS Textual Output |
2032 | @subsubsection Textual Output | |
2033 | ||
2034 | @deffn {Scheme Procedure} put-char port char | |
2035 | Writes @var{char} to the port. The @code{put-char} procedure returns | |
2036 | @end deffn | |
2037 | ||
2038 | @deffn {Scheme Procedure} put-string port string | |
2039 | @deffnx {Scheme Procedure} put-string port string start | |
2040 | @deffnx {Scheme Procedure} put-string port string start count | |
2041 | ||
2042 | @var{start} and @var{count} must be non-negative exact integer objects. | |
2043 | @var{string} must have a length of at least @math{@var{start} + | |
2044 | @var{count}}. @var{start} defaults to 0. @var{count} defaults to | |
2045 | @math{@code{(string-length @var{string})} - @var{start}}$. The | |
2046 | @code{put-string} procedure writes the @var{count} characters of | |
2047 | @var{string} starting at index @var{start} to the port. The | |
2048 | @code{put-string} procedure returns an unspecified value. | |
2049 | @end deffn | |
2050 | ||
2051 | @deffn {Scheme Procedure} put-datum port datum | |
2052 | @var{datum} should be a datum value. The @code{put-datum} procedure | |
2053 | writes an external representation of @var{datum} to | |
2054 | @var{textual-output-port}. The specific external representation is | |
2055 | implementation-dependent. However, whenever possible, an implementation | |
2056 | should produce a representation for which @code{get-datum}, when reading | |
2057 | the representation, will return an object equal (in the sense of | |
2058 | @code{equal?}) to @var{datum}. | |
2059 | ||
2060 | @quotation Note | |
2061 | Not all datums may allow producing an external representation for which | |
2062 | @code{get-datum} will produce an object that is equal to the | |
2063 | original. Specifically, NaNs contained in @var{datum} may make | |
2064 | this impossible. | |
2065 | @end quotation | |
2066 | ||
2067 | @quotation Note | |
2068 | The @code{put-datum} procedure merely writes the external | |
2069 | representation, but no trailing delimiter. If @code{put-datum} is | |
2070 | used to write several subsequent external representations to an | |
2071 | output port, care should be taken to delimit them properly so they can | |
2072 | be read back in by subsequent calls to @code{get-datum}. | |
2073 | @end quotation | |
2074 | @end deffn | |
b242715b | 2075 | |
07d83abe MV |
2076 | @node I/O Extensions |
2077 | @subsection Using and Extending Ports in C | |
2078 | ||
2079 | @menu | |
2080 | * C Port Interface:: Using ports from C. | |
2081 | * Port Implementation:: How to implement a new port type in C. | |
2082 | @end menu | |
2083 | ||
2084 | ||
2085 | @node C Port Interface | |
2086 | @subsubsection C Port Interface | |
bf5df489 KR |
2087 | @cindex C port interface |
2088 | @cindex Port, C interface | |
07d83abe MV |
2089 | |
2090 | This section describes how to use Scheme ports from C. | |
2091 | ||
2092 | @subsubheading Port basics | |
2093 | ||
3081aee1 KR |
2094 | @cindex ptob |
2095 | @tindex scm_ptob_descriptor | |
2096 | @tindex scm_port | |
2097 | @findex SCM_PTAB_ENTRY | |
2098 | @findex SCM_PTOBNUM | |
2099 | @vindex scm_ptobs | |
07d83abe MV |
2100 | There are two main data structures. A port type object (ptob) is of |
2101 | type @code{scm_ptob_descriptor}. A port instance is of type | |
2102 | @code{scm_port}. Given an @code{SCM} variable which points to a port, | |
2103 | the corresponding C port object can be obtained using the | |
2104 | @code{SCM_PTAB_ENTRY} macro. The ptob can be obtained by using | |
2105 | @code{SCM_PTOBNUM} to give an index into the @code{scm_ptobs} | |
2106 | global array. | |
2107 | ||
2108 | @subsubheading Port buffers | |
2109 | ||
2110 | An input port always has a read buffer and an output port always has a | |
2111 | write buffer. However the size of these buffers is not guaranteed to be | |
2112 | more than one byte (e.g., the @code{shortbuf} field in @code{scm_port} | |
2113 | which is used when no other buffer is allocated). The way in which the | |
2114 | buffers are allocated depends on the implementation of the ptob. For | |
2115 | example in the case of an fport, buffers may be allocated with malloc | |
2116 | when the port is created, but in the case of an strport the underlying | |
2117 | string is used as the buffer. | |
2118 | ||
2119 | @subsubheading The @code{rw_random} flag | |
2120 | ||
2121 | Special treatment is required for ports which can be seeked at random. | |
2122 | Before various operations, such as seeking the port or changing from | |
2123 | input to output on a bidirectional port or vice versa, the port | |
2124 | implementation must be given a chance to update its state. The write | |
2125 | buffer is updated by calling the @code{flush} ptob procedure and the | |
2126 | input buffer is updated by calling the @code{end_input} ptob procedure. | |
2127 | In the case of an fport, @code{flush} causes buffered output to be | |
2128 | written to the file descriptor, while @code{end_input} causes the | |
2129 | descriptor position to be adjusted to account for buffered input which | |
2130 | was never read. | |
2131 | ||
2132 | The special treatment must be performed if the @code{rw_random} flag in | |
2133 | the port is non-zero. | |
2134 | ||
2135 | @subsubheading The @code{rw_active} variable | |
2136 | ||
2137 | The @code{rw_active} variable in the port is only used if | |
2138 | @code{rw_random} is set. It's defined as an enum with the following | |
2139 | values: | |
2140 | ||
2141 | @table @code | |
2142 | @item SCM_PORT_READ | |
2143 | the read buffer may have unread data. | |
2144 | ||
2145 | @item SCM_PORT_WRITE | |
2146 | the write buffer may have unwritten data. | |
2147 | ||
2148 | @item SCM_PORT_NEITHER | |
2149 | neither the write nor the read buffer has data. | |
2150 | @end table | |
2151 | ||
2152 | @subsubheading Reading from a port. | |
2153 | ||
2154 | To read from a port, it's possible to either call existing libguile | |
2155 | procedures such as @code{scm_getc} and @code{scm_read_line} or to read | |
2156 | data from the read buffer directly. Reading from the buffer involves | |
2157 | the following steps: | |
2158 | ||
2159 | @enumerate | |
2160 | @item | |
2161 | Flush output on the port, if @code{rw_active} is @code{SCM_PORT_WRITE}. | |
2162 | ||
2163 | @item | |
2164 | Fill the read buffer, if it's empty, using @code{scm_fill_input}. | |
2165 | ||
2166 | @item Read the data from the buffer and update the read position in | |
2167 | the buffer. Steps 2) and 3) may be repeated as many times as required. | |
2168 | ||
2169 | @item Set rw_active to @code{SCM_PORT_READ} if @code{rw_random} is set. | |
2170 | ||
2171 | @item update the port's line and column counts. | |
2172 | @end enumerate | |
2173 | ||
2174 | @subsubheading Writing to a port. | |
2175 | ||
2176 | To write data to a port, calling @code{scm_lfwrite} should be sufficient for | |
2177 | most purposes. This takes care of the following steps: | |
2178 | ||
2179 | @enumerate | |
2180 | @item | |
2181 | End input on the port, if @code{rw_active} is @code{SCM_PORT_READ}. | |
2182 | ||
2183 | @item | |
2184 | Pass the data to the ptob implementation using the @code{write} ptob | |
2185 | procedure. The advantage of using the ptob @code{write} instead of | |
2186 | manipulating the write buffer directly is that it allows the data to be | |
2187 | written in one operation even if the port is using the single-byte | |
2188 | @code{shortbuf}. | |
2189 | ||
2190 | @item | |
2191 | Set @code{rw_active} to @code{SCM_PORT_WRITE} if @code{rw_random} | |
2192 | is set. | |
2193 | @end enumerate | |
2194 | ||
2195 | ||
2196 | @node Port Implementation | |
2197 | @subsubsection Port Implementation | |
28cc8dac | 2198 | @cindex Port implementation |
07d83abe MV |
2199 | |
2200 | This section describes how to implement a new port type in C. | |
2201 | ||
2202 | As described in the previous section, a port type object (ptob) is | |
2203 | a structure of type @code{scm_ptob_descriptor}. A ptob is created by | |
2204 | calling @code{scm_make_port_type}. | |
2205 | ||
23f2b9a3 KR |
2206 | @deftypefun scm_t_bits scm_make_port_type (char *name, int (*fill_input) (SCM port), void (*write) (SCM port, const void *data, size_t size)) |
2207 | Return a new port type object. The @var{name}, @var{fill_input} and | |
2208 | @var{write} parameters are initial values for those port type fields, | |
2209 | as described below. The other fields are initialized with default | |
2210 | values and can be changed later. | |
2211 | @end deftypefun | |
2212 | ||
07d83abe MV |
2213 | All of the elements of the ptob, apart from @code{name}, are procedures |
2214 | which collectively implement the port behaviour. Creating a new port | |
2215 | type mostly involves writing these procedures. | |
2216 | ||
07d83abe MV |
2217 | @table @code |
2218 | @item name | |
2219 | A pointer to a NUL terminated string: the name of the port type. This | |
2220 | is the only element of @code{scm_ptob_descriptor} which is not | |
2221 | a procedure. Set via the first argument to @code{scm_make_port_type}. | |
2222 | ||
2223 | @item mark | |
2224 | Called during garbage collection to mark any SCM objects that a port | |
2225 | object may contain. It doesn't need to be set unless the port has | |
23f2b9a3 KR |
2226 | @code{SCM} components. Set using |
2227 | ||
2228 | @deftypefun void scm_set_port_mark (scm_t_bits tc, SCM (*mark) (SCM port)) | |
2229 | @end deftypefun | |
07d83abe MV |
2230 | |
2231 | @item free | |
2232 | Called when the port is collected during gc. It | |
2233 | should free any resources used by the port. | |
23f2b9a3 KR |
2234 | Set using |
2235 | ||
2236 | @deftypefun void scm_set_port_free (scm_t_bits tc, size_t (*free) (SCM port)) | |
2237 | @end deftypefun | |
07d83abe MV |
2238 | |
2239 | @item print | |
2240 | Called when @code{write} is called on the port object, to print a | |
23f2b9a3 KR |
2241 | port description. E.g., for an fport it may produce something like: |
2242 | @code{#<input: /etc/passwd 3>}. Set using | |
2243 | ||
2244 | @deftypefun void scm_set_port_print (scm_t_bits tc, int (*print) (SCM port, SCM dest_port, scm_print_state *pstate)) | |
2245 | The first argument @var{port} is the object being printed, the second | |
2246 | argument @var{dest_port} is where its description should go. | |
2247 | @end deftypefun | |
07d83abe MV |
2248 | |
2249 | @item equalp | |
23f2b9a3 KR |
2250 | Not used at present. Set using |
2251 | ||
2252 | @deftypefun void scm_set_port_equalp (scm_t_bits tc, SCM (*equalp) (SCM, SCM)) | |
2253 | @end deftypefun | |
07d83abe MV |
2254 | |
2255 | @item close | |
2256 | Called when the port is closed, unless it was collected during gc. It | |
2257 | should free any resources used by the port. | |
23f2b9a3 KR |
2258 | Set using |
2259 | ||
2260 | @deftypefun void scm_set_port_close (scm_t_bits tc, int (*close) (SCM port)) | |
2261 | @end deftypefun | |
07d83abe MV |
2262 | |
2263 | @item write | |
2264 | Accept data which is to be written using the port. The port implementation | |
2265 | may choose to buffer the data instead of processing it directly. | |
2266 | Set via the third argument to @code{scm_make_port_type}. | |
2267 | ||
2268 | @item flush | |
2269 | Complete the processing of buffered output data. Reset the value of | |
2270 | @code{rw_active} to @code{SCM_PORT_NEITHER}. | |
23f2b9a3 KR |
2271 | Set using |
2272 | ||
2273 | @deftypefun void scm_set_port_flush (scm_t_bits tc, void (*flush) (SCM port)) | |
2274 | @end deftypefun | |
07d83abe MV |
2275 | |
2276 | @item end_input | |
2277 | Perform any synchronization required when switching from input to output | |
2278 | on the port. Reset the value of @code{rw_active} to @code{SCM_PORT_NEITHER}. | |
23f2b9a3 KR |
2279 | Set using |
2280 | ||
2281 | @deftypefun void scm_set_port_end_input (scm_t_bits tc, void (*end_input) (SCM port, int offset)) | |
2282 | @end deftypefun | |
07d83abe MV |
2283 | |
2284 | @item fill_input | |
2285 | Read new data into the read buffer and return the first character. It | |
2286 | can be assumed that the read buffer is empty when this procedure is called. | |
2287 | Set via the second argument to @code{scm_make_port_type}. | |
2288 | ||
2289 | @item input_waiting | |
2290 | Return a lower bound on the number of bytes that could be read from the | |
2291 | port without blocking. It can be assumed that the current state of | |
2292 | @code{rw_active} is @code{SCM_PORT_NEITHER}. | |
23f2b9a3 KR |
2293 | Set using |
2294 | ||
2295 | @deftypefun void scm_set_port_input_waiting (scm_t_bits tc, int (*input_waiting) (SCM port)) | |
2296 | @end deftypefun | |
07d83abe MV |
2297 | |
2298 | @item seek | |
2299 | Set the current position of the port. The procedure can not make | |
2300 | any assumptions about the value of @code{rw_active} when it's | |
2301 | called. It can reset the buffers first if desired by using something | |
2302 | like: | |
2303 | ||
2304 | @example | |
23f2b9a3 KR |
2305 | if (pt->rw_active == SCM_PORT_READ) |
2306 | scm_end_input (port); | |
2307 | else if (pt->rw_active == SCM_PORT_WRITE) | |
2308 | ptob->flush (port); | |
07d83abe MV |
2309 | @end example |
2310 | ||
2311 | However note that this will have the side effect of discarding any data | |
2312 | in the unread-char buffer, in addition to any side effects from the | |
2313 | @code{end_input} and @code{flush} ptob procedures. This is undesirable | |
2314 | when seek is called to measure the current position of the port, i.e., | |
2315 | @code{(seek p 0 SEEK_CUR)}. The libguile fport and string port | |
2316 | implementations take care to avoid this problem. | |
2317 | ||
23f2b9a3 KR |
2318 | The procedure is set using |
2319 | ||
f1ce9199 | 2320 | @deftypefun void scm_set_port_seek (scm_t_bits tc, scm_t_off (*seek) (SCM port, scm_t_off offset, int whence)) |
23f2b9a3 | 2321 | @end deftypefun |
07d83abe MV |
2322 | |
2323 | @item truncate | |
2324 | Truncate the port data to be specified length. It can be assumed that the | |
2325 | current state of @code{rw_active} is @code{SCM_PORT_NEITHER}. | |
23f2b9a3 KR |
2326 | Set using |
2327 | ||
f1ce9199 | 2328 | @deftypefun void scm_set_port_truncate (scm_t_bits tc, void (*truncate) (SCM port, scm_t_off length)) |
23f2b9a3 | 2329 | @end deftypefun |
07d83abe MV |
2330 | |
2331 | @end table | |
2332 | ||
07d83abe MV |
2333 | @c Local Variables: |
2334 | @c TeX-master: "guile.texi" | |
2335 | @c End: |