Add a path.formatUri method and release path 1.2.0.

pkg/path/lib/path.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 /// A comprehensive, cross-platform path manipulation library.
 ///
 /// ## Installing ##
 ///
 /// Use [pub][] to install this package. Add the following to your
 /// `pubspec.yaml` file.
@@ skipping 348 matching lines @@
 ///
 ///     // URL
 ///     path.toUri('http://dartlang.org/path/to/foo')
 ///       // -> Uri.parse('http://dartlang.org/path/to/foo')
 ///
 /// If [path] is relative, a relative URI will be returned.
 ///
 ///     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.