source: project/chicken/trunk/manual/Unit utils @ 5945

Last change on this file since 5945 was 5945, checked in by felix winkelmann, 12 years ago

renamed some tools in misc/; apply hack fix on x86-64 (again); re-added manual

File size: 7.4 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4
5== Unit utils
6
7This unit contains file/pathname oriented procedures, apropos, plus acts as a "grab bag" for procedures without a good home,
8and which don't have to be available by default (as compared to the [[Unit extras|extras]] unit).
9
10This unit uses the {{extras}} and {{regex}} units.
11
12
13=== Environment Query
14
15==== apropos
16
17 [procedure] (apropos SYMBOL-PATTERN [ENVIRONMENT] [#:MACROS?])
18
19Displays symbols & type matching {{SYMBOL-PATTERN}} in the {{ENVIRONMENT}} on the {{(current-output-port)}}.
20
21; {{SYMBOL-PATTERN}} : A symbol, string, or regex. When symbol or string substring matching is performed.
22; {{ENVIRONMENT}} : An environment. When missing the {{(interaction-environment)}} is assumed.
23; {{#:MACROS?}} : Keyword argument. A boolean. Include macro symbols? When missing {{#f}} is assumed.
24
25==== apropos-list
26
27 [procedure] (apropos-list SYMBOL-PATTERN [ENVIRONMENT] [#:MACROS?])
28
29Like {{apropos}} but returns a list of matching symbols.
30
31
32=== Pathname operations
33
34==== absolute-pathname?
35
36 [procedure] (absolute-pathname? PATHNAME)
37
38Returns {{#t}} if the string {{PATHNAME}} names an absolute
39pathname, and returns {{#f}} otherwise.
40
41==== decompose-pathname
42
43 [procedure] (decompose-pathname PATHNAME)
44
45Returns three values: the directory-, filename- and extension-components
46of the file named by the string {{PATHNAME}}.
47For any component that is not contained in {{PATHNAME}}, {{#f}} is returned.
48
49==== make-pathname
50==== make-absolute-pathname
51
52 [procedure] (make-pathname DIRECTORY FILENAME [EXTENSION [SEPARATOR]])
53 [procedure] (make-absolute-pathname DIRECTORY FILENAME [EXTENSION [SEPARATOR]])
54
55Returns a string that names the file with the
56components {{DIRECTORY, FILENAME}} and (optionally)
57{{EXTENSION}} with {{SEPARATOR}} being the directory separation indicator
58(usually {{/}} on UNIX systems and {{\}} on Windows, defaulting to whatever
59platform this is running on).
60{{DIRECTORY}} can be {{#f}} (meaning no
61directory component), a string or a list of strings. {{FILENAME}}
62and {{EXTENSION}} should be strings or {{#f}}.
63{{make-absolute-pathname}} returns always an absolute pathname.
64
65==== pathname-directory
66
67 [procedure] (pathname-directory PATHNAME)
68
69==== pathname-file
70
71 [procedure] (pathname-file PATHNAME)
72
73==== pathname-extension
74
75 [procedure] (pathname-extension PATHNAME)
76
77Accessors for the components of {{PATHNAME}}. If the pathname does
78not contain the accessed component, then {{#f}} is returned.
79
80==== pathname-replace-directory
81
82 [procedure] (pathname-replace-directory PATHNAME DIRECTORY)
83
84==== pathname-replace-file
85
86 [procedure] (pathname-replace-file PATHNAME FILENAME)
87
88==== pathname-replace-extension
89
90 [procedure] (pathname-replace-extension PATHNAME EXTENSION)
91
92Return a new pathname with the specified component of {{PATHNAME}}
93replaced by a new value.
94
95==== pathname-strip-directory
96
97 [procedure] (pathname-strip-directory PATHNAME)
98
99==== pathname-strip-extension
100
101 [procedure] (pathname-strip-extension PATHNAME)
102
103Return a new pathname with the specified component of {{PATHNAME}}
104stripped.
105
106==== directory-null?
107
108 [procedure] (directory-null? DIRECTORY)
109
110Does the {{DIRECTORY}} consist only of path separators and the period?
111
112{{DIRECTORY}} may be a string or a list of strings.
113
114
115=== Temporary files
116
117==== create-temporary-file
118
119 [procedure] (create-temporary-file [EXTENSION])
120
121Creates an empty temporary file and returns its pathname. If
122{{EXTENSION}} is not given, then {{.tmp}} is used. If the
123environment variable {{TMPDIR, TEMP}} or {{TMP}} is set,
124then the pathname names a file in that directory.
125
126
127=== Deleting a file without signalling an error
128
129==== delete-file*
130
131 [procedure] (delete-file* FILENAME)
132
133If the file {{FILENAME}} exists, it is deleted and {{#t}}
134is returned.  If the file does not exist, nothing happens and {{#f}}
135is returned.
136
137
138=== Iterating over input lines and files
139
140==== for-each-line
141
142 [procedure] (for-each-line PROCEDURE [PORT])
143
144Calls {{PROCEDURE}} for each line read from {{PORT}} (which defaults to the
145value of {{(current-input-port)}}. The argument passed to {{PORCEDURE}}
146is a string with the contents of the line, excluding any line-terminators.
147When all input has been read from the port, {{for-each-line}} returns some unspecified value.
148
149==== for-each-argv-line
150
151 [procedure] (for-each-argv-line PROCEDURE)
152
153Opens each file listed on the command line in order, passing one line
154at a time into {{PROCEDURE}}.  The filename {{-}} is interpreted as
155{{(current-input-port)}}.  If no arguments are given on the command line
156it again uses the value of {{(current-input-port)}}. During execution of
157{{PROCEDURE}}, the current input port will be correctly bound to
158the current input source.
159
160This code will act as a simple Unix cat(1) command:
161
162<enscript highlight=scheme>
163(for-each-argv-line print)
164</enscript>
165
166==== port-for-each
167
168 [procedure] (port-for-each FN THUNK)
169
170Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}}
171until it returns {{#!eof}}, discarding the results.
172
173==== port-map
174
175 [procedure] (port-map FN THUNK)
176
177Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}}
178until it returns {{#!eof}}, returning a list of the collected results.
179
180==== port-fold
181
182 [procedure] (port-map FN ACC THUNK)
183
184Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}},
185passing the {{ACC}} value as the second argument. The {{FN}} result becomes the new
186{{ACC}} value. When {{THUNK}} returns {{#!eof}}, the last {{FN}} result is returned.
187
188=== Executing shell commands with formatstring and error checking
189
190==== system*
191
192 [procedure] (system* FORMATSTRING ARGUMENT1 ...)
193
194Similar to {{(system (sprintf FORMATSTRING ARGUMENT1 ...))}},
195but signals an error if the invoked program should return a nonzero
196exit status.
197
198
199=== Reading a file's contents
200
201==== read-all
202
203 [procedure] (read-all [FILE-OR-PORT])
204
205If {{FILE-OR-PORT}} is a string, then this procedure returns the contents of the file
206as a string. If {{FILE-OR-PORT}} is a port, all remaining input is read and returned as
207a string. The port is not closed. If no argument is provided, input will be read from the
208port that is the current value of {{(current-input-port)}}.
209
210
211=== Funky ports
212
213==== make-broadcast-port
214
215 [procedure] (make-broadcast-port PORT ...)
216
217Returns a custom output port that emits everything written into it to
218the ports given as {{PORT ...}}. Closing the broadcast port does not close
219any of the argument ports.
220
221==== make-concatenated-port
222
223 [procedure] (make-concatenated-port PORT1 PORT2 ...)
224
225Returns a custom input port that reads its input from {{PORT1}}, until it
226is empty, then from {{PORT2}} and so on. Closing the concatenated port
227does not close any of the argument ports.
228
229
230===  Miscellaneous handy things
231
232==== shift!
233
234 [procedure] (shift! LIST [DEFAULT])
235
236Returns the car of {{LIST}} (or {{DEFAULT}} if {{LIST}} is empty) and replaces
237the car of {{LIST}} with it's cadr and the cdr with the cddr. If {{DEFAULT}} is not given, and
238the list is empty, {{#f}} is returned. An example might be clearer, here:
239
240<enscript highlight=scheme>
241(define lst '(1 2 3))
242(shift! lst)             ==> 1, lst is now (2 3)
243</enscript>
244
245The list must contain at least 2 elements.
246
247==== unshift!
248
249 [procedure] (unshift! X PAIR)
250
251Sets the car of {{PAIR}} to {{X}} and the cdr to its cddr. Returns {{PAIR}}:
252
253<enscript highlight=scheme>
254(define lst '(2))
255(unshift! 99 lst)      ; lst is now (99 2)
256</enscript>
257
258
259Previous: [[Unit posix]]
260
261Next: [[Unit tcp]]
Note: See TracBrowser for help on using the repository browser.