Move path-manipulation code from io.dart into path.dart.

utils/pub/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.
 library path;
 
 import 'dart:io' as io;
 
 /// An internal builder for the current OS so we can provide a straight
 /// functional interface and not require users to create one.
 final _builder = new Builder();
 
 /// Gets the path to the current working directory.
 String get current => new io.Directory.current().path;
 
 /// Gets the path separator for the current platform. On Mac and Linux, this
 /// is `/`. On Windows, it's `\`.
 String get separator => _builder.separator;
 
 /// Converts [path] to an absolute path by resolving it relative to the current
 /// working directory. If [path] is already an absolute path, just returns it.
 ///
 ///     path.absolute('foo/bar.txt'); // -> /your/current/dir/foo/bar.txt
 String absolute(String path) => join(current, path);
 
+/// Gets the part of [path] before the last separator.
+///
+///     path.dirname('path/to/foo.dart'); // -> 'path/to'
+///     path.dirname('path/to');          // -> 'to'
+String dirname(String path) => _builder.dirname(path);
+
 /// Gets the part of [path] after the last separator.
 ///
 ///     path.basename('path/to/foo.dart'); // -> 'foo.dart'
 ///     path.basename('path/to');          // -> 'to'
 String basename(String path) => _builder.basename(path);
 
 /// Gets the part of [path] after the last separator, and without any trailing
 /// file extension.
 ///
 ///     path.basenameWithoutExtension('path/to/foo.dart'); // -> 'foo'
 String basenameWithoutExtension(String path) =>
     _builder.basenameWithoutExtension(path);
 
 /// Gets the file extension of [path]: the portion of [basename] from the last
 /// `.` to the end (including the `.` itself).
 ///
 ///     path.extension('path/to/foo.dart');    // -> '.dart'
 ///     path.extension('path/to/foo');         // -> ''
 ///     path.extension('path.to/foo');         // -> ''
 ///     path.extension('path/to/foo.dart.js'); // -> '.js'
 ///
 /// If the file name starts with a `.`, then that is not considered the
 /// extension:
 ///
 ///     path.extension('~/.bashrc');    // -> ''
 ///     path.extension('~/.notes.txt'); // -> '.txt'
 String extension(String path) => _builder.extension(path);
 
+// TODO(nweiz): add a UNC example for Windows once issue 7323 is fixed.
+/// Returns the root of [path], if it's absolute, or `null` if it's relative.

[Bob Nystrom, 2012/12/12 00:01:20]

Generally, this library returns empty strings instead of null. That way you can
rely on getting a valid string out. How about doing that here too?

[nweiz, 2012/12/12 00:50:37]

I based it on the ParsedPath API, which also returns null here. I think null
makes sense when you're indicating the absence of the property you're querying
for. Also, the empty string won't work any more correctly if you try to treat it
as the root in e.g. join().

[Bob Nystrom, 2012/12/12 01:02:13]

That's part of the reason ParsedPath is still private.
But it won't work *less* correctly there, will it? I really think we should
avoid returning null here.

[nweiz, 2012/12/12 02:45:57]

Done.

+///
+///     // Unix
+///     path.rootOf('path/to/foo'); // -> null
+///     path.rootOf('/path/to/foo'); // -> '/'
+///
+///     // Windows
+///     path.rootOf(r'path\to\foo'); // -> null
+///     path.rootOf(r'C:\path\to\foo'); // -> r'C:\'
+String rootOf(String path) => _builder.rootOf(path);

[Bob Nystrom, 2012/12/12 00:01:20]

"rootOf" -> "root", I think. I like English-like APIs but that feels a bit too
much to me.

[nweiz, 2012/12/12 00:50:37]

I had it as "root" originally, but that causes a name conflict with
Builder.root.

[Bob Nystrom, 2012/12/12 01:02:13]

maybe rootPrefix?

[nweiz, 2012/12/12 02:45:57]

Done.

