Mercurial > projects > dwt2
comparison org.eclipse.equinox.common/src/org/eclipse/core/runtime/IPath.d @ 12:bc29606a740c
Added dwt-addons in original directory structure of eclipse.org
author | Frank Benoit <benoit@tionex.de> |
---|---|
date | Sat, 14 Mar 2009 18:23:29 +0100 |
parents | |
children | bbe49769ec18 |
comparison
equal
deleted
inserted
replaced
11:43904fec5dca | 12:bc29606a740c |
---|---|
1 /******************************************************************************* | |
2 * Copyright (c) 2000, 2008 IBM Corporation and others. | |
3 * All rights reserved. This program and the accompanying materials | |
4 * are made available under the terms of the Eclipse Public License v1.0 | |
5 * which accompanies this distribution, and is available at | |
6 * http://www.eclipse.org/legal/epl-v10.html | |
7 * | |
8 * Contributors: | |
9 * IBM Corporation - initial API and implementation | |
10 * Port to the D programming language: | |
11 * Frank Benoit <benoit@tionex.de> | |
12 *******************************************************************************/ | |
13 module org.eclipse.core.runtime.IPath; | |
14 | |
15 import java.lang.all; | |
16 import tango.io.FilePath; | |
17 | |
18 /** | |
19 * A path is an ordered collection of string segments, | |
20 * separated by a standard separator character, "/". | |
21 * A path may also have a leading and/or a trailing separator. | |
22 * Paths may also be prefixed by an optional device id, which includes | |
23 * the character(s) which separate the device id from the rest | |
24 * of the path. For example, "C:" and "Server/Volume:" are typical | |
25 * device ids. | |
26 * A device independent path has <code>null</code> for a device id. | |
27 * <p> | |
28 * Note that paths are value objects; all operations on paths | |
29 * return a new path; the path that is operated on is unscathed. | |
30 * </p> | |
31 * <p> | |
32 * UNC paths are denoted by leading double-slashes such | |
33 * as <code>//Server/Volume/My/Path</code>. When a new path | |
34 * is constructed all double-slashes are removed except those | |
35 * appearing at the beginning of the path. | |
36 * </p> | |
37 * <p> | |
38 * This interface can be used without OSGi running. | |
39 * </p><p> | |
40 * This interface is not intended to be implemented by clients. | |
41 * </p> | |
42 * @see Path | |
43 * @noextend This interface is not intended to be extended by clients. | |
44 * @noimplement This interface is not intended to be implemented by clients. | |
45 */ | |
46 public interface IPath : Cloneable { | |
47 | |
48 /** | |
49 * Path separator character constant "/" used in paths. | |
50 */ | |
51 public static const char SEPARATOR = '/'; | |
52 | |
53 /** | |
54 * Device separator character constant ":" used in paths. | |
55 */ | |
56 public static const char DEVICE_SEPARATOR = ':'; | |
57 | |
58 /** | |
59 * Returns a new path which is the same as this path but with | |
60 * the given file extension added. If this path is empty, root or has a | |
61 * trailing separator, this path is returned. If this path already | |
62 * has an extension, the existing extension is left and the given | |
63 * extension simply appended. Clients wishing to replace | |
64 * the current extension should first remove the extension and | |
65 * then add the desired one. | |
66 * <p> | |
67 * The file extension portion is defined as the string | |
68 * following the last period (".") character in the last segment. | |
69 * The given extension should not include a leading ".". | |
70 * </p> | |
71 * | |
72 * @param extension the file extension to append | |
73 * @return the new path | |
74 */ | |
75 public IPath addFileExtension(String extension); | |
76 | |
77 /** | |
78 * Returns a path with the same segments as this path | |
79 * but with a trailing separator added. | |
80 * This path must have at least one segment. | |
81 * <p> | |
82 * If this path already has a trailing separator, | |
83 * this path is returned. | |
84 * </p> | |
85 * | |
86 * @return the new path | |
87 * @see #hasTrailingSeparator() | |
88 * @see #removeTrailingSeparator() | |
89 */ | |
90 public IPath addTrailingSeparator(); | |
91 | |
92 /** | |
93 * Returns the canonicalized path obtained from the | |
94 * concatenation of the given string path to the | |
95 * end of this path. The given string path must be a valid | |
96 * path. If it has a trailing separator, | |
97 * the result will have a trailing separator. | |
98 * The device id of this path is preserved (the one | |
99 * of the given string is ignored). Duplicate slashes | |
100 * are removed from the path except at the beginning | |
101 * where the path is considered to be UNC. | |
102 * | |
103 * @param path the string path to concatenate | |
104 * @return the new path | |
105 * @see #isValidPath(String) | |
106 */ | |
107 public IPath append(String path); | |
108 | |
109 /** | |
110 * Returns the canonicalized path obtained from the | |
111 * concatenation of the given path's segments to the | |
112 * end of this path. If the given path has a trailing | |
113 * separator, the result will have a trailing separator. | |
114 * The device id of this path is preserved (the one | |
115 * of the given path is ignored). Duplicate slashes | |
116 * are removed from the path except at the beginning | |
117 * where the path is considered to be UNC. | |
118 * | |
119 * @param path the path to concatenate | |
120 * @return the new path | |
121 */ | |
122 public IPath append(IPath path); | |
123 | |
124 /** | |
125 * Returns a copy of this path. | |
126 * | |
127 * @return the cloned path | |
128 */ | |
129 public Object clone(); | |
130 | |
131 /** | |
132 * Returns whether this path equals the given object. | |
133 * <p> | |
134 * Equality for paths is defined to be: same sequence of segments, | |
135 * same absolute/relative status, and same device. | |
136 * Trailing separators are disregarded. | |
137 * Paths are not generally considered equal to objects other than paths. | |
138 * </p> | |
139 * | |
140 * @param obj the other object | |
141 * @return <code>true</code> if the paths are equivalent, | |
142 * and <code>false</code> if they are not | |
143 */ | |
144 public int opEquals(Object obj); | |
145 | |
146 /** | |
147 * Returns the device id for this path, or <code>null</code> if this | |
148 * path has no device id. Note that the result will end in ':'. | |
149 * | |
150 * @return the device id, or <code>null</code> | |
151 * @see #setDevice(String) | |
152 */ | |
153 public String getDevice(); | |
154 | |
155 /** | |
156 * Returns the file extension portion of this path, | |
157 * or <code>null</code> if there is none. | |
158 * <p> | |
159 * The file extension portion is defined as the string | |
160 * following the last period (".") character in the last segment. | |
161 * If there is no period in the last segment, the path has no | |
162 * file extension portion. If the last segment ends in a period, | |
163 * the file extension portion is the empty string. | |
164 * </p> | |
165 * | |
166 * @return the file extension or <code>null</code> | |
167 */ | |
168 public String getFileExtension(); | |
169 | |
170 /** | |
171 * Returns whether this path has a trailing separator. | |
172 * <p> | |
173 * Note: In the root path ("/"), the separator is considered to | |
174 * be leading rather than trailing. | |
175 * </p> | |
176 * | |
177 * @return <code>true</code> if this path has a trailing | |
178 * separator, and <code>false</code> otherwise | |
179 * @see #addTrailingSeparator() | |
180 * @see #removeTrailingSeparator() | |
181 */ | |
182 public bool hasTrailingSeparator(); | |
183 | |
184 /** | |
185 * Returns whether this path is an absolute path (ignoring | |
186 * any device id). | |
187 * <p> | |
188 * Absolute paths start with a path separator. | |
189 * A root path, like <code>/</code> or <code>C:/</code>, | |
190 * is considered absolute. UNC paths are always absolute. | |
191 * </p> | |
192 * | |
193 * @return <code>true</code> if this path is an absolute path, | |
194 * and <code>false</code> otherwise | |
195 */ | |
196 public bool isAbsolute(); | |
197 | |
198 /** | |
199 * Returns whether this path has no segments and is not | |
200 * a root path. | |
201 * | |
202 * @return <code>true</code> if this path is empty, | |
203 * and <code>false</code> otherwise | |
204 */ | |
205 public bool isEmpty(); | |
206 | |
207 /** | |
208 * Returns whether this path is a prefix of the given path. | |
209 * To be a prefix, this path's segments must | |
210 * appear in the argument path in the same order, | |
211 * and their device ids must match. | |
212 * <p> | |
213 * An empty path is a prefix of all paths with the same device; a root path is a prefix of | |
214 * all absolute paths with the same device. | |
215 * </p> | |
216 * @param anotherPath the other path | |
217 * @return <code>true</code> if this path is a prefix of the given path, | |
218 * and <code>false</code> otherwise | |
219 */ | |
220 public bool isPrefixOf(IPath anotherPath); | |
221 | |
222 /** | |
223 * Returns whether this path is a root path. | |
224 * <p> | |
225 * The root path is the absolute non-UNC path with zero segments; | |
226 * e.g., <code>/</code> or <code>C:/</code>. | |
227 * The separator is considered a leading separator, not a trailing one. | |
228 * </p> | |
229 * | |
230 * @return <code>true</code> if this path is a root path, | |
231 * and <code>false</code> otherwise | |
232 */ | |
233 public bool isRoot(); | |
234 | |
235 /** | |
236 * Returns a bool value indicating whether or not this path | |
237 * is considered to be in UNC form. Return false if this path | |
238 * has a device set or if the first 2 characters of the path string | |
239 * are not <code>Path.SEPARATOR</code>. | |
240 * | |
241 * @return bool indicating if this path is UNC | |
242 */ | |
243 public bool isUNC(); | |
244 | |
245 /** | |
246 * Returns whether the given string is syntactically correct as | |
247 * a path. The device id is the prefix up to and including the device | |
248 * separator for the local file system; the path proper is everything to | |
249 * the right of it, or the entire string if there is no device separator. | |
250 * When the platform location is a file system with no meaningful device | |
251 * separator, the entire string is treated as the path proper. | |
252 * The device id is not checked for validity; the path proper is correct | |
253 * if each of the segments in its canonicalized form is valid. | |
254 * | |
255 * @param path the path to check | |
256 * @return <code>true</code> if the given string is a valid path, | |
257 * and <code>false</code> otherwise | |
258 * @see #isValidSegment(String) | |
259 */ | |
260 public bool isValidPath(String path); | |
261 | |
262 /** | |
263 * Returns whether the given string is valid as a segment in | |
264 * a path. The rules for valid segments are as follows: | |
265 * <ul> | |
266 * <li> the empty string is not valid | |
267 * <li> any string containing the slash character ('/') is not valid | |
268 * <li>any string containing segment or device separator characters | |
269 * on the local file system, such as the backslash ('\') and colon (':') | |
270 * on some file systems. | |
271 * </ul> | |
272 * | |
273 * @param segment the path segment to check | |
274 * @return <code>true</code> if the given path segment is valid, | |
275 * and <code>false</code> otherwise | |
276 */ | |
277 public bool isValidSegment(String segment); | |
278 | |
279 /** | |
280 * Returns the last segment of this path, or | |
281 * <code>null</code> if it does not have any segments. | |
282 * | |
283 * @return the last segment of this path, or <code>null</code> | |
284 */ | |
285 public String lastSegment(); | |
286 | |
287 /** | |
288 * Returns an absolute path with the segments and device id of this path. | |
289 * Absolute paths start with a path separator. If this path is absolute, | |
290 * it is simply returned. | |
291 * | |
292 * @return the new path | |
293 */ | |
294 public IPath makeAbsolute(); | |
295 | |
296 /** | |
297 * Returns a relative path with the segments and device id of this path. | |
298 * Absolute paths start with a path separator and relative paths do not. | |
299 * If this path is relative, it is simply returned. | |
300 * | |
301 * @return the new path | |
302 */ | |
303 public IPath makeRelative(); | |
304 | |
305 /** | |
306 * Return a new path which is the equivalent of this path converted to UNC | |
307 * form (if the given bool is true) or this path not as a UNC path (if the given | |
308 * bool is false). If UNC, the returned path will not have a device and the | |
309 * first 2 characters of the path string will be <code>Path.SEPARATOR</code>. If not UNC, the | |
310 * first 2 characters of the returned path string will not be <code>Path.SEPARATOR</code>. | |
311 * | |
312 * @param toUNC true if converting to UNC, false otherwise | |
313 * @return the new path, either in UNC form or not depending on the bool parameter | |
314 */ | |
315 public IPath makeUNC(bool toUNC); | |
316 | |
317 /** | |
318 * Returns a count of the number of segments which match in | |
319 * this path and the given path (device ids are ignored), | |
320 * comparing in increasing segment number order. | |
321 * | |
322 * @param anotherPath the other path | |
323 * @return the number of matching segments | |
324 */ | |
325 public int matchingFirstSegments(IPath anotherPath); | |
326 | |
327 /** | |
328 * Returns a new path which is the same as this path but with | |
329 * the file extension removed. If this path does not have an | |
330 * extension, this path is returned. | |
331 * <p> | |
332 * The file extension portion is defined as the string | |
333 * following the last period (".") character in the last segment. | |
334 * If there is no period in the last segment, the path has no | |
335 * file extension portion. If the last segment ends in a period, | |
336 * the file extension portion is the empty string. | |
337 * </p> | |
338 * | |
339 * @return the new path | |
340 */ | |
341 public IPath removeFileExtension(); | |
342 | |
343 /** | |
344 * Returns a copy of this path with the given number of segments | |
345 * removed from the beginning. The device id is preserved. | |
346 * The number must be greater or equal zero. | |
347 * If the count is zero, this path is returned. | |
348 * The resulting path will always be a relative path with respect | |
349 * to this path. If the number equals or exceeds the number | |
350 * of segments in this path, an empty relative path is returned. | |
351 * | |
352 * @param count the number of segments to remove | |
353 * @return the new path | |
354 */ | |
355 public IPath removeFirstSegments(int count); | |
356 | |
357 /** | |
358 * Returns a copy of this path with the given number of segments | |
359 * removed from the end. The device id is preserved. | |
360 * The number must be greater or equal zero. | |
361 * If the count is zero, this path is returned. | |
362 * <p> | |
363 * If this path has a trailing separator, it will still | |
364 * have a trailing separator after the last segments are removed | |
365 * (assuming there are some segments left). If there is no | |
366 * trailing separator, the result will not have a trailing | |
367 * separator. | |
368 * If the number equals or exceeds the number | |
369 * of segments in this path, a path with no segments is returned. | |
370 * </p> | |
371 * | |
372 * @param count the number of segments to remove | |
373 * @return the new path | |
374 */ | |
375 public IPath removeLastSegments(int count); | |
376 | |
377 /** | |
378 * Returns a path with the same segments as this path | |
379 * but with a trailing separator removed. | |
380 * Does nothing if this path does not have at least one segment. | |
381 * The device id is preserved. | |
382 * <p> | |
383 * If this path does not have a trailing separator, | |
384 * this path is returned. | |
385 * </p> | |
386 * | |
387 * @return the new path | |
388 * @see #addTrailingSeparator() | |
389 * @see #hasTrailingSeparator() | |
390 */ | |
391 public IPath removeTrailingSeparator(); | |
392 | |
393 /** | |
394 * Returns the specified segment of this path, or | |
395 * <code>null</code> if the path does not have such a segment. | |
396 * | |
397 * @param index the 0-based segment index | |
398 * @return the specified segment, or <code>null</code> | |
399 */ | |
400 public String segment(int index); | |
401 | |
402 /** | |
403 * Returns the number of segments in this path. | |
404 * <p> | |
405 * Note that both root and empty paths have 0 segments. | |
406 * </p> | |
407 * | |
408 * @return the number of segments | |
409 */ | |
410 public int segmentCount(); | |
411 | |
412 /** | |
413 * Returns the segments in this path in order. | |
414 * | |
415 * @return an array of string segments | |
416 */ | |
417 public String[] segments(); | |
418 | |
419 /** | |
420 * Returns a new path which is the same as this path but with | |
421 * the given device id. The device id must end with a ":". | |
422 * A device independent path is obtained by passing <code>null</code>. | |
423 * <p> | |
424 * For example, "C:" and "Server/Volume:" are typical device ids. | |
425 * </p> | |
426 * | |
427 * @param device the device id or <code>null</code> | |
428 * @return a new path | |
429 * @see #getDevice() | |
430 */ | |
431 public IPath setDevice(String device); | |
432 | |
433 /** | |
434 * Returns a <code>java.io.File</code> corresponding to this path. | |
435 * | |
436 * @return the file corresponding to this path | |
437 */ | |
438 public tango.io.FilePath.FilePath toFile(); | |
439 | |
440 /** | |
441 * Returns a string representation of this path which uses the | |
442 * platform-dependent path separator defined by <code>java.io.File</code>. | |
443 * This method is like <code>toString()</code> except that the | |
444 * latter always uses the same separator (<code>/</code>) regardless of platform. | |
445 * <p> | |
446 * This string is suitable for passing to <code>java.io.File(String)</code>. | |
447 * </p> | |
448 * | |
449 * @return a platform-dependent string representation of this path | |
450 */ | |
451 public String toOSString(); | |
452 | |
453 /** | |
454 * Returns a platform-neutral string representation of this path. The | |
455 * format is not specified, except that the resulting string can be | |
456 * passed back to the <code>Path#fromPortableString(String)</code> | |
457 * constructor to produce the exact same path on any platform. | |
458 * <p> | |
459 * This string is suitable for passing to <code>Path#fromPortableString(String)</code>. | |
460 * </p> | |
461 * | |
462 * @return a platform-neutral string representation of this path | |
463 * @see Path#fromPortableString(String) | |
464 * @since 3.1 | |
465 */ | |
466 public String toPortableString(); | |
467 | |
468 /** | |
469 * Returns a string representation of this path, including its | |
470 * device id. The same separator, "/", is used on all platforms. | |
471 * <p> | |
472 * Example result strings (without and with device id): | |
473 * <pre> | |
474 * "/foo/bar.txt" | |
475 * "bar.txt" | |
476 * "/foo/" | |
477 * "foo/" | |
478 * "" | |
479 * "/" | |
480 * "C:/foo/bar.txt" | |
481 * "C:bar.txt" | |
482 * "C:/foo/" | |
483 * "C:foo/" | |
484 * "C:" | |
485 * "C:/" | |
486 * </pre> | |
487 * This string is suitable for passing to <code>Path(String)</code>. | |
488 * </p> | |
489 * | |
490 * @return a string representation of this path | |
491 * @see Path | |
492 */ | |
493 public String toString(); | |
494 | |
495 /** | |
496 * Returns a copy of this path truncated after the | |
497 * given number of segments. The number must not be negative. | |
498 * The device id is preserved. | |
499 * <p> | |
500 * If this path has a trailing separator, the result will too | |
501 * (assuming there are some segments left). If there is no | |
502 * trailing separator, the result will not have a trailing | |
503 * separator. | |
504 * Copying up to segment zero simply means making an copy with | |
505 * no path segments. | |
506 * </p> | |
507 * | |
508 * @param count the segment number at which to truncate the path | |
509 * @return the new path | |
510 */ | |
511 public IPath uptoSegment(int count); | |
512 } |