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 | ||
339 | @deffn {Scheme Procedure} print-options-interface [setting] | |
340 | @deffnx {C Function} scm_print_options (setting) | |
341 | Option interface for the print options. Instead of using | |
342 | this procedure directly, use the procedures | |
343 | @code{print-enable}, @code{print-disable}, @code{print-set!} | |
344 | and @code{print-options}. | |
345 | @end deffn | |
346 | ||
347 | @deffn {Scheme Procedure} simple-format destination message . args | |
348 | @deffnx {C Function} scm_simple_format (destination, message, args) | |
349 | Write @var{message} to @var{destination}, defaulting to | |
350 | the current output port. | |
351 | @var{message} can contain @code{~A} (was @code{%s}) and | |
352 | @code{~S} (was @code{%S}) escapes. When printed, | |
353 | the escapes are replaced with corresponding members of | |
354 | @var{ARGS}: | |
355 | @code{~A} formats using @code{display} and @code{~S} formats | |
356 | using @code{write}. | |
357 | If @var{destination} is @code{#t}, then use the current output | |
358 | port, if @var{destination} is @code{#f}, then return a string | |
359 | containing the formatted text. Does not add a trailing newline. | |
360 | @end deffn | |
361 | ||
362 | @rnindex write-char | |
363 | @deffn {Scheme Procedure} write-char chr [port] | |
364 | @deffnx {C Function} scm_write_char (chr, port) | |
365 | Send character @var{chr} to @var{port}. | |
366 | @end deffn | |
367 | ||
368 | @deftypefn {C Function} void scm_c_write (SCM port, const void *buffer, size_t size) | |
369 | Write @var{size} bytes at @var{buffer} to @var{port}. | |
370 | ||
371 | Note that this function does not update @code{port-line} and | |
372 | @code{port-column} (@pxref{Reading}). | |
373 | @end deftypefn | |
374 | ||
375 | @findex fflush | |
376 | @deffn {Scheme Procedure} force-output [port] | |
377 | @deffnx {C Function} scm_force_output (port) | |
378 | Flush the specified output port, or the current output port if @var{port} | |
379 | is omitted. The current output buffer contents are passed to the | |
380 | underlying port implementation (e.g., in the case of fports, the | |
381 | data will be written to the file and the output buffer will be cleared.) | |
382 | It has no effect on an unbuffered port. | |
383 | ||
384 | The return value is unspecified. | |
385 | @end deffn | |
386 | ||
387 | @deffn {Scheme Procedure} flush-all-ports | |
388 | @deffnx {C Function} scm_flush_all_ports () | |
389 | Equivalent to calling @code{force-output} on | |
390 | all open output ports. The return value is unspecified. | |
391 | @end deffn | |
392 | ||
393 | ||
394 | @node Closing | |
395 | @subsection Closing | |
bf5df489 KR |
396 | @cindex Closing ports |
397 | @cindex Port, close | |
07d83abe MV |
398 | |
399 | @deffn {Scheme Procedure} close-port port | |
400 | @deffnx {C Function} scm_close_port (port) | |
401 | Close the specified port object. Return @code{#t} if it | |
402 | successfully closes a port or @code{#f} if it was already | |
403 | closed. An exception may be raised if an error occurs, for | |
404 | example when flushing buffered output. See also @ref{Ports and | |
405 | File Descriptors, close}, for a procedure which can close file | |
406 | descriptors. | |
407 | @end deffn | |
408 | ||
409 | @deffn {Scheme Procedure} close-input-port port | |
410 | @deffnx {Scheme Procedure} close-output-port port | |
411 | @deffnx {C Function} scm_close_input_port (port) | |
412 | @deffnx {C Function} scm_close_output_port (port) | |
413 | @rnindex close-input-port | |
414 | @rnindex close-output-port | |
415 | Close the specified input or output @var{port}. An exception may be | |
416 | raised if an error occurs while closing. If @var{port} is already | |
417 | closed, nothing is done. The return value is unspecified. | |
418 | ||
419 | See also @ref{Ports and File Descriptors, close}, for a procedure | |
420 | which can close file descriptors. | |
421 | @end deffn | |
422 | ||
423 | @deffn {Scheme Procedure} port-closed? port | |
424 | @deffnx {C Function} scm_port_closed_p (port) | |
425 | Return @code{#t} if @var{port} is closed or @code{#f} if it is | |
426 | open. | |
427 | @end deffn | |
428 | ||
429 | ||
430 | @node Random Access | |
431 | @subsection Random Access | |
bf5df489 KR |
432 | @cindex Random access, ports |
433 | @cindex Port, random access | |
07d83abe MV |
434 | |
435 | @deffn {Scheme Procedure} seek fd_port offset whence | |
436 | @deffnx {C Function} scm_seek (fd_port, offset, whence) | |
437 | Sets the current position of @var{fd/port} to the integer | |
438 | @var{offset}, which is interpreted according to the value of | |
439 | @var{whence}. | |
440 | ||
441 | One of the following variables should be supplied for | |
442 | @var{whence}: | |
443 | @defvar SEEK_SET | |
444 | Seek from the beginning of the file. | |
445 | @end defvar | |
446 | @defvar SEEK_CUR | |
447 | Seek from the current position. | |
448 | @end defvar | |
449 | @defvar SEEK_END | |
450 | Seek from the end of the file. | |
451 | @end defvar | |
452 | If @var{fd/port} is a file descriptor, the underlying system | |
453 | call is @code{lseek}. @var{port} may be a string port. | |
454 | ||
455 | The value returned is the new position in the file. This means | |
456 | that the current position of a port can be obtained using: | |
457 | @lisp | |
458 | (seek port 0 SEEK_CUR) | |
459 | @end lisp | |
460 | @end deffn | |
461 | ||
462 | @deffn {Scheme Procedure} ftell fd_port | |
463 | @deffnx {C Function} scm_ftell (fd_port) | |
464 | Return an integer representing the current position of | |
465 | @var{fd/port}, measured from the beginning. Equivalent to: | |
466 | ||
467 | @lisp | |
468 | (seek port 0 SEEK_CUR) | |
469 | @end lisp | |
470 | @end deffn | |
471 | ||
472 | @findex truncate | |
473 | @findex ftruncate | |
40296bab KR |
474 | @deffn {Scheme Procedure} truncate-file file [length] |
475 | @deffnx {C Function} scm_truncate_file (file, length) | |
476 | Truncate @var{file} to @var{length} bytes. @var{file} can be a | |
477 | filename string, a port object, or an integer file descriptor. The | |
478 | return value is unspecified. | |
479 | ||
480 | For a port or file descriptor @var{length} can be omitted, in which | |
481 | case the file is truncated at the current position (per @code{ftell} | |
482 | above). | |
483 | ||
484 | On most systems a file can be extended by giving a length greater than | |
485 | the current size, but this is not mandatory in the POSIX standard. | |
07d83abe MV |
486 | @end deffn |
487 | ||
488 | @node Line/Delimited | |
489 | @subsection Line Oriented and Delimited Text | |
bf5df489 KR |
490 | @cindex Line input/output |
491 | @cindex Port, line input/output | |
07d83abe MV |
492 | |
493 | The delimited-I/O module can be accessed with: | |
494 | ||
aba0dff5 | 495 | @lisp |
07d83abe | 496 | (use-modules (ice-9 rdelim)) |
aba0dff5 | 497 | @end lisp |
07d83abe MV |
498 | |
499 | It can be used to read or write lines of text, or read text delimited by | |
500 | a specified set of characters. It's similar to the @code{(scsh rdelim)} | |
501 | module from guile-scsh, but does not use multiple values or character | |
502 | sets and has an extra procedure @code{write-line}. | |
503 | ||
504 | @c begin (scm-doc-string "rdelim.scm" "read-line") | |
505 | @deffn {Scheme Procedure} read-line [port] [handle-delim] | |
506 | Return a line of text from @var{port} if specified, otherwise from the | |
507 | value returned by @code{(current-input-port)}. Under Unix, a line of text | |
508 | is terminated by the first end-of-line character or by end-of-file. | |
509 | ||
510 | If @var{handle-delim} is specified, it should be one of the following | |
511 | symbols: | |
512 | @table @code | |
513 | @item trim | |
514 | Discard the terminating delimiter. This is the default, but it will | |
515 | be impossible to tell whether the read terminated with a delimiter or | |
516 | end-of-file. | |
517 | @item concat | |
518 | Append the terminating delimiter (if any) to the returned string. | |
519 | @item peek | |
520 | Push the terminating delimiter (if any) back on to the port. | |
521 | @item split | |
522 | Return a pair containing the string read from the port and the | |
523 | terminating delimiter or end-of-file object. | |
524 | @end table | |
c62da8f8 LC |
525 | |
526 | Like @code{read-char}, this procedure can throw to @code{decoding-error} | |
527 | (@pxref{Reading, @code{read-char}}). | |
07d83abe MV |
528 | @end deffn |
529 | ||
530 | @c begin (scm-doc-string "rdelim.scm" "read-line!") | |
531 | @deffn {Scheme Procedure} read-line! buf [port] | |
532 | Read a line of text into the supplied string @var{buf} and return the | |
533 | number of characters added to @var{buf}. If @var{buf} is filled, then | |
534 | @code{#f} is returned. | |
535 | Read from @var{port} if | |
536 | specified, otherwise from the value returned by @code{(current-input-port)}. | |
537 | @end deffn | |
538 | ||
539 | @c begin (scm-doc-string "rdelim.scm" "read-delimited") | |
540 | @deffn {Scheme Procedure} read-delimited delims [port] [handle-delim] | |
541 | Read text until one of the characters in the string @var{delims} is found | |
542 | or end-of-file is reached. Read from @var{port} if supplied, otherwise | |
543 | from the value returned by @code{(current-input-port)}. | |
544 | @var{handle-delim} takes the same values as described for @code{read-line}. | |
545 | @end deffn | |
546 | ||
547 | @c begin (scm-doc-string "rdelim.scm" "read-delimited!") | |
548 | @deffn {Scheme Procedure} read-delimited! delims buf [port] [handle-delim] [start] [end] | |
e7fb779f AW |
549 | Read text into the supplied string @var{buf}. |
550 | ||
551 | If a delimiter was found, return the number of characters written, | |
552 | except if @var{handle-delim} is @code{split}, in which case the return | |
553 | value is a pair, as noted above. | |
554 | ||
555 | As a special case, if @var{port} was already at end-of-stream, the EOF | |
556 | object is returned. Also, if no characters were written because the | |
557 | buffer was full, @code{#f} is returned. | |
558 | ||
559 | It's something of a wacky interface, to be honest. | |
07d83abe MV |
560 | @end deffn |
561 | ||
562 | @deffn {Scheme Procedure} write-line obj [port] | |
563 | @deffnx {C Function} scm_write_line (obj, port) | |
564 | Display @var{obj} and a newline character to @var{port}. If | |
565 | @var{port} is not specified, @code{(current-output-port)} is | |
566 | used. This function is equivalent to: | |
567 | @lisp | |
568 | (display obj [port]) | |
569 | (newline [port]) | |
570 | @end lisp | |
571 | @end deffn | |
572 | ||
28cc8dac | 573 | Some of the aforementioned I/O functions rely on the following C |
07d83abe MV |
574 | primitives. These will mainly be of interest to people hacking Guile |
575 | internals. | |
576 | ||
577 | @deffn {Scheme Procedure} %read-delimited! delims str gobble [port [start [end]]] | |
578 | @deffnx {C Function} scm_read_delimited_x (delims, str, gobble, port, start, end) | |
579 | Read characters from @var{port} into @var{str} until one of the | |
580 | characters in the @var{delims} string is encountered. If | |
581 | @var{gobble} is true, discard the delimiter character; | |
582 | otherwise, leave it in the input stream for the next read. If | |
583 | @var{port} is not specified, use the value of | |
584 | @code{(current-input-port)}. If @var{start} or @var{end} are | |
585 | specified, store data only into the substring of @var{str} | |
586 | bounded by @var{start} and @var{end} (which default to the | |
587 | beginning and end of the string, respectively). | |
588 | ||
589 | Return a pair consisting of the delimiter that terminated the | |
590 | string and the number of characters read. If reading stopped | |
591 | at the end of file, the delimiter returned is the | |
592 | @var{eof-object}; if the string was filled without encountering | |
593 | a delimiter, this value is @code{#f}. | |
594 | @end deffn | |
595 | ||
596 | @deffn {Scheme Procedure} %read-line [port] | |
597 | @deffnx {C Function} scm_read_line (port) | |
598 | Read a newline-terminated line from @var{port}, allocating storage as | |
599 | necessary. The newline terminator (if any) is removed from the string, | |
600 | and a pair consisting of the line and its delimiter is returned. The | |
601 | delimiter may be either a newline or the @var{eof-object}; if | |
602 | @code{%read-line} is called at the end of file, it returns the pair | |
603 | @code{(#<eof> . #<eof>)}. | |
604 | @end deffn | |
605 | ||
606 | @node Block Reading and Writing | |
607 | @subsection Block reading and writing | |
bf5df489 KR |
608 | @cindex Block read/write |
609 | @cindex Port, block read/write | |
07d83abe MV |
610 | |
611 | The Block-string-I/O module can be accessed with: | |
612 | ||
aba0dff5 | 613 | @lisp |
07d83abe | 614 | (use-modules (ice-9 rw)) |
aba0dff5 | 615 | @end lisp |
07d83abe MV |
616 | |
617 | It currently contains procedures that help to implement the | |
618 | @code{(scsh rw)} module in guile-scsh. | |
619 | ||
620 | @deffn {Scheme Procedure} read-string!/partial str [port_or_fdes [start [end]]] | |
621 | @deffnx {C Function} scm_read_string_x_partial (str, port_or_fdes, start, end) | |
622 | Read characters from a port or file descriptor into a | |
623 | string @var{str}. A port must have an underlying file | |
624 | descriptor --- a so-called fport. This procedure is | |
625 | scsh-compatible and can efficiently read large strings. | |
626 | It will: | |
627 | ||
628 | @itemize | |
629 | @item | |
630 | attempt to fill the entire string, unless the @var{start} | |
631 | and/or @var{end} arguments are supplied. i.e., @var{start} | |
632 | defaults to 0 and @var{end} defaults to | |
633 | @code{(string-length str)} | |
634 | @item | |
635 | use the current input port if @var{port_or_fdes} is not | |
636 | supplied. | |
637 | @item | |
638 | return fewer than the requested number of characters in some | |
639 | cases, e.g., on end of file, if interrupted by a signal, or if | |
640 | not all the characters are immediately available. | |
641 | @item | |
642 | wait indefinitely for some input if no characters are | |
643 | currently available, | |
644 | unless the port is in non-blocking mode. | |
645 | @item | |
646 | read characters from the port's input buffers if available, | |
647 | instead from the underlying file descriptor. | |
648 | @item | |
649 | return @code{#f} if end-of-file is encountered before reading | |
650 | any characters, otherwise return the number of characters | |
651 | read. | |
652 | @item | |
653 | return 0 if the port is in non-blocking mode and no characters | |
654 | are immediately available. | |
655 | @item | |
656 | return 0 if the request is for 0 bytes, with no | |
657 | end-of-file check. | |
658 | @end itemize | |
659 | @end deffn | |
660 | ||
661 | @deffn {Scheme Procedure} write-string/partial str [port_or_fdes [start [end]]] | |
662 | @deffnx {C Function} scm_write_string_partial (str, port_or_fdes, start, end) | |
663 | Write characters from a string @var{str} to a port or file | |
664 | descriptor. A port must have an underlying file descriptor | |
665 | --- a so-called fport. This procedure is | |
666 | scsh-compatible and can efficiently write large strings. | |
667 | It will: | |
668 | ||
669 | @itemize | |
670 | @item | |
671 | attempt to write the entire string, unless the @var{start} | |
672 | and/or @var{end} arguments are supplied. i.e., @var{start} | |
673 | defaults to 0 and @var{end} defaults to | |
674 | @code{(string-length str)} | |
675 | @item | |
676 | use the current output port if @var{port_of_fdes} is not | |
677 | supplied. | |
678 | @item | |
679 | in the case of a buffered port, store the characters in the | |
680 | port's output buffer, if all will fit. If they will not fit | |
681 | then any existing buffered characters will be flushed | |
682 | before attempting | |
683 | to write the new characters directly to the underlying file | |
684 | descriptor. If the port is in non-blocking mode and | |
685 | buffered characters can not be flushed immediately, then an | |
686 | @code{EAGAIN} system-error exception will be raised (Note: | |
687 | scsh does not support the use of non-blocking buffered ports.) | |
688 | @item | |
689 | write fewer than the requested number of | |
690 | characters in some cases, e.g., if interrupted by a signal or | |
691 | if not all of the output can be accepted immediately. | |
692 | @item | |
693 | wait indefinitely for at least one character | |
694 | from @var{str} to be accepted by the port, unless the port is | |
695 | in non-blocking mode. | |
696 | @item | |
697 | return the number of characters accepted by the port. | |
698 | @item | |
699 | return 0 if the port is in non-blocking mode and can not accept | |
700 | at least one character from @var{str} immediately | |
701 | @item | |
702 | return 0 immediately if the request size is 0 bytes. | |
703 | @end itemize | |
704 | @end deffn | |
705 | ||
706 | @node Default Ports | |
707 | @subsection Default Ports for Input, Output and Errors | |
bf5df489 KR |
708 | @cindex Default ports |
709 | @cindex Port, default | |
07d83abe MV |
710 | |
711 | @rnindex current-input-port | |
712 | @deffn {Scheme Procedure} current-input-port | |
713 | @deffnx {C Function} scm_current_input_port () | |
34846414 | 714 | @cindex standard input |
07d83abe | 715 | Return the current input port. This is the default port used |
3fa0a042 KR |
716 | by many input procedures. |
717 | ||
718 | Initially this is the @dfn{standard input} in Unix and C terminology. | |
719 | When the standard input is a tty the port is unbuffered, otherwise | |
720 | it's fully buffered. | |
721 | ||
722 | Unbuffered input is good if an application runs an interactive | |
723 | subprocess, since any type-ahead input won't go into Guile's buffer | |
9782da8a | 724 | and be unavailable to the subprocess. |
3fa0a042 KR |
725 | |
726 | Note that Guile buffering is completely separate from the tty ``line | |
9782da8a KR |
727 | discipline''. In the usual cooked mode on a tty Guile only sees a |
728 | line of input once the user presses @key{Return}. | |
07d83abe MV |
729 | @end deffn |
730 | ||
731 | @rnindex current-output-port | |
732 | @deffn {Scheme Procedure} current-output-port | |
733 | @deffnx {C Function} scm_current_output_port () | |
34846414 | 734 | @cindex standard output |
07d83abe | 735 | Return the current output port. This is the default port used |
3fa0a042 KR |
736 | by many output procedures. |
737 | ||
738 | Initially this is the @dfn{standard output} in Unix and C terminology. | |
739 | When the standard output is a tty this port is unbuffered, otherwise | |
740 | it's fully buffered. | |
741 | ||
742 | Unbuffered output to a tty is good for ensuring progress output or a | |
743 | prompt is seen. But an application which always prints whole lines | |
744 | could change to line buffered, or an application with a lot of output | |
745 | could go fully buffered and perhaps make explicit @code{force-output} | |
746 | calls (@pxref{Writing}) at selected points. | |
07d83abe MV |
747 | @end deffn |
748 | ||
749 | @deffn {Scheme Procedure} current-error-port | |
750 | @deffnx {C Function} scm_current_error_port () | |
34846414 | 751 | @cindex standard error output |
3fa0a042 KR |
752 | Return the port to which errors and warnings should be sent. |
753 | ||
754 | Initially this is the @dfn{standard error} in Unix and C terminology. | |
755 | When the standard error is a tty this port is unbuffered, otherwise | |
756 | it's fully buffered. | |
07d83abe MV |
757 | @end deffn |
758 | ||
759 | @deffn {Scheme Procedure} set-current-input-port port | |
760 | @deffnx {Scheme Procedure} set-current-output-port port | |
761 | @deffnx {Scheme Procedure} set-current-error-port port | |
762 | @deffnx {C Function} scm_set_current_input_port (port) | |
763 | @deffnx {C Function} scm_set_current_output_port (port) | |
764 | @deffnx {C Function} scm_set_current_error_port (port) | |
765 | Change the ports returned by @code{current-input-port}, | |
766 | @code{current-output-port} and @code{current-error-port}, respectively, | |
767 | so that they use the supplied @var{port} for input or output. | |
768 | @end deffn | |
769 | ||
661ae7ab MV |
770 | @deftypefn {C Function} void scm_dynwind_current_input_port (SCM port) |
771 | @deftypefnx {C Function} void scm_dynwind_current_output_port (SCM port) | |
772 | @deftypefnx {C Function} void scm_dynwind_current_error_port (SCM port) | |
07d83abe | 773 | These functions must be used inside a pair of calls to |
661ae7ab MV |
774 | @code{scm_dynwind_begin} and @code{scm_dynwind_end} (@pxref{Dynamic |
775 | Wind}). During the dynwind context, the indicated port is set to | |
07d83abe MV |
776 | @var{port}. |
777 | ||
778 | More precisely, the current port is swapped with a `backup' value | |
661ae7ab | 779 | whenever the dynwind context is entered or left. The backup value is |
07d83abe MV |
780 | initialized with the @var{port} argument. |
781 | @end deftypefn | |
782 | ||
783 | @node Port Types | |
784 | @subsection Types of Port | |
bf5df489 KR |
785 | @cindex Types of ports |
786 | @cindex Port, types | |
07d83abe MV |
787 | |
788 | [Types of port; how to make them.] | |
789 | ||
790 | @menu | |
791 | * File Ports:: Ports on an operating system file. | |
792 | * String Ports:: Ports on a Scheme string. | |
793 | * Soft Ports:: Ports on arbitrary Scheme procedures. | |
794 | * Void Ports:: Ports on nothing at all. | |
795 | @end menu | |
796 | ||
797 | ||
798 | @node File Ports | |
799 | @subsubsection File Ports | |
bf5df489 KR |
800 | @cindex File port |
801 | @cindex Port, file | |
07d83abe MV |
802 | |
803 | The following procedures are used to open file ports. | |
804 | See also @ref{Ports and File Descriptors, open}, for an interface | |
805 | to the Unix @code{open} system call. | |
806 | ||
807 | Most systems have limits on how many files can be open, so it's | |
808 | strongly recommended that file ports be closed explicitly when no | |
809 | longer required (@pxref{Ports}). | |
810 | ||
811 | @deffn {Scheme Procedure} open-file filename mode | |
812 | @deffnx {C Function} scm_open_file (filename, mode) | |
813 | Open the file whose name is @var{filename}, and return a port | |
814 | representing that file. The attributes of the port are | |
815 | determined by the @var{mode} string. The way in which this is | |
816 | interpreted is similar to C stdio. The first character must be | |
817 | one of the following: | |
c755b861 | 818 | |
07d83abe MV |
819 | @table @samp |
820 | @item r | |
821 | Open an existing file for input. | |
822 | @item w | |
823 | Open a file for output, creating it if it doesn't already exist | |
824 | or removing its contents if it does. | |
825 | @item a | |
826 | Open a file for output, creating it if it doesn't already | |
827 | exist. All writes to the port will go to the end of the file. | |
828 | The "append mode" can be turned off while the port is in use | |
829 | @pxref{Ports and File Descriptors, fcntl} | |
830 | @end table | |
c755b861 | 831 | |
07d83abe | 832 | The following additional characters can be appended: |
c755b861 | 833 | |
07d83abe MV |
834 | @table @samp |
835 | @item + | |
836 | Open the port for both input and output. E.g., @code{r+}: open | |
837 | an existing file for both input and output. | |
838 | @item 0 | |
839 | Create an "unbuffered" port. In this case input and output | |
840 | operations are passed directly to the underlying port | |
841 | implementation without additional buffering. This is likely to | |
842 | slow down I/O operations. The buffering mode can be changed | |
843 | while a port is in use @pxref{Ports and File Descriptors, | |
844 | setvbuf} | |
845 | @item l | |
846 | Add line-buffering to the port. The port output buffer will be | |
847 | automatically flushed whenever a newline character is written. | |
c755b861 KR |
848 | @item b |
849 | Use binary mode. On DOS systems the default text mode converts CR+LF | |
850 | in the file to newline for the program, whereas binary mode reads and | |
851 | writes all bytes unchanged. On Unix-like systems there is no such | |
852 | distinction, text files already contain just newlines and no | |
853 | conversion is ever made. The @code{b} flag is accepted on all | |
854 | systems, but has no effect on Unix-like systems. | |
855 | ||
856 | (For reference, Guile leaves text versus binary up to the C library, | |
857 | @code{b} here just adds @code{O_BINARY} to the underlying @code{open} | |
858 | call, when that flag is available.) | |
211683cc MG |
859 | |
860 | Also, open the file using the 8-bit character encoding "ISO-8859-1", | |
861 | ignoring any coding declaration or port encoding. | |
862 | ||
863 | Note that, when reading or writing binary data with ports, the | |
864 | bytevector ports in the @code{(rnrs io ports)} module are preferred, | |
865 | as they return vectors, and not strings (@pxref{R6RS I/O Ports}). | |
07d83abe | 866 | @end table |
c755b861 | 867 | |
092bdcc4 KR |
868 | If a file cannot be opened with the access |
869 | requested, @code{open-file} throws an exception. | |
870 | ||
211683cc MG |
871 | When the file is opened, this procedure will scan for a coding |
872 | declaration (@pxref{Character Encoding of Source Files}). If present | |
873 | will use that encoding for interpreting the file. Otherwise, the | |
ecb87335 | 874 | port's encoding will be used. To suppress this behavior, open |
211683cc MG |
875 | the file in binary mode and then set the port encoding explicitly |
876 | using @code{set-port-encoding!}. | |
877 | ||
07d83abe MV |
878 | In theory we could create read/write ports which were buffered |
879 | in one direction only. However this isn't included in the | |
092bdcc4 | 880 | current interfaces. |
07d83abe MV |
881 | @end deffn |
882 | ||
883 | @rnindex open-input-file | |
884 | @deffn {Scheme Procedure} open-input-file filename | |
885 | Open @var{filename} for input. Equivalent to | |
aba0dff5 | 886 | @lisp |
07d83abe | 887 | (open-file @var{filename} "r") |
aba0dff5 | 888 | @end lisp |
07d83abe MV |
889 | @end deffn |
890 | ||
891 | @rnindex open-output-file | |
892 | @deffn {Scheme Procedure} open-output-file filename | |
893 | Open @var{filename} for output. Equivalent to | |
aba0dff5 | 894 | @lisp |
07d83abe | 895 | (open-file @var{filename} "w") |
aba0dff5 | 896 | @end lisp |
07d83abe MV |
897 | @end deffn |
898 | ||
899 | @deffn {Scheme Procedure} call-with-input-file filename proc | |
900 | @deffnx {Scheme Procedure} call-with-output-file filename proc | |
901 | @rnindex call-with-input-file | |
902 | @rnindex call-with-output-file | |
903 | Open @var{filename} for input or output, and call @code{(@var{proc} | |
904 | port)} with the resulting port. Return the value returned by | |
905 | @var{proc}. @var{filename} is opened as per @code{open-input-file} or | |
28cc8dac | 906 | @code{open-output-file} respectively, and an error is signaled if it |
07d83abe MV |
907 | cannot be opened. |
908 | ||
909 | When @var{proc} returns, the port is closed. If @var{proc} does not | |
28cc8dac | 910 | return (e.g.@: if it throws an error), then the port might not be |
07d83abe MV |
911 | closed automatically, though it will be garbage collected in the usual |
912 | way if not otherwise referenced. | |
913 | @end deffn | |
914 | ||
915 | @deffn {Scheme Procedure} with-input-from-file filename thunk | |
916 | @deffnx {Scheme Procedure} with-output-to-file filename thunk | |
917 | @deffnx {Scheme Procedure} with-error-to-file filename thunk | |
918 | @rnindex with-input-from-file | |
919 | @rnindex with-output-to-file | |
920 | Open @var{filename} and call @code{(@var{thunk})} with the new port | |
921 | setup as respectively the @code{current-input-port}, | |
922 | @code{current-output-port}, or @code{current-error-port}. Return the | |
923 | value returned by @var{thunk}. @var{filename} is opened as per | |
924 | @code{open-input-file} or @code{open-output-file} respectively, and an | |
28cc8dac | 925 | error is signaled if it cannot be opened. |
07d83abe MV |
926 | |
927 | When @var{thunk} returns, the port is closed and the previous setting | |
928 | of the respective current port is restored. | |
929 | ||
930 | The current port setting is managed with @code{dynamic-wind}, so the | |
931 | previous value is restored no matter how @var{thunk} exits (eg.@: an | |
932 | exception), and if @var{thunk} is re-entered (via a captured | |
933 | continuation) then it's set again to the @var{FILENAME} port. | |
934 | ||
935 | The port is closed when @var{thunk} returns normally, but not when | |
936 | exited via an exception or new continuation. This ensures it's still | |
937 | ready for use if @var{thunk} is re-entered by a captured continuation. | |
938 | Of course the port is always garbage collected and closed in the usual | |
939 | way when no longer referenced anywhere. | |
940 | @end deffn | |
941 | ||
942 | @deffn {Scheme Procedure} port-mode port | |
943 | @deffnx {C Function} scm_port_mode (port) | |
944 | Return the port modes associated with the open port @var{port}. | |
945 | These will not necessarily be identical to the modes used when | |
946 | the port was opened, since modes such as "append" which are | |
947 | used only during port creation are not retained. | |
948 | @end deffn | |
949 | ||
950 | @deffn {Scheme Procedure} port-filename port | |
951 | @deffnx {C Function} scm_port_filename (port) | |
ac012a27 AW |
952 | Return the filename associated with @var{port}, or @code{#f} if no |
953 | filename is associated with the port. | |
e55abf41 KR |
954 | |
955 | @var{port} must be open, @code{port-filename} cannot be used once the | |
956 | port is closed. | |
07d83abe MV |
957 | @end deffn |
958 | ||
959 | @deffn {Scheme Procedure} set-port-filename! port filename | |
960 | @deffnx {C Function} scm_set_port_filename_x (port, filename) | |
961 | Change the filename associated with @var{port}, using the current input | |
962 | port if none is specified. Note that this does not change the port's | |
963 | source of data, but only the value that is returned by | |
964 | @code{port-filename} and reported in diagnostic output. | |
965 | @end deffn | |
966 | ||
967 | @deffn {Scheme Procedure} file-port? obj | |
968 | @deffnx {C Function} scm_file_port_p (obj) | |
969 | Determine whether @var{obj} is a port that is related to a file. | |
970 | @end deffn | |
971 | ||
972 | ||
973 | @node String Ports | |
974 | @subsubsection String Ports | |
bf5df489 KR |
975 | @cindex String port |
976 | @cindex Port, string | |
07d83abe | 977 | |
ecb87335 | 978 | The following allow string ports to be opened by analogy to R4RS |
07d83abe MV |
979 | file port facilities: |
980 | ||
28cc8dac MG |
981 | With string ports, the port-encoding is treated differently than other |
982 | types of ports. When string ports are created, they do not inherit a | |
983 | character encoding from the current locale. They are given a | |
984 | default locale that allows them to handle all valid string characters. | |
985 | Typically one should not modify a string port's character encoding | |
986 | away from its default. | |
987 | ||
07d83abe MV |
988 | @deffn {Scheme Procedure} call-with-output-string proc |
989 | @deffnx {C Function} scm_call_with_output_string (proc) | |
990 | Calls the one-argument procedure @var{proc} with a newly created output | |
991 | port. When the function returns, the string composed of the characters | |
992 | written into the port is returned. @var{proc} should not close the port. | |
7b041912 LC |
993 | |
994 | Note that which characters can be written to a string port depend on the port's | |
995 | encoding. The default encoding of string ports is specified by the | |
996 | @code{%default-port-encoding} fluid (@pxref{Ports, | |
997 | @code{%default-port-encoding}}). For instance, it is an error to write Greek | |
998 | letter alpha to an ISO-8859-1-encoded string port since this character cannot be | |
999 | represented with ISO-8859-1: | |
1000 | ||
1001 | @example | |
1002 | (define alpha (integer->char #x03b1)) ; GREEK SMALL LETTER ALPHA | |
1003 | ||
1004 | (with-fluids ((%default-port-encoding "ISO-8859-1")) | |
1005 | (call-with-output-string | |
1006 | (lambda (p) | |
1007 | (display alpha p)))) | |
1008 | ||
1009 | @result{} | |
1010 | Throw to key `encoding-error' | |
1011 | @end example | |
1012 | ||
1013 | Changing the string port's encoding to a Unicode-capable encoding such as UTF-8 | |
1014 | solves the problem. | |
07d83abe MV |
1015 | @end deffn |
1016 | ||
1017 | @deffn {Scheme Procedure} call-with-input-string string proc | |
1018 | @deffnx {C Function} scm_call_with_input_string (string, proc) | |
1019 | Calls the one-argument procedure @var{proc} with a newly | |
1020 | created input port from which @var{string}'s contents may be | |
1021 | read. The value yielded by the @var{proc} is returned. | |
1022 | @end deffn | |
1023 | ||
1024 | @deffn {Scheme Procedure} with-output-to-string thunk | |
1025 | Calls the zero-argument procedure @var{thunk} with the current output | |
1026 | port set temporarily to a new string port. It returns a string | |
1027 | composed of the characters written to the current output. | |
7b041912 LC |
1028 | |
1029 | See @code{call-with-output-string} above for character encoding considerations. | |
07d83abe MV |
1030 | @end deffn |
1031 | ||
1032 | @deffn {Scheme Procedure} with-input-from-string string thunk | |
1033 | Calls the zero-argument procedure @var{thunk} with the current input | |
1034 | port set temporarily to a string port opened on the specified | |
1035 | @var{string}. The value yielded by @var{thunk} is returned. | |
1036 | @end deffn | |
1037 | ||
1038 | @deffn {Scheme Procedure} open-input-string str | |
1039 | @deffnx {C Function} scm_open_input_string (str) | |
1040 | Take a string and return an input port that delivers characters | |
1041 | from the string. The port can be closed by | |
1042 | @code{close-input-port}, though its storage will be reclaimed | |
1043 | by the garbage collector if it becomes inaccessible. | |
1044 | @end deffn | |
1045 | ||
1046 | @deffn {Scheme Procedure} open-output-string | |
1047 | @deffnx {C Function} scm_open_output_string () | |
1048 | Return an output port that will accumulate characters for | |
1049 | retrieval by @code{get-output-string}. The port can be closed | |
1050 | by the procedure @code{close-output-port}, though its storage | |
1051 | will be reclaimed by the garbage collector if it becomes | |
1052 | inaccessible. | |
1053 | @end deffn | |
1054 | ||
1055 | @deffn {Scheme Procedure} get-output-string port | |
1056 | @deffnx {C Function} scm_get_output_string (port) | |
1057 | Given an output port created by @code{open-output-string}, | |
1058 | return a string consisting of the characters that have been | |
1059 | output to the port so far. | |
1060 | ||
1061 | @code{get-output-string} must be used before closing @var{port}, once | |
1062 | closed the string cannot be obtained. | |
1063 | @end deffn | |
1064 | ||
1065 | A string port can be used in many procedures which accept a port | |
1066 | but which are not dependent on implementation details of fports. | |
1067 | E.g., seeking and truncating will work on a string port, | |
1068 | but trying to extract the file descriptor number will fail. | |
1069 | ||
1070 | ||
1071 | @node Soft Ports | |
1072 | @subsubsection Soft Ports | |
bf5df489 KR |
1073 | @cindex Soft port |
1074 | @cindex Port, soft | |
07d83abe MV |
1075 | |
1076 | A @dfn{soft-port} is a port based on a vector of procedures capable of | |
1077 | accepting or delivering characters. It allows emulation of I/O ports. | |
1078 | ||
1079 | @deffn {Scheme Procedure} make-soft-port pv modes | |
1080 | @deffnx {C Function} scm_make_soft_port (pv, modes) | |
1081 | Return a port capable of receiving or delivering characters as | |
1082 | specified by the @var{modes} string (@pxref{File Ports, | |
1083 | open-file}). @var{pv} must be a vector of length 5 or 6. Its | |
1084 | components are as follows: | |
1085 | ||
1086 | @enumerate 0 | |
1087 | @item | |
1088 | procedure accepting one character for output | |
1089 | @item | |
1090 | procedure accepting a string for output | |
1091 | @item | |
1092 | thunk for flushing output | |
1093 | @item | |
1094 | thunk for getting one character | |
1095 | @item | |
1096 | thunk for closing port (not by garbage collection) | |
1097 | @item | |
1098 | (if present and not @code{#f}) thunk for computing the number of | |
1099 | characters that can be read from the port without blocking. | |
1100 | @end enumerate | |
1101 | ||
1102 | For an output-only port only elements 0, 1, 2, and 4 need be | |
1103 | procedures. For an input-only port only elements 3 and 4 need | |
1104 | be procedures. Thunks 2 and 4 can instead be @code{#f} if | |
1105 | there is no useful operation for them to perform. | |
1106 | ||
1107 | If thunk 3 returns @code{#f} or an @code{eof-object} | |
1108 | (@pxref{Input, eof-object?, ,r5rs, The Revised^5 Report on | |
1109 | Scheme}) it indicates that the port has reached end-of-file. | |
1110 | For example: | |
1111 | ||
1112 | @lisp | |
1113 | (define stdout (current-output-port)) | |
1114 | (define p (make-soft-port | |
1115 | (vector | |
1116 | (lambda (c) (write c stdout)) | |
1117 | (lambda (s) (display s stdout)) | |
1118 | (lambda () (display "." stdout)) | |
1119 | (lambda () (char-upcase (read-char))) | |
1120 | (lambda () (display "@@" stdout))) | |
1121 | "rw")) | |
1122 | ||
1123 | (write p p) @result{} #<input-output: soft 8081e20> | |
1124 | @end lisp | |
1125 | @end deffn | |
1126 | ||
1127 | ||
1128 | @node Void Ports | |
1129 | @subsubsection Void Ports | |
bf5df489 KR |
1130 | @cindex Void port |
1131 | @cindex Port, void | |
07d83abe MV |
1132 | |
1133 | This kind of port causes any data to be discarded when written to, and | |
1134 | always returns the end-of-file object when read from. | |
1135 | ||
1136 | @deffn {Scheme Procedure} %make-void-port mode | |
1137 | @deffnx {C Function} scm_sys_make_void_port (mode) | |
1138 | Create and return a new void port. A void port acts like | |
1139 | @file{/dev/null}. The @var{mode} argument | |
1140 | specifies the input/output modes for this port: see the | |
1141 | documentation for @code{open-file} in @ref{File Ports}. | |
1142 | @end deffn | |
1143 | ||
1144 | ||
b242715b LC |
1145 | @node R6RS I/O Ports |
1146 | @subsection R6RS I/O Ports | |
1147 | ||
1148 | @cindex R6RS | |
1149 | @cindex R6RS ports | |
1150 | ||
1151 | The I/O port API of the @uref{http://www.r6rs.org/, Revised Report^6 on | |
1152 | the Algorithmic Language Scheme (R6RS)} is provided by the @code{(rnrs | |
1153 | io ports)} module. It provides features, such as binary I/O and Unicode | |
1154 | string I/O, that complement or refine Guile's historical port API | |
1155 | presented above (@pxref{Input and Output}). | |
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 | |
1161 | * R6RS End-of-File:: The end-of-file object. | |
1162 | * R6RS Port Manipulation:: Manipulating R6RS ports. | |
1163 | * R6RS Binary Input:: Binary input. | |
1164 | * R6RS Binary Output:: Binary output. | |
1165 | @end menu | |
1166 | ||
1167 | @node R6RS End-of-File | |
1168 | @subsubsection The End-of-File Object | |
1169 | ||
1170 | @cindex EOF | |
1171 | @cindex end-of-file | |
1172 | ||
1173 | R5RS' @code{eof-object?} procedure is provided by the @code{(rnrs io | |
1174 | ports)} module: | |
1175 | ||
1176 | @deffn {Scheme Procedure} eof-object? obj | |
1177 | @deffnx {C Function} scm_eof_object_p (obj) | |
1178 | Return true if @var{obj} is the end-of-file (EOF) object. | |
1179 | @end deffn | |
1180 | ||
1181 | In addition, the following procedure is provided: | |
1182 | ||
1183 | @deffn {Scheme Procedure} eof-object | |
1184 | @deffnx {C Function} scm_eof_object () | |
1185 | Return the end-of-file (EOF) object. | |
1186 | ||
1187 | @lisp | |
1188 | (eof-object? (eof-object)) | |
1189 | @result{} #t | |
1190 | @end lisp | |
1191 | @end deffn | |
1192 | ||
1193 | ||
1194 | @node R6RS Port Manipulation | |
1195 | @subsubsection Port Manipulation | |
1196 | ||
1197 | The procedures listed below operate on any kind of R6RS I/O port. | |
1198 | ||
1199 | @deffn {Scheme Procedure} port-position port | |
1200 | If @var{port} supports it (see below), return the offset (an integer) | |
1201 | indicating where the next octet will be read from/written to in | |
1202 | @var{port}. If @var{port} does not support this operation, an error | |
1203 | condition is raised. | |
1204 | ||
1205 | This is similar to Guile's @code{seek} procedure with the | |
1206 | @code{SEEK_CUR} argument (@pxref{Random Access}). | |
1207 | @end deffn | |
1208 | ||
1209 | @deffn {Scheme Procedure} port-has-port-position? port | |
1210 | Return @code{#t} is @var{port} supports @code{port-position}. | |
1211 | @end deffn | |
1212 | ||
1213 | @deffn {Scheme Procedure} set-port-position! port offset | |
1214 | If @var{port} supports it (see below), set the position where the next | |
1215 | octet will be read from/written to @var{port} to @var{offset} (an | |
1216 | integer). If @var{port} does not support this operation, an error | |
1217 | condition is raised. | |
1218 | ||
1219 | This is similar to Guile's @code{seek} procedure with the | |
1220 | @code{SEEK_SET} argument (@pxref{Random Access}). | |
1221 | @end deffn | |
1222 | ||
1223 | @deffn {Scheme Procedure} port-has-set-port-position!? port | |
1224 | Return @code{#t} is @var{port} supports @code{set-port-position!}. | |
1225 | @end deffn | |
1226 | ||
1227 | @deffn {Scheme Procedure} call-with-port port proc | |
1228 | Call @var{proc}, passing it @var{port} and closing @var{port} upon exit | |
1229 | of @var{proc}. Return the return values of @var{proc}. | |
1230 | @end deffn | |
1231 | ||
1232 | ||
1233 | @node R6RS Binary Input | |
1234 | @subsubsection Binary Input | |
1235 | ||
1236 | @cindex binary input | |
1237 | ||
1238 | R6RS binary input ports can be created with the procedures described | |
1239 | below. | |
1240 | ||
1241 | @deffn {Scheme Procedure} open-bytevector-input-port bv [transcoder] | |
1242 | @deffnx {C Function} scm_open_bytevector_input_port (bv, transcoder) | |
1243 | Return an input port whose contents are drawn from bytevector @var{bv} | |
1244 | (@pxref{Bytevectors}). | |
1245 | ||
1246 | @c FIXME: Update description when implemented. | |
1247 | The @var{transcoder} argument is currently not supported. | |
1248 | @end deffn | |
1249 | ||
1250 | @cindex custom binary input ports | |
1251 | ||
1252 | @deffn {Scheme Procedure} make-custom-binary-input-port id read! get-position set-position! close | |
1253 | @deffnx {C Function} scm_make_custom_binary_input_port (id, read!, get-position, set-position!, close) | |
1254 | Return a new custom binary input port@footnote{This is similar in spirit | |
1255 | to Guile's @dfn{soft ports} (@pxref{Soft Ports}).} named @var{id} (a | |
1256 | string) whose input is drained by invoking @var{read!} and passing it a | |
1257 | bytevector, an index where bytes should be written, and the number of | |
1258 | bytes to read. The @code{read!} procedure must return an integer | |
1259 | indicating the number of bytes read, or @code{0} to indicate the | |
1260 | end-of-file. | |
1261 | ||
1262 | Optionally, if @var{get-position} is not @code{#f}, it must be a thunk | |
1263 | that will be called when @var{port-position} is invoked on the custom | |
1264 | binary port and should return an integer indicating the position within | |
1265 | the underlying data stream; if @var{get-position} was not supplied, the | |
1266 | returned port does not support @var{port-position}. | |
1267 | ||
1268 | Likewise, if @var{set-position!} is not @code{#f}, it should be a | |
1269 | one-argument procedure. When @var{set-port-position!} is invoked on the | |
1270 | custom binary input port, @var{set-position!} is passed an integer | |
1271 | indicating the position of the next byte is to read. | |
1272 | ||
1273 | Finally, if @var{close} is not @code{#f}, it must be a thunk. It is | |
1274 | invoked when the custom binary input port is closed. | |
1275 | ||
1276 | Using a custom binary input port, the @code{open-bytevector-input-port} | |
1277 | procedure could be implemented as follows: | |
1278 | ||
1279 | @lisp | |
1280 | (define (open-bytevector-input-port source) | |
1281 | (define position 0) | |
1282 | (define length (bytevector-length source)) | |
1283 | ||
1284 | (define (read! bv start count) | |
1285 | (let ((count (min count (- length position)))) | |
1286 | (bytevector-copy! source position | |
1287 | bv start count) | |
1288 | (set! position (+ position count)) | |
1289 | count)) | |
1290 | ||
1291 | (define (get-position) position) | |
1292 | ||
1293 | (define (set-position! new-position) | |
1294 | (set! position new-position)) | |
1295 | ||
1296 | (make-custom-binary-input-port "the port" read! | |
1297 | get-position | |
1298 | set-position!)) | |
1299 | ||
1300 | (read (open-bytevector-input-port (string->utf8 "hello"))) | |
1301 | @result{} hello | |
1302 | @end lisp | |
1303 | @end deffn | |
1304 | ||
1305 | @cindex binary input | |
1306 | Binary input is achieved using the procedures below: | |
1307 | ||
1308 | @deffn {Scheme Procedure} get-u8 port | |
1309 | @deffnx {C Function} scm_get_u8 (port) | |
1310 | Return an octet read from @var{port}, a binary input port, blocking as | |
1311 | necessary, or the end-of-file object. | |
1312 | @end deffn | |
1313 | ||
1314 | @deffn {Scheme Procedure} lookahead-u8 port | |
1315 | @deffnx {C Function} scm_lookahead_u8 (port) | |
1316 | Like @code{get-u8} but does not update @var{port}'s position to point | |
1317 | past the octet. | |
1318 | @end deffn | |
1319 | ||
1320 | @deffn {Scheme Procedure} get-bytevector-n port count | |
1321 | @deffnx {C Function} scm_get_bytevector_n (port, count) | |
1322 | Read @var{count} octets from @var{port}, blocking as necessary and | |
1323 | return a bytevector containing the octets read. If fewer bytes are | |
1324 | available, a bytevector smaller than @var{count} is returned. | |
1325 | @end deffn | |
1326 | ||
1327 | @deffn {Scheme Procedure} get-bytevector-n! port bv start count | |
1328 | @deffnx {C Function} scm_get_bytevector_n_x (port, bv, start, count) | |
1329 | Read @var{count} bytes from @var{port} and store them in @var{bv} | |
1330 | starting at index @var{start}. Return either the number of bytes | |
1331 | actually read or the end-of-file object. | |
1332 | @end deffn | |
1333 | ||
1334 | @deffn {Scheme Procedure} get-bytevector-some port | |
1335 | @deffnx {C Function} scm_get_bytevector_some (port) | |
1336 | Read from @var{port}, blocking as necessary, until data are available or | |
1337 | and end-of-file is reached. Return either a new bytevector containing | |
1338 | the data read or the end-of-file object. | |
1339 | @end deffn | |
1340 | ||
1341 | @deffn {Scheme Procedure} get-bytevector-all port | |
1342 | @deffnx {C Function} scm_get_bytevector_all (port) | |
1343 | Read from @var{port}, blocking as necessary, until the end-of-file is | |
1344 | reached. Return either a new bytevector containing the data read or the | |
1345 | end-of-file object (if no data were available). | |
1346 | @end deffn | |
1347 | ||
1348 | @node R6RS Binary Output | |
1349 | @subsubsection Binary Output | |
1350 | ||
1351 | Binary output ports can be created with the procedures below. | |
1352 | ||
1353 | @deffn {Scheme Procedure} open-bytevector-output-port [transcoder] | |
1354 | @deffnx {C Function} scm_open_bytevector_output_port (transcoder) | |
1355 | Return two values: a binary output port and a procedure. The latter | |
1356 | should be called with zero arguments to obtain a bytevector containing | |
1357 | the data accumulated by the port, as illustrated below. | |
1358 | ||
1359 | @lisp | |
1360 | (call-with-values | |
1361 | (lambda () | |
1362 | (open-bytevector-output-port)) | |
1363 | (lambda (port get-bytevector) | |
1364 | (display "hello" port) | |
1365 | (get-bytevector))) | |
1366 | ||
1367 | @result{} #vu8(104 101 108 108 111) | |
1368 | @end lisp | |
1369 | ||
1370 | @c FIXME: Update description when implemented. | |
1371 | The @var{transcoder} argument is currently not supported. | |
1372 | @end deffn | |
1373 | ||
1374 | @cindex custom binary output ports | |
1375 | ||
1376 | @deffn {Scheme Procedure} make-custom-binary-output-port id write! get-position set-position! close | |
1377 | @deffnx {C Function} scm_make_custom_binary_output_port (id, write!, get-position, set-position!, close) | |
1378 | Return a new custom binary output port named @var{id} (a string) whose | |
1379 | output is sunk by invoking @var{write!} and passing it a bytevector, an | |
1380 | index where bytes should be read from this bytevector, and the number of | |
1381 | bytes to be ``written''. The @code{write!} procedure must return an | |
1382 | integer indicating the number of bytes actually written; when it is | |
1383 | passed @code{0} as the number of bytes to write, it should behave as | |
1384 | though an end-of-file was sent to the byte sink. | |
1385 | ||
1386 | The other arguments are as for @code{make-custom-binary-input-port} | |
1387 | (@pxref{R6RS Binary Input, @code{make-custom-binary-input-port}}). | |
1388 | @end deffn | |
1389 | ||
1390 | @cindex binary output | |
1391 | Writing to a binary output port can be done using the following | |
1392 | procedures: | |
1393 | ||
1394 | @deffn {Scheme Procedure} put-u8 port octet | |
1395 | @deffnx {C Function} scm_put_u8 (port, octet) | |
1396 | Write @var{octet}, an integer in the 0--255 range, to @var{port}, a | |
1397 | binary output port. | |
1398 | @end deffn | |
1399 | ||
1400 | @deffn {Scheme Procedure} put-bytevector port bv [start [count]] | |
1401 | @deffnx {C Function} scm_put_bytevector (port, bv, start, count) | |
1402 | Write the contents of @var{bv} to @var{port}, optionally starting at | |
1403 | index @var{start} and limiting to @var{count} octets. | |
1404 | @end deffn | |
1405 | ||
1406 | ||
07d83abe MV |
1407 | @node I/O Extensions |
1408 | @subsection Using and Extending Ports in C | |
1409 | ||
1410 | @menu | |
1411 | * C Port Interface:: Using ports from C. | |
1412 | * Port Implementation:: How to implement a new port type in C. | |
1413 | @end menu | |
1414 | ||
1415 | ||
1416 | @node C Port Interface | |
1417 | @subsubsection C Port Interface | |
bf5df489 KR |
1418 | @cindex C port interface |
1419 | @cindex Port, C interface | |
07d83abe MV |
1420 | |
1421 | This section describes how to use Scheme ports from C. | |
1422 | ||
1423 | @subsubheading Port basics | |
1424 | ||
3081aee1 KR |
1425 | @cindex ptob |
1426 | @tindex scm_ptob_descriptor | |
1427 | @tindex scm_port | |
1428 | @findex SCM_PTAB_ENTRY | |
1429 | @findex SCM_PTOBNUM | |
1430 | @vindex scm_ptobs | |
07d83abe MV |
1431 | There are two main data structures. A port type object (ptob) is of |
1432 | type @code{scm_ptob_descriptor}. A port instance is of type | |
1433 | @code{scm_port}. Given an @code{SCM} variable which points to a port, | |
1434 | the corresponding C port object can be obtained using the | |
1435 | @code{SCM_PTAB_ENTRY} macro. The ptob can be obtained by using | |
1436 | @code{SCM_PTOBNUM} to give an index into the @code{scm_ptobs} | |
1437 | global array. | |
1438 | ||
1439 | @subsubheading Port buffers | |
1440 | ||
1441 | An input port always has a read buffer and an output port always has a | |
1442 | write buffer. However the size of these buffers is not guaranteed to be | |
1443 | more than one byte (e.g., the @code{shortbuf} field in @code{scm_port} | |
1444 | which is used when no other buffer is allocated). The way in which the | |
1445 | buffers are allocated depends on the implementation of the ptob. For | |
1446 | example in the case of an fport, buffers may be allocated with malloc | |
1447 | when the port is created, but in the case of an strport the underlying | |
1448 | string is used as the buffer. | |
1449 | ||
1450 | @subsubheading The @code{rw_random} flag | |
1451 | ||
1452 | Special treatment is required for ports which can be seeked at random. | |
1453 | Before various operations, such as seeking the port or changing from | |
1454 | input to output on a bidirectional port or vice versa, the port | |
1455 | implementation must be given a chance to update its state. The write | |
1456 | buffer is updated by calling the @code{flush} ptob procedure and the | |
1457 | input buffer is updated by calling the @code{end_input} ptob procedure. | |
1458 | In the case of an fport, @code{flush} causes buffered output to be | |
1459 | written to the file descriptor, while @code{end_input} causes the | |
1460 | descriptor position to be adjusted to account for buffered input which | |
1461 | was never read. | |
1462 | ||
1463 | The special treatment must be performed if the @code{rw_random} flag in | |
1464 | the port is non-zero. | |
1465 | ||
1466 | @subsubheading The @code{rw_active} variable | |
1467 | ||
1468 | The @code{rw_active} variable in the port is only used if | |
1469 | @code{rw_random} is set. It's defined as an enum with the following | |
1470 | values: | |
1471 | ||
1472 | @table @code | |
1473 | @item SCM_PORT_READ | |
1474 | the read buffer may have unread data. | |
1475 | ||
1476 | @item SCM_PORT_WRITE | |
1477 | the write buffer may have unwritten data. | |
1478 | ||
1479 | @item SCM_PORT_NEITHER | |
1480 | neither the write nor the read buffer has data. | |
1481 | @end table | |
1482 | ||
1483 | @subsubheading Reading from a port. | |
1484 | ||
1485 | To read from a port, it's possible to either call existing libguile | |
1486 | procedures such as @code{scm_getc} and @code{scm_read_line} or to read | |
1487 | data from the read buffer directly. Reading from the buffer involves | |
1488 | the following steps: | |
1489 | ||
1490 | @enumerate | |
1491 | @item | |
1492 | Flush output on the port, if @code{rw_active} is @code{SCM_PORT_WRITE}. | |
1493 | ||
1494 | @item | |
1495 | Fill the read buffer, if it's empty, using @code{scm_fill_input}. | |
1496 | ||
1497 | @item Read the data from the buffer and update the read position in | |
1498 | the buffer. Steps 2) and 3) may be repeated as many times as required. | |
1499 | ||
1500 | @item Set rw_active to @code{SCM_PORT_READ} if @code{rw_random} is set. | |
1501 | ||
1502 | @item update the port's line and column counts. | |
1503 | @end enumerate | |
1504 | ||
1505 | @subsubheading Writing to a port. | |
1506 | ||
1507 | To write data to a port, calling @code{scm_lfwrite} should be sufficient for | |
1508 | most purposes. This takes care of the following steps: | |
1509 | ||
1510 | @enumerate | |
1511 | @item | |
1512 | End input on the port, if @code{rw_active} is @code{SCM_PORT_READ}. | |
1513 | ||
1514 | @item | |
1515 | Pass the data to the ptob implementation using the @code{write} ptob | |
1516 | procedure. The advantage of using the ptob @code{write} instead of | |
1517 | manipulating the write buffer directly is that it allows the data to be | |
1518 | written in one operation even if the port is using the single-byte | |
1519 | @code{shortbuf}. | |
1520 | ||
1521 | @item | |
1522 | Set @code{rw_active} to @code{SCM_PORT_WRITE} if @code{rw_random} | |
1523 | is set. | |
1524 | @end enumerate | |
1525 | ||
1526 | ||
1527 | @node Port Implementation | |
1528 | @subsubsection Port Implementation | |
28cc8dac | 1529 | @cindex Port implementation |
07d83abe MV |
1530 | |
1531 | This section describes how to implement a new port type in C. | |
1532 | ||
1533 | As described in the previous section, a port type object (ptob) is | |
1534 | a structure of type @code{scm_ptob_descriptor}. A ptob is created by | |
1535 | calling @code{scm_make_port_type}. | |
1536 | ||
23f2b9a3 KR |
1537 | @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)) |
1538 | Return a new port type object. The @var{name}, @var{fill_input} and | |
1539 | @var{write} parameters are initial values for those port type fields, | |
1540 | as described below. The other fields are initialized with default | |
1541 | values and can be changed later. | |
1542 | @end deftypefun | |
1543 | ||
07d83abe MV |
1544 | All of the elements of the ptob, apart from @code{name}, are procedures |
1545 | which collectively implement the port behaviour. Creating a new port | |
1546 | type mostly involves writing these procedures. | |
1547 | ||
07d83abe MV |
1548 | @table @code |
1549 | @item name | |
1550 | A pointer to a NUL terminated string: the name of the port type. This | |
1551 | is the only element of @code{scm_ptob_descriptor} which is not | |
1552 | a procedure. Set via the first argument to @code{scm_make_port_type}. | |
1553 | ||
1554 | @item mark | |
1555 | Called during garbage collection to mark any SCM objects that a port | |
1556 | object may contain. It doesn't need to be set unless the port has | |
23f2b9a3 KR |
1557 | @code{SCM} components. Set using |
1558 | ||
1559 | @deftypefun void scm_set_port_mark (scm_t_bits tc, SCM (*mark) (SCM port)) | |
1560 | @end deftypefun | |
07d83abe MV |
1561 | |
1562 | @item free | |
1563 | Called when the port is collected during gc. It | |
1564 | should free any resources used by the port. | |
23f2b9a3 KR |
1565 | Set using |
1566 | ||
1567 | @deftypefun void scm_set_port_free (scm_t_bits tc, size_t (*free) (SCM port)) | |
1568 | @end deftypefun | |
07d83abe MV |
1569 | |
1570 | @item print | |
1571 | Called when @code{write} is called on the port object, to print a | |
23f2b9a3 KR |
1572 | port description. E.g., for an fport it may produce something like: |
1573 | @code{#<input: /etc/passwd 3>}. Set using | |
1574 | ||
1575 | @deftypefun void scm_set_port_print (scm_t_bits tc, int (*print) (SCM port, SCM dest_port, scm_print_state *pstate)) | |
1576 | The first argument @var{port} is the object being printed, the second | |
1577 | argument @var{dest_port} is where its description should go. | |
1578 | @end deftypefun | |
07d83abe MV |
1579 | |
1580 | @item equalp | |
23f2b9a3 KR |
1581 | Not used at present. Set using |
1582 | ||
1583 | @deftypefun void scm_set_port_equalp (scm_t_bits tc, SCM (*equalp) (SCM, SCM)) | |
1584 | @end deftypefun | |
07d83abe MV |
1585 | |
1586 | @item close | |
1587 | Called when the port is closed, unless it was collected during gc. It | |
1588 | should free any resources used by the port. | |
23f2b9a3 KR |
1589 | Set using |
1590 | ||
1591 | @deftypefun void scm_set_port_close (scm_t_bits tc, int (*close) (SCM port)) | |
1592 | @end deftypefun | |
07d83abe MV |
1593 | |
1594 | @item write | |
1595 | Accept data which is to be written using the port. The port implementation | |
1596 | may choose to buffer the data instead of processing it directly. | |
1597 | Set via the third argument to @code{scm_make_port_type}. | |
1598 | ||
1599 | @item flush | |
1600 | Complete the processing of buffered output data. Reset the value of | |
1601 | @code{rw_active} to @code{SCM_PORT_NEITHER}. | |
23f2b9a3 KR |
1602 | Set using |
1603 | ||
1604 | @deftypefun void scm_set_port_flush (scm_t_bits tc, void (*flush) (SCM port)) | |
1605 | @end deftypefun | |
07d83abe MV |
1606 | |
1607 | @item end_input | |
1608 | Perform any synchronization required when switching from input to output | |
1609 | on the port. Reset the value of @code{rw_active} to @code{SCM_PORT_NEITHER}. | |
23f2b9a3 KR |
1610 | Set using |
1611 | ||
1612 | @deftypefun void scm_set_port_end_input (scm_t_bits tc, void (*end_input) (SCM port, int offset)) | |
1613 | @end deftypefun | |
07d83abe MV |
1614 | |
1615 | @item fill_input | |
1616 | Read new data into the read buffer and return the first character. It | |
1617 | can be assumed that the read buffer is empty when this procedure is called. | |
1618 | Set via the second argument to @code{scm_make_port_type}. | |
1619 | ||
1620 | @item input_waiting | |
1621 | Return a lower bound on the number of bytes that could be read from the | |
1622 | port without blocking. It can be assumed that the current state of | |
1623 | @code{rw_active} is @code{SCM_PORT_NEITHER}. | |
23f2b9a3 KR |
1624 | Set using |
1625 | ||
1626 | @deftypefun void scm_set_port_input_waiting (scm_t_bits tc, int (*input_waiting) (SCM port)) | |
1627 | @end deftypefun | |
07d83abe MV |
1628 | |
1629 | @item seek | |
1630 | Set the current position of the port. The procedure can not make | |
1631 | any assumptions about the value of @code{rw_active} when it's | |
1632 | called. It can reset the buffers first if desired by using something | |
1633 | like: | |
1634 | ||
1635 | @example | |
23f2b9a3 KR |
1636 | if (pt->rw_active == SCM_PORT_READ) |
1637 | scm_end_input (port); | |
1638 | else if (pt->rw_active == SCM_PORT_WRITE) | |
1639 | ptob->flush (port); | |
07d83abe MV |
1640 | @end example |
1641 | ||
1642 | However note that this will have the side effect of discarding any data | |
1643 | in the unread-char buffer, in addition to any side effects from the | |
1644 | @code{end_input} and @code{flush} ptob procedures. This is undesirable | |
1645 | when seek is called to measure the current position of the port, i.e., | |
1646 | @code{(seek p 0 SEEK_CUR)}. The libguile fport and string port | |
1647 | implementations take care to avoid this problem. | |
1648 | ||
23f2b9a3 KR |
1649 | The procedure is set using |
1650 | ||
f1ce9199 | 1651 | @deftypefun void scm_set_port_seek (scm_t_bits tc, scm_t_off (*seek) (SCM port, scm_t_off offset, int whence)) |
23f2b9a3 | 1652 | @end deftypefun |
07d83abe MV |
1653 | |
1654 | @item truncate | |
1655 | Truncate the port data to be specified length. It can be assumed that the | |
1656 | current state of @code{rw_active} is @code{SCM_PORT_NEITHER}. | |
23f2b9a3 KR |
1657 | Set using |
1658 | ||
f1ce9199 | 1659 | @deftypefun void scm_set_port_truncate (scm_t_bits tc, void (*truncate) (SCM port, scm_t_off length)) |
23f2b9a3 | 1660 | @end deftypefun |
07d83abe MV |
1661 | |
1662 | @end table | |
1663 | ||
1664 | ||
1665 | @c Local Variables: | |
1666 | @c TeX-master: "guile.texi" | |
1667 | @c End: |