Make pathos run in the browser.

pkg/pathos/README.md

 A comprehensive, cross-platform path manipulation library for Dart.
 
 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
 
 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:pathos/path.dart' as path;
 
 ## Top-level functions
 
 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)
 
 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 basename(String path)
 
@@ skipping 50 matching lines @@
 relative.
 
     // 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:\'
 
+    // 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)
 
 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 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
 [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:
 
@@ skipping 15 matching lines @@
 
 If [path] is absolute, the root directory will be the first element in the
 array. Example:
 
     // Unix
     path.split('/path/to/foo'); // -> ['/', 'path', 'to', 'foo']
 
     // 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
 removing redundant path separators whenever possible.
 
     path.normalize('path/./to/..//file.text'); // -> 'path/file.txt'
 String normalize(String path) => _builder.normalize(path);
 
 ### String relative(String path, {String from})
 
 Attempts to convert [path] to an equivalent relative path from the current
 directory.
 
     // Given current directory is /root/path:
     path.relative('/root/path/a/b.dart'); // -> 'a/b.dart'
     path.relative('/root/other.dart'); // -> '../other.dart'
 
 If the [from] argument is passed, [path] is made relative to that instead.
 
     path.relative('/root/path/a/b.dart',
         from: '/root/path'); // -> 'a/b.dart'
     path.relative('/root/other.dart',
         from: '/root/path'); // -> '../other.dart'
 
 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].
 
     withoutExtension('path/to/foo.dart'); // -> 'path/to/foo'
 
 ## The path.Builder class
 
 In addition to the functions, path exposes a `path.Builder` class. This lets
 you configure the root directory and path style that paths are built using
@@ skipping 36 matching lines @@
 relative.
 
     // Unix
     builder.rootPrefix('path/to/foo'); // -> ''
     builder.rootPrefix('/path/to/foo'); // -> '/'
 
     // Windows
     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].
 Equivalent to [join()] with [root] as the first argument. Example:
 
     var builder = new Builder(root: 'root');
     builder.resolve('path', 'to', 'foo'); // -> 'root/path/to/foo'
 
 ## 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
 
 POSIX-style paths use "/" (forward slash) as separators. Absolute paths
 start with "/". Used by UNIX, Linux, Mac OS X, and others.
 
 ### path.Style.windows
 
 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?
 
 When you have path *objects*, then every API that takes a path has to decide if
 it accepts strings, path objects, or both.
 
  *  Accepting strings is the most convenient, but then it seems weird to have
     these path objects that aren't actually accepted by anything that needs a
     path. Once you've created a path, you have to always call `.toString()` on
     it before you can do anything useful with it.
@@ skipping 21 matching lines @@
  *  It can accurately tell if a path is absolute based on drive-letters or UNC
     prefix.
 
  *  It understands that "/foo" is not an absolute path on Windows.
 
  *  It knows that "C:\foo\one.txt" and "c:/foo\two.txt" are two files in the
     same directory.
 
 If you find a problem, surprise or something that's unclear, please don't
 hesitate to [file a bug](http://dartbug.com/new) and let us know.