Make pathos run in the browser.

pkg/pathos/README.md

Index: pkg/pathos/README.md
diff --git a/pkg/pathos/README.md b/pkg/pathos/README.md
index 66f40b1f0340aa0c32c9c48571221a3a5ac83a04..e67fc5e0199066880a06460fb88de0d68173980e 100644
--- a/pkg/pathos/README.md
+++ b/pkg/pathos/README.md
@@ -4,9 +4,9 @@ The pathos library provides common operations for manipulating file paths:
 joining, splitting, normalizing, etc.
 
 We've tried very hard to make this library do the "right" thing on whatever
-platform you run it on. When you use the top-level functions, it will assume
-the host OS's path style and work with that. If you want to specifically work
-with paths of a specific style, you can construct a `path.Builder` for that
+platform you run it on. When you use the top-level functions, it will assume the
+current platform's path style and work with that. If you want to specifically
+work with paths of a specific style, you can construct a `path.Builder` for that
 style.
 
 ## Using
@@ -20,16 +20,18 @@ have to if you don't want to:
 
 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 or Windows) of the host operating system.
+path style (POSIX, Windows, or URLs) of the host platform.
 
 ### String get current
 
-Gets the path to the current working directory.
+Gets the path to the current working directory. In the browser, this means the
+current URL. When using dart2js, this currently returns `.` due to technical
+constraints. In the future, it will return the current URL.
 
 ### String get separator
 
-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. On Mac, Linux, and the
+browser, this is `/`. On Windows, it's `\`.
 
 ### String absolute(String path)
 
@@ -100,12 +102,23 @@ relative.
     path.rootPrefix(r'path\to\foo'); // -> ''
     path.rootPrefix(r'C:\path\to\foo'); // -> r'C:\'
 
+    // URL
+    path.rootPrefix('path/to/foo'); // -> ''
+    path.rootPrefix('http://dartlang.org/path/to/foo');
+      // -> 'http://dartlang.org'
+
 ### bool isAbsolute(String 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 `:\`.
+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 `:\`. 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 isRelative(String path)
 
@@ -114,6 +127,16 @@ 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 isRootRelative(String 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.
+
 ### String join(String part1, [String part2, String part3, ...])
 
 Joins the given path parts into a single path using the current platform's
@@ -149,6 +172,10 @@ array. Example:
     // Windows
     path.split(r'C:\path\to\foo'); // -> [r'C:\', 'path', 'to', 'foo']
 
+    // Browser
+    path.split('http://dartlang.org/path/to/foo');
+      // -> ['http://dartlang.org', 'path', 'to', 'foo']
+
 ### String normalize(String path)
 
 Normalizes [path], simplifying it by handling `..`, and `.`, and
@@ -176,8 +203,13 @@ If the [from] argument is passed, [path] is made relative to that instead.
 Since there is no relative path from one drive letter to another on Windows,
 this will return an absolute path in that case.
 
+    // 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 withoutExtension(String path)
 
 Removes a trailing extension from the last part of [path].
@@ -234,6 +266,11 @@ relative.
     builder.rootPrefix(r'path\to\foo'); // -> ''
     builder.rootPrefix(r'C:\path\to\foo'); // -> r'C:\'
 
+    // URL
+    builder.rootPrefix('path/to/foo'); // -> ''
+    builder.rootPrefix('http://dartlang.org/path/to/foo');
+      // -> 'http://dartlang.org'
+
 ### String resolve(String part1, [String part2, String part3, ...])
 
 Creates a new path by appending the given path parts to the [root].
@@ -244,9 +281,9 @@ Equivalent to [join()] with [root] as the first argument. Example:
 
 ## The path.Style class
 
-The path library can work with two different "flavors" of path: POSIX and
-Windows. The differences between these are encapsulated by the `path.Style`
-enum class. There are two instances of it:
+The path library can work with three different "flavors" of path: POSIX,
+Windows, and URLs. The differences between these are encapsulated by the
+`path.Style` enum class. There are three instances of it:
 
 ### path.Style.posix
 
@@ -259,16 +296,22 @@ 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.
 
+### path.Style.url
+
+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
+"/".
+
 ## FAQ
 
 ### Where can I use this?
 
-Currently, Dart has no way of encapsulating configuration-specific code.
-Ideally, this library would be able to import dart:io when that's available or
-dart:html when that is. That would let it seamlessly work on both.
-
-Until then, this only works on the standalone VM. It's API is not coupled to
-dart:io, but it uses it internally to determine the current working directory.
+Pathos runs on the Dart VM and in the browser under both dart2js and Dartium.
+Under dart2js, it currently returns "." as the current working directory, while
+under Dartium it returns the current URL.
 
 ### Why doesn't this make paths first-class objects?