dart:io | Add Link class, as sibling to File and Directory.

sdk/lib/io/link.dart

Index: sdk/lib/io/link.dart
diff --git a/sdk/lib/io/link.dart b/sdk/lib/io/link.dart
new file mode 100644
index 0000000000000000000000000000000000000000..3e4606758bed0db260d48a85ca64087cb3615623
--- /dev/null
+++ b/sdk/lib/io/link.dart
@@ -0,0 +1,230 @@
+// 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.
+
+part of dart.io;
+
+/**
+ * [Link] objects are references to filesystem links.
+ *
+ */
+abstract class Link extends FileSystemEntity {
+  /**
+   * Create a Link object.
+   */
+  factory Link(String path) => new _Link(path);
+
+  /**
+   * Create a Link object from a Path object.
+   */
+  factory Link.fromPath(Path path) => new _Link.fromPath(path);
+
+  /**
+   * Check if the link exists. The link may exist, even if its target
+   * is missing or deleted.
+   * Returns a [:Future<bool>:] that completes when the answer is known.
+   */
+  Future<bool> exists();
+
+  /**
+   * Synchronously check if the link exists. The link may exist, even if
+   * its target is missing or deleted.
+   */
+  bool existsSync();
+
+  /**
+   * Create a symbolic link. Returns a [:Future<Link>:] that completes with
+   * the link when it has been created. If the link exists, the function
+   * the future will complete with an error.
+   *
+   * If [linkRelative] is true, the target argument should be a relative path,
+   * and the link will interpret the target as a path relative to the link's
+   * directory.

[nweiz, 2013/03/08 20:26:41]

Explain what [target] is relative to if [linkRelative] is false (presumably the
CWD). Also mention whether the symlink will be relative or absolute in this case
-- that is, will "new Symlink('foo').create('bar')" create a symlink that points
to "bar", or to "`pwd`/bar"?

[Bill Hesse, 2013/03/11 09:25:59]

Done.

+   *
+   * On the Windows platform, this will only work with directories, and the
+   * target directory must exist. The link will be created as a Junction.

[nweiz, 2013/03/08 20:26:41]

Is it possible to create actual symlinks on Windows, rather than junction
points? I believe it supports them in all our supported versions. We're only
using junctions in pub because we couldn't figure out how to get the permissions
right to create real symlinks.

[Bill Hesse, 2013/03/11 09:25:59]

Eventually, we want to provide access to all types of links, including hard
links.  The permissions problem for symbolic links on Windows is pretty severe,
so the default link type should be Junction, I think.  There is different
treatment for admin and non-admin users, even if they both have permission to
create symbolic links, and admin users are actually harder to handle than
non-admin users.


On 2013/03/08 20:26:41, nweiz wrote:

+   */
+  Future<Link> create(String target, {bool linkRelative: false });
+
+  /**
+   * Synchronously create the link. Calling [createSync] on an existing link
+   * will throw an exception.
+   *
+   * If [linkRelative] is true, the target argument should be a relative path,
+   * and the link will interpret the target as a path relative to the link's
+   * directory.
+   *
+   * On the Windows platform, this will only work with directories, and the
+   * target directory must exist. The link will be created as a Junction.
+   */
+  void createSync(String target, {bool linkRelative: false });
+
+   /**
+   * Updates a link to point to a different target.
+   * Returns a [:Future<Link>:] that completes with
+   * the link when it has been created.  If the link does not exist,
+   * the future completes with an exception.
+   *
+   * If [linkRelative] is true, the target argument should be a relative path,
+   * and the link will interpret the target as a path relative to the link's
+   * directory.
+   *
+   * On the Windows platform, this will only work with directories, and the
+   * target directory must exist.
+   */
+  Future<Link> update(String target, {bool linkRelative: false });
+
+  /**
+   * Synchronously update the link. Calling [updateSync] on a non-existing link
+   * will throw an exception.
+   *
+   * If [linkRelative] is true, the target argument should be a relative path,
+   * and the link will interpret the target as a path relative to the link's
+   * directory.
+   *
+   * On the Windows platform, this will only work with directories, and the
+   * target directory must exist.
+   */
+  void updateSync(String target, {bool linkRelative: false });
+
+  /**
+   * Delete the link. Returns a [:Future<Link>:] that completes with
+   * the link when it has been deleted.  This does not delete, or otherwise
+   * affect, the target of the link.
+   */
+  Future<Link> delete();
+
+  /**
+   * Synchronously delete the link. This does not delete, or otherwise
+   * affect, the target of the link.
+   */
+  void deleteSync();
+
+  /**
+   * Get a [Directory] object for the directory containing this
+   * link. This is the directory containing the link, not the directory
+   * containing the target of the link. Returns a [:Future<Directory>:]
+   * that completes with the directory.
+   */
+  Future<Directory> directory();
+
+  /**
+   * Synchronously get a [Directory] object for the directory containing
+   * this link. This is the directory containing the link, not the directory
+   * containing the target of the link.
+   */
+  Directory directorySync();
+
+  /**
+   * Get the target of the link. Returns a future that completes with
+   * the path to the target.
+   *
+   * If [linkRelative] is true and the link target is a path relative to
+   * the link's directory, the future will complete with that relative path.
+   * Otherwise, the future completes with an error.

[nweiz, 2013/03/08 20:26:41]

Again, explain what happens if the target is relative and [linkRelative] is
false.

It seems unhelpful for this to complete with an error if the link happens to be
absolute when [linkRelative] is true. It would be better to return either null
or the absolute path; throwing an error just obligates everyone who uses this
method with [linkRelative] to add cumbersome error-handling.

[Bill Hesse, 2013/03/11 09:25:59]

This was intended as an initial implementation, with unimplemented cases being
filled out later.  But I have specified that the returned path will be absolute
if linkRelative is false.  This will throw an UnimplementedError currently.

+   */
+  Future<String> target({bool linkRelative: false });
+
+  /**
+   * Synchronously get the target of the link. Returns the path to the target.
+   *
+   * If [linkRelative] is true and the link target is a path relative to
+   * the link's directory, that relative path will be returned.  Otherwise,
+   * an exception is thrown.
+   */
+  String targetSync({bool linkRelative: false });
+
+  /**
+   * Get the canonical full path corresponding to the link path.
+   * Returns a [:Future<String>:] that completes with the path.
+   */
+  Future<String> fullPath();
+
+  /**
+   * Synchronously get the canonical full path corresponding to the link path.
+   */
+  String fullPathSync();
+}
+
+
+class _Link extends FileSystemEntity {
+  final String path;
+
+  _Link(String this.path);
+
+  _Link.fromPath(Path inputPath) : path = inputPath.toNativePath();
+
+  Future<bool> exists() {
+    // TODO(whesse): Replace with asynchronous version.
+    return new Future.of(existsSync());
+  }
+
+  bool existsSync() => FileSystemEntity.isLinkSync(path);
+
+  Future<Link> create(String target, {bool linkRelative: false }) {
+    // TODO(whesse): Replace with asynchronous version.
+    return new Future.of(() {
+      createSync(target, linkRelative: linkRelative);
+      return this;
+    });
+  }
+
+  void createSync(String target, {bool linkRelative: false }) {
+    if (!new Path(target).isAbsolute && !linkRelative) {
+      throw new UnimplementedError(
+          "Link.create with relative path must be linkRelative");

[nweiz, 2013/03/08 20:26:41]

This is not user-friendly behavior. This puts a lot of burden onto the user of
this code to make sure that the input path is either absolute or relative to the
link, and to make sure that [linkRelative] is set correctly. It also means that
the [linkRelative] flag doesn't do anything other than cause additional errors
if it's unset.

My preferred behavior as a user of the code would be to have "new
Symlink(linkPath).create(relativePath)" create a symlink with target
"path.relative(relativePath, from: path.dirname(linkPath))".

[Bill Hesse, 2013/03/11 09:25:59]

This CL was intended as a partial, initial implementation, which is why this
case throws UnimplementedError, rather than the
LinkIOException.

We think that this is not always possible, and that creating a relative path
when it is possible and an absolute path when it isn't makes the behavior harder
to predict for the user.

+    }
+    var result = _File._createLink(path, target);
+    if (result is OSError) {
+      throw new LinkIOException("Error in Link.createSync", result);
+    }
+  }
+
+  Future<Link> update(String target, {bool linkRelative: false }) {
+    delete().then((link) {

[nweiz, 2013/03/08 20:26:41]

return

+      link.create(target, linkRelative: linkRelative);
+    });

[nweiz, 2013/03/08 20:26:41]

It worries me that this isn't atomic. It could leave the filesystem in an
unexpected state if delete succeeds and create fails, to say nothing of
inspecting the filesystem during the operation.

[Bill Hesse, 2013/03/11 09:25:59]

This was just a temporary implementation, but you are right, it is not atomic. 
Replacing with Unimplemented until it is correct.

+  }
+
+  void updateSync(String target, {bool linkRelative: false }) {
+    deleteSync();
+    createSync(target, linkRelative: linkRelative);
+  }
+
+  Future<Link> delete() {
+    return new File(path).delete().then((_) => this);
+  }
+
+  void deleteSync() {
+    new File(path).deleteSync();
+  }
+}

[nweiz, 2013/03/08 20:26:41]

It would be nice to have a [follow] method that returned a
Future<FileSystemEntity> that is the target of the link.

[Bill Hesse, 2013/03/11 09:25:59]

Do you mean "transitively follow links, until a non-link is reached"?  That
would be a useful method.

[nweiz, 2013/03/11 20:26:32]

No, I meant just once, although a transitive version (or flag) might also be
useful.

+
+
+class LinkIOException implements Exception {
+  const LinkIOException([String this.message = "",
+                         String this.path = "",
+                         OSError this.osError = null]);
+  String toString() {
+    StringBuffer sb = new StringBuffer();
+    sb.write("LinkIOException");
+    if (!message.isEmpty) {
+      sb.write(": $message");
+      if (path != null) {
+        sb.write(", path = $path");
+      }
+      if (osError != null) {
+        sb.write(" ($osError)");
+      }
+    } else if (osError != null) {
+      sb.write(": $osError");
+      if (path != null) {
+        sb.write(", path = $path");
+      }
+    }
+    return sb.toString();
+  }
+  final String message;
+  final String path;
+  final OSError osError;
+}