+
 /// Returns `true` if [path] is an absolute path and `false` if it is a
 /// relative path. On POSIX systems, absolute paths start with a `/` (forward
 /// slash). On Windows, an absolute path starts with `\\`, or a drive letter
 /// followed by `:/` or `:\`.
 bool isAbsolute(String path) => _builder.isAbsolute(path);
 
 /// Returns `true` if [path] is a relative path and `false` if it is absolute.
 /// On POSIX systems, absolute paths start with a `/` (forward slash). On
 /// Windows, an absolute path starts with `\\`, or a drive letter followed by
 /// `:/` or `:\`.
 bool isRelative(String path) => _builder.isRelative(path);
 
 /// Joins the given path parts into a single path using the current platform's
 /// [separator]. Example:
 ///
 ///     path.join('path', 'to', 'foo'); // -> 'path/to/foo'
 ///
 /// If any part ends in a path separator, then a redundant separator will not
 /// be added:
 ///
 ///     path.join('path/', 'to', 'foo'); // -> 'path/to/foo
 ///
 /// If a part is an absolute path, then anything before that will be ignored:
 ///
 ///     path.join('path', '/to', 'foo'); // -> '/to/foo'
 String join(String part1, [String part2, String part3, String part4,
-            String part5, String part6, String part7, String part8]) {
-  if (!?part2) return _builder.join(part1);
-  if (!?part3) return _builder.join(part1, part2);
-  if (!?part4) return _builder.join(part1, part2, part3);
-  if (!?part5) return _builder.join(part1, part2, part3, part4);
-  if (!?part6) return _builder.join(part1, part2, part3, part4, part5);
-  if (!?part7) return _builder.join(part1, part2, part3, part4, part5, part6);
-  if (!?part8) return _builder.join(part1, part2, part3, part4, part5, part6,
-                                    part7);
-  return _builder.join(part1, part2, part3, part4, part5, part6, part7, part8);
-}
+            String part5, String part6, String part7, String part8]) =>
+  _builder.join(part1, part2, part3, part4, part5, part6, part7, part8);
+
+// TODO(nweiz): add a UNC example for Windows once issue 7323 is fixed.
+/// Splits [path] into its components using the current platform's [separator].
+/// Example:
+///
+///     path.split('path/to/foo'); // -> ['path', 'to', 'foo']
+///
+/// If [path] is absolute, the root directory will be the first element in the
+/// array. Example:
+///
+///     // Unix
+///     path.split('/path/to/foo'); // -> ['/', 'path', 'to', 'foo']
+///
+///     // Windows
+///     path.split(r'C:\path\to\foo'); // -> [r'C:\', 'path', 'to', 'foo']
+List<String> split(String path) => _builder.split(path);

[Bob Nystrom, 2012/12/12 00:01:20]

Heh, my preflight patch has an implementation of this too. For mine, I put the
prefix in the first part: ['/path', 'foo', 'bar']. Does that work for you?

[nweiz, 2012/12/12 00:50:37]

I like this version better, since it lists all directories in the original path
whereas ['/path', 'foo', 'bar'] leaves off '/'. That makes it harder to e.g.
check if there's any parent directory with a given name.

[Bob Nystrom, 2012/12/12 01:02:13]

Ah, good call. Works for me.

 
 /// Normalizes [path], simplifying it by handling `..`, and `.`, and
 /// removing redundant path separators whenever possible.
 ///
 ///     path.normalize('path/./to/..//file.text'); // -> 'path/file.txt'
 String normalize(String path) => _builder.normalize(path);
 
 /// Attempts to convert [path] to an equivalent relative path from the current
 /// directory.
 ///
 ///     // Given current directory is /root/path:
 ///     path.relative('/root/path/a/b.dart'); // -> 'a/b.dart'
 ///     path.relative('/root/other.dart'); // -> '../other.dart'
 ///
+/// If the [to] argument is passed, [path] is made relative to that instead.

[Bob Nystrom, 2012/12/12 00:01:20]

I don't like reinterpreting one argument based on whether or not another one was
passed. Can you do "from:" instead of "to:" here?

[nweiz, 2012/12/12 00:50:37]

The idea is that it returns "path" relative to "to". "to" is effectively short
for "relativeTo".

I'm going to change it to "base" to sidestep any attempts to think of it as an
English phrase, since that can evidently be interpreted in two conflicting ways.

