Add a path.formatUri method and release path 1.2.0.

pkg/path/lib/path.dart

Index: pkg/path/lib/path.dart
diff --git a/pkg/path/lib/path.dart b/pkg/path/lib/path.dart
index 524f16dc0115fdcd36f6e820265415df6d800602..c10f9d469149295c20c4af3d5f136775eeb9a05b 100644
--- a/pkg/path/lib/path.dart
+++ b/pkg/path/lib/path.dart
@@ -366,3 +366,26 @@ String fromUri(uri) => _context.fromUri(uri);
 ///     path.toUri('path/to/foo')
 ///       // -> Uri.parse('path/to/foo')
 Uri toUri(String path) => _context.toUri(path);
+
+/// Returns a human-readable representation of [uri].

[Bob Nystrom, 2014/05/23 21:57:52]

"a human" -> "a terse, human".

[nweiz, 2014/05/23 22:18:04]

Done.

+///
+/// If [uri] can be made relative to the current working directory, that's

[Bob Nystrom, 2014/05/23 21:57:52]

Document what types uri may be.

[nweiz, 2014/05/23 22:18:04]

Done.

+/// done. Otherwise, it's returned as-is. This gracefully handles non-`file:`
+/// URIs for [Style.posix] and [Style.windows].
+///
+/// The returned value is meant for human consumption, and may be either URI-
+/// or path-formatted.
+///
+///     // POSIX at "/root/path"
+///     path.formatUri('file:///root/path/a/b.dart'); // -> 'a/b.dart'
+///     path.formatUri('http://dartlang.org/'); // -> 'http://dartlang.org'
+///
+///     // Windows at "C:\root\path"
+///     path.formatUri('file:///C:/root/path/a/b.dart'); // -> r'a\b.dart'
+///     path.formatUri('http://dartlang.org/'); // -> 'http://dartlang.org'
+///
+///     // URL at "http://dartlang.org/root/path"
+///     path.formatUri('http://dartlang.org/root/path/a/b.dart');
+///         // -> r'a/b.dart'
+///     path.formatUri('file:///root/path'); // -> 'file:///root/path'

[Bob Nystrom, 2014/05/23 21:57:52]

Should this normalize too?

[nweiz, 2014/05/23 22:18:04]

Good idea, done.

+String formatUri(uri) => _context.formatUri(uri);

[Bob Nystrom, 2014/05/23 21:57:52]

"format" still feels wrong to me. I expect it to take a format string or somehow
let the user configure the format. The intent of the method is not that the
result follows some specific format. If anything, it's the opposite: the result
will be less structured than the argument.

How about "shortenUri" or "prettyUri"?

[nweiz, 2014/05/23 22:18:04]

I feel like "format" can be interpreted in the same sense as e.g. "the Dart
formatter", but I don't mind "pretty" much either (although it's not a verb).
It's up to you.

[Bob Nystrom, 2014/05/23 22:24:38]

I like "pretty" a lot more than "format". It makes it clear that it produces
something for human aesthetics. It's a verb where I'm from!

[nweiz, 2014/05/23 22:36:55]

Done.