source: project/chicken/trunk/manual/Unit utils @ 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.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=== File move/copy
139
140==== file-copy
141
142 [procedure] (file-copy ORIGFILE NEWFILE #!optional CLOBBER BLOCKSIZE)
143
144Copies {{ORIGFILE}} (a string denoting some filename) to {{NEWFILE}},
145{{BLOCKSIZE}} bytes at a time.  {{BLOCKSIZE}} defaults to 1024, and must be
146a positive integer.  Returns the number of bytes copied on success, or errors
147on failure.  {{CLOBBER}} determines the behaviour of {{file-copy}} when
148{{NEWFILE}} is already extant.  When set to {{#f}} (default), an error is
149signalled.  When set to any other value, {{NEWFILE}} is overwritten.
150{{file-copy}} will work across filesystems and devices and is not
151platform-dependent.
152
153==== file-move
154
155 [procedure] (file-move ORIGFILE NEWFILE #!optional CLOBBER BLOCKSIZE)
156
157Moves {{ORIGFILE}} (a string denoting some filename) to {{NEWFILE}}, with
158the same semantics as {{file-copy}}, above.  {{file-move}} is safe across
159filesystems and devices (unlike {{file-rename}}).  It is possible for an
160error to be signalled despite partial success if {{NEWFILE}} could be created
161and fully written but removing {{ORIGFILE}} fails.
162
163
164=== Iterating over input lines and files
165
166==== for-each-line
167
168 [procedure] (for-each-line PROCEDURE [PORT])
169
170Calls {{PROCEDURE}} for each line read from {{PORT}} (which defaults to the
171value of {{(current-input-port)}}. The argument passed to {{PROCEDURE}}
172is a string with the contents of the line, excluding any line-terminators.
173When all input has been read from the port, {{for-each-line}} returns some unspecified value.
174
175==== for-each-argv-line
176
177 [procedure] (for-each-argv-line PROCEDURE)
178
179Opens each file listed on the command line in order, passing one line
180at a time into {{PROCEDURE}}.  The filename {{-}} is interpreted as
181{{(current-input-port)}}.  If no arguments are given on the command line
182it again uses the value of {{(current-input-port)}}. During execution of
183{{PROCEDURE}}, the current input port will be correctly bound to
184the current input source.
185
186This code will act as a simple Unix cat(1) command:
187
188<enscript highlight=scheme>
189(for-each-argv-line print)
190</enscript>
191
192==== port-for-each
193
194 [procedure] (port-for-each FN THUNK)
195
196Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}}
197until it returns {{#!eof}}, discarding the results.
198
199==== port-map
200
201 [procedure] (port-map FN THUNK)
202
203Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}}
204until it returns {{#!eof}}, returning a list of the collected results.
205
206==== port-fold
207
208 [procedure] (port-map FN ACC THUNK)
209
210Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}},
211passing the {{ACC}} value as the second argument. The {{FN}} result becomes the new
212{{ACC}} value. When {{THUNK}} returns {{#!eof}}, the last {{FN}} result is returned.
213
214=== Executing shell commands with formatstring and error checking
215
216==== system*
217
218 [procedure] (system* FORMATSTRING ARGUMENT1 ...)
219
220Similar to {{(system (sprintf FORMATSTRING ARGUMENT1 ...))}},
221but signals an error if the invoked program should return a nonzero
222exit status.
223
224
225=== Reading a file's contents
226
227==== read-all
228
229 [procedure] (read-all [FILE-OR-PORT])
230
231If {{FILE-OR-PORT}} is a string, then this procedure returns the contents of the file
232as a string. If {{FILE-OR-PORT}} is a port, all remaining input is read and returned as
233a string. The port is not closed. If no argument is provided, input will be read from the
234port that is the current value of {{(current-input-port)}}.
235
236
237=== Funky ports
238
239==== make-broadcast-port
240
241 [procedure] (make-broadcast-port PORT ...)
242
243Returns a custom output port that emits everything written into it to
244the ports given as {{PORT ...}}. Closing the broadcast port does not close
245any of the argument ports.
246
247==== make-concatenated-port
248
249 [procedure] (make-concatenated-port PORT1 PORT2 ...)
250
251Returns a custom input port that reads its input from {{PORT1}}, until it
252is empty, then from {{PORT2}} and so on. Closing the concatenated port
253does not close any of the argument ports.
254
255
256===  Miscellaneous handy things
257
258==== shift! DEPRECATED
259
260 [procedure] (shift! LIST [DEFAULT])
261
262Returns the car of {{LIST}} (or {{DEFAULT}} if {{LIST}} is empty) and replaces
263the car of {{LIST}} with it's cadr and the cdr with the cddr. If {{DEFAULT}} is not given, and
264the list is empty, {{#f}} is returned. An example might be clearer, here:
265
266<enscript highlight=scheme>
267(define lst '(1 2 3))
268(shift! lst)             ==> 1, lst is now (2 3)
269</enscript>
270
271The list must contain at least 2 elements.
272
273==== unshift! DEPRECATED
274
275 [procedure] (unshift! X PAIR)
276
277Sets the car of {{PAIR}} to {{X}} and the cdr to its cddr. Returns {{PAIR}}:
278
279<enscript highlight=scheme>
280(define lst '(2))
281(unshift! 99 lst)      ; lst is now (99 2)
282</enscript>
283
284
285Previous: [[Unit posix]]
286
287Next: [[Unit tcp]]
Note: See TracBrowser for help on using the repository browser.