Index: pkg/path/lib/path.dart |
diff --git a/pkg/path/lib/path.dart b/pkg/path/lib/path.dart |
index bb88953f36c0f2e13c25d46ade9ab8d6e3184835..e226ec73fb3198839f03f1341eebe2e68c821366 100644 |
--- a/pkg/path/lib/path.dart |
+++ b/pkg/path/lib/path.dart |
@@ -18,6 +18,32 @@ |
/// |
/// [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 |
+/// "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, ' |
@@ -67,8 +93,8 @@ String get current { |
} |
} |
-/// 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 |
@@ -765,9 +791,10 @@ class Builder { |
/// // -> 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); |
+ return style.relativePathToUri(parsed.parts); |
} else { |
- return style.pathToUri(join(root, path)); |
+ return style.absolutePathToUri(join(root, path)); |
} |
} |
@@ -821,8 +848,8 @@ abstract class Style { |
// 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`, |
@@ -885,11 +912,11 @@ abstract class Style { |
/// 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); |
+ |
+ /// Returns the URI that represents [path], which is assumed to be absolute. |
+ Uri absolutePathToUri(String path); |
String toString() => name; |
} |
@@ -913,7 +940,7 @@ class _PosixStyle extends Style { |
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) { |
@@ -960,7 +987,7 @@ class _WindowsStyle extends Style { |
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". |
@@ -1013,7 +1040,14 @@ class _UrlStyle extends Style { |
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)); |
+ } |
+ |
+ Uri absolutePathToUri(String path) => Uri.parse(path); |
} |
// TODO(rnystrom): Make this public? |