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

sdk/lib/io/link.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.
+
+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. Returns a
+   * [:Future<bool>:] that completes when the answer is known.

[Søren Gjesse, 2013/03/08 10:22:31]

Maybe expand this comment to say that the existence if the link says nothing
about whether it points to something.

[Bill Hesse, 2013/03/08 12:04:26]

Done.

[Bill Hesse, 2013/03/08 12:04:26]

Done.

+   */
+  Future<bool> exists();
+
+  /**
+   * Synchronously check if the link exists.

[Søren Gjesse, 2013/03/08 10:22:31]

Ditto.

+   */
+  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
+   * will throw an exception on the future.

[Søren Gjesse, 2013/03/08 10:22:31]

"the function will throw an exception on the future" -> "the future will
complete with an error".

[Bill Hesse, 2013/03/08 12:04:26]

Done.

[Bill Hesse, 2013/03/08 12:04:26]

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.
+   */
+  Future<Link> create(String target);
+
+  /**
+   * Synchronously create the link. Calling [createSync] on an existing link
+   * will throw an exception.
+   *
+   * 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();

[Anders Johnsen, 2013/03/08 10:11:47]

String target

[Bill Hesse, 2013/03/08 12:04:26]

Done.

[Bill Hesse, 2013/03/08 12:04:26]

Done.

+
+   /**
+   * Updates a symbolic link to point to a different target.

[Søren Gjesse, 2013/03/08 10:22:31]

Maybe remove symbolic here, as in all other places it is just called link.

[Bill Hesse, 2013/03/08 12:04:26]

Done.

+   * Returns a [:Future<Link>:] that completes with
+   * the link when it has been created.  If the link does not exist,
+   * the function will throw an exception on the future.

[Søren Gjesse, 2013/03/08 10:22:31]

As above change to "the future will complete with an error".

[Bill Hesse, 2013/03/08 12:04:26]

Done.

+   *
+   * On the Windows platform, this will only work with directories, and the
+   * target directory must exist.
+   */
+  Future<Link> update(String target);
+
+  /**
+   * Synchronously update the link. Calling [updateSync] on a non-existing link
+   * will throw an exception.
+   *
+   * On the Windows platform, this will only work with directories, and the
+   * target directory must exist.
+   */
+  void updateSync();

[Anders Johnsen, 2013/03/08 10:11:47]

String target

+
+  /**
+   * 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 body of the link.

[Søren Gjesse, 2013/03/08 10:22:31]

body -> target

+   */
+  Future<Link> delete();
+
+  /**
+   * Synchronously delete the link. This does not delete, or otherwise
+   * affect, the body of the link.

[Søren Gjesse, 2013/03/08 10:22:31]

body -> target

+   */
+  void deleteSync();
+
+  /**
+   * Get a [Directory] object for the directory containing this
+   * link. Returns a [:Future<Directory>:] that completes with the
+   * directory.
+   */
+  Future<Directory> directory();

[Søren Gjesse, 2013/03/08 10:22:31]

Do we need directory() when we have target()?

[Bill Hesse, 2013/03/08 12:04:26]

Directory is just the parent directory of the link location, not the link
target.  Since link-relative paths are relative to this, I think it is important
to have.

+
+  /**
+   * Synchronously get a [Directory] object for the directory containing
+   * this link.
+   */
+  Directory directorySync();
+
+  /**
+   * Get the target of the link. Returns a [:Future<FileSystemEntity>:] that
+   * is either a File, Directory, or Link.

[Søren Gjesse, 2013/03/08 10:22:31]

What happens if the link is broken?

[Bill Hesse, 2013/03/08 12:04:26]

Returning a String instead.

+   */
+  Future<FileSystemEntity> target();

[Anders Johnsen, 2013/03/08 10:11:47]

Imo, this should be String

[Bill Hesse, 2013/03/08 12:04:26]

Done.

+
+  /**
+   * Synchronously get the target of the link. Returns a [FileSystemEntity] that
+   * is either a File, Directory, or Link.
+   */
+  int targetSync();

[Anders Johnsen, 2013/03/08 10:11:47]

FileSystemEntity or String

[Bill Hesse, 2013/03/08 12:04:26]

Done.

+
+  /**
+   * 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();
+
+  /**
+   * Get the path of the link.
+   */
+  String get path;

[Søren Gjesse, 2013/03/08 10:22:31]

Isn't path already on FileSystemEntity?

[Søren Gjesse, 2013/03/08 10:22:31]

Should we perhaps have

String get targetPath

or is link.target().path sufficient?

[Anders Johnsen, 2013/03/08 10:27:09]

Not if the link is broken. I'm all for having a helper function for getting the
entity, but the 'data' of a Link is a String, thus the reason for why I would
prefer 'target' to be String.

[Bill Hesse, 2013/03/08 12:04:26]

yES. Removed.

[Bill Hesse, 2013/03/08 12:04:26]

.target() now returns a string.

+}
+
+
+class _Link extends FileSystemEntity {
+  /**
+   * Create a Link object.
+   */
+  _Link(String path) {
+    throw new UnimplementedError("Link not implemented");
+  }
+
+  /**
+   * Create a Link object from a Path object.
+   */
+  _Link.fromPath(Path path) {
+    throw new UnimplementedError("Link not implemented");
+  }
+}
+
+
+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;
+}