source: project/chicken/branches/release/manual/Unit files @ 15293

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

merged prerelease branch r15292 into release branch; synced with manual in wiki

File size: 4.8 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4
5== Unit files
6
7This unit contains file- and pathname-oriented procedures. It uses the {{regex}} unit.
8
9
10=== Pathname operations
11
12==== absolute-pathname?
13
14<procedure>(absolute-pathname? PATHNAME)</procedure>
15
16Returns {{#t}} if the string {{PATHNAME}} names an absolute
17pathname, and returns {{#f}} otherwise.
18
19==== decompose-pathname
20
21<procedure>(decompose-pathname PATHNAME)</procedure>
22
23Returns three values: the directory-, filename- and extension-components
24of the file named by the string {{PATHNAME}}.
25For any component that is not contained in {{PATHNAME}}, {{#f}} is returned.
26
27==== make-pathname
28==== make-absolute-pathname
29
30<procedure>(make-pathname DIRECTORY FILENAME [EXTENSION [SEPARATOR]])</procedure>
31<procedure>(make-absolute-pathname DIRECTORY FILENAME [EXTENSION [SEPARATOR]])</procedure>
32
33Returns a string that names the file with the
34components {{DIRECTORY, FILENAME}} and (optionally)
35{{EXTENSION}} with {{SEPARATOR}} being the directory separation indicator
36(usually {{/}} on UNIX systems and {{\}} on Windows, defaulting to whatever
37platform this is running on).
38{{DIRECTORY}} can be {{#f}} (meaning no
39directory component), a string or a list of strings. {{FILENAME}}
40and {{EXTENSION}} should be strings or {{#f}}.
41{{make-absolute-pathname}} returns always an absolute pathname.
42
43==== pathname-directory
44
45<procedure>(pathname-directory PATHNAME)</procedure>
46
47==== pathname-file
48
49<procedure>(pathname-file PATHNAME)</procedure>
50
51==== pathname-extension
52
53<procedure>(pathname-extension PATHNAME)</procedure>
54
55Accessors for the components of {{PATHNAME}}. If the pathname does
56not contain the accessed component, then {{#f}} is returned.
57
58==== pathname-replace-directory
59
60<procedure>(pathname-replace-directory PATHNAME DIRECTORY)</procedure>
61
62==== pathname-replace-file
63
64<procedure>(pathname-replace-file PATHNAME FILENAME)</procedure>
65
66==== pathname-replace-extension
67
68<procedure>(pathname-replace-extension PATHNAME EXTENSION)</procedure>
69
70Return a new pathname with the specified component of {{PATHNAME}}
71replaced by a new value.
72
73==== pathname-strip-directory
74
75<procedure>(pathname-strip-directory PATHNAME)</procedure>
76
77==== pathname-strip-extension
78
79<procedure>(pathname-strip-extension PATHNAME)</procedure>
80
81Return a new pathname with the specified component of {{PATHNAME}}
82stripped.
83
84==== normalize-pathname
85
86<procedure>(normalize-pathname PATHNAME [PLATFORM])</procedure>
87
88Performs a simple "normalization" on the {{PATHNAME}}, suitably for
89{{PLATFORM}}, which should be one of the symbols {{windows}}
90or {{unix}} and defaults to on whatever platform is currently
91in use. All relative path elements and duplicate separators are processed
92and removed.  If {{NAME}} ends with
93a {{/}} or is empty, the appropriate slash is appended to the tail.
94Tilde {{~}} and variable {{$<name>/...}} expansion is also done.
95
96No directories or files are actually tested for existence; this
97procedure only canonicalises path syntax.
98
99==== directory-null?
100
101<procedure>(directory-null? DIRECTORY)</procedure>
102
103Does the {{DIRECTORY}} consist only of path separators and the period?
104
105{{DIRECTORY}} may be a string or a list of strings.
106
107
108=== Temporary files
109
110==== create-temporary-file
111
112<procedure>(create-temporary-file [EXTENSION])</procedure>
113
114Creates an empty temporary file and returns its pathname. If
115{{EXTENSION}} is not given, then {{.tmp}} is used. If the
116environment variable {{TMPDIR, TEMP}} or {{TMP}} is set,
117then the pathname names a file in that directory.
118
119
120=== Deleting a file without signalling an error
121
122==== delete-file*
123
124<procedure>(delete-file* FILENAME)</procedure>
125
126If the file {{FILENAME}} exists, it is deleted and {{#t}}
127is returned.  If the file does not exist, nothing happens and {{#f}}
128is returned.
129
130
131=== File move/copy
132
133==== file-copy
134
135<procedure>(file-copy ORIGFILE NEWFILE #!optional CLOBBER BLOCKSIZE)</procedure>
136
137Copies {{ORIGFILE}} (a string denoting some filename) to {{NEWFILE}},
138{{BLOCKSIZE}} bytes at a time.  {{BLOCKSIZE}} defaults to 1024, and must be
139a positive integer.  Returns the number of bytes copied on success, or errors
140on failure.  {{CLOBBER}} determines the behaviour of {{file-copy}} when
141{{NEWFILE}} is already extant.  When set to {{#f}} (default), an error is
142signalled.  When set to any other value, {{NEWFILE}} is overwritten.
143{{file-copy}} will work across filesystems and devices and is not
144platform-dependent.
145
146==== file-move
147
148<procedure>(file-move ORIGFILE NEWFILE #!optional CLOBBER BLOCKSIZE)</procedure>
149
150Moves {{ORIGFILE}} (a string denoting some filename) to {{NEWFILE}}, with
151the same semantics as {{file-copy}}, above.  {{file-move}} is safe across
152filesystems and devices (unlike {{file-rename}}).  It is possible for an
153error to be signalled despite partial success if {{NEWFILE}} could be created
154and fully written but removing {{ORIGFILE}} fails.
155
156---
157Previous: [[Unit ports]]
158
159Next: [[Unit extras]]
Note: See TracBrowser for help on using the repository browser.