Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(877)

Unified Diff: pkg/path/lib/path.dart

Issue 20364002: Remove API documentation from path README. (Closed) Base URL: https://dart.googlecode.com/svn/branches/bleeding_edge/dart
Patch Set: Add doc link to pubspec. Created 7 years, 5 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View side-by-side diff with in-line comments
Download patch
« no previous file with comments | « pkg/path/README.md ('k') | pkg/path/pubspec.yaml » ('j') | no next file with comments »
Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
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?
« no previous file with comments | « pkg/path/README.md ('k') | pkg/path/pubspec.yaml » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698