source: project/chicken/trunk/manual/Unit ports @ 13659

Last change on this file since 13659 was 13659, checked in by felix winkelmann, 11 years ago

small manual fixes; merged wiki changes (rev. 13647) into manual

File size: 4.1 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Unit ports
5
6This unit contains various extended port definitions. This unit is
7used by default, unless the program is compiled with the
8{{-explicit-use}} option.
9
10=== Input/output port extensions
11
12==== with-output-to-port
13
14<procedure>(with-output-to-port PORT THUNK)</procedure>
15
16Call procedure {{THUNK}} with the current output-port temporarily
17bound to {{PORT}}.
18
19==== make-input-port
20
21<procedure>(make-input-port READ READY? CLOSE [PEEK])</procedure>
22
23Returns a custom input port. Common operations on this
24port are handled by the given parameters, which should be
25procedures of no arguments. {{READ}} is called when the
26next character is to be read and should return a character or
27{{#!eof}}. {{READY?}} is called
28when {{char-ready?}} is called on this port and should return
29{{#t}} or {{#f}}.  {{CLOSE}} is called when the port is
30closed. {{PEEK}} is called when {{peek-char}} is called on this
31port and should return a character or {{#!eof}}.
32if the argument {{PEEK}} is not given, then {{READ}} is used
33instead and the created port object handles peeking automatically (by
34calling {{READ}} and buffering the character).
35
36
37==== make-output-port
38
39<procedure>(make-output-port WRITE CLOSE [FLUSH])</procedure>
40
41Returns a custom output port. Common operations on this port are handled
42by the given parameters, which should be procedures.  {{WRITE}} is
43called when output is sent to the port and receives a single argument,
44a string.  {{CLOSE}} is called when the port is closed and should
45be a procedure of no arguments. {{FLUSH}} (if provided) is called
46for flushing the output port.
47
48
49==== with-error-output-to-port
50
51<procedure>(with-error-output-to-port PORT THUNK)</procedure>
52
53Call procedure {{THUNK}} with the current error output-port
54temporarily bound to {{PORT}}.
55
56
57==== with-input-from-port
58
59<procedure>(with-input-from-port PORT THUNK)</procedure>
60
61Call procedure {{THUNK}} with the current input-port temporarily
62bound to {{PORT}}.
63
64
65=== String-port extensions
66
67==== call-with-input-string
68
69<procedure>(call-with-input-string STRING PROC)</procedure>
70
71Calls the procedure {{PROC}} with a single argument that is a
72string-input-port with the contents of {{STRING}}.
73
74
75==== call-with-output-string
76
77<procedure>(call-with-output-string PROC)</procedure>
78
79Calls the procedure {{PROC}} with a single argument that is a
80string-output-port.  Returns the accumulated output-string.
81
82
83==== with-input-from-string
84
85<procedure>(with-input-from-string STRING THUNK)</procedure>
86
87Call procedure {{THUNK}} with the current input-port temporarily
88bound to an input-string-port with the contents of {{STRING}}.
89
90
91==== with-output-to-string
92
93<procedure>(with-output-to-string THUNK)</procedure>
94
95Call procedure {{THUNK}} with the current output-port temporarily
96bound to a string-output-port and return the accumulated output string.
97
98
99=== Port iterators
100
101==== port-for-each
102
103<procedure>(port-for-each FN THUNK)</procedure>
104
105Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}}
106until it returns {{#!eof}}, discarding the results.
107
108==== port-map
109
110<procedure>(port-map FN THUNK)</procedure>
111
112Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}}
113until it returns {{#!eof}}, returning a list of the collected results.
114
115==== port-fold
116
117<procedure>(port-map FN ACC THUNK)</procedure>
118
119Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}},
120passing the {{ACC}} value as the second argument. The {{FN}} result becomes the new
121{{ACC}} value. When {{THUNK}} returns {{#!eof}}, the last {{FN}} result is returned.
122
123
124=== Funky ports
125
126==== make-broadcast-port
127
128<procedure>(make-broadcast-port PORT ...)</procedure>
129
130Returns a custom output port that emits everything written into it to
131the ports given as {{PORT ...}}. Closing the broadcast port does not close
132any of the argument ports.
133
134==== make-concatenated-port
135
136<procedure>(make-concatenated-port PORT1 PORT2 ...)</procedure>
137
138Returns a custom input port that reads its input from {{PORT1}}, until it
139is empty, then from {{PORT2}} and so on. Closing the concatenated port
140does not close any of the argument ports.
141
142
143Previous: [[Unit data-structures]]
144
145Next: [[Unit files]]
Note: See TracBrowser for help on using the repository browser.