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..5266671fccd6dadcb3648099e75bfed0a634e022
--- /dev/null
+++ b/runtime/bin/path.dart
@@ -0,0 +1,39 @@
+// 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.
+ */
+interface Path default _PathImpl {

[Søren Gjesse, 2012/05/29 07:18:01]

Each constructor/method should have a documentation comment.

[Bob Nystrom, 2012/05/30 17:58:37]

Why isn't Path a class?

[Bill Hesse, 2012/05/31 15:55:10]

Only so that the interface is clear to the reader of path.dart.  Is that not a
good reason?

[Bob Nystrom, 2012/05/31 18:06:46]

The interface is clear either way: they'll see a type with some members. Most
users will learn the API through auto-complete in the editor or from
api.dartlang.org before they ever venture into the code.

Classes are, I believe a much simpler mental model than interfaces: they are a
concrete thing you can construct. For someone coming from a dynamic language,
interfaces are distinctly challenging since they don't exist outside of
statically-typed languages and don't actually do anything useful outside of the
type system.

We get frequent feedback that default classes are really hard for users to
understand. I think there may be some cases where it makes sense to use them,
but if you have a conceptual "thing" that has a single implementation of some
operations and can be constructed, there's already a perfectly natural mechanism
for that: a class.

Given that we have implicit interfaces, I think we should need a strong
compelling reason before we reach for an interface. Otherwise, it's just adding
needless complexity.

+  Path(String source);

[Anders Johnsen, 2012/05/25 13:37:30]

I think we should have
- const Path(source)
- Path.join(List parts);

[Mads Ager (google), 2012/05/29 07:36:02]

I agree that it should be a const constructor. The join constructor could be
nice if it doesn't conflict with the join method (need to check the spec).

[Bill Hesse, 2012/05/31 15:55:10]

Path() is now a const constructor
Path.fromNative() is a non-const constructor that only
does changes on Windows (/ to \ and initial / before c:).

Path.join(List) can be done later, if possible.

+  const Path.c(String source);

[Søren Gjesse, 2012/05/29 07:18:01]

What does the Path.c constructor do?

+
+  bool get isEmpty();
+  bool get isAbsolute();
+  bool get isDirectory();

[Anders Johnsen, 2012/05/25 13:37:30]

Since it have no knowledge of the underlying system, we can not answer this
question. I think we should remove it, and have something more explicit being a
test for tailing '/'.

[Bill Hesse, 2012/05/31 15:55:10]

Now called get hasTrailingSlash().

+  bool get isCanonical();
+
+  Path canonicalize();
+  Path join(further);  // further is Path or String.

[Anders Johnsen, 2012/05/25 13:37:30]

Comment in /** ... **/ so we can mark it with as [further].

[Mads Ager (google), 2012/05/29 07:36:02]

Yes, and please add doc comments to all of these since this is a public
interface. Anders' comment about 'isDirectory' would be less of an issue if
there is a clear explanation of the functionality.

[Bill Hesse, 2012/05/31 15:55:10]

Done.

+  Path relativeTo(Path base);

[Anders Johnsen, 2012/05/25 13:37:30]

I'm in favor of relativePathTo, or pathRelativeTo, since relativeTo could sound
like a boolean question.

[Mads Ager (google), 2012/05/29 07:36:02]

On the other hand, all of the getters in the interface are called 'isSomething'
so I'm not sure there will be much confusion. This method needs a good doc
comment with a couple of examples (including one that will throw an exception).

[Bob Nystrom, 2012/05/30 17:58:37]

+1 to Mads.

[Bill Hesse, 2012/05/31 15:55:10]

Done.

+
+  /**
+   * Converts a path to a string using the native filesystem's conventions.
+   */
+  String toNativePath();
+
+  // '$foo' == '${foo.dirname()}/${foo.filename()}' if dirname is nonempty.

[Mads Ager (google), 2012/05/29 07:36:02]

I don't understand these comments.

[Bill Hesse, 2012/05/31 15:55:10]

Done.

+  // '${foo.filename}' == '${foo.basename()}.${foo.extension()}' if
+  //     foo.extension() is nonempty.

[Søren Gjesse, 2012/05/29 07:18:01]

I am in favor of these being getters. Regarding the naming I think they should
be short.

How about having first(int n) and last(int n) methods methods as well. With
negative indexes these could take from the other end, e.g last(-1) will return a
path with all but the last element.

[Bob Nystrom, 2012/05/30 17:58:37]

+1. These should be getters.

[Bill Hesse, 2012/05/31 15:55:10]

Done.

[Bill Hesse, 2012/05/31 15:55:10]

Done.

+  Path dirname();  // or get directoryPath

[Anders Johnsen, 2012/05/25 13:37:30]

IMO, dirname != directoryPath. 
E.g.: /my/path/to/a/dir
dirname == dir (same as filename iff no tailing '/')
directoryPath == /my/path/to/a/

[Søren Gjesse, 2012/05/29 07:18:01]

I agree with Anders that we should use "directory" with care. The path itself
cannot know whether it is dealing with a directory or a file.

[Bill Hesse, 2012/05/31 15:55:10]

Done.

+  String filename();  // or get filename
+  String basename();  // or get filenameWithoutExtension
+  String extension();  // or get extension

[Søren Gjesse, 2012/05/29 07:18:01]

How about mentioning toString and document what it does.

Should there be other toString variants e.g toPlatformString and toShortString?

[Bill Hesse, 2012/05/31 15:55:10]

toNativePath is what I called toPlatformString, but I think toPlatformString is
better.  What would toShortString do?

I put toString in the interface and documented it, but I think that is illegal
Dart.

On 2012/05/29 07:18:01, Søren Gjesse wrote:

+}
+
+class PathException implements Exception {

[Bob Nystrom, 2012/05/30 17:58:37]

I don't think you should have this. We should only define new exception classes
when they represent something that a user may want to catch differently. We
shouldn't define an exception class that just tells you want class it was thrown
from. The caller already knows that: they know what they're calling.

[Bill Hesse, 2012/05/31 15:55:10]

Done.

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