--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/dwtx/core/runtime/IPath.d	Wed Mar 26 00:57:19 2008 +0100
@@ -0,0 +1,510 @@
+/*******************************************************************************
+ * Copyright (c) 2000, 2006 IBM Corporation and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ *     IBM Corporation - initial API and implementation
+ * Port to the D programming language:
+ *     Frank Benoit <benoit@tionex.de>
+ *******************************************************************************/
+module dwtx.core.runtime.IPath;
+
+import dwt.dwthelper.utils;
+import tango.io.FilePath;
+
+/**
+ * A path is an ordered collection of string segments,
+ * separated by a standard separator character, "/".
+ * A path may also have a leading and/or a trailing separator.
+ * Paths may also be prefixed by an optional device id, which includes
+ * the character(s) which separate the device id from the rest
+ * of the path. For example, "C:" and "Server/Volume:" are typical
+ * device ids.
+ * A device independent path has <code>null</code> for a device id.
+ * <p>
+ * Note that paths are value objects; all operations on paths
+ * return a new path; the path that is operated on is unscathed.
+ * </p>
+ * <p>
+ * UNC paths are denoted by leading double-slashes such
+ * as <code>//Server/Volume/My/Path</code>. When a new path
+ * is constructed all double-slashes are removed except those
+ * appearing at the beginning of the path.
+ * </p>
+ * <p>
+ * This interface can be used without OSGi running.
+ * </p><p>
+ * This interface is not intended to be implemented by clients.
+ * </p>
+ * @see Path
+ */
+public interface IPath : Cloneable {
+
+    /**
+     * Path separator character constant "/" used in paths.
+     */
+    public static const char SEPARATOR = '/';
+
+    /**
+     * Device separator character constant ":" used in paths.
+     */
+    public static const char DEVICE_SEPARATOR = ':';
+
+    /**
+     * Returns a new path which is the same as this path but with
+     * the given file extension added.  If this path is empty, root or has a
+     * trailing separator, this path is returned.  If this path already
+     * has an extension, the existing extension is left and the given
+     * extension simply appended.  Clients wishing to replace
+     * the current extension should first remove the extension and
+     * then add the desired one.
+     * <p>
+     * The file extension portion is defined as the string
+     * following the last period (".") character in the last segment.
+     * The given extension should not include a leading ".".
+     * </p>
+     *
+     * @param extension the file extension to append
+     * @return the new path
+     */
+    public IPath addFileExtension(String extension);
+
+    /**
+     * Returns a path with the same segments as this path
+     * but with a trailing separator added.
+     * This path must have at least one segment.
+     * <p>
+     * If this path already has a trailing separator,
+     * this path is returned.
+     * </p>
+     *
+     * @return the new path
+     * @see #hasTrailingSeparator()
+     * @see #removeTrailingSeparator()
+     */
+    public IPath addTrailingSeparator();
+
+    /**
+     * Returns the canonicalized path obtained from the
+     * concatenation of the given string path to the
+     * end of this path. The given string path must be a valid
+     * path. If it has a trailing separator,
+     * the result will have a trailing separator.
+     * The device id of this path is preserved (the one
+     * of the given string is ignored). Duplicate slashes
+     * are removed from the path except at the beginning
+     * where the path is considered to be UNC.
+     *
+     * @param path the string path to concatenate
+     * @return the new path
+     * @see #isValidPath(String)
+     */
+    public IPath append(String path);
+
+    /**
+     * Returns the canonicalized path obtained from the
+     * concatenation of the given path's segments to the
+     * end of this path.  If the given path has a trailing
+     * separator, the result will have a trailing separator.
+     * The device id of this path is preserved (the one
+     * of the given path is ignored). Duplicate slashes
+     * are removed from the path except at the beginning
+     * where the path is considered to be UNC.
+     *
+     * @param path the path to concatenate
+     * @return the new path
+     */
+    public IPath append(IPath path);
+
+    /**
+     * Returns a copy of this path.
+     *
+     * @return the cloned path
+     */
+    public Object clone();
+
+    /**
+     * Returns whether this path equals the given object.
+     * <p>
+     * Equality for paths is defined to be: same sequence of segments,
+     * same absolute/relative status, and same device.
+     * Trailing separators are disregarded.
+     * Paths are not generally considered equal to objects other than paths.
+     * </p>
+     *
+     * @param obj the other object
+     * @return <code>true</code> if the paths are equivalent,
+     *    and <code>false</code> if they are not
+     */
+    public int opEquals(Object obj);
+
+    /**
+     * Returns the device id for this path, or <code>null</code> if this
+     * path has no device id. Note that the result will end in ':'.
+     *
+     * @return the device id, or <code>null</code>
+     * @see #setDevice(String)
+     */
+    public String getDevice();
+
+    /**
+     * Returns the file extension portion of this path,
+     * or <code>null</code> if there is none.
+     * <p>
+     * The file extension portion is defined as the string
+     * following the last period (".") character in the last segment.
+     * If there is no period in the last segment, the path has no
+     * file extension portion. If the last segment ends in a period,
+     * the file extension portion is the empty string.
+     * </p>
+     *
+     * @return the file extension or <code>null</code>
+     */
+    public String getFileExtension();
+
+    /**
+     * Returns whether this path has a trailing separator.
+     * <p>
+     * Note: In the root path ("/"), the separator is considered to
+     * be leading rather than trailing.
+     * </p>
+     *
+     * @return <code>true</code> if this path has a trailing
+     *    separator, and <code>false</code> otherwise
+     * @see #addTrailingSeparator()
+     * @see #removeTrailingSeparator()
+     */
+    public bool hasTrailingSeparator();
+
+    /**
+     * Returns whether this path is an absolute path (ignoring
+     * any device id).
+     * <p>
+     * Absolute paths start with a path separator.
+     * A root path, like <code>/</code> or <code>C:/</code>,
+     * is considered absolute.  UNC paths are always absolute.
+     * </p>
+     *
+     * @return <code>true</code> if this path is an absolute path,
+     *    and <code>false</code> otherwise
+     */
+    public bool isAbsolute();
+
+    /**
+     * Returns whether this path has no segments and is not
+     * a root path.
+     *
+     * @return <code>true</code> if this path is empty,
+     *    and <code>false</code> otherwise
+     */
+    public bool isEmpty();
+
+    /**
+     * Returns whether this path is a prefix of the given path.
+     * To be a prefix, this path's segments must
+     * appear in the argument path in the same order,
+     * and their device ids must match.
+     * <p>
+     * An empty path is a prefix of all paths with the same device; a root path is a prefix of
+     * all absolute paths with the same device.
+     * </p>
+     * @param anotherPath the other path
+     * @return <code>true</code> if this path is a prefix of the given path,
+     *    and <code>false</code> otherwise
+     */
+    public bool isPrefixOf(IPath anotherPath);
+
+    /**
+     * Returns whether this path is a root path.
+     * <p>
+     * The root path is the absolute non-UNC path with zero segments;
+     * e.g., <code>/</code> or <code>C:/</code>.
+     * The separator is considered a leading separator, not a trailing one.
+     * </p>
+     *
+     * @return <code>true</code> if this path is a root path,
+     *    and <code>false</code> otherwise
+     */
+    public bool isRoot();
+
+    /**
+     * Returns a bool value indicating whether or not this path
+     * is considered to be in UNC form. Return false if this path
+     * has a device set or if the first 2 characters of the path string
+     * are not <code>Path.SEPARATOR</code>.
+     *
+     * @return bool indicating if this path is UNC
+     */
+    public bool isUNC();
+
+    /**
+     * Returns whether the given string is syntactically correct as
+     * a path.  The device id is the prefix up to and including the device
+     * separator for the local file system; the path proper is everything to
+     * the right of it, or the entire string if there is no device separator.
+     * When the platform location is a file system with no meaningful device
+     * separator, the entire string is treated as the path proper.
+     * The device id is not checked for validity; the path proper is correct
+    * if each of the segments in its canonicalized form is valid.
+     *
+     * @param path the path to check
+     * @return <code>true</code> if the given string is a valid path,
+     *    and <code>false</code> otherwise
+     * @see #isValidSegment(String)
+     */
+    public bool isValidPath(String path);
+
+    /**
+     * Returns whether the given string is valid as a segment in
+     * a path. The rules for valid segments are as follows:
+     * <ul>
+     * <li> the empty string is not valid
+     * <li> any string containing the slash character ('/') is not valid
+     * <li>any string containing segment or device separator characters
+     * on the local file system, such as the backslash ('\') and colon (':')
+     * on some file systems.
+     * </ul>
+     *
+     * @param segment the path segment to check
+     * @return <code>true</code> if the given path segment is valid,
+     *    and <code>false</code> otherwise
+     */
+    public bool isValidSegment(String segment);
+
+    /**
+     * Returns the last segment of this path, or
+     * <code>null</code> if it does not have any segments.
+     *
+     * @return the last segment of this path, or <code>null</code>
+     */
+    public String lastSegment();
+
+    /**
+     * Returns an absolute path with the segments and device id of this path.
+     * Absolute paths start with a path separator. If this path is absolute,
+     * it is simply returned.
+     *
+     * @return the new path
+     */
+    public IPath makeAbsolute();
+
+    /**
+     * Returns a relative path with the segments and device id of this path.
+     * Absolute paths start with a path separator and relative paths do not.
+     * If this path is relative, it is simply returned.
+     *
+     * @return the new path
+     */
+    public IPath makeRelative();
+
+    /**
+     * Return a new path which is the equivalent of this path converted to UNC
+     * form (if the given bool is true) or this path not as a UNC path (if the given
+     * bool is false). If UNC, the returned path will not have a device and the
+     * first 2 characters of the path string will be <code>Path.SEPARATOR</code>. If not UNC, the
+     *  first 2 characters of the returned path string will not be <code>Path.SEPARATOR</code>.
+     *
+     * @param toUNC true if converting to UNC, false otherwise
+     * @return the new path, either in UNC form or not depending on the bool parameter
+     */
+    public IPath makeUNC(bool toUNC);
+
+    /**
+     * Returns a count of the number of segments which match in
+     * this path and the given path (device ids are ignored),
+     * comparing in increasing segment number order.
+     *
+     * @param anotherPath the other path
+     * @return the number of matching segments
+     */
+    public int matchingFirstSegments(IPath anotherPath);
+
+    /**
+     * Returns a new path which is the same as this path but with
+     * the file extension removed.  If this path does not have an
+     * extension, this path is returned.
+     * <p>
+     * The file extension portion is defined as the string
+     * following the last period (".") character in the last segment.
+     * If there is no period in the last segment, the path has no
+     * file extension portion. If the last segment ends in a period,
+     * the file extension portion is the empty string.
+     * </p>
+     *
+     * @return the new path
+     */
+    public IPath removeFileExtension();
+
+    /**
+     * Returns a copy of this path with the given number of segments
+     * removed from the beginning. The device id is preserved.
+     * The number must be greater or equal zero.
+     * If the count is zero, this path is returned.
+     * The resulting path will always be a relative path with respect
+     * to this path.  If the number equals or exceeds the number
+     * of segments in this path, an empty relative path is returned.
+     *
+     * @param count the number of segments to remove
+     * @return the new path
+     */
+    public IPath removeFirstSegments(int count);
+
+    /**
+     * Returns a copy of this path with the given number of segments
+     * removed from the end. The device id is preserved.
+     * The number must be greater or equal zero.
+     * If the count is zero, this path is returned.
+     * <p>
+     * If this path has a trailing separator, it will still
+     * have a trailing separator after the last segments are removed
+     * (assuming there are some segments left).  If there is no
+     * trailing separator, the result will not have a trailing
+     * separator.
+     * If the number equals or exceeds the number
+     * of segments in this path, a path with no segments is returned.
+     * </p>
+     *
+     * @param count the number of segments to remove
+     * @return the new path
+     */
+    public IPath removeLastSegments(int count);
+
+    /**
+     * Returns a path with the same segments as this path
+     * but with a trailing separator removed.
+     * Does nothing if this path does not have at least one segment.
+     * The device id is preserved.
+     * <p>
+     * If this path does not have a trailing separator,
+     * this path is returned.
+     * </p>
+     *
+     * @return the new path
+     * @see #addTrailingSeparator()
+     * @see #hasTrailingSeparator()
+     */
+    public IPath removeTrailingSeparator();
+
+    /**
+     * Returns the specified segment of this path, or
+     * <code>null</code> if the path does not have such a segment.
+     *
+     * @param index the 0-based segment index
+     * @return the specified segment, or <code>null</code>
+     */
+    public String segment(int index);
+
+    /**
+     * Returns the number of segments in this path.
+     * <p>
+     * Note that both root and empty paths have 0 segments.
+     * </p>
+     *
+     * @return the number of segments
+     */
+    public int segmentCount();
+
+    /**
+     * Returns the segments in this path in order.
+     *
+     * @return an array of string segments
+     */
+    public String[] segments();
+
+    /**
+     * Returns a new path which is the same as this path but with
+     * the given device id.  The device id must end with a ":".
+     * A device independent path is obtained by passing <code>null</code>.
+     * <p>
+     * For example, "C:" and "Server/Volume:" are typical device ids.
+     * </p>
+     *
+     * @param device the device id or <code>null</code>
+     * @return a new path
+     * @see #getDevice()
+     */
+    public IPath setDevice(String device);
+
+    /**
+     * Returns a <code>java.io.File</code> corresponding to this path.
+     *
+     * @return the file corresponding to this path
+     */
+    public tango.io.FilePath.FilePath toFile();
+
+    /**
+     * Returns a string representation of this path which uses the
+     * platform-dependent path separator defined by <code>java.io.File</code>.
+     * This method is like <code>toString()</code> except that the
+     * latter always uses the same separator (<code>/</code>) regardless of platform.
+     * <p>
+     * This string is suitable for passing to <code>java.io.File(String)</code>.
+     * </p>
+     *
+     * @return a platform-dependent string representation of this path
+     */
+    public String toOSString();
+
+    /**
+     * Returns a platform-neutral string representation of this path. The
+     * format is not specified, except that the resulting string can be
+     * passed back to the <code>Path#fromPortableString(String)</code>
+     * constructor to produce the exact same path on any platform.
+     * <p>
+     * This string is suitable for passing to <code>Path#fromPortableString(String)</code>.
+     * </p>
+     *
+     * @return a platform-neutral string representation of this path
+     * @see Path#fromPortableString(String)
+     * @since 3.1
+     */
+    public String toPortableString();
+
+    /**
+     * Returns a string representation of this path, including its
+     * device id.  The same separator, "/", is used on all platforms.
+     * <p>
+     * Example result strings (without and with device id):
+     * <pre>
+     * "/foo/bar.txt"
+     * "bar.txt"
+     * "/foo/"
+     * "foo/"
+     * ""
+     * "/"
+     * "C:/foo/bar.txt"
+     * "C:bar.txt"
+     * "C:/foo/"
+     * "C:foo/"
+     * "C:"
+     * "C:/"
+     * </pre>
+     * This string is suitable for passing to <code>Path(String)</code>.
+     * </p>
+     *
+     * @return a string representation of this path
+     * @see Path
+     */
+    public String toString();
+
+    /**
+     * Returns a copy of this path truncated after the
+     * given number of segments. The number must not be negative.
+     * The device id is preserved.
+     * <p>
+     * If this path has a trailing separator, the result will too
+     * (assuming there are some segments left). If there is no
+     * trailing separator, the result will not have a trailing
+     * separator.
+     * Copying up to segment zero simply means making an copy with
+     * no path segments.
+     * </p>
+     *
+     * @param count the segment number at which to truncate the path
+     * @return the new path
+     */
+    public IPath uptoSegment(int count);
+}