1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
|
@page
@node Input and Output
@chapter Input and Output
@menu
* Ports:: The idea of the port abstraction.
* Reading:: Procedures for reading from a port.
* Writing:: Procedures for writing to a port.
* Closing:: Procedures to close a port.
* Random Access:: Moving around a random access port.
* Line/Delimited:: Read and write lines or delimited text.
* Block Reading and Writing:: Reading and writing blocks of text.
* Default Ports:: Defaults for input, output and errors.
* Port Types:: Types of port and how to make them.
@end menu
@node Ports
@section Ports
[Concept of the port abstraction.]
Sequential input/output in Scheme is represented by operations on a
@dfn{port}. Characters can be read from an input port and
written to an output port. This chapter explains the operations
that Guile provides for working with ports.
The formal definition of a port is very generic: an input port is
simply ``an object which can deliver characters on command,'' and
an output port is ``an object which can accept characters.''
Because this definition is so loose, it is easy to write functions
that simulate ports in software. @dfn{Soft ports} and @dfn{string
ports} are two interesting and powerful examples of this technique.
@rnindex input-port?
@deffn primitive input-port? x
Return @code{#t} if @var{x} is an input port, otherwise return
@code{#f}. Any object satisfying this predicate also satisfies
@code{port?}.
@end deffn
@rnindex output-port?
@deffn primitive output-port? x
Return @code{#t} if @var{x} is an output port, otherwise return
@code{#f}. Any object satisfying this predicate also satisfies
@code{port?}.
@end deffn
@deffn primitive port? x
Return a boolean indicating whether @var{x} is a port.
Equivalent to @code{(or (input-port? @var{x}) (output-port?
@var{x}))}.
@end deffn
@node Reading
@section Reading
[Generic procedures for reading from ports.]
@rnindex eof-object?
@deffn primitive eof-object? x
Return @code{#t} if @var{x} is an end-of-file object; otherwise
return @code{#f}.
@end deffn
@rnindex char-ready?
@deffn primitive char-ready? [port]
Return @code{#t} if a character is ready on input @var{port}
and return @code{#f} otherwise. If @code{char-ready?} returns
@code{#t} then the next @code{read-char} operation on
@var{port} is guaranteed not to hang. If @var{port} is a file
port at end of file then @code{char-ready?} returns @code{#t}.
@footnote{@code{char-ready?} exists to make it possible for a
program to accept characters from interactive ports without
getting stuck waiting for input. Any input editors associated
with such ports must make sure that characters whose existence
has been asserted by @code{char-ready?} cannot be rubbed out.
If @code{char-ready?} were to return @code{#f} at end of file,
a port at end of file would be indistinguishable from an
interactive port that has no ready characters.}
@end deffn
@rnindex read-char?
@deffn primitive read-char [port]
Return the next character available from @var{port}, updating
@var{port} to point to the following character. If no more
characters are available, the end-of-file object is returned.
@end deffn
@rnindex peek-char?
@deffn primitive peek-char [port]
Return the next character available from @var{port},
@emph{without} updating @var{port} to point to the following
character. If no more characters are available, the
end-of-file object is returned.@footnote{The value returned by
a call to @code{peek-char} is the same as the value that would
have been returned by a call to @code{read-char} on the same
port. The only difference is that the very next call to
@code{read-char} or @code{peek-char} on that @var{port} will
return the value returned by the preceding call to
@code{peek-char}. In particular, a call to @code{peek-char} on
an interactive port will hang waiting for input whenever a call
to @code{read-char} would have hung.}
@end deffn
@deffn primitive unread-char cobj port
Place @var{char} in @var{port} so that it will be read by the
next read operation. If called multiple times, the unread characters
will be read again in last-in first-out order. If @var{port} is
not supplied, the current input port is used.
@end deffn
@deffn primitive unread-string str port
Place the string @var{str} in @var{port} so that its characters will be
read in subsequent read operations. If called multiple times, the
unread characters will be read again in last-in first-out order. If
@var{port} is not supplied, the current-input-port is used.
@end deffn
@deffn primitive drain-input port
Drain @var{port}'s read buffers (including any pushed-back
characters) and return the content as a single string.
@end deffn
@deffn primitive port-column port
@deffnx primitive port-line port
Return the current column number or line number of @var{port},
using the current input port if none is specified. If the number is
unknown, the result is #f. Otherwise, the result is a 0-origin integer
- i.e. the first character of the first line is line 0, column 0.
(However, when you display a file position, for example in an error
message, we recommend you add 1 to get 1-origin integers. This is
because lines and column numbers traditionally start with 1, and that is
what non-programmers will find most natural.)
@end deffn
@deffn primitive set-port-column! port column
@deffnx primitive set-port-line! port line
Set the current column or line number of @var{port}, using the
current input port if none is specified.
@end deffn
@node Writing
@section Writing
[Generic procedures for writing to ports.]
@deffn primitive get-print-state port
Return the print state of the port @var{port}. If @var{port}
has no associated print state, @code{#f} is returned.
@end deffn
@rnindex display
@deffn primitive display obj [port]
Send a representation of @var{obj} to @var{current-output-port}.
Optional second arg @var{port} specifies an alternative output port.
The representation is similar to that produced by @code{write} (REFFIXME),
the differences being strings are not quoted (and their characters are not
escaped), and characters are rendered as if with @code{write-char}.
@end deffn
@rnindex newline
@deffn primitive newline [port]
Send a newline to @var{port} (default @var{current-output-port} if omitted).
@end deffn
@deffn primitive port-with-print-state port pstate
Create a new port which behaves like @var{port}, but with an
included print state @var{pstate}.
@end deffn
@deffn primitive print-options-interface [setting]
Option interface for the print options. Instead of using
this procedure directly, use the procedures
@code{print-enable}, @code{print-disable}, @code{print-set!}
and @code{print-options}.
@end deffn
@deffn primitive simple-format destination message . args
Write @var{message} to @var{destination}, defaulting to
the current output port.
@var{message} can contain @code{~A} (was @code{%s}) and
@code{~S} (was @code{%S}) escapes. When printed,
the escapes are replaced with corresponding members of
@var{ARGS}:
@code{~A} formats using @code{display} and @code{~S} formats
using @code{write}.
If @var{destination} is @code{#t}, then use the current output
port, if @var{destination} is @code{#f}, then return a string
containing the formatted text. Does not add a trailing newline.
@end deffn
@rnindex write-char
@deffn primitive write-char chr [port]
Send character @var{chr} to @var{port}.
@end deffn
@findex fflush
@deffn primitive force-output [port]
Flush the specified output port, or the current output port if @var{port}
is omitted. The current output buffer contents are passed to the
underlying port implementation (e.g., in the case of fports, the
data will be written to the file and the output buffer will be cleared.)
It has no effect on an unbuffered port.
The return value is unspecified.
@end deffn
@deffn primitive flush-all-ports
Equivalent to calling @code{force-output} on
all open output ports. The return value is unspecified.
@end deffn
@node Closing
@section Closing
@deffn primitive close-port port
Close the specified port object. Return @code{#t} if it
successfully closes a port or @code{#f} if it was already
closed. An exception may be raised if an error occurs, for
example when flushing buffered output. See also @ref{Ports and
File Descriptors, close}, for a procedure which can close file
descriptors.
@end deffn
@rnindex close-input-port
@deffn primitive close-input-port port
Close the specified input port object. The routine has no effect if
the file has already been closed. An exception may be raised if an
error occurs. The value returned is unspecified.
See also @ref{Ports and File Descriptors, close}, for a procedure
which can close file descriptors.
@end deffn
@rnindex close-output-port
@deffn primitive close-output-port port
Close the specified output port object. The routine has no effect if
the file has already been closed. An exception may be raised if an
error occurs. The value returned is unspecified.
See also @ref{Ports and File Descriptors, close}, for a procedure
which can close file descriptors.
@end deffn
@deffn primitive port-closed? port
Return @code{#t} if @var{port} is closed or @code{#f} if it is
open.
@end deffn
@node Random Access
@section Random Access
@deffn primitive seek fd_port offset whence
Sets the current position of @var{fd/port} to the integer
@var{offset}, which is interpreted according to the value of
@var{whence}.
One of the following variables should be supplied for
@var{whence}:
@defvar SEEK_SET
Seek from the beginning of the file.
@end defvar
@defvar SEEK_CUR
Seek from the current position.
@end defvar
@defvar SEEK_END
Seek from the end of the file.
@end defvar
If @var{fd/port} is a file descriptor, the underlying system
call is @code{lseek}. @var{port} may be a string port.
The value returned is the new position in the file. This means
that the current position of a port can be obtained using:
@lisp
(seek port 0 SEEK_CUR)
@end lisp
@end deffn
@deffn primitive ftell fd_port
Return an integer representing the current position of
@var{fd/port}, measured from the beginning. Equivalent to:
@lisp
(seek port 0 SEEK_CUR)
@end lisp
@end deffn
@findex truncate
@findex ftruncate
@deffn primitive truncate-file object [length]
Truncates the object referred to by @var{object} to at most
@var{length} bytes. @var{object} can be a string containing a
file name or an integer file descriptor or a port.
@var{length} may be omitted if @var{object} is not a file name,
in which case the truncation occurs at the current port.
position. The return value is unspecified.
@end deffn
@node Line/Delimited
@section Line Oriented and Delimited Text
The delimited-I/O module can be accessed with:
@smalllisp
(use-modules (ice-9 rdelim))
@end smalllisp
It can be used to read or write lines of text, or read text delimited by
a specified set of characters. It's similar to the @code{(scsh rdelim)}
module from guile-scsh, but does not use multiple values or character
sets and has an extra procedure @code{write-line}.
@c begin (scm-doc-string "rdelim.scm" "read-line")
@deffn procedure read-line [port] [handle-delim]
Return a line of text from @var{port} if specified, otherwise from the
value returned by @code{(current-input-port)}. Under Unix, a line of text
is terminated by the first end-of-line character or by end-of-file.
If @var{handle-delim} is specified, it should be one of the following
symbols:
@table @code
@item trim
Discard the terminating delimiter. This is the default, but it will
be impossible to tell whether the read terminated with a delimiter or
end-of-file.
@item concat
Append the terminating delimiter (if any) to the returned string.
@item peek
Push the terminating delimiter (if any) back on to the port.
@item split
Return a pair containing the string read from the port and the
terminating delimiter or end-of-file object.
@end table
@end deffn
@c begin (scm-doc-string "rdelim.scm" "read-line!")
@deffn procedure read-line! buf [port]
Read a line of text into the supplied string @var{buf} and return the
number of characters added to @var{buf}. If @var{buf} is filled, then
@code{#f} is returned.
Read from @var{port} if
specified, otherwise from the value returned by @code{(current-input-port)}.
@end deffn
@c begin (scm-doc-string "rdelim.scm" "read-delimited")
@deffn procedure read-delimited delims [port] [handle-delim]
Read text until one of the characters in the string @var{delims} is found
or end-of-file is reached. Read from @var{port} if supplied, otherwise
from the value returned by @code{(current-input-port)}.
@var{handle-delim} takes the same values as described for @code{read-line}.
@end deffn
@c begin (scm-doc-string "rdelim.scm" "read-delimited!")
@deffn procedure read-delimited! delims buf [port] [handle-delim] [start] [end]
Read text into the supplied string @var{buf} and return the number of
characters added to @var{buf} (subject to @var{handle-delim}, which takes
the same values specified for @code{read-line}. If @var{buf} is filled,
@code{#f} is returned for both the number of characters read and the
delimiter. Also terminates if one of the characters in the string
@var{delims} is found
or end-of-file is reached. Read from @var{port} if supplied, otherwise
from the value returned by @code{(current-input-port)}.
@end deffn
@deffn primitive write-line obj [port]
Display @var{obj} and a newline character to @var{port}. If
@var{port} is not specified, @code{(current-output-port)} is
used. This function is equivalent to:
@lisp
(display obj [port])
(newline [port])
@end lisp
@end deffn
Some of the abovementioned I/O functions rely on the following C
primitives. These will mainly be of interest to people hacking Guile
internals.
@deffn primitive %read-delimited! delims str gobble [port [start [end]]]
Read characters from @var{port} into @var{str} until one of the
characters in the @var{delims} string is encountered. If
@var{gobble} is true, discard the delimiter character;
otherwise, leave it in the input stream for the next read. If
@var{port} is not specified, use the value of
@code{(current-input-port)}. If @var{start} or @var{end} are
specified, store data only into the substring of @var{str}
bounded by @var{start} and @var{end} (which default to the
beginning and end of the string, respectively).
Return a pair consisting of the delimiter that terminated the
string and the number of characters read. If reading stopped
at the end of file, the delimiter returned is the
@var{eof-object}; if the string was filled without encountering
a delimiter, this value is @code{#f}.
@end deffn
@deffn primitive %read-line [port]
Read a newline-terminated line from @var{port}, allocating storage as
necessary. The newline terminator (if any) is removed from the string,
and a pair consisting of the line and its delimiter is returned. The
delimiter may be either a newline or the @var{eof-object}; if
@code{%read-line} is called at the end of file, it returns the pair
@code{(#<eof> . #<eof>)}.
@end deffn
@node Block Reading and Writing
@section Block reading and writing
The Block-string-I/O module can be accessed with:
@smalllisp
(use-modules (ice-9 rw))
@end smalllisp
It currently contains procedures that help to implement the
@code{(scsh rw)} module in guile-scsh.
@deffn primitive read-string!/partial str [port_or_fdes start end]
Read characters from a port or file descriptor into a
string @var{str}. A port must have an underlying file
descriptor --- a so-called fport. This procedure is
scsh-compatible and can efficiently read large strings.
It will:
@itemize
@item
attempt to fill the entire string, unless the @var{start}
and/or @var{end} arguments are supplied. i.e., @var{start}
defaults to 0 and @var{end} defaults to
@code{(string-length str)}
@item
use the current input port if @var{port_or_fdes} is not
supplied.
@item
return fewer than the requested number of characters in some
cases, e.g., on end of file, if interrupted by a signal, or if
not all the characters are immediately available.
@item
wait indefinitely for some input if no characters are
currently available,
unless the port is in non-blocking mode.
@item
read characters from the port's input buffers if available,
instead from the underlying file descriptor.
@item
return @code{#f} if end-of-file is encountered before reading
any characters, otherwise return the number of characters
read.
@item
return 0 if the port is in non-blocking mode and no characters
are immediately available.
@item
return 0 if the request is for 0 bytes, with no
end-of-file check.
@end itemize
@end deffn
@deffn primitive write-string/partial str [port_or_fdes start end]
Write characters from a string @var{str} to a port or file
descriptor. A port must have an underlying file descriptor
--- a so-called fport. This procedure is
scsh-compatible and can efficiently write large strings.
It will:
@itemize
@item
attempt to write the entire string, unless the @var{start}
and/or @var{end} arguments are supplied. i.e., @var{start}
defaults to 0 and @var{end} defaults to
@code{(string-length str)}
@item
use the current output port if @var{port_of_fdes} is not
supplied.
@item
in the case of a buffered port, store the characters in the
port's output buffer, if all will fit. If they will not fit
then any existing buffered characters will be flushed
before attempting
to write the new characters directly to the underlying file
descriptor. If the port is in non-blocking mode and
buffered characters can not be flushed immediately, then an
@code{EAGAIN} system-error exception will be raised (Note:
scsh does not support the use of non-blocking buffered ports.)
@item
write fewer than the requested number of
characters in some cases, e.g., if interrupted by a signal or
if not all of the output can be accepted immediately.
@item
wait indefinitely for at least one character
from @var{str} to be accepted by the port, unless the port is
in non-blocking mode.
@item
return the number of characters accepted by the port.
@item
return 0 if the port is in non-blocking mode and can not accept
at least one character from @var{str} immediately
@item
return 0 immediately if the request size is 0 bytes.
@end itemize
@end deffn
@node Default Ports
@section Default Ports for Input, Output and Errors
@rnindex current-input-port
@deffn primitive current-input-port
Return the current input port. This is the default port used
by many input procedures. Initially, @code{current-input-port}
returns the @dfn{standard input} in Unix and C terminology.
@end deffn
@rnindex current-output-port
@deffn primitive current-output-port
Return the current output port. This is the default port used
by many output procedures. Initially,
@code{current-output-port} returns the @dfn{standard output} in
Unix and C terminology.
@end deffn
@deffn primitive current-error-port
Return the port to which errors and warnings should be sent (the
@dfn{standard error} in Unix and C terminology).
@end deffn
@deffn primitive set-current-input-port port
@deffnx primitive set-current-output-port port
@deffnx primitive set-current-error-port port
Change the ports returned by @code{current-input-port},
@code{current-output-port} and @code{current-error-port}, respectively,
so that they use the supplied @var{port} for input or output.
@end deffn
@deffn primitive set-current-output-port port
Set the current default output port to PORT.
@end deffn
@deffn primitive set-current-error-port port
Set the current default error port to PORT.
@end deffn
@node Port Types
@section Types of Port
[Types of port; how to make them.]
@menu
* File Ports:: Ports on an operating system file.
* String Ports:: Ports on a Scheme string.
* Soft Ports:: Ports on arbitrary Scheme procedures.
* Void Ports:: Ports on nothing at all.
@end menu
@node File Ports
@subsection File Ports
The following procedures are used to open file ports.
See also @ref{Ports and File Descriptors, open}, for an interface
to the Unix @code{open} system call.
@deffn primitive open-file filename mode
Open the file whose name is @var{filename}, and return a port
representing that file. The attributes of the port are
determined by the @var{mode} string. The way in which this is
interpreted is similar to C stdio. The first character must be
one of the following:
@table @samp
@item r
Open an existing file for input.
@item w
Open a file for output, creating it if it doesn't already exist
or removing its contents if it does.
@item a
Open a file for output, creating it if it doesn't already
exist. All writes to the port will go to the end of the file.
The "append mode" can be turned off while the port is in use
@pxref{Ports and File Descriptors, fcntl}
@end table
The following additional characters can be appended:
@table @samp
@item +
Open the port for both input and output. E.g., @code{r+}: open
an existing file for both input and output.
@item 0
Create an "unbuffered" port. In this case input and output
operations are passed directly to the underlying port
implementation without additional buffering. This is likely to
slow down I/O operations. The buffering mode can be changed
while a port is in use @pxref{Ports and File Descriptors,
setvbuf}
@item l
Add line-buffering to the port. The port output buffer will be
automatically flushed whenever a newline character is written.
@end table
In theory we could create read/write ports which were buffered
in one direction only. However this isn't included in the
current interfaces. If a file cannot be opened with the access
requested, @code{open-file} throws an exception.
@end deffn
@rnindex open-input-file
@deffn procedure open-input-file filename
Open @var{filename} for input. Equivalent to
@smalllisp
(open-file @var{filename} "r")
@end smalllisp
@end deffn
@rnindex open-output-file
@deffn procedure open-output-file filename
Open @var{filename} for output. Equivalent to
@smalllisp
(open-file @var{filename} "w")
@end smalllisp
@end deffn
@rnindex call-with-input-file
@deffn procedure call-with-input-file file proc
@var{proc} should be a procedure of one argument, and @var{file} should
be a string naming a file. The file must already exist. These
procedures call @var{proc} with one argument: the port obtained by
opening the named file for input or output. If the file cannot be
opened, an error is signalled. If the procedure returns, then the port
is closed automatically and the value yielded by the procedure is
returned. If the procedure does not return, then the port will not be
closed automatically unless it is possible to prove that the port will
never again be used for a read or write operation.
@end deffn
@rnindex call-with-output-file
@deffn procedure call-with-output-file file proc
@var{proc} should be a procedure of one argument, and @var{file} should
be a string naming a file. The behaviour is unspecified if the file
already exists. These procedures call @var{proc} with one argument: the
port obtained by opening the named file for input or output. If the
file cannot be opened, an error is signalled. If the procedure returns,
then the port is closed automatically and the value yielded by the
procedure is returned. If the procedure does not return, then the port
will not be closed automatically unless it is possible to prove that the
port will never again be used for a read or write operation.
@end deffn
@rnindex with-input-from-file
@deffn procedure with-input-from-file file thunk
@var{thunk} must be a procedure of no arguments, and @var{file} must be
a string naming a file. The file must already exist. The file is opened
for input, an input port connected to it is made the default value
returned by @code{current-input-port}, and the @var{thunk} is called
with no arguments. When the @var{thunk} returns, the port is closed and
the previous default is restored. Returns the value yielded by
@var{thunk}. If an escape procedure is used to escape from the
continuation of these procedures, their behavior is implementation
dependent.
@end deffn
@rnindex with-output-to-file
@deffn procedure with-output-to-file file thunk
@var{thunk} must be a procedure of no arguments, and @var{file} must be
a string naming a file. The effect is unspecified if the file already
exists. The file is opened for output, an output port connected to it
is made the default value returned by @code{current-output-port}, and
the @var{thunk} is called with no arguments. When the @var{thunk}
returns, the port is closed and the previous default is restored.
Returns the value yielded by @var{thunk}. If an escape procedure is
used to escape from the continuation of these procedures, their behavior
is implementation dependent.
@end deffn
@deffn procedure with-error-to-file file thunk
@var{thunk} must be a procedure of no arguments, and @var{file} must be
a string naming a file. The effect is unspecified if the file already
exists. The file is opened for output, an output port connected to it
is made the default value returned by @code{current-error-port}, and the
@var{thunk} is called with no arguments. When the @var{thunk} returns,
the port is closed and the previous default is restored. Returns the
value yielded by @var{thunk}. If an escape procedure is used to escape
from the continuation of these procedures, their behavior is
implementation dependent.
@end deffn
@deffn primitive port-mode port
Returns the port modes associated with the open port @var{port}. These
will not necessarily be identical to the modes used when the port was
opened, since modes such as "append" which are used only during
port creation are not retained.
@end deffn
@deffn primitive port-filename port
Return the filename associated with @var{port}. This function returns
the strings "standard input", "standard output" and "standard error"
when called on the current input, output and error ports respectively.
@end deffn
@deffn primitive set-port-filename! port filename
Change the filename associated with @var{port}, using the current input
port if none is specified. Note that this does not change the port's
source of data, but only the value that is returned by
@code{port-filename} and reported in diagnostic output.
@end deffn
@deffn primitive file-port? obj
Determine whether @var{obj} is a port that is related to a file.
@end deffn
@node String Ports
@subsection String Ports
The following allow string ports to be opened by analogy to R4R*
file port facilities:
@deffn primitive call-with-output-string proc
Calls the one-argument procedure @var{proc} with a newly created output
port. When the function returns, the string composed of the characters
written into the port is returned.
@end deffn
@deffn primitive call-with-input-string string proc
Calls the one-argument procedure @var{proc} with a newly
created input port from which @var{string}'s contents may be
read. The value yielded by the @var{proc} is returned.
@end deffn
@deffn procedure with-output-to-string thunk
Calls the zero-argument procedure @var{thunk} with the current output
port set temporarily to a new string port. It returns a string
composed of the characters written to the current output.
@end deffn
@deffn procedure with-input-from-string string thunk
Calls the zero-argument procedure @var{thunk} with the current input
port set temporarily to a string port opened on the specified
@var{string}. The value yielded by @var{thunk} is returned.
@end deffn
@deffn primitive open-input-string str
Take a string and return an input port that delivers characters
from the string. The port can be closed by
@code{close-input-port}, though its storage will be reclaimed
by the garbage collector if it becomes inaccessible.
@end deffn
@deffn primitive open-output-string
Return an output port that will accumulate characters for
retrieval by @code{get-output-string}. The port can be closed
by the procedure @code{close-output-port}, though its storage
will be reclaimed by the garbage collector if it becomes
inaccessible.
@end deffn
@deffn primitive get-output-string port
Given an output port created by @code{open-output-string},
return a string consisting of the characters that have been
output to the port so far.
@end deffn
A string port can be used in many procedures which accept a port
but which are not dependent on implementation details of fports.
E.g., seeking and truncating will work on a string port,
but trying to extract the file descriptor number will fail.
@node Soft Ports
@subsection Soft Ports
A @dfn{soft-port} is a port based on a vector of procedures capable of
accepting or delivering characters. It allows emulation of I/O ports.
@deffn primitive make-soft-port pv modes
Return a port capable of receiving or delivering characters as
specified by the @var{modes} string (@pxref{File Ports,
open-file}). @var{pv} must be a vector of length 5. Its
components are as follows:
@enumerate 0
@item
procedure accepting one character for output
@item
procedure accepting a string for output
@item
thunk for flushing output
@item
thunk for getting one character
@item
thunk for closing port (not by garbage collection)
@end enumerate
For an output-only port only elements 0, 1, 2, and 4 need be
procedures. For an input-only port only elements 3 and 4 need
be procedures. Thunks 2 and 4 can instead be @code{#f} if
there is no useful operation for them to perform.
If thunk 3 returns @code{#f} or an @code{eof-object}
(@pxref{Input, eof-object?, ,r5rs, The Revised^5 Report on
Scheme}) it indicates that the port has reached end-of-file.
For example:
@lisp
(define stdout (current-output-port))
(define p (make-soft-port
(vector
(lambda (c) (write c stdout))
(lambda (s) (display s stdout))
(lambda () (display "." stdout))
(lambda () (char-upcase (read-char)))
(lambda () (display "@@" stdout)))
"rw"))
(write p p) @result{} #<input-output: soft 8081e20>
@end lisp
@end deffn
@node Void Ports
@subsection Void Ports
This kind of port causes any data to be discarded when written to, and
always returns the end-of-file object when read from.
@deffn primitive %make-void-port mode
Create and return a new void port. A void port acts like
@code{/dev/null}. The @var{mode} argument specifies the input/output
modes for this port: see the documentation for @code{open-file} in
@ref{File Ports}.
@end deffn
@c Local Variables:
@c TeX-master: "guile.texi"
@c End:
|