Attachment 81292 Details for Bug 207078 – updated patch

[patch] updated patch

IUniversalPath.patch.txt (text/plain), 21.42 KB, created by Chris Recoskie

on 2007-10-26 15:27:12 EDT

(hide)

Description:

Filename:

MIME Type:

Creator: Chris Recoskie

Created: 2007-10-26 15:27:12 EDT

Size: 21.42 KB

patch

obsolete

>### Eclipse Workspace Patch 1.0
>#P org.eclipse.cdt.core
>Index: remote/org/eclipse/cdt/core/remote/IUniversalPath.java
>===================================================================
>RCS file: remote/org/eclipse/cdt/core/remote/IUniversalPath.java
>diff -N remote/org/eclipse/cdt/core/remote/IUniversalPath.java
>--- /dev/null	1 Jan 1970 00:00:00 -0000
>+++ remote/org/eclipse/cdt/core/remote/IUniversalPath.java	1 Jan 1970 00:00:00 -0000
>@@ -0,0 +1,611 @@
>+package org.eclipse.cdt.core.remote;
>+
>+import java.net.URI;
>+
>+import org.eclipse.core.resources.IResource;
>+import org.eclipse.core.runtime.IPath;
>+import org.eclipse.core.runtime.Path;
>+
>+/**
>+ * 
>+ * 
>+ * A universal representation of local and remote paths, which provides path manipulation facilities.
>+ * 
>+ * 
>+ * EXPERIMENTAL. This class or interface has been added as
>+ * part of a work in progress. There is no guarantee that this API will work or
>+ * that it will remain the same. Please do not use this API without consulting
>+ * with the author.
>+ * 
>+ * 
>+ * This interface essentially bridges local paths and URIs that represent paths.
>+ * 
>+ * 
>+ * A path is an ordered collection of string segments, separated by a separator character
>+ * (either a forward slash or a backslash depending upon the path format).
>+ * 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.
>+ * 
>+ * 
>+ * Note that paths are value objects; all operations on paths 
>+ * return a new path; the path that is operated on is unscathed.
>+ * 
>+ * 
>+ * 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.
>+ * 
>+ * @author crecoskie
>+ * @see java.net.URI
>+ *
>+ */
>+public interface IUniversalPath extends Cloneable {
>+	
>+	/**
>+	 * Encapsulates possible formats for paths. Paths can be either UNIX or Windows format.
>+	 *
>+	 */
>+	public enum Format {
>+		/**
>+		 * Constant indicating that this path is in UNIX format. I.e., it has no device id, and
>+		 * the path separator is the forward slash character.
>+		 */
>+		UNIX,
>+		
>+		/**
>+		 * Constant indicating that this path is in Windows format. I.e., it can have a device id, and
>+		 * the path separator is the backslash character.
>+		 */
>+		WINDOWS
>+	}
>+	
>+	/**
>+	 * 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.
>+	 * 
>+	 * 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 ".".
>+	 * 
>+	 *
>+	 * @param extension the file extension to append
>+	 * @return the new path
>+	 */
>+	public IUniversalPath 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.
>+	 * 
>+	 * If this path already has a trailing separator,
>+	 * this path is returned.
>+	 * 
>+	 *
>+	 * @return the new path
>+	 * @see #hasTrailingSeparator()
>+	 * @see #removeTrailingSeparator()
>+	 */
>+	public IUniversalPath addTrailingSeparator();
>+	
>+	/**
>+	 * 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 IUniversalPath append(IUniversalPath tail);
>+	
>+	/**
>+	 * 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 IUniversalPath append(String path);
>+	
>+	/**
>+	 * Returns a copy of this path.
>+	 *
>+	 * @return the cloned path
>+	 */
>+	public Object clone();
>+	
>+	/**
>+	 * 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.
>+	 * 
>+	 * 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.
>+	 * 
>+	 *
>+	 * @return the file extension or <code>null</code>
>+	 */
>+	public String getFileExtension();
>+	
>+	/**
>+	 * Returns the format for native paths on the local machine.
>+	 * 
>+	 * @return Format.FORMAT_WINDOWS if native paths are in Windows format, Format.FORMAT_UNIX otherwise 
>+	 */
>+	public Format getLocalPathFormat();
>+	
>+	
>+	/**
>+	 * Returns the format of this path as it would be represented on the targeted machine.
>+	 * The targeted machine might be local or remote.
>+	 * 
>+	 * @return Format.FORMAT_WINDOWS if this path represents a Windows path, Format.FORMAT_UNIX otherwise.
>+	 */
>+	public Format getTargetPathFormat();
>+	
>+		
>+	/**
>+	 * Gets only the filesystem specific part of the path, in the context of the target.
>+	 * The target's path format is used to format the string.
>+	 * 
>+	 * 
>+	 * Example:
>+	 * 
>+	 * 
>+	 * Original path: <code>rse://remoteMachine/home/youraccount/foo/bar.cpp</code>
>+	 * 
>+	 * 
>+	 * Format: <code>Format.FORMAT_UNIX</code>
>+	 * 
>+	 * Result: <code>/home/youraccount/foo/bar.cpp</code>
>+	 * 
>+	 * 
>+	 * Example:
>+	 * 
>+	 * 
>+	 * Original path: <code>file://C%30/foo/bar.cpp</code>
>+	 * 
>+	 * 
>+	 * Format: <code>Format.FORMAT_WINDOWS</code>
>+	 * 
>+	 * Result: <code>C:\foo\bar.cpp</code>
>+	 * 
>+	 * 
>+	 * @return a <code>String</code> corresponding to the target path
>+	 */
>+	public String getTargetPathString();
>+	
>+	/**
>+	 * Gets the path relative to the workspace.
>+	 * 
>+	 * @return an IResource corresponding to the path's location in the workspace, or
>+	 * <code>null</code> if this path is not represented in the workspace.
>+	 * 
>+	 */
>+	public IResource getWorkspaceResource();
>+	
>+	/**
>+	 * Returns whether this path has a trailing separator.
>+	 * 
>+	 * Note: In the root path ("/"), the separator is considered to
>+	 * be leading rather than trailing.
>+	 * 
>+	 *
>+	 * @return <code>true</code> if this path has a trailing
>+	 * separator, and <code>false</code> otherwise
>+	 * @see #addTrailingSeparator()
>+	 * @see #removeTrailingSeparator()
>+	 */
>+	public boolean hasTrailingSeparator();
>+	
>+	
>+	/**
>+	 * Returns whether this path is an absolute path (ignoring
>+	 * any device id).
>+	 * 
>+	 * 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.
>+	 * 
>+	 *
>+	 * @return <code>true</code> if this path is an absolute path,
>+	 * and <code>false</code> otherwise
>+	 */
>+	public boolean 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 boolean isEmpty();
>+	
>+	/**
>+	 * @return true if the path corresponds to the local machine's native filesystem, false otherwise.
>+	 */
>+	public boolean isLocal();
>+	
>+	/**
>+	 * 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.
>+	 * 
>+	 * 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.
>+	 * 
>+	 * @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 boolean isPrefixOf(IUniversalPath anotherPath);
>+	
>+	/**
>+	 * Returns whether this path is a root path.
>+	 * 
>+	 * 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.
>+	 * 
>+	 *
>+	 * @return <code>true</code> if this path is a root path,
>+	 * and <code>false</code> otherwise
>+	 */
>+	public boolean isRoot();
>+	
>+	/**
>+	 * Returns a boolean 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 boolean indicating if this path is UNC
>+	 */
>+	public boolean isUNC();
>+	
>+	/**
>+	 * Returns whether the given string is syntactically correct as
>+	 * a universal 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 boolean 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 boolean 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 IUniversalPath 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 IUniversalPath makeRelative();
>+
>+	/**
>+	 * Return a new path which is the equivalent of this path converted to UNC
>+	 * form (if the given boolean is true) or this path not as a UNC path (if the given
>+	 * boolean 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 boolean parameter
>+	 */
>+	public IUniversalPath makeUNC(boolean 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(IUniversalPath 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.
>+	 * 
>+	 * 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.
>+	 * 
>+	 *
>+	 * @return the new path
>+	 */
>+	public IUniversalPath 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 IUniversalPath 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.
>+	 * 
>+	 * 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.
>+	 * 
>+	 *
>+	 * @param count the number of segments to remove
>+	 * @return the new path
>+	 */
>+	public IUniversalPath 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.
>+	 * 
>+	 * If this path does not have a trailing separator,
>+	 * this path is returned.
>+	 * 
>+	 *
>+	 * @return the new path
>+	 * @see #addTrailingSeparator()
>+	 * @see #hasTrailingSeparator()
>+	 */
>+	public IUniversalPath 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.
>+	 * 
>+	 * Note that both root and empty paths have 0 segments.
>+	 * 
>+	 *
>+	 * @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>.
>+	 * 
>+	 * For example, "C:" and "Server/Volume:" are typical device ids.
>+	 * 
>+	 *
>+	 * @param device the device id or <code>null</code>
>+	 * @return a new path
>+	 * @see #getDevice()
>+	 */
>+	public IUniversalPath setDevice(String device);
>+
>+	/**
>+	 * Sets the format of this path as it would be represented on the targeted machine.
>+	 * The targeted machine might be local or remote.
>+	 * 
>+	 * @param format - Format of the path
>+	 * @return a new universal path with the specified format.
>+	 */
>+	public IUniversalPath setTargetPathFormat(Format format);
>+
>+	/**
>+	 * Sets up a mapping between this path and a path in the workspace. This does not in any way
>+	 * setup a link in the workspace itself or otherwise indicate to any of the workspace's resource
>+	 * management facilities that such a mapping exists.
>+	 * 
>+	 * @param resource - the resource in the workspace to map to.
>+	 * @return a new path with the appropriate mapping set.
>+	 */
>+	public IUniversalPath setWorkspaceResource(IResource resource);
>+	
>+	/**
>+	 * Returns a string representation of this path which uses the
>+	 * platform-dependent path separator defined by <code>java.io.File</code> corresponding
>+	 * to the local execution environment.
>+	 * @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.
>+	 * 
>+	 * This string is suitable for passing to <code>Path#fromPortableString(String)</code>.
>+	 * 
>+	 *
>+	 * @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, suitable for display in the UI.
>+	 * 
>+	 * In the case of local paths, this will be a path in the local filesystem, including any device id.
>+	 * The scheme portion of the URI is not displayed for local files (i.e. c:/foo not file://c:/foo
>+	 * 
>+	 * For non-local files, the full URI of the file will be displayed.
>+	 * 
>+	 * @return a string representation of this path
>+	 */
>+	public String toString();
>+
>+	/**
>+	 * Returns a string representing the path in the given format
>+	 * 
>+	 * @param format - either Format.FORMAT_UNIX or Format.FORMAT_WINDOWS
>+	 * @return
>+	 */
>+	public String toStringInFormat(Format format);
>+
>+	/**
>+	 * Converts this path to a relative path in the context of the target.
>+	 * 
>+	 * Example:
>+	 * 
>+	 * Original path: <code>rse://remoteMachine/home/youraccount/foo/bar.cpp</code>
>+	 * 
>+	 * pathRelativeTo: <code>/home/yourAccount</code>
>+	 * 
>+	 * Result: <code>foo/bar.cpp</code>
>+	 * 
>+	 * @param uriRelativeTo - The URI which the path should be relative to
>+	 * @return A universal path relative to the given location
>+	 */
>+	public IUniversalPath toTargetRelativePath(IUniversalPath pathRelativeTo);
>+	
>+	/**
>+	 * Converts this path to a URI. The URI may be absolute or relative depending upon whether or not the path
>+	 * is absolute or relative.
>+	 * 
>+	 * 
>+	 * In the case of local paths, path separators are converted to URI format (forward slashes),
>+	 * but any other characters which are not legally allowed in the path portion of the URI are escaped.
>+	 * E.g., in the case of paths targeting Windows systems, the URI may potentially contain an escaped colon
>+	 * corresponding to the device id. E.g., <code>C:\foo\bar</code> becomes <code>file://C%30/foo/bar</code>.
>+	 * 
>+	 * 
>+	 * 
>+	 * This will return a URI mapping to the local filesystem (file://...) if the path is local and absolute
>+	 * (i.e. both <code>isLocal()</code> and <code>isAbsolute()</code> return true).
>+	 * 
>+	 * 
>+	 * @return a URI representing the path, or <code>null</code> if the path is empty. 
>+	 * 
>+	 */
>+	public URI toURI();
>+	
>+	/**
>+	 * Returns a copy of this path truncated after the
>+	 * given number of segments. The number must not be negative.
>+	 * The device id is preserved.
>+	 * 
>+	 * 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.
>+	 * 
>+	 *
>+	 * @param count the segment number at which to truncate the path
>+	 * @return the new path
>+	 */
>+	public IUniversalPath uptoSegment(int count);
>+	
>+}

Actions: View | Diff

Attachments on bug 207078: 80897 | 81292 | 85201