source: project/chicken/trunk/manual/Unit extras @ 10513

Last change on this file since 10513 was 10513, checked in by Ivan Raikov, 11 years ago

Version increased to 3.1.6

File size: 8.2 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Unit extras
5
6This unit contains a collection of useful utility definitions.
7This unit is used by default, unless the program
8is compiled with the {{-explicit-use}} option.
9
10
11=== String-port extensions
12
13
14==== call-with-input-string
15
16 [procedure] (call-with-input-string STRING PROC)
17
18Calls the procedure {{PROC}} with a single argument that is a
19string-input-port with the contents of {{STRING}}.
20
21
22==== call-with-output-string
23
24 [procedure] (call-with-output-string PROC)
25
26Calls the procedure {{PROC}} with a single argument that is a
27string-output-port.  Returns the accumulated output-string.
28
29
30==== with-input-from-string
31
32 [procedure] (with-input-from-string STRING THUNK)
33
34Call procedure {{THUNK}} with the current input-port temporarily
35bound to an input-string-port with the contents of {{STRING}}.
36
37
38==== with-output-to-string
39
40 [procedure] (with-output-to-string THUNK)
41
42Call procedure {{THUNK}} with the current output-port temporarily
43bound to a string-output-port and return the accumulated output string.
44
45
46
47=== Formatted output
48
49
50==== printf
51==== fprintf
52==== sprintf
53
54 [procedure] (fprintf PORT FORMATSTRING ARG ...)
55 [procedure] (printf FORMATSTRING ARG ...)
56 [procedure] (sprintf FORMATSTRING ARG ...)
57
58Simple formatted output to a given port ({{fprintf}}), the
59value of {{(current-output-port)}} ({{printf}}), or a string
60({{sprintf}}).  The {{FORMATSTRING}} can contain any sequence
61of characters.  There must be at least as many {{ARG}} arguments given as there are format directives that require an argument in {{FORMATSTRING}}.  Extra {{ARG}} arguments are ignored.  The character `~' prefixes special formatting directives:
62
63<table>
64<tr><td> ~%
65write newline character
66</td></tr><tr><td> ~N
67the same as {{~%}}
68</td></tr><tr><td> ~S
69write the next argument
70</td></tr><tr><td> ~A
71display the next argument
72</td></tr><tr><td> ~\n
73skip all whitespace in the format-string until the next non-whitespace character
74</td></tr><tr><td> ~B
75write the next argument as a binary number
76</td></tr><tr><td> ~O
77write the next argument as an octal number
78</td></tr><tr><td> ~X
79write the next argument as a hexadecimal number
80</td></tr><tr><td> ~C
81write the next argument as a character
82</td></tr><tr><td> ~~
83display `~'
84</td></tr><tr><td> ~!
85flush all pending output
86</td></tr><tr><td> ~?
87invoke formatted output routine recursively with the next two arguments as format-string and list of parameters
88</td></tr></table>
89
90
91==== format
92
93 [procedure] (format [DESTINATION] FORMATSTRING ARG ...)
94
95The parameters  {{FORMATSTRING}} and {{ARG ...}} are as for
96({{printf}}/{{sprintf}}/{{fprintf}}).
97
98The optional {{DESTINATION}}, when supplied, performs
99a ({{sprintf}}) for a  {{#f}},
100a ({{printf}}) for a {{#t}},
101and a ({{fprintf}}) for an output-port.
102When missing a ({{sprintf}}) is performed.
103
104
105
106=== Random numbers
107
108
109==== random-seed
110
111 [procedure] (random-seed [SEED])
112
113Seeds the random number generator with {{SEED}} (an exact integer) or
114{{(current-seconds)}} if {{SEED}} is not given.
115
116
117==== random
118
119 [procedure] (random N)
120
121Returns an exact random integer from 0 to {{N}}-1.
122
123
124==== randomize
125
126 [procedure] (randomize [X])
127
128Set random-number seed. If {{X}} is not supplied, the current time is used.
129On startup (when the {{extras}} unit is initialized), the random number generator
130is initialized with the current time.
131
132
133
134=== Input/Output extensions
135
136
137==== make-input-port
138
139 [procedure] (make-input-port READ READY? CLOSE [PEEK])
140
141Returns a custom input port. Common operations on this
142port are handled by the given parameters, which should be
143procedures of no arguments. {{READ}} is called when the
144next character is to be read and should return a character or
145{{#!eof}}. {{READY?}} is called
146when {{char-ready?}} is called on this port and should return
147{{#t}} or {{#f}}.  {{CLOSE}} is called when the port is
148closed. {{PEEK}} is called when {{peek-char}} is called on this
149port and should return a character or {{#!eof}}.
150if the argument {{PEEK}} is not given, then {{READ}} is used
151instead and the created port object handles peeking automatically (by
152calling {{READ}} and buffering the character).
153
154
155==== make-output-port
156
157 [procedure] (make-output-port WRITE CLOSE [FLUSH])
158
159Returns a custom output port. Common operations on this port are handled
160by the given parameters, which should be procedures.  {{WRITE}} is
161called when output is sent to the port and receives a single argument,
162a string.  {{CLOSE}} is called when the port is closed and should
163be a procedure of no arguments. {{FLUSH}} (if provided) is called
164for flushing the output port.
165
166
167==== pretty-print
168
169 [procedure] (pretty-print EXP [PORT])
170 [procedure] (pp EXP [PORT])
171
172Print expression nicely formatted. {{PORT}} defaults to the value
173of {{(current-output-port)}}.
174
175
176==== pretty-print-width
177(Parameter) Specifies the maximal line-width for pretty printing, after which line
178wrap will occur.
179
180==== read-byte
181==== write-byte
182
183 [procedure] (read-byte [PORT])
184 [procedure] (write-byte BYTE [PORT])
185
186Read/write a byte to the port given in {{PORT}}, which default to the values
187of {{(current-input-port)}} and {{(current-output-port)}}, respectively.
188
189==== read-file
190
191 [procedure] (read-file [FILE-OR-PORT [READER [MAXCOUNT]]])
192
193Returns a list containing all toplevel expressions
194read from the file or port {{FILE-OR-PORT}}. If no argument is given,
195input is read from the port that is the current value of {{(current-input-port)}}.
196After all expressions are read, and if the argument is a port, then the port will
197not be closed. The {{READER}} argument specifies the procedure used to read
198expressions from the given file or port and defaults to {{read}}. The reader
199procedure will be called with a single argument (an input port).
200If {{MAXCOUNT}} is given then only up to {{MAXCOUNT}} expressions will be read in.
201
202
203==== read-line
204==== write-line
205
206 [procedure] (read-line [PORT [LIMIT]])
207 [procedure] (write-line STRING [PORT])
208
209Line-input and -output. {{PORT}} defaults to the value of
210{{(current-input-port)}} and {{(current-output-port)}},
211respectively. If the optional argument {{LIMIT}} is given and
212not {{#f}}, then {{read-line}} reads at most {{LIMIT}}
213characters per line. {{read-line}} returns a string without the terminating newline and {{write-line}} adds a terminating newline  before outputting.
214
215
216==== read-lines
217
218 [procedure] (read-lines [PORT [MAX]])
219
220Read {{MAX}} or fewer lines from {{PORT}}. {{PORT}}
221defaults to the value of {{(current-input-port)}}. {{PORT}} may optionally be
222a string naming a file. Returns a list of strings, each string representing a line read, not including any line separation character(s).
223
224
225==== read-string
226==== read-string!
227==== write-string
228
229 [procedure] (read-string [NUM [PORT]])
230 [procedure] (read-string! NUM STRING [PORT [START]])
231 [procedure] (write-string STRING [NUM [PORT]]
232
233Read or write {{NUM}} characters from/to {{PORT}}, which defaults to the
234value of {{(current-input-port)}} or {{(current-output-port)}}, respectively.
235If {{NUM}} is {{#f}} or not given, then all data
236up to the end-of-file is read, or, in the case of {{write-string}} the whole
237string is written. If no more input is available, {{read-string}} returns the
238empty string. {{read-string!}} reads destructively into the given {{STRING}} argument,
239but never more characters that would fit into {{STRING}}. If {{START}} is given, then
240the read characters are stored starting at that position.
241{{read-string!}} returns the actual number of characters read.
242
243
244==== read-token
245
246 [procedure] (read-token PREDICATE [PORT])
247
248Reads characters from {{PORT}} (which defaults to the value of {{(current-input-port)}})
249and calls the procedure {{PREDICATE}} with each character until {{PREDICATE}} returns
250false. Returns a string with the accumulated characters.
251
252
253==== with-error-output-to-port
254
255 [procedure] (with-error-output-to-port PORT THUNK)
256
257Call procedure {{THUNK}} with the current error output-port
258temporarily bound to {{PORT}}.
259
260
261==== with-input-from-port
262
263 [procedure] (with-input-from-port PORT THUNK)
264
265Call procedure {{THUNK}} with the current input-port temporarily
266bound to {{PORT}}.
267
268
269==== with-output-to-port
270
271 [procedure] (with-output-to-port PORT THUNK)
272
273Call procedure {{THUNK}} with the current output-port temporarily
274bound to {{PORT}}.
275
276
277
278Previous: [[Unit data-structures]]
279
280Next: [[Unit srfi-1]]
Note: See TracBrowser for help on using the repository browser.