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

runtime/bin/path.dart

+// 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, interpreted as a sequence of strings separated by forward slashes.
+ * Paths are immutable wrappers of a String, that offer member functions for
+ * useful path manipulations and queries.
+ */
+interface Path default _PathImpl {
+  const Path(String source);

[Mads Ager (google), 2012/06/01 08:11:31]

Please document the constructor. Maybe with a comment about what happens when
you create a Path with an invalid path string and operate on it?

[Bill Hesse, 2012/06/15 14:23:08]

Done.

+
+  /**
+   * 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();
+
+  /**
+   * Does this path begin with '/'?

[Mads Ager (google), 2012/06/01 08:11:31]

It seems strange that the getter name is 'isAbsolute' but the word absolute is
not used in the comment at all. Seems like either the comment should use the
word 'absolute' or the name should change to beginsWithSeparator (which would
also make it consistent with endsWithSeparator below).

[Bill Hesse, 2012/06/15 14:23:08]

Done.

+   */
+  bool get isAbsolute();
+
+  /**
+   * Does this path end with '/'?
+   */
+  bool get hasTrailingSlash();

[Mads Ager (google), 2012/06/01 08:11:31]

I think I would prefer 'path separator' instead of 'slash'.

[Bill Hesse, 2012/06/15 14:23:08]

Done.

+
+  /**
+   * Does this path contain no segments . or .., except leading .. segments,

[Mads Ager (google), 2012/06/01 08:11:31]

If you use the term segments here, maybe the initial comment about the path
class should use the term segment as well: 'A Path, interpreted as a sequence of
path segments (components?) separated by forward slashes.'?

Maybe put quotes around '.', '..'?

[Bill Hesse, 2012/06/15 14:23:08]

Done.

+   * and contain no consecutive path separators?
+   */
+  bool get isCanonical();
+
+  /**
+   * Make a path canonical by dropping . segments, canceling .. segments with

[Mads Ager (google), 2012/06/01 08:11:31]

Ditto.

[Bill Hesse, 2012/06/15 14:23:08]

Done.

+   * preceding segments, if possible, and combining consecutive path separators.
+   */
+  Path canonicalize();
+
+  /**
+   * Joins the relative path [further] to this path, which may be absolute
+   * or relative.  Canonicalizes the path, to remove ., .., and //.

[Mads Ager (google), 2012/06/01 08:11:31]

Examples or a more thorough explanation would be good. Does this take the
components/segments of [further] and append them to the components/segments of
'this'. In that case it never fails? What is it that may be absolute or
relative? Both [this] and [further]? 

[Bill Hesse, 2012/06/15 14:23:08]

Done.

+   */
+  Path join(Path further);
+
+  /**
+   * Joins the relative path [further] to this path, which may be absolute
+   * or relative.  Canonicalizes the path, to remove ., .., and //.
+   * [further] may not contain '..' segments which would traverse into
+   * this path, so [further.canonicalize()] is checked that it does not
+   * begin with '..'

[Mads Ager (google), 2012/06/01 08:11:31]

I think examples would be good here. What happens if you do something unsafe?
Throws an exception? Could be good to document that as well.

[Bill Hesse, 2012/06/15 14:23:08]

Done.

+   */
+  Path safeJoin(Path further);
+
+  /**
+   * Converts a path to a string using the native filesystem's conventions.
+   */
+  String toNativePath();
+
+  /**
+   * 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 (the strings separated by /)

[Mads Ager (google), 2012/06/01 08:11:31]

Instead of the parenthesis you could have an example instead.

[Bill Hesse, 2012/06/15 14:23:08]

Done.

+   */
+  List<String> segments();
+
+  /**
+   * Drops the final '/' and whatever follows it from this Path, and returns

[Mads Ager (google), 2012/06/01 08:11:31]

should we write out 'path separator' instead of '/' in these comments?

[Bill Hesse, 2012/06/15 14:23:08]

Done.

+   * the resulting Path object.  If the only '/' in this Path is the first
+   * character, returns '/' instead of ''.  If there is no '/' in the Path,

[Mads Ager (google), 2012/06/01 08:11:31]

Text is good. Examples is better. :)

Also in the text I would write out 'empty string' instead of ''

[Bill Hesse, 2012/06/15 14:23:08]

Done.

+   * returns ''.
+   */
+  Path get directoryPath();
+
+  /**
+   * The part of the path after the last '/', or the entire path if it contains
+   * no '/'.
+   */
+  String get filename();
+
+  /**
+   * The part of [filename] before the last '.', or the entire filename if it
+   * contains no '.'.
+   */
+  String get filenameWithoutExtension();
+
+  /**
+   * The part of [filename] after the last '.', or '' if [filename]
+   * contains no '.'.
+   */
+  String get extension();
+}
+
+class PathException implements Exception {

[Bill Hesse, 2012/06/15 14:23:08]

Removed.

+  const PathException([String this.message]);
+  String toString() => "PathException: $message";
+  final String message;
+}