source: project/wiki/eggref/3/filepath @ 13621

Last change on this file since 13621 was 13621, checked in by sjamaan, 11 years ago

Move old chicken 3 eggs over to eggref/3

File size: 7.6 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? PATH) => BOOL</procedure>
195
196<procedure>(filepath:add-trailing-path-separator PATH) => PATH</procedure>
197
198<procedure>(filepath:drop-trailing-path-separator PATH) => PATH</procedure>
199
200==== File Name Normalization and Predicates
201
202<procedure>(filepath:normalise PATH) => PATH</procedure>
203
204<procedure>(filepath:path-equal? PATH1 PATH2) => BOOL</procedure>
205
206<procedure>(filepath:make-relative ROOT PATH) => PATH</procedure>
207
208<procedure>(filepath:is-relative? PATH) => BOOL</procedure>
209
210<procedure>(filepath:is-absolute? PATH) => BOOL</procedure>
211
212<procedure>(filepath:is-valid? PATH) => BOOL</procedure>
213
214<procedure>(filepath:make-valid PATH) => PATH</procedure>
215
216
217=== Requires
218
219; [[matchable]]
220
221=== Version History
222
223* 1.0 Initial Release
224
225=== License
226
227
228Based on the [[http://www-users.cs.york.ac.uk/~ndm/filepath|Haskell FilePath library]] by Neil Mitchell.
229
230Copyright 2008 Ivan Raikov.
231
232Redistribution and use in source and binary forms, with or without
233modification, are permitted provided that the following conditions are
234met:
235
236- Redistributions of source code must retain the above copyright
237  notice, this list of conditions and the following disclaimer.
238
239- Redistributions in binary form must reproduce the above copyright
240  notice, this list of conditions and the following disclaimer in the
241  documentation and/or other materials provided with the distribution.
242
243- Neither name of the copyright holders nor the names of its
244  contributors may be used to endorse or promote products derived from
245  this software without specific prior written permission.
246
247THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND THE
248CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
249BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
250FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
251COPYRIGHT HOLDERS OR THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
252INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
253(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
254SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
255HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
256STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
257IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
258POSSIBILITY OF SUCH DAMAGE.
259
Note: See TracBrowser for help on using the repository browser.