Add Path class to dart:io, and add unit tests for it.

runtime/bin/path.dart

Index: runtime/bin/path.dart
diff --git a/runtime/bin/path.dart b/runtime/bin/path.dart
new file mode 100644
index 0000000000000000000000000000000000000000..02945728068a3aff9dd8e36326593f1daddd627e
--- /dev/null
+++ b/runtime/bin/path.dart
@@ -0,0 +1,160 @@
+// Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+/**
+ * A Path, which is a String interpreted as a sequence of path segments,
+ * which are strings, separated by forward slashes.
+ * Paths are immutable wrappers of a String, that offer member functions for
+ * useful path manipulations and queries.  Joining of paths and normalization
+ * interpret '.' and '..' in the usual way.
+ */
+interface Path default _PathImpl {

[Søren Gjesse, 2012/06/18 07:29:35]

Following the convention for the rest of dart:io default class should be just
_Path (without Impl)

[Bill Hesse, 2012/06/18 15:46:38]

Done.

+  /**
+   * Creates a Path from the String [source].  [source] is used as-is, so if
+   * the string does not consist of segments separated by forward slashes, the
+   * behavior may not be as expected.  Paths are immutable, and constant
+   * Path objects may be constructed from constant Strings.
+   */
+  const Path(String source);
+
+  /**
+   * Creates a Path from a String that uses the native filesystem's conventions.
+   * On Windows, this converts '\' to '/', and adds a '/' before a drive letter.
+   */
+  Path.fromNative(String source);
+
+  /**
+   * Is this path the empty string?
+   */
+  bool get isEmpty();
+
+  /**
+   * Is this path an absolute path, beginning with a path separator?

[Søren Gjesse, 2012/06/18 07:29:35]

Should there be some additional information on Windows and drive letters? How is
a drive letter without a '/' before interpreted?

[Bill Hesse, 2012/06/18 15:46:38]

Done.

+   */
+  bool get isAbsolute();
+
+  /**
+   * Does this path end with a path separator?
+   */
+  bool get hasTrailingSeparator();
+
+  /**
+   * Does this path contain no consecutive path separators, no segments that
+   * are '.' unless the path is exactly '.', and segments that are '..' only
+   * as the leading segments on a relative path?
+   */
+  bool get isCanonical();
+
+  /**
+   * Make a path canonical by dropping segments that are '.', cancelling
+   * segments that are '..' with preceding segments, if possible,
+   * and combining consecutive path separators.

[Søren Gjesse, 2012/06/18 07:29:35]

What happens if there are more '..'s that "real" segments? Exception?

[Bill Hesse, 2012/06/18 15:46:38]

Leading '..' segments are kept on relative paths, and dropped on absolute paths.

+   */
+  Path canonicalize();

[Anders Johnsen, 2012/06/18 06:27:08]

I'm not sure what I like the most, so what does other people feel about
canonicalize vs. canonicalForm()?

+
+  /**
+   * Joins the relative path [further] to this path.  Canonicalizes the path,
+   * interpreting '.' and '..' as directory traversal commands, and removing

[Søren Gjesse, 2012/06/18 07:29:35]

The explanation of '.'  and '..' here is slightly different that for
canonicalize. Maybe just say that the raw joined path is canonicalizeed to avoid
duplicating the description.

[Bill Hesse, 2012/06/18 15:46:38]

Done.

+   * consecutive path separators.
+   *
+   * If [further] is an absolute path, an IllegalArgument exception is thrown.
+   *
+   * Examples:
+   *   `new Path('/a/b/c').join(new Path('d/e'))` returns the Path object
+   *   containing `'a/b/c/d/e'`.
+   *
+   *   `new Path('a/b/../c/').join(new Path('d/./e//')` returns the Path
+   *   containing `'a/c/d/e/'`.
+   *
+   *   `new Path('a/b/c').join(new Path('d/../../e')` returns the Path
+   *   containing `'a/b/e'`.
+   *
+   * Note that the join operation does not drop the last segment of the
+   * base path, the way URL joining does.  That would be accomplished with
+   * basepath.directoryPath.join(further).
+   *
+   * If you want to avoid joins that traverse
+   * parent directories in the base, you can check whether
+   * `further.canonicalize()` starts with '../' or equals '..'.

[Søren Gjesse, 2012/06/18 07:29:35]

Is that sufficient? What about a [further] of 'x/../..'?

[Bill Hesse, 2012/06/18 15:46:38]

'x/../..'.canonicalize() is '..'.

+   */
+  Path join(Path further);
+
+
+  /**
+   * Returns a path [:relative:] such that
+   *    [:base.join(relative) == this.canonicalize():].
+   * Throws an exception if no such path exists, or if this
+   * case is not implemented yet.

[Anders Johnsen, 2012/06/18 06:27:08]

A few comments here.
1) Do you really mean "if no such path exists"? I thought this lib was purely
acting as a String manipulator?
2) What do you mean by a case is not implemented? If something is not
implementable, we should write it here. And AFAIK, there is a few cases that'll
not work out?

[Bill Hesse, 2012/06/18 15:46:38]

Done.

+   */
+  Path relativeTo(Path base);
+
+  /**
+   * Converts a path to a string using the native filesystem's conventions.
+   *
+   * On Windows, converts path separators to backwards slashes, and removes
+   * the leading path separator if the path starts with a drive specification.

[Søren Gjesse, 2012/06/18 07:29:35]

Should the invariant here be that is the fromNative constructor was used that
toNativePath should return the exact same string?

[Bill Hesse, 2012/06/18 15:46:38]

There are some corner cases, with mixed backward and forward slashes.  But in
general, yes.

+   */
+  String toNativePath();

[Søren Gjesse, 2012/06/18 07:29:35]

The name toNativePath indicate that a Path not a String is returned.

[Bill Hesse, 2012/06/18 15:46:38]

Could we say toNativeFilepath?  toNativepath?  toNativeFilesystemPath?

+
+  /**
+   * Returns the path as a string.  If this path is constructed using
+   * new Path() or new Path.fromNative() on a non-Windows system, the
+   * returned value is the original string argument to the constructor.
+   */
+  String toString();
+
+  /**
+   * Gets the segments of a Path.  Paths beginning or ending with the
+   * path separator do not have leading or terminating empty segments.
+   * Other than that, the segments are just the result of splitting the
+   * path on the path separator.
+   *
+   *     new Path('/a/b/c/d').segments() == ['a', 'b', 'c', d'];
+   *     new Path(' foo bar //../') == [' foo bar ', '', '..'];
+   */
+  List<String> segments();
+
+  /**
+   * Drops the final path separator and whatever follows it from this Path,
+   * and returns the resulting Path object.  If the only path separator in
+   * this Path is the first character, returns '/' instead of the empty string.
+   * If there is no path separator in the Path, returns the empty string.
+   *
+   *     new Path('../images/dot.gif').directoryPath == '../images'
+   *     new Path('/usr/geoffrey/www/').directoryPath == '/usr/geoffrey/www'
+   *     new Path('lost_file_old').directoryPath == ''
+   *     new Path('/src').directoryPath == '/'
+   *     Note: new Path('/D:/src').directoryPath == '/D:'
+   */
+  Path get directoryPath();

[Anders Johnsen, 2012/06/18 06:27:08]

I really like this one! Thanks!

+
+  /**
+   * The part of the path after the last path separator, or the entire path if
+   * it contains no path separator.
+   *
+   *     new Path('images/DSC_0027.jpg).filename == 'DSC_0027.jpg'
+   *     new Path('users/fred/').filename == ''
+   */
+  String get filename();

[Søren Gjesse, 2012/06/18 07:29:35]

fileName (uppercase N)?

[Bill Hesse, 2012/06/18 15:46:38]

I think filename is a common noun, and not the same as file name.

On 2012/06/18 07:29:35, Søren Gjesse wrote:

+
+  /**
+   * The part of [filename] before the last '.', or the entire filename if it
+   * contains no '.'.
+   *
+   *     new Path('/c:/My Documents/Heidi.txt').filenameWithoutExtension
+   *     would return 'Heidi'.
+   *     new Path('not what I would call a path').filenameWithoutExtension
+   *     would return 'not what I would call a path'.
+   */
+  String get filenameWithoutExtension();

[Anders Johnsen, 2012/06/18 06:27:08]

I see you went for this, and not basename. Given that basename conflicts with C,
I think this might be the right thing to do.

[Søren Gjesse, 2012/06/18 07:29:35]

fileNameWithoutExtension (uppercase N)?

+
+  /**
+   * The part of [filename] after the last '.', or '' if [filename]
+   * contains no '.'.
+   *
+   *     new Path('tiger.svg').extension == 'svg'
+   *     new Path('/src/dart/dart_secrets').extension == ''
+   */
+  String get extension();

[Anders Johnsen, 2012/06/18 06:27:08]

With the classic case of .tar.gz, should we have a "fullExtension", or leave it
to the use to extract that?

[Bill Hesse, 2012/06/18 15:46:38]

We could add that.  or get extensions?
multipleExtensions?

+}