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

[Bob Nystrom, 2013/06/06 22:50:40]

Long lines.

[nweiz, 2013/06/07 01:04:30]

Done.

+  /// 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

[Bob Nystrom, 2013/06/06 22:50:40]

Ditto.

[nweiz, 2013/06/07 01:04:30]

Done.

+  /// 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 19 matching lines @@
   /// 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;
 
     for (var part in parts) {
-      if (this.isAbsolute(part)) {
+      if (this.isRootRelative(part) &&
+          this.isAbsolute(buffer.toString()) &&
+          !this.isRootRelative(buffer.toString())) {
+        var oldRoot = this.rootPrefix(buffer.toString());

[Bob Nystrom, 2013/06/06 22:50:40]

A couple of things here:

1. Calling toString() on the buffer multiple times for each part feels slow. How
about keeping track of whether or not the current buffer is absolute or root
relative? You can make two bools that default to false and then set them as
appropriate in the if (this.isAbsolute(part)) arm.

2. It isn't obvious what this is for. How about a "if the new part is root
relative, it replaces the previous path but preserves the rootPrefix". 

3. Is that actually the correct behavior? Do we want to support a base URL or
something?

4. I don't understand what the !this.isRootRelative(buffer.toString()) case is
for.

[nweiz, 2013/06/07 01:04:30]

Done.
Done.
Yes. This makes pathos.join("http://foo.com", "/bar") return
"http://foo.com/bar", which is correct. It's analogous to relative parts being
interpreted as relative to the prior components of the path.
If the existing path is also root-relative, we don't want to preserve anything
about it. For example, path.join("/foo", "/bar") should just return "/bar".

+        buffer = new StringBuffer();

[Bob Nystrom, 2013/06/06 22:50:40]

buffer.clear() seems cleaner to me. Below too?

[nweiz, 2013/06/07 01:04:30]

Done.

+        buffer.write(oldRoot);
+        buffer.write(part);
+      } else if (this.isAbsolute(part)) {
         // An absolute path discards everything before it.
         buffer = new StringBuffer();
         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.
+  ///
+  /// Some styles ([url] in particlar) have moderately complex rules about when
+  /// a separator is needed, especially for root path components.

[Bob Nystrom, 2013/06/06 22:50:40]

Can you explain what these rules are somewhere?

[nweiz, 2013/06/07 01:04:30]

Done.

+  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 getRelativeRoot(path);
+    return match[0];

[Bob Nystrom, 2013/06/06 22:50:40]

Seems weird to refer back to match here after delegating to getRelativeRoot. How
about flipping the if to be "match != null"?

[nweiz, 2013/06/07 01:04:30]

Done.

+  }
+
+  /// 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 preceeding each part.

[Bob Nystrom, 2013/06/06 22:50:40]

"preceeding" -> "preceding".

[nweiz, 2013/06/07 01:04:30]

Done.

+  ///
+  /// 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));
 }