Handle special characters in path<->uri conversion.

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.
 ///
 ///     dependencies:
 ///       path: any
 ///
 /// Then run `pub install`.
 ///
 /// For more information, see the [path package on pub.dartlang.org][pkg].
 ///
 /// [pub]: http://pub.dartlang.org
 /// [pkg]: http://pub.dartlang.org/packages/path
+///
+/// ## Usage ##
+///
+/// The path library was designed to be imported with a prefix, though you don't
+/// have to if you don't want to:
+///
+///     import 'package:path/path.dart' as path;
+///
+/// The most common way to use the library is through the top-level functions.
+/// These manipulate path strings based on your current working directory and
+/// the path style (POSIX, Windows, or URLs) of the host platform. For example:
+///
+///     path.join("directory", "file.txt");
+///
+/// This calls the top-level [join()] function to join "directory" and

[nweiz, 2013/07/25 20:47:02]

Nit: "[join()]" -> "[join]".

[Bob Nystrom, 2013/07/25 23:20:10]

Done.

+/// "file.txt" using the current platform's directory separator.
+///
+/// If you want to work with paths for a specific platform regardless of the
+/// underlying platform that the program is running on, you can create a
+/// [Builder] and give it an explicit [Style]:
+///
+///     var builder = new path.Builder(style: Style.windows);
+///     builder.join("directory", "file.txt");
+///
+/// This will join "directory" and "file.txt" using the Windows path separator,
+/// even when the program is run on a POSIX machine.
 library path;
 
 @MirrorsUsed(targets: 'dart.dom.html.window, '
     'dart.io.Directory.current, '
     'dart.io.Platform.operatingSystem')
 import 'dart:mirrors';
 
 /// 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();
@@ skipping 29 matching lines @@
     return _io.classes[const Symbol('Directory')]
         .getField(const Symbol('current')).reflectee.path;
   } else if (_html != null) {
     return _html.getField(const Symbol('window'))
         .reflectee.location.href;
   } else {
     return '.';
   }
 }
 
-/// Gets the path separator for the current platform. On Mac and Linux, this
-/// is `/`. On Windows, it's `\`.
+/// Gets the path separator for the current platform. This is `\` on Windows
+/// and `/` on other platforms (including the browser).
 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.
 ///
 ///     path.absolute('foo/bar.txt'); // -> /your/current/dir/foo/bar.txt
 String absolute(String path) => join(current, path);
 
 /// Gets the part of [path] after the last separator.
 ///
@@ skipping 676 matching lines @@
   ///
   ///     // Windows
   ///     builder.toUri(r'C:\path\to\foo')
   ///       // -> Uri.parse('file:///C:/path/to/foo')
   ///
   ///     // URL
   ///     builder.toUri('http://dartlang.org/path/to/foo')
   ///       // -> Uri.parse('http://dartlang.org/path/to/foo')
   Uri toUri(String path) {
     if (isRelative(path)) {
-      return Uri.parse(path.replaceAll(style.separatorPattern, '/'));
+      var parsed = _parse(path);

[nweiz, 2013/07/25 20:47:02]

Why use [_parse] here instead of [split]?

[Bob Nystrom, 2013/07/25 23:20:10]

This path is known to be relative, so I don't think split() buys much. It calls
_parse() itself, so this seemed a bit more straightforward.

[nweiz, 2013/07/25 23:44:27]

It's not more straightforward to a reader of the code who's more familiar with
the external API than the internal one (that is, everyone but you and maybe me).

In general, I think it's almost always cleaner to implement stuff in terms of
the public API if possible.

[Bob Nystrom, 2013/07/25 23:58:37]

This code was removed anyway, so it's a moot point. :)

+      return style.relativePathToUri(parsed.parts);
     } else {
-      return style.pathToUri(join(root, path));
+      return style.absolutePathToUri(join(root, path));
     }
   }
 
   _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);
@@ skipping 33 matching lines @@
   /// start with "/". Used by UNIX, Linux, Mac OS X, and others.
   static final posix = new _PosixStyle();
 
   /// 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 _WindowsStyle();
 
-  /// URLs aren't filesystem paths, but they're supported by Pathos to make it
-  /// easier to manipulate URL paths in the browser.
+  /// URLs aren't filesystem paths, but they're supported 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 _UrlStyle();
 
   /// The name of this path style. Will be "posix" or "windows".
   String get name;
 
   /// The path separator for this style. On POSIX, this is `/`. On Windows,
