Add a path.formatUri method and release path 1.2.0.

pkg/path/lib/src/context.dart

 // Copyright (c) 2013, 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.
 
 library path.context;
 
 import 'style.dart';
 import 'parsed_path.dart';
 import 'path_exception.dart';
 import '../path.dart' as p;
@@ skipping 454 matching lines @@
   ///     context.toUri('http://dartlang.org/path/to/foo')
   ///       // -> Uri.parse('http://dartlang.org/path/to/foo')
   Uri toUri(String path) {
     if (isRelative(path)) {
       return style.relativePathToUri(path);
     } else {
       return style.absolutePathToUri(join(current, path));
     }
   }
 
+  /// Returns a human-readable representation of [uri].
+  ///
+  /// If [uri] can be made relative to the current working directory, that's
+  /// 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
+  ///     var context = new Context(current: '/root/path');
+  ///     context.formatUri('file:///root/path/a/b.dart'); // -> 'a/b.dart'
+  ///     context.formatUri('http://dartlang.org/'); // -> 'http://dartlang.org'
+  ///
+  ///     // Windows
+  ///     var context = new Context(current: r'C:\root\path');
+  ///     context.formatUri('file:///C:/root/path/a/b.dart'); // -> r'a\b.dart'
+  ///     context.formatUri('http://dartlang.org/'); // -> 'http://dartlang.org'
+  ///
+  ///     // URL
+  ///     var context = new Context(current: 'http://dartlang.org/root/path');
+  ///     context.formatUri('http://dartlang.org/root/path/a/b.dart');
+  ///         // -> r'a/b.dart'
+  ///     context.formatUri('file:///root/path'); // -> 'file:///root/path'
+  String formatUri(uri) {
+    if (uri is String) uri = Uri.parse(uri);
+    if (uri.scheme == 'file' && style == Style.url) return uri.toString();
+    if (uri.scheme != 'file' && uri.scheme != '' && style != Style.url) {
+      return uri.toString();
+    }
+
+    var path = fromUri(uri);
+    var rel = relative(path);
+    var components = split(rel);
+
+    // Return whichever of the relative path and the original path has the
+    // fewest components. This avoids ugly things like long "../" chains to get

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

How about replacing the first sentence with:

"Only return a relative path if it's actually shorter than the original one."

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

Done.

+    // to the root and then go back down.
+    return split(rel).length > split(path).length ? path : rel;
+  }
+
   ParsedPath _parse(String path) => new ParsedPath.parse(path, style);
 }
 
 /// Validates that there are no non-null arguments following a null one and
 /// throws an appropriate [ArgumentError] on failure.
 _validateArgList(String method, List<String> args) {
   for (var i = 1; i < args.length; i++) {
     // Ignore nulls hanging off the end.
     if (args[i] == null || args[i - 1] != null) continue;
 
     var numArgs;
     for (numArgs = args.length; numArgs >= 1; numArgs--) {
       if (args[numArgs - 1] != null) break;
     }
 
     // Show the arguments.
     var message = new StringBuffer();
     message.write("$method(");
     message.write(args.take(numArgs)
         .map((arg) => arg == null ? "null" : '"$arg"')
         .join(", "));
     message.write("): part ${i - 1} was null, but part $i was not.");
     throw new ArgumentError(message.toString());
   }
 }