[Bob Nystrom, 2012/12/12 01:02:13]

Before I accidentally lost the implementation, I was using from: here, and I
liked it:

path.relative('foo/bar', from: 'foo') -> 'bar'

[nweiz, 2012/12/12 02:45:57]

That reads as "'foo/bar' relative from 'foo'" to me, which sounds awkward, but
if you like it I'll make the switch.

[Bob Nystrom, 2012/12/12 04:52:33]

Yeah, I like it a bit more. I read it as "get a path relative to 'foo/bar' from
'foo'" which has the nouns in about the right order.

+///
+///     path.relative('/root/path/a/b.dart', to: '/root/path'); // -> 'a/b.dart'
+///     path.relative('/root/other.dart',
+///         to: '/root/path'); // -> '../other.dart'
+///
 /// Since there is no relative path from one drive letter to another on Windows,
 /// this will return an absolute path in that case.
 ///
-///     // Given current directory is C:\home:
-///     path.relative(r'D:\other'); // -> 'D:\other'
-String relative(String path) => _builder.relative(path);
+///     path.relative(r'D:\other', to: r'C:\home'); // -> 'D:\other'
+String relative(String path, {String to}) => _builder.relative(path, to: to);
 
 /// Removes a trailing extension from the last part of [path].
 ///
 ///     withoutExtension('path/to/foo.dart'); // -> 'path/to/foo'
 String withoutExtension(String path) => _builder.withoutExtension(path);
 
 /// An instantiable class for manipulating paths. Unlike the top-level
 /// functions, this lets you explicitly select what platform the paths will use.
 class Builder {
   /// Creates a new path builder for the given style and root directory.
@@ skipping 20 matching lines @@
   /// The style of path that this builder works with.
   final Style style;
 
   /// The root directory that relative paths will be relative to.
   final String root;
 
   /// Gets the path separator for the builder's [style]. On Mac and Linux,
   /// this is `/`. On Windows, it's `\`.
   String get separator => style.separator;
 
+  /// Gets the part of [path] before the last separator.
+  ///
+  ///     builder.dirname('path/to/foo.dart'); // -> 'path/to'
+  ///     builder.dirname('path/to');          // -> 'to'

[Bob Nystrom, 2012/12/12 00:01:20]

Show an example of what happens if there's a trailing separator too. :)

[nweiz, 2012/12/12 00:50:37]

I left that out intentionally because I want to change that behavior in the near
future.

+  String dirname(String path) {

[Bob Nystrom, 2012/12/12 00:01:20]

Nit, but can you move this after basenameWithoutExtension. The methods here are
alphabetical (mostly).

[nweiz, 2012/12/12 00:50:37]

Done.

+    var parsed = _parse(path);
+    if (parsed.parts.isEmpty) return '.';

[Bob Nystrom, 2012/12/12 00:01:20]

You'll need to handle absolute paths here. If there's a root, return that
instead of '.'.

[nweiz, 2012/12/12 00:50:37]

Done.

+    if (parsed.separators.last == '') {

[Bob Nystrom, 2012/12/12 00:01:20]

!parsed.hasTrailingSeparator

[nweiz, 2012/12/12 00:50:37]

Done.

+      if (parsed.parts.length == 1) return '.';

[Bob Nystrom, 2012/12/12 00:01:20]

I think you should be able to skip this check.

[nweiz, 2012/12/12 00:50:37]

It dirname("a") should return ".", not "".

[Bob Nystrom, 2012/12/12 01:02:13]

Right, but I believe toString() handles that, doesn't it?

[nweiz, 2012/12/12 02:45:57]

No, it would just return ''.

+      parsed.parts.removeLast();
+      parsed.separators.removeLast();
+    }
+    parsed.separators[parsed.separators.length - 1] = '';

[Bob Nystrom, 2012/12/12 00:01:20]

What's this for?

[nweiz, 2012/12/12 00:50:37]

For paths with trailing separators, this makes dirname("a/") return "a". I don't
like it, but it is consistent with the behavior of basename().

For paths without trailing separators, this makes dirname("a/b") return "a"
rather than "a/".

[Bob Nystrom, 2012/12/12 01:02:13]

Yeah, consistency is what matters most to me here.
OK.

+    return parsed.toString();
+  }
+
   /// Gets the part of [path] after the last separator on the builder's
   /// platform.
   ///
   ///     builder.basename('path/to/foo.dart'); // -> 'foo.dart'
   ///     builder.basename('path/to');          // -> 'to'
   String basename(String path) => _parse(path).basename;
 
   /// Gets the part of [path] after the last separator on the builder's
   /// platform, and without any trailing file extension.
   ///
   ///     builder.basenameWithoutExtension('path/to/foo.dart'); // -> 'foo'
   String basenameWithoutExtension(String path) =>
       _parse(path).basenameWithoutExtension;
 
   /// Gets the file extension of [path]: the portion of [basename] from the last
   /// `.` to the end (including the `.` itself).
   ///
   ///     builder.extension('path/to/foo.dart'); // -> '.dart'
   ///     builder.extension('path/to/foo'); // -> ''
   ///     builder.extension('path.to/foo'); // -> ''
   ///     builder.extension('path/to/foo.dart.js'); // -> '.js'
   ///
   /// If the file name starts with a `.`, then it is not considered an
   /// extension:
   ///
   ///     builder.extension('~/.bashrc');    // -> ''
   ///     builder.extension('~/.notes.txt'); // -> '.txt'
   String extension(String path) => _parse(path).extension;
 
+  // TODO(nweiz): add a UNC example for Windows once issue 7323 is fixed.
+  /// Returns the root of [path], if it's absolute, or `null` if it's relative.
+  ///
+  ///     // Unix
+  ///     builder.rootOf('path/to/foo'); // -> null
+  ///     builder.rootOf('/path/to/foo'); // -> '/'
+  ///
+  ///     // Windows
+  ///     builder.rootOf(r'path\to\foo'); // -> null
+  ///     builder.rootOf(r'C:\path\to\foo'); // -> r'C:\'
+  String rootOf(String path) => _parse(path).root;
+
   /// Returns `true` if [path] is an absolute path and `false` if it is a
   /// relative path. On POSIX systems, absolute paths start with a `/` (forward
   /// slash). On Windows, an absolute path starts with `\\`, or a drive letter
   /// followed by `:/` or `:\`.
   bool isAbsolute(String path) => _parse(path).isAbsolute;
 
   /// Returns `true` if [path] is a relative path and `false` if it is absolute.
   /// On POSIX systems, absolute paths start with a `/` (forward slash). On
   /// Windows, an absolute path starts with `\\`, or a drive letter followed by
   /// `:/` or `:\`.
@@ skipping 10 matching lines @@
   ///
   /// If a part is an absolute path, then anything before that will be ignored:
   ///
   ///     builder.join('path', '/to', 'foo'); // -> '/to/foo'
   ///
   String join(String part1, [String part2, String part3, String part4,
               String part5, String part6, String part7, String part8]) {
     var buffer = new StringBuffer();
     var needsSeparator = false;
 
-    addPart(condition, part) {
-      if (!condition) return;
+    var parts = [part1, part2, part3, part4, part5, part6, part7, part8];
+    for (var i = 1; i < parts.length; i++) {
+      if (parts[i] == null || parts[i - 1] != null) continue;

[Bob Nystrom, 2012/12/12 00:01:20]

I'd find this more intuitive if you flipped the logic:

parts[i] != null && parts[i - 1] == null

[nweiz, 2012/12/12 00:50:37]

Done.

+      throw new ArgumentError("join(): part ${i - 1} was null, but part $i was "
+          "not.");
+    }
+
+    for (var part in parts) {
+      if (part == null) continue;
 
       if (this.isAbsolute(part)) {
         // An absolute path discards everything before it.
         buffer.clear();
         buffer.add(part);
       } else {
         if (part.length > 0 && style.separatorPattern.hasMatch(part[0])) {
           // The part starts with a separator, so we don't need to add one.
         } else if (needsSeparator) {
           buffer.add(separator);
         }
 
         buffer.add(part);
       }
 
       // Unless this part ends with a separator, we'll need to add one before
       // the next part.
       needsSeparator = part.length > 0 &&
           !style.separatorPattern.hasMatch(part[part.length - 1]);
     }
 
-    addPart(true, part1);
-    addPart(?part2, part2);
-    addPart(?part3, part3);
-    addPart(?part4, part4);
-    addPart(?part5, part5);
-    addPart(?part6, part6);
-    addPart(?part7, part7);
-    addPart(?part8, part8);
+    return buffer.toString();
+  }
 
-    return buffer.toString();
+  // TODO(nweiz): add a UNC example for Windows once issue 7323 is fixed.
+  /// Splits [path] into its components using the current platform's [separator].

[Bob Nystrom, 2012/12/12 00:01:20]

Long line.

[nweiz, 2012/12/12 00:50:37]

Done.

+  /// Example:
+  ///
+  ///     builder.split('path/to/foo'); // -> ['path', 'to', 'foo']
+  ///
+  /// If [path] is absolute, the root directory will be the first element in the
+  /// array. Example:
+  ///
+  ///     // Unix
+  ///     builder.split('/path/to/foo'); // -> ['/', 'path', 'to', 'foo']
+  ///
+  ///     // Windows
+  ///     builder.split(r'C:\path\to\foo'); // -> [r'C:\', 'path', 'to', 'foo']
+  List<String> split(String path) {
+    var parsed = _parse(path);
+    // Filter out empty parts that exist due to multiple separators in a row.
+    parsed.parts = parsed.parts.filter((part) => part != '');
+    if (parsed.root != null) parsed.parts.insertRange(0, 1, parsed.root);
+    return parsed.parts;
   }
 
   /// Normalizes [path], simplifying it by handling `..`, and `.`, and
   /// removing redundant path separators whenever possible.
   ///
   ///     builder.normalize('path/./to/..//file.text'); // -> 'path/file.txt'
   String normalize(String path) {
     if (path == '') return path;
 
     var parsed = _parse(path);
@@ skipping 17 matching lines @@
     return join(root, part1, part2, part3, part4, part5, part6, part7);
   }
 
   /// Attempts to convert [path] to an equivalent relative path relative to
   /// [root].
   ///
   ///     var builder = new Builder(root: '/root/path');
   ///     builder.relative('/root/path/a/b.dart'); // -> 'a/b.dart'
   ///     builder.relative('/root/other.dart'); // -> '../other.dart'
   ///
+  /// If the [to] argument is passed, [path] is made relative to that instead.
+  ///
+  ///     builder.relative('/root/path/a/b.dart',
+  ///         to: '/root/path'); // -> 'a/b.dart'
+  ///     builder.relative('/root/other.dart',
+  ///         to: '/root/path'); // -> '../other.dart'
+  ///
   /// Since there is no relative path from one drive letter to another on
   /// Windows, this will return an absolute path in that case.
   ///
-  ///     var builder = new Builder(root: r'C:\home');
-  ///     builder.relative(r'D:\other'); // -> 'D:\other'
-  String relative(String path) {
+  ///     builder.relative(r'D:\other', to: r'C:\other'); // -> 'D:\other'
+  String relative(String path, {String to}) {
     if (path == '') return '.';
 
     // If the base path is relative, resolve it relative to the current
     // directory.
-    var base = root;
+    var base = to == null ? root : to;
     if (this.isRelative(base)) base = absolute(base);
 
     // If the given path is relative, resolve it relative to the base.
     if (this.isRelative(path)) return this.normalize(path);
 
     var baseParsed = _parse(base)..normalize();
     var pathParsed = _parse(path)..normalize();
 
     // If the root prefixes don't match (for example, different drive letters
     // on Windows), then there is no relative path, so just return the absolute
@@ skipping 224 matching lines @@
 
     var lastDot = file.lastIndexOf('.');
 
     // If there is no dot, or it's the first character, like '.bashrc', it
     // doesn't count.
     if (lastDot <= 0) return [file, ''];
 
     return [file.substring(0, lastDot), file.substring(lastDot)];
   }
 }