Mercurial > projects > dwt-addons

comparison dwtx/core/runtime/IPath.d @ 3:6518c18a01f7

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