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
+///     path.isWithin('/root/path', '/root/path') // -> false
+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 77 matching lines @@
   /// Since there is no relative path from one drive letter to another on
   /// Windows, this will return an absolute path in that case.
   ///
   ///     builder.relative(r'D:\other', from: r'C:\other'); // -> 'D:\other'
   ///
   /// This will also return an absolute path if an absolute [path] is passed to
   /// a builder with a relative [root].
   ///
   ///     var builder = new Builder(r'some/relative/path');
   ///     builder.relative(r'/absolute/path'); // -> '/absolute/path'
+  ///
+  /// If [root] is relative, it may be impossible to determine a path from
+  /// [from] to [path]. For example, if [root] and [path] are "." and [from] is
+  /// "/", no path can be determined. In this case, a [PathException] will be
+  /// thrown.
   String relative(String path, {String from}) {
     from = from == null ? root : this.join(root, from);
 
     // We can't determine the path from a relative path to an absolute path.
     if (this.isRelative(from) && this.isAbsolute(path)) {
       return this.normalize(path);
     }
 
     // If the given path is relative, resolve it relative to the root of the
     // builder.
     if (this.isRelative(path) || this.isRootRelative(path)) {
       path = this.resolve(path);
     }
 
     // If the path is still relative and `from` is absolute, we're unable to
     // find a path from `from` to `path`.
     if (this.isRelative(path) && this.isAbsolute(from)) {
-      throw new ArgumentError('Unable to find a path to "$path" from "$from".');
+      throw new PathException('Unable to find a path to "$path" from "$from".');
     }
 
     var fromParsed = _parse(from)..normalize();
     var pathParsed = _parse(path)..normalize();
 
     if (fromParsed.parts.length > 0 && fromParsed.parts[0] == '.') {
       return pathParsed.toString();
     }
 
     // If the root prefixes don't match (for example, different drive letters
@@ skipping 13 matching lines @@
       fromParsed.parts.removeAt(0);
       fromParsed.separators.removeAt(1);
       pathParsed.parts.removeAt(0);
       pathParsed.separators.removeAt(1);
     }
 
     // If there are any directories left in the from path, we need to walk up
     // out of them. If a directory left in the from path is '..', it cannot
     // be cancelled by adding a '..'.
     if (fromParsed.parts.length > 0 && fromParsed.parts[0] == '..') {
-      throw new ArgumentError('Unable to find a path to "$path" from "$from".');
+      throw new PathException('Unable to find a path to "$path" from "$from".');
     }
     _growListFront(pathParsed.parts, fromParsed.parts.length, '..');
     pathParsed.separators[0] = '';
     pathParsed.separators.insertAll(1,
         new List.filled(fromParsed.parts.length, style.separator));
 
     // Corner case: the paths completely collapsed.
     if (pathParsed.parts.length == 0) return '.';
 
     // Corner case: path was '.' and some '..' directories were added in front.
     // Don't add a final '/.' in that case.
     if (pathParsed.parts.length > 1 && pathParsed.parts.last == '.') {
       pathParsed.parts.removeLast();
       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
+  ///     path.isWithin('/root/path', '/root/path') // -> false
+  bool isWithin(String parent, String child) {
+    var relative;
+    try {
+      relative = this.relative(child, from: parent);
+    } on PathException catch (_) {
+      // 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));
 }
+
+/// An exception class that's thrown when a path operation is unable to be
+/// computed accurately.
+class PathException implements Exception {
+  String message;
+
+  PathException(this.message);
+
+  String toString() => "PathException: $message";
+}