@@ skipping 42 matching lines @@
     if (relativeRootPattern == null) return null;
     // TODO(rnystrom): Use firstMatch() when #7080 is fixed.
     var matches = relativeRootPattern.allMatches(path);
     if (matches.isEmpty) return null;
     return matches.first[0];
   }
 
   /// Returns the path represented by [uri] in this style.
   String pathFromUri(Uri uri);
 
-  /// Returns the URI that represents [path].
-  ///
-  /// Pathos will always path an absolute path for [path]. Relative paths are
-  /// handled automatically by [Builder].
-  Uri pathToUri(String path);
+  /// Returns the URI that represents the relative path made of [parts].
+  Uri relativePathToUri(Iterable<String> parts) => new Uri(pathSegments: parts);

[nweiz, 2013/07/25 20:47:02]

It's weird that this takes a list of parts but [absolutePathToUri] takes a
string. It feels like this should take a string and split it apart in the
default implementation. Then the URL implementation can just be
"Uri.parse(path)".

[Bob Nystrom, 2013/07/25 23:20:10]

Done. Good call.

+
+  /// Returns the URI that represents [path], which is assumed to be absolute.
+  Uri absolutePathToUri(String path);
 
   String toString() => name;
 }
 
 /// The style for POSIX paths.
 class _PosixStyle extends Style {
   _PosixStyle();
 
   static final _builder = new Builder(style: Style.posix);
 
   final name = 'posix';
   final separator = '/';
   final separatorPattern = new RegExp(r'/');
   final needsSeparatorPattern = new RegExp(r'[^/]$');
   final rootPattern = new RegExp(r'^/');
 
   String pathFromUri(Uri uri) {
     if (uri.scheme == '' || uri.scheme == 'file') {
       return Uri.decodeComponent(uri.path);
     }
     throw new ArgumentError("Uri $uri must have scheme 'file:'.");
   }
 
-  Uri pathToUri(String path) {
+  Uri absolutePathToUri(String path) {
     var parsed = _builder._parse(path);
 
     if (parsed.parts.isEmpty) {
       // If the path is a bare root (e.g. "/"), [components] will
       // currently be empty. We add two empty components so the URL constructor
       // produces "file:///", with a trailing slash.
       parsed.parts.addAll(["", ""]);
     } else if (parsed.hasTrailingSeparator) {
       // If the path has a trailing slash, add a single empty component so the
       // URI has a trailing slash as well.
@@ skipping 26 matching lines @@
       // Drive-letter paths look like "file:///C:/path/to/file". The
       // replaceFirst removes the extra initial slash.
       if (path.startsWith('/')) path = path.replaceFirst("/", "");
     } else {
       // Network paths look like "file://hostname/path/to/file".
       path = '\\\\${uri.host}$path';
     }
     return Uri.decodeComponent(path.replaceAll("/", "\\"));
   }
 
-  Uri pathToUri(String path) {
+  Uri absolutePathToUri(String path) {
     var parsed = _builder._parse(path);
     if (parsed.root == r'\\') {
       // Network paths become "file://hostname/path/to/file".
 
       var host = parsed.parts.removeAt(0);
 
       if (parsed.parts.isEmpty) {
         // If the path is a bare root (e.g. "\\hostname"), [parsed.parts] will
         // currently be empty. We add two empty components so the URL
         // constructor produces "file://hostname/", with a trailing slash.
@@ skipping 32 matching lines @@
   final name = 'url';
   final separator = '/';
   final separatorPattern = new RegExp(r'/');
   final needsSeparatorPattern = new RegExp(
       r"(^[a-zA-Z][-+.a-zA-Z\d]*://|[^/])$");
   final rootPattern = new RegExp(r"[a-zA-Z][-+.a-zA-Z\d]*://[^/]*");
   final relativeRootPattern = new RegExp(r"^/");
 
   String pathFromUri(Uri uri) => uri.toString();
 
-  Uri pathToUri(String path) => Uri.parse(path);
+  Uri relativePathToUri(Iterable<String> parts) {
+    // Since [parts] is itself from a URI, it may contain percent-encoded
+    // components. We don't want to double percent-encode them, so we
+    // percent-decode first.
+    return super.relativePathToUri(parts.map(Uri.decodeComponent));

[nweiz, 2013/07/25 20:47:02]

Seems unnecessary to parse and then re-serialize the URI. See above comment.

[Bob Nystrom, 2013/07/25 23:20:10]

Done.

+  }
+
+  Uri absolutePathToUri(String path) => Uri.parse(path);
 }
 
 // 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
@@ skipping 125 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));
 }