Add isWithin to pkg/path.

pkg/path/lib/path.dart

Index: pkg/path/lib/path.dart
diff --git a/pkg/path/lib/path.dart b/pkg/path/lib/path.dart
index 3c5f51eb3ea967285dfa8aee4586088c21e8a588..f1d7228c28256dc9efce6a8f290e1f9efed1c9dd 100644
--- a/pkg/path/lib/path.dart
+++ b/pkg/path/lib/path.dart
@@ -301,6 +301,12 @@ String normalize(String path) => _builder.normalize(path);
 String relative(String path, {String from}) =>
     _builder.relative(path, from: from);
 
+/// Returns `true` if [child] is a path beneath `parent`, and `false` otherwise.
+///
+///     path.isWithin('/root/path', '/root/path/a'); // -> true
+///     path.isWithin('/root/path', '/root/other'); // -> false

[Bob Nystrom, 2013/11/14 22:58:59]

Add an example for

path.isWith('/root/path', '/root/path');

[nweiz, 2013/11/14 23:51:55]

Done.

+bool isWithin(String parent, String child) => _builder.isWithin(parent, child);
+
 /// Removes a trailing extension from the last part of [path].
 ///
 ///     withoutExtension('path/to/foo.dart'); // -> 'path/to/foo'
@@ -560,10 +566,13 @@ class Builder {
       if (this.isRootRelative(part) && isAbsoluteAndNotRootRelative) {
         // If the new part is root-relative, it preserves the previous root but
         // replaces the path after it.
-        var oldRoot = this.rootPrefix(buffer.toString());
+        var parsed = _parse(part);
+        parsed.root = this.rootPrefix(buffer.toString());
+        if (parsed.root.contains(style.needsSeparatorPattern)) {
+          parsed.separators[0] = style.separator;
+        }
         buffer.clear();
-        buffer.write(oldRoot);
-        buffer.write(part);
+        buffer.write(parsed);
       } else if (this.isAbsolute(part)) {
         isAbsoluteAndNotRootRelative = !this.isRootRelative(part);
         // An absolute path discards everything before it.
@@ -736,6 +745,26 @@ class Builder {
     return pathParsed.toString();
   }
 
+  /// Returns `true` if [child] is a path beneath `parent`, and `false`
+  /// otherwise.
+  ///
+  ///     path.isWithin('/root/path', '/root/path/a'); // -> true
+  ///     path.isWithin('/root/path', '/root/other'); // -> false
+  bool isWithin(String parent, String child) {
+    var relative;
+    try {
+      relative = this.relative(child, from: parent);
+    } on ArgumentError catch (_) {

[Bob Nystrom, 2013/11/14 22:58:59]

relative() can throw an ArgumentError?

We really shouldn't be catching that. It should either throw an exception, or
there should be a way to proactively detect if it would fail.

[nweiz, 2013/11/14 23:51:55]

Yes. If [root] is relative, you can get unresolvable cases. For example, if
[root] and [path] are both "." and [from] is "/" or "..", there's no correct
return value.
I'm not sure I agree. I don't think there's a clean way to express "detect
whether relative will fail" other than [canFindRelativePath], and no clean way
to implement it other than calling [relative] and catching the error.

I'm pretty sure this shouldn't throw an exception. `isWithin(".", "/foo")`
should return false even if [root] is ".". A relative root indicates that there
is no meaningful absolute root, which means that relative paths aren't beneath
any absolute paths.

[Bob Nystrom, 2013/11/15 00:05:51]

Right. In that case, relative() should throw a subclass of Exception, not
ArgumentError. The latter indicates a programmatic error, and should never be
caught (outside of logging, etc.). Maybe FormatException?
SGTM. I definitely prefer stuff here to not throw exceptions, so I'm fine with
this catching and eating it. I just don't think it should catch something of
type ArgumentError.

[nweiz, 2013/11/15 01:17:50]

I don't like FormatException, because nothing's being parsed or interpreted. I'm
going to add a PathException class for this.

[Bob Nystrom, 2013/11/15 01:44:52]

I was thinking the same thing. We should document that relative() can throw that
too.

+      // If no relative path from [parent] to [child] is found, [child]
+      // definitely isn't a child of [parent].
+      return false;
+    }
+
+    var parts = this.split(relative);
+    return this.isRelative(relative) && parts.first != '..' &&
+        parts.first != '.';
+  }
+
   /// Removes a trailing extension from the last part of [path].
   ///
   ///     builder.withoutExtension('path/to/foo.dart'); // -> 'path/to/foo'
@@ -983,6 +1012,10 @@ class _WindowsStyle extends Style {
   final needsSeparatorPattern = new RegExp(r'[^/\\]$');
   final rootPattern = new RegExp(r'^(\\\\[^\\]+\\[^\\/]+|[a-zA-Z]:[/\\])');
 
+  // Matches a back or forward slash that's not followed by another back or
+  // forward slash.
+  final relativeRootPattern = new RegExp(r"^[/\\](?![/\\])");
+
   String pathFromUri(Uri uri) {
     if (uri.scheme != '' && uri.scheme != 'file') {
       throw new ArgumentError("Uri $uri must have scheme 'file:'.");