source: project/chicken/trunk/manual/Unit files @ 15813

Last change on this file since 15813 was 15813, checked in by Kon Lovett, 11 years ago

posixwin use of 'fx= 0' instead of 'zero?'
posixunix use of 'fx= 0' instead of 'zero?', fix for 'create-directory' when absolute pathname & easier to read
files common code for "is this a pds char?", added 'decompose-directory', rmvd redundent compile-time proc cache
files added 'decompose-directory'
data-structures 'random-seed' not here

File size: 5.4 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==== decompose-directory
108
109<procedure>(decompose-directory DIRECTORY)</procedure>
110
111Returns 3 values: the {{base-origin}}, {{base-directory}}, and the
112{{directory-elements}} for the {{DIRECTORY}}.
113
114; {{base-origin}} : a {{string}} or {{#f}}. The drive, if any.
115; {{base-directory}} : a {{string}} or {{#f}}. A directory-separator when {{DIRECTORY}} is an {{absolute-pathname}}.
116; {{directory-elements}} : a {{list-of string}} or {{#f}}. The non-directory-separator bits.
117
118{{DIRECTORY}} is a {{string}}.
119
120* On WIndows {{(decompose-directory "c:foo/bar")}} => {{"c:" #f ("foo" "bar")}}
121
122
123=== Temporary files
124
125==== create-temporary-file
126
127<procedure>(create-temporary-file [EXTENSION])</procedure>
128
129Creates an empty temporary file and returns its pathname. If
130{{EXTENSION}} is not given, then {{.tmp}} is used. If the
131environment variable {{TMPDIR, TEMP}} or {{TMP}} is set,
132then the pathname names a file in that directory.
133
134
135=== Deleting a file without signalling an error
136
137==== delete-file*
138
139<procedure>(delete-file* FILENAME)</procedure>
140
141If the file {{FILENAME}} exists, it is deleted and {{#t}}
142is returned.  If the file does not exist, nothing happens and {{#f}}
143is returned.
144
145
146=== File move/copy
147
148==== file-copy
149
150<procedure>(file-copy ORIGFILE NEWFILE #!optional CLOBBER BLOCKSIZE)</procedure>
151
152Copies {{ORIGFILE}} (a string denoting some filename) to {{NEWFILE}},
153{{BLOCKSIZE}} bytes at a time.  {{BLOCKSIZE}} defaults to 1024, and must be
154a positive integer.  Returns the number of bytes copied on success, or errors
155on failure.  {{CLOBBER}} determines the behaviour of {{file-copy}} when
156{{NEWFILE}} is already extant.  When set to {{#f}} (default), an error is
157signalled.  When set to any other value, {{NEWFILE}} is overwritten.
158{{file-copy}} will work across filesystems and devices and is not
159platform-dependent.
160
161==== file-move
162
163<procedure>(file-move ORIGFILE NEWFILE #!optional CLOBBER BLOCKSIZE)</procedure>
164
165Moves {{ORIGFILE}} (a string denoting some filename) to {{NEWFILE}}, with
166the same semantics as {{file-copy}}, above.  {{file-move}} is safe across
167filesystems and devices (unlike {{file-rename}}).  It is possible for an
168error to be signalled despite partial success if {{NEWFILE}} could be created
169and fully written but removing {{ORIGFILE}} fails.
170
171---
172Previous: [[Unit ports]]
173
174Next: [[Unit extras]]
Note: See TracBrowser for help on using the repository browser.