source: project/wiki/filepath @ 12294

Last change on this file since 12294 was 12294, checked in by Ivan Raikov, 13 years ago

Added documentation for file path operations.

File size: 7.5 KB
Line 
1[[tags: eggs]]
2[[toc:]]
3
4== filepath
5
6=== Description
7
8The {{filepath}} library contains procedures for cross-platform
9parsing and manipulation of file paths. It supports both Windows and
10POSIX paths, including Windows share paths.
11
12=== Library Procedures
13
14==== Platform Flags
15
16<procedure>(filepath:posix [BOOL]) => BOOL</procedure>
17
18If invoked without arguments, this procedure returns whether the
19library procedures assume POSIX-style paths or not. Invoking the
20procedure with a boolean argument disables or enables POSIX-style
21paths. If set to false, the library procedures assume Windows-style
22paths.
23
24<procedure>(filepath:is-windows?) => BOOL</procedure>
25
26Convenience function that returns the inverse of {{(filepath:posix)}}.
27
28<procedure>(filepath:is-posix?) => BOOL</procedure>
29
30Convenience function that returns the result of {{(filepath:posix)}}.
31
32==== Path Separators
33
34<procedure>(filepath:path-separator) => CHAR</procedure>
35
36The character that separates directories. On platforms where more than
37one character is possible, this procedure returns the default one.
38
39<procedure>(filepath:path-separator-set) => CHAR-SET</procedure>
40
41The set of all possible path separator characters.
42
43<procedure>(filepath:is-path-separator? CHAR) => BOOL</procedure>
44
45A predicate that returns whether the given character is a path
46separator for the current platform.
47
48<procedure>(filepath:search-path-separator) => CHAR</procedure>
49
50The character that is used to separate the entries in the {{PATH}}
51environment variable.
52
53<procedure>(filepath:is-search-path-separator? CHAR) => BOOL</procedure>
54
55A predicate that returns whether the given character can be used a
56separator in the {{PATH}} environment variable.
57
58<procedure>(filepath:ext-separator) => CHAR</procedure>
59
60The character that is used to separate file extensions.
61
62<procedure>(filepath:is-ext-separator? CHAR) => BOOL</procedure>
63
64A predicate that returns whether the given character is a file
65extension separator.
66
67==== Search Path
68
69<procedure>(filepath:split-search-path STRING) => LIST</procedure>
70
71Splits a string on the search path separator character.
72
73<procedure>(filepath:get-search-path) => STRING</procedure>
74
75Returns search path from the OS environment.
76
77==== Extension procedures
78
79<procedure>(filepath:split-extension PATH) => (NAME EXT)</procedure>
80
81Splits path on the last extension.
82
83<procedure>(filepath:take-extension PATH) => EXT</procedure>
84
85Returns last extension of given path, or empty string.
86
87<procedure>(filepath:replace-extension PATH EXT) => PATH</procedure>
88 
89Replaces the last path extension with the given extension.
90
91<procedure>(filepath:drop-extension PATH) => PATH</procedure>
92
93Removes last extension and extension separator preceding it.
94
95<procedure>(filepath:add-extension PATH EXT) => PATH</procedure>
96 
97Appends an extension to the given path.
98
99<procedure>(filepath:has-extension? PATH) => BOOL</procedure>
100
101Returns true if the given path has an extension.
102 
103<procedure>(filepath:split-all-extensions PATH) => (NAME EXT)</procedure>
104
105Splits path on the first extension.
106
107<procedure>(filepath:drop-all-extensions PATH) => PATH</procedure>
108 
109Removes all extensions from the path.
110
111<procedure>(filepath:take-all-extensions PATH) => EXT</procedure>
112
113Returns all extensions from the path.
114
115==== Drive procedures
116
117<procedure>filepath:split-drive</procedure> 
118
119Splits a path into a Windows drive and a path. When in POSIX mode,
120{{/}} is treated as a drive.
121
122<procedure>(filepath:join-drive DRIVE PATH) => PATH</procedure>
123
124Joins a drive and the rest of the path.
125
126<procedure>(filepath:take-drive PATH) => DRIVE</procedure>
127
128Returns the drive of a path.
129
130<procedure>(filepath:has-drive? PATH) => BOOL</procedure>
131
132Returns whether the given path has a drive.
133
134<procedure>(filepath:drop-drive PATH) => PATH</procedure>
135
136Removes the drive from the given path.
137
138<procedure>(filepath:is-drive? STRING) => BOOL</procedure>
139
140Returns true if the given string is a drive specification.
141
142==== Operations on a file path
143
144<procedure>(filepath:split-file-name PATH) => (DIR FILE)</procedure>
145
146Splits a path into directory and file.
147
148<procedure>(filepath:take-file-name PATH) => FILE</procedure>
149
150Returns the filename component of a path.
151
152<procedure>(filepath:replace-file-name PATH FILE) => PATH</procedure>
153
154Replaces the filename component of a path with the given one.
155
156<procedure>(filepath:drop-file-name PATH) => PATH</procedure>
157
158Removes the filename component of a path.
159
160<procedure>(filepath:take-base-name PATH) => STRING</procedure>
161
162Returns the base file name (no extension) of a path.
163
164<procedure>(filepath:replace-base-name PATH BASE) => PATH</procedure>
165
166Replaces the base file name of a path with the given one.
167
168<procedure>(filepath:take-directory PATH) => DIR</procedure>
169
170Returns the directory component of a path.
171
172<procedure>(filepath:replace-directory PATH DIR) => PATH</procedure>
173
174Replaces the directory component of a path with the given one.
175
176<procedure>(filepath:combine PATH1 PATH2) => PATH</procedure>
177
178Combines two paths. If the second path is absolute, then it returns the second.
179
180<procedure>(filepath:split-path PATH) => LIST</procedure>
181
182Splits a path by the directory separator.
183
184<procedure>(filepath:join-path LIST) => PATH</procedure>
185
186Joins path elements back together.
187
188<procedure>filepath:split-directories</procedure>
189
190As {{split-path}}, but does not add trailing separators to each element.
191
192==== Trailing Separators
193
194<procedure>filepath:has-trailing-path-separator?</procedure>
195
196<procedure>filepath:add-trailing-path-separator</procedure>
197
198<procedure>filepath:drop-trailing-path-separator</procedure>
199
200==== File Name Normalization
201
202<procedure>filepath:normalise</procedure>
203
204<procedure>filepath:path-equal?</procedure>
205
206<procedure>filepath:make-relative</procedure>
207
208<procedure>filepath:is-relative?</procedure>
209
210<procedure>filepath:is-absolute?</procedure>
211
212<procedure>filepath:is-valid?</procedure> 
213
214<procedure>filepath:make-valid</procedure>
215
216
217
218
219=== Requires
220
221; [[matchable]]
222
223=== Version History
224
225* 1.0 Initial Release
226
227=== License
228
229
230Based on the [[http://www-users.cs.york.ac.uk/~ndm/filepath|Haskell FilePath library]] by Neil Mitchell.
231
232Copyright 2008 Ivan Raikov.
233
234Redistribution and use in source and binary forms, with or without
235modification, are permitted provided that the following conditions are
236met:
237
238- Redistributions of source code must retain the above copyright
239  notice, this list of conditions and the following disclaimer.
240
241- Redistributions in binary form must reproduce the above copyright
242  notice, this list of conditions and the following disclaimer in the
243  documentation and/or other materials provided with the distribution.
244
245- Neither name of the copyright holders nor the names of its
246  contributors may be used to endorse or promote products derived from
247  this software without specific prior written permission.
248
249THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND THE
250CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
251BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
252FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
253COPYRIGHT HOLDERS OR THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
254INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
255(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
256SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
257HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
258STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
259IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
260POSSIBILITY OF SUCH DAMAGE.
261
Note: See TracBrowser for help on using the repository browser.