Support a URL style for pathos.

pkg/pathos/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 13 matching lines @@
 import 'dart:io' as io;
 
 /// An internal builder for the current OS so we can provide a straight
 /// functional interface and not require users to create one.
 final _builder = new Builder();
 
 /**
  * Inserts [length] elements in front of the [list] and fills them with the
  * [fillValue].
  */
-void _growListFront(List list, int length, fillValue) {
-  list.length += length;
-  list.setRange(length, list.length, list);
-  for (var i = 0; i < length; i++) {
-    list[i] = fillValue;
-  }
-}
+void _growListFront(List list, int length, fillValue) =>
+  list.insertAll(0, new List.filled(length, fillValue));
 
 /// Gets the path to the current working directory.
 String get current => io.Directory.current.path;
 
 /// Gets the path separator for the current platform. On Mac and Linux, this
 /// is `/`. On Windows, it's `\`.
 String get separator => _builder.separator;
 
 /// Converts [path] to an absolute path by resolving it relative to the current
 /// working directory. If [path] is already an absolute path, just returns it.
@@ skipping 54 matching lines @@
 ///     // Unix
 ///     path.rootPrefix('path/to/foo'); // -> ''
 ///     path.rootPrefix('/path/to/foo'); // -> '/'
 ///
 ///     // Windows
 ///     path.rootPrefix(r'path\to\foo'); // -> ''
 ///     path.rootPrefix(r'C:\path\to\foo'); // -> r'C:\'
 String rootPrefix(String path) => _builder.rootPrefix(path);
 
 /// Returns `true` if [path] is an absolute path and `false` if it is a
-/// relative path. On POSIX systems, absolute paths start with a `/` (forward
-/// slash). On Windows, an absolute path starts with `\\`, or a drive letter
-/// followed by `:/` or `:\`.
+/// relative path.
+///
+/// On POSIX systems, absolute paths start with a `/` (forward slash). On
+/// Windows, an absolute path starts with `\\`, or a drive letter followed by
+/// `:/` or `:\`. For URLs, absolute paths either start with a protocol and
+/// optional hostname (e.g. `http://dartlang.org`, `file://`) or with a `/`.
+///
+/// URLs that start with `/` are known as "root-relative", since they're
+/// relative to the root of the current URL. Since root-relative paths are still
+/// absolute in every other sense, [isAbsolute] will return true for them. They
+/// can be detected using [isRootRelative].
 bool isAbsolute(String path) => _builder.isAbsolute(path);
 
 /// Returns `true` if [path] is a relative path and `false` if it is absolute.
 /// On POSIX systems, absolute paths start with a `/` (forward slash). On
 /// Windows, an absolute path starts with `\\`, or a drive letter followed by
 /// `:/` or `:\`.
 bool isRelative(String path) => _builder.isRelative(path);
 
+/// Returns `true` if [path] is a root-relative path and `false` if it's not.
+///
+/// URLs that start with `/` are known as "root-relative", since they're
+/// relative to the root of the current URL. Since root-relative paths are still
+/// absolute in every other sense, [isAbsolute] will return true for them. They
+/// can be detected using [isRootRelative].
+///
+/// No POSIX and Windows paths are root-relative.
+bool isRootRelative(String path) => _builder.isRootRelative(path);
+
 /// Joins the given path parts into a single path using the current platform's
 /// [separator]. Example:
 ///
 ///     path.join('path', 'to', 'foo'); // -> 'path/to/foo'
 ///
 /// If any part ends in a path separator, then a redundant separator will not
 /// be added:
 ///
 ///     path.join('path/', 'to', 'foo'); // -> 'path/to/foo
 ///
@@ skipping 197 matching lines @@
   ///
   ///     // Windows
   ///     builder.rootPrefix(r'path\to\foo'); // -> ''
   ///     builder.rootPrefix(r'C:\path\to\foo'); // -> r'C:\'
   String rootPrefix(String path) {
     var root = _parse(path).root;
     return root == null ? '' : root;
   }
 
   /// Returns `true` if [path] is an absolute path and `false` if it is a
-  /// relative path. On POSIX systems, absolute paths start with a `/` (forward
-  /// slash). On Windows, an absolute path starts with `\\`, or a drive letter
-  /// followed by `:/` or `:\`.
+  /// relative path.
+  ///
+  /// On POSIX systems, absolute paths start with a `/` (forward slash). On
+  /// Windows, an absolute path starts with `\\`, or a drive letter followed by
+  /// `:/` or `:\`. For URLs, absolute paths either start with a protocol and
+  /// optional hostname (e.g. `http://dartlang.org`, `file://`) or with a `/`.
+  ///
+  /// URLs that start with `/` are known as "root-relative", since they're
+  /// relative to the root of the current URL. Since root-relative paths are
+  /// still absolute in every other sense, [isAbsolute] will return true for
+  /// them. They can be detected using [isRootRelative].
   bool isAbsolute(String path) => _parse(path).isAbsolute;
 
   /// Returns `true` if [path] is a relative path and `false` if it is absolute.
   /// On POSIX systems, absolute paths start with a `/` (forward slash). On
   /// Windows, an absolute path starts with `\\`, or a drive letter followed by
   /// `:/` or `:\`.
   bool isRelative(String path) => !isAbsolute(path);
 
+  /// Returns `true` if [path] is a root-relative path and `false` if it's not.
+  ///
+  /// URLs that start with `/` are known as "root-relative", since they're
+  /// relative to the root of the current URL. Since root-relative paths are
+  /// still absolute in every other sense, [isAbsolute] will return true for
+  /// them. They can be detected using [isRootRelative].
+  ///
+  /// No POSIX and Windows paths are root-relative.
+  bool isRootRelative(String path) => _parse(path).isRootRelative;
+
   /// Joins the given path parts into a single path. Example:
   ///
   ///     builder.join('path', 'to', 'foo'); // -> 'path/to/foo'
   ///
   /// If any part ends in a path separator, then a redundant separator will not
   /// be added:
   ///
   ///     builder.join('path/', 'to', 'foo'); // -> 'path/to/foo
   ///
   /// If a part is an absolute path, then anything before that will be ignored:
@@ skipping 17 matching lines @@
   ///     builder.joinAll(['path/', 'to', 'foo']); // -> 'path/to/foo
   ///
   /// If a part is an absolute path, then anything before that will be ignored:
   ///
   ///     builder.joinAll(['path', '/to', 'foo']); // -> '/to/foo'
   ///
   /// 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) {
-      if (this.isAbsolute(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());
+        buffer.clear();
+        buffer.write(oldRoot);
+        buffer.write(part);
+      } else if (this.isAbsolute(part)) {
+        isAbsoluteAndNotRootRelative = !this.isRootRelative(part);
         // An absolute path discards everything before it.
-        buffer = new StringBuffer();
+        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);
         }
 
         buffer.write(part);
       }
 
       // Unless this part ends with a separator, we'll need to add one before
       // the next part.
-      needsSeparator = part.length > 0 &&
-          !part[part.length - 1].contains(style.separatorPattern);
+      needsSeparator = part.contains(style.needsSeparatorPattern);
     }
 
     return buffer.toString();
   }
 
   // TODO(nweiz): add a UNC example for Windows once issue 7323 is fixed.
   /// Splits [path] into its components using the current platform's
   /// [separator]. Example:
   ///
   ///     builder.split('path/to/foo'); // -> ['path', 'to', 'foo']
@@ skipping 70 matching lines @@
 
     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)) path = this.resolve(path);
+    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".');
     }
 
     var fromParsed = _parse(from)..normalize();
     var pathParsed = _parse(path)..normalize();
 
     // If the root prefixes don't match (for example, different drive letters
     // on Windows), then there is no relative path, so just return the absolute
     // one. In Windows, drive letters are case-insenstive and we allow
     // calculation of relative paths, even if a path has not been normalized.
     if (fromParsed.root != pathParsed.root &&
         ((fromParsed.root ==  null || pathParsed.root == null) ||
           fromParsed.root.toLowerCase().replaceAll('/', '\\') !=
           pathParsed.root.toLowerCase().replaceAll('/', '\\'))) {
       return pathParsed.toString();
     }
 
     // Strip off their common prefix.
     while (fromParsed.parts.length > 0 && pathParsed.parts.length > 0 &&
            fromParsed.parts[0] == pathParsed.parts[0]) {
       fromParsed.parts.removeAt(0);
-      fromParsed.separators.removeAt(0);
+      fromParsed.separators.removeAt(1);
       pathParsed.parts.removeAt(0);
-      pathParsed.separators.removeAt(0);
+      pathParsed.separators.removeAt(1);
     }
 
     // If there are any directories left in the root path, we need to walk up
     // out of them.
     _growListFront(pathParsed.parts, fromParsed.parts.length, '..');
-    _growListFront(
-        pathParsed.separators, fromParsed.parts.length, style.separator);
+    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 '.';
 
     // Make it relative.
     pathParsed.root = '';
     pathParsed.removeTrailingSeparators();
 
     return pathParsed.toString();
   }
@@ skipping 12 matching lines @@
     }
 
     return parsed.toString();
   }
 
   _ParsedPath _parse(String path) {
     var before = path;
 
     // Remove the root prefix, if any.
     var root = style.getRoot(path);
+    var isRootRelative = style.getRelativeRoot(path) != null;
     if (root != null) path = path.substring(root.length);
 
     // Split the parts on path separators.
     var parts = [];
     var separators = [];
+
+    var firstSeparator = style.separatorPattern.firstMatch(path);
+    if (firstSeparator != null && firstSeparator.start == 0) {
+      separators.add(firstSeparator[0]);
+      path = path.substring(firstSeparator[0].length);
+    } else {
+      separators.add('');
+    }
+
     var start = 0;
     for (var match in style.separatorPattern.allMatches(path)) {
       parts.add(path.substring(start, match.start));
       separators.add(match[0]);
       start = match.end;
     }
 
     // Add the final part, if any.
     if (start < path.length) {
       parts.add(path.substring(start));
       separators.add('');
     }
 
-    return new _ParsedPath(style, root, parts, separators);
+    return new _ParsedPath(style, root, isRootRelative, parts, separators);
   }
 }
 
 /// An enum type describing a "flavor" of path.
 class Style {
   /// POSIX-style paths use "/" (forward slash) as separators. Absolute paths
   /// start with "/". Used by UNIX, Linux, Mac OS X, and others.
-  static final posix = new Style._('posix', '/', '/', '/');
+  static final posix = new Style._('posix', '/', '/', r'[^/]$', '/');
 
   /// Windows paths use "\" (backslash) as separators. Absolute paths start with
   /// a drive letter followed by a colon (example, "C:") or two backslashes
   /// ("\\") for UNC paths.
   // TODO(rnystrom): The UNC root prefix should include the drive name too, not
   // just the "\\".
-  static final windows = new Style._('windows', '\\', r'[/\\]',
+  static final windows = new Style._('windows', '\\', r'[/\\]', r'[^/\\]$',
       r'\\\\|[a-zA-Z]:[/\\]');
 
+  /// URLs aren't filesystem paths, but they're supported by Pathos to make it
+  /// easier to manipulate URL paths in the browser.
+  ///
+  /// URLs use "/" (forward slash) as separators. Absolute paths either start
+  /// with a protocol and optional hostname (e.g. `http://dartlang.org`,
+  /// `file://`) or with "/".
+  static final url = new Style._('url', '/', '/',
+      r"(^[a-zA-Z][-+.a-zA-Z\d]*://|[^/])$",
+      r"[a-zA-Z][-+.a-zA-Z\d]*://[^/]*", r"/");
+
   Style._(this.name, this.separator, String separatorPattern,
-      String rootPattern)
+      String needsSeparatorPattern, String rootPattern,
+      [String relativeRootPattern])
     : separatorPattern = new RegExp(separatorPattern),
-      _rootPattern = new RegExp('^$rootPattern');
+      needsSeparatorPattern = new RegExp(needsSeparatorPattern),
+      _rootPattern = new RegExp('^$rootPattern'),
+      _relativeRootPattern = relativeRootPattern == null ? null :
+          new RegExp('^$relativeRootPattern');
 
   /// The name of this path style. Will be "posix" or "windows".
   final String name;
 
   /// The path separator for this style. On POSIX, this is `/`. On Windows,
   /// it's `\`.
   final String separator;
 
   /// The [Pattern] that can be used to match a separator for a path in this
   /// style. Windows allows both "/" and "\" as path separators even though
   /// "\" is the canonical one.
   final Pattern separatorPattern;
 
+  /// The [Pattern] that matches path components that need a separator after
+  /// them.
+  ///
+  /// Windows and POSIX styles just need separators when the previous component
+  /// doesn't already end in a separator, but the URL always needs to place a
+  /// separator between the root and the first component, even if the root
+  /// already ends in a separator character. For example, to join "file://" and
+  /// "usr", an additional "/" is needed (making "file:///usr").
+  final Pattern needsSeparatorPattern;
+
   // TODO(nweiz): make this a Pattern when issue 7080 is fixed.
   /// The [RegExp] that can be used to match the root prefix of an absolute
   /// path in this style.
   final RegExp _rootPattern;
 
+  /// The [RegExp] that can be used to match the root prefix of a root-relative
+  /// path in this style.
+  ///
+  /// This can be null to indicate that this style doesn't support root-relative
+  /// paths.
+  final RegExp _relativeRootPattern;
+
   /// Gets the root prefix of [path] if path is absolute. If [path] is relative,
   /// returns `null`.
   String getRoot(String path) {
     var match = _rootPattern.firstMatch(path);
+    if (match != null) return match[0];
+    return getRelativeRoot(path);
+  }
+
+  /// Gets the root prefix of [path] if it's root-relative.
+  ///
+  /// If [path] is relative or absolute and not root-relative, returns `null`.
+  String getRelativeRoot(String path) {
+    if (_relativeRootPattern == null) return null;
+    var match = _relativeRootPattern.firstMatch(path);
     if (match == null) return null;
     return match[0];
   }
 
   String toString() => name;
 }
 
 // TODO(rnystrom): Make this public?
 class _ParsedPath {
   /// The [Style] that was used to parse this path.
   Style style;
 
   /// The absolute root portion of the path, or `null` if the path is relative.
   /// On POSIX systems, this will be `null` or "/". On Windows, it can be
   /// `null`, "//" for a UNC path, or something like "C:\" for paths with drive
   /// letters.
   String root;
 
+  /// Whether this path is root-relative.
+  ///
+  /// See [Builder.isRootRelative].
+  bool isRootRelative;
+
   /// The path-separated parts of the path. All but the last will be
   /// directories.
   List<String> parts;
 
-  /// The path separators following each part. The last one will be an empty
-  /// string unless the path ends with a trailing separator.
+  /// The path separators preceding each part.
+  ///
+  /// The first one will be an empty string unless the root requires a separator
+  /// between it and the path. The last one will be an empty string unless the
+  /// path ends with a trailing separator.
   List<String> separators;
 
   /// The file extension of the last part, or "" if it doesn't have one.
   String get extension => _splitExtension()[1];
 
   /// `true` if this is an absolute path.
   bool get isAbsolute => root != null;
 
-  _ParsedPath(this.style, this.root, this.parts, this.separators);
+  _ParsedPath(this.style, this.root, this.isRootRelative, this.parts,
+      this.separators);
 
   String get basename {
     var copy = this.clone();
     copy.removeTrailingSeparators();
     if (copy.parts.isEmpty) return root == null ? '' : root;
     return copy.parts.last;
   }
 
   String get basenameWithoutExtension {
     var copy = this.clone();
@@ skipping 34 matching lines @@
     if (!isAbsolute) {
       _growListFront(newParts, leadingDoubles, '..');
     }
 
     // If we collapsed down to nothing, do ".".
     if (newParts.length == 0 && !isAbsolute) {
       newParts.add('.');
     }
 
     // Canonicalize separators.
-    var newSeparators = [];
-    _growListFront(newSeparators, newParts.length, style.separator);
+    var newSeparators = new List.generate(
+        newParts.length, (_) => style.separator, growable: true);
+    newSeparators.insert(0,
+        isAbsolute && newParts.length > 0 &&
+                root.contains(style.needsSeparatorPattern) ?
+            style.separator : '');
 
     parts = newParts;
     separators = newSeparators;
 
     // Normalize the Windows root if needed.
     if (root != null && style == Style.windows) {
       root = root.replaceAll('/', '\\');
     }
     removeTrailingSeparators();
   }
 
   String toString() {
     var builder = new StringBuffer();
     if (root != null) builder.write(root);
     for (var i = 0; i < parts.length; i++) {
+      builder.write(separators[i]);
       builder.write(parts[i]);
-      builder.write(separators[i]);
     }
+    builder.write(separators.last);
 
     return builder.toString();
   }
 
   /// Splits the last part of the path into a two-element list. The first is
   /// the name of the file without any extension. The second is the extension
   /// or "" if it has none.
   List<String> _splitExtension() {
     if (parts.isEmpty) return ['', ''];
 
     var file = parts.last;
     if (file == '..') return ['..', ''];
 
     var lastDot = file.lastIndexOf('.');
 
     // If there is no dot, or it's the first character, like '.bashrc', it
     // doesn't count.
     if (lastDot <= 0) return [file, ''];
 
     return [file.substring(0, lastDot), file.substring(lastDot)];
   }
 
   _ParsedPath clone() => new _ParsedPath(
-      style, root, new List.from(parts), new List.from(separators));
+      style, root, isRootRelative,
+      new List.from(parts), new List.from(separators));
 }