Add isWithin to pkg/path.

pkg/path/lib/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 comprehensive, cross-platform path manipulation library.
 ///
 /// ## Installing ##
 ///
 /// Use [pub][] to install this package. Add the following to your
 /// `pubspec.yaml` file.
@@ skipping 283 matching lines @@
 ///
 ///     // Windows
 ///     path.relative(r'D:\other', from: r'C:\home'); // -> 'D:\other'
 ///
 ///     // URL
 ///     path.relative('http://dartlang.org', from: 'http://pub.dartlang.org');
 ///       // -> 'http://dartlang.org'
 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'
 String withoutExtension(String path) => _builder.withoutExtension(path);
 
 /// Returns the path represented by [uri].
 ///
 /// For POSIX and Windows styles, [uri] must be a `file:` URI. For the URL
 /// style, this will just convert [uri] to a string.
 ///
@@ skipping 239 matching lines @@
   /// For a fixed number of parts, [join] is usually terser.
   String joinAll(Iterable<String> parts) {
     var buffer = new StringBuffer();
     var needsSeparator = false;
     var isAbsoluteAndNotRootRelative = false;
 
     for (var part in parts.where((part) => part != '')) {
       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.
         buffer.clear();
         buffer.write(part);
       } else {
         if (part.length > 0 && part[0].contains(style.separatorPattern)) {
           // The part starts with a separator, so we don't need to add one.
         } else if (needsSeparator) {
           buffer.write(separator);
@@ skipping 152 matching lines @@
       pathParsed.separators..removeLast()..removeLast()..add('');
     }
 
     // Make it relative.
     pathParsed.root = '';
     pathParsed.removeTrailingSeparators();
 
     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'
   String withoutExtension(String path) {
     var parsed = _parse(path);
 
     for (var i = parsed.parts.length - 1; i >= 0; i--) {
       if (!parsed.parts[i].isEmpty) {
         parsed.parts[i] = parsed.basenameWithoutExtension;
         break;
@@ skipping 227 matching lines @@
 /// The style for Windows paths.
 class _WindowsStyle extends Style {
   _WindowsStyle();
 
   final name = 'windows';
   final separator = '\\';
   final separatorPattern = new RegExp(r'[/\\]');
   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:'.");
     }
 
     var path = uri.path;
     if (uri.host == '') {
       // Drive-letter paths look like "file:///C:/path/to/file". The
       // replaceFirst removes the extra initial slash.
       if (path.startsWith('/')) path = path.replaceFirst("/", "");
@@ skipping 194 matching lines @@
     // doesn't count.
     if (lastDot <= 0) return [file, ''];
 
     return [file.substring(0, lastDot), file.substring(lastDot)];
   }
 
   _ParsedPath clone() => new _ParsedPath(
       style, root, isRootRelative,
       new List.from(parts), new List.from(separators));
 }