Move delete/deleteSync up to FileSystemEntity, with a shared documentation.

sdk/lib/io/file_system_entity.dart

Index: sdk/lib/io/file_system_entity.dart
diff --git a/sdk/lib/io/file_system_entity.dart b/sdk/lib/io/file_system_entity.dart
index ee088cc7ce7ee6a4dee91827802ac92cbeed2832..0887175e859713a681c37ffc5c57d96c66a0cc3a 100644
--- a/sdk/lib/io/file_system_entity.dart
+++ b/sdk/lib/io/file_system_entity.dart
@@ -168,77 +168,6 @@ FileStat: type $type
 abstract class FileSystemEntity {
   String get path;
 
-  external static _getType(String path, bool followLinks);
-  external static _identical(String path1, String path2);
-
-  static int _getTypeSync(String path, bool followLinks) {
-    var result = _getType(path, followLinks);
-    _throwIfError(result, 'Error getting type of FileSystemEntity');
-    return result;
-  }
-
-  static Future<int> _getTypeAsync(String path, bool followLinks) {
-    // Get a new file service port for each request.  We could also cache one.
-    var service = _FileUtils._newServicePort();
-    List request = new List(3);
-    request[0] = _TYPE_REQUEST;
-    request[1] = path;
-    request[2] = followLinks;
-    return service.call(request).then((response) {
-      if (_isErrorResponse(response)) {
-        throw _exceptionFromResponse(response, "Error getting type", path);
-      }
-      return response;
-    });
-  }
-
-  /**
-   * Synchronously checks whether two paths refer to the same object in the
-   * file system. Returns a [:Future<bool>:] that completes with the result.
-   *
-   * Comparing a link to its target returns false, as does comparing two links
-   * that point to the same target.  To check the target of a link, use
-   * Link.target explicitly to fetch it.  Directory links appearing
-   * inside a path are followed, though, to find the file system object.
-   *
-   * Completes the returned Future with an error if one of the paths points
-   * to an object that does not exist.
-   */
-  static Future<bool> identical(String path1, String path2) {
-    // Get a new file service port for each request.  We could also cache one.
-    var service = _FileUtils._newServicePort();
-    List request = new List(3);
-    request[0] = _IDENTICAL_REQUEST;
-    request[1] = path1;
-    request[2] = path2;
-    return service.call(request).then((response) {
-      if (_isErrorResponse(response)) {
-        throw _exceptionFromResponse(response,
-            "Error in FileSystemEntity.identical($path1, $path2)", "");
-      }
-      return response;
-    });
-  }
-
-
-  /**
-   * Synchronously checks whether two paths refer to the same object in the
-   * file system.
-   *
-   * Comparing a link to its target returns false, as does comparing two links
-   * that point to the same target.  To check the target of a link, use
-   * Link.target explicitly to fetch it.  Directory links appearing
-   * inside a path are followed, though, to find the file system object.
-   *
-   * Throws an error if one of the paths points to an object that does not
-   * exist.
-   */
-  static bool identicalSync(String path1, String path2) {
-    var result = _identical(path1, path2);
-    _throwIfError(result, 'Error in FileSystemEntity.identicalSync');
-    return result;
-  }
-
   /**
    * Checks whether the file system entity with this path exists. Returns
    * a [:Future<bool>:] that completes with the result.
@@ -316,6 +245,45 @@ abstract class FileSystemEntity {
    */
   FileStat statSync();
 
+  /**
+   * Deletes this [FileSystemEntity].
+   *
+   * If the [FileSystemEntity] is a directory, and if [recursive] is false,
+   * the directory must be empty. Otherwise, if [recursive] is true, the
+   * directory and all sub-directories and files in the directories are
+   * deleted. Links are not followed when deleting recursively. Only the link
+   * is deleted, not its target.
+   *
+   * If [recursive] is true, the [FileSystemEntity] is deleted even if the type
+   * of the [FileSystemEntity] doesn't match the content of the file system.
+   * This behavior allows [delete] to be used to unconditionally delete any file
+   * system object.
+   *
+   * Returns a [:Future<FileSystemEntity>:] that completes with this
+   * [FileSystemEntity] when the deletion is done. If the [FileSystemEntity]
+   * cannot be deleted, the future completes with an exception.
+   */
+  Future<FileSystemEntity> delete({recursive: false})
+      => _delete(recursive: recursive);
+
+  /**
+   * Synchronously deletes this [FileSystemEntity].
+   *
+   * If the [FileSystemEntity] is a directory, and if [recursive] is false,
+   * the directory must be empty. Otherwise, if [recursive] is true, the
+   * directory and all sub-directories and files in the directories are
+   * deleted. Links are not followed when deleting recursively. Only the link
+   * is deleted, not its target.
+   *
+   * If [recursive] is true, the [FileSystemEntity] is deleted even if the type
+   * of the [FileSystemEntity] doesn't match the content of the file system.
+   * This behavior allows [deleteSync] to be used to unconditionally delete any
+   * file system object.
+   *
+   * Throws an exception if the [FileSystemEntity] cannot be deleted.
+   */
+  void deleteSync({recursive: false})
+      => _deleteSync(recursive: recursive);
 
 
   /**
@@ -344,6 +312,56 @@ abstract class FileSystemEntity {
                                events,
                                recursive).stream;
 
+  Future<FileSystemEntity> _delete({recursive: false});
+  void _deleteSync({recursive: false});
+
+  /**
+   * Synchronously checks whether two paths refer to the same object in the
+   * file system. Returns a [:Future<bool>:] that completes with the result.
+   *
+   * Comparing a link to its target returns false, as does comparing two links
+   * that point to the same target.  To check the target of a link, use
+   * Link.target explicitly to fetch it.  Directory links appearing
+   * inside a path are followed, though, to find the file system object.
+   *
+   * Completes the returned Future with an error if one of the paths points
+   * to an object that does not exist.
+   */
+  static Future<bool> identical(String path1, String path2) {
+    // Get a new file service port for each request.  We could also cache one.
+    var service = _FileUtils._newServicePort();
+    List request = new List(3);
+    request[0] = _IDENTICAL_REQUEST;
+    request[1] = path1;
+    request[2] = path2;
+    return service.call(request).then((response) {
+      if (_isErrorResponse(response)) {
+        throw _exceptionFromResponse(response,
+            "Error in FileSystemEntity.identical($path1, $path2)", "");
+      }
+      return response;
+    });
+  }
+
+
+  /**
+   * Synchronously checks whether two paths refer to the same object in the
+   * file system.
+   *
+   * Comparing a link to its target returns false, as does comparing two links
+   * that point to the same target.  To check the target of a link, use
+   * Link.target explicitly to fetch it.  Directory links appearing
+   * inside a path are followed, though, to find the file system object.
+   *
+   * Throws an error if one of the paths points to an object that does not
+   * exist.
+   */
+  static bool identicalSync(String path1, String path2) {
+    var result = _identical(path1, path2);
+    _throwIfError(result, 'Error in FileSystemEntity.identicalSync');
+    return result;
+  }
+
   /**
    * Test if [watch] is supported on the current system.
    *
@@ -351,7 +369,6 @@ abstract class FileSystemEntity {
    */
   static bool get isWatchSupported => _FileSystemWatcher.isSupported;
 
-
   /**
    * Finds the type of file system object that a path points to. Returns
    * a [:Future<FileSystemEntityType>:] that completes with the result.
@@ -383,7 +400,6 @@ abstract class FileSystemEntity {
   static FileSystemEntityType typeSync(String path, {bool followLinks: true})
       => FileSystemEntityType._lookup(_getTypeSync(path, followLinks));
 
-
   /**
    * Checks if type(path, followLinks: false) returns
    * FileSystemEntityType.LINK.
@@ -424,6 +440,29 @@ abstract class FileSystemEntity {
   static bool isDirectorySync(String path) =>
       (_getTypeSync(path, true) == FileSystemEntityType.DIRECTORY._type);
 
+  external static _getType(String path, bool followLinks);
+  external static _identical(String path1, String path2);
+
+  static int _getTypeSync(String path, bool followLinks) {
+    var result = _getType(path, followLinks);
+    _throwIfError(result, 'Error getting type of FileSystemEntity');
+    return result;
+  }
+
+  static Future<int> _getTypeAsync(String path, bool followLinks) {
+    // Get a new file service port for each request.  We could also cache one.
+    var service = _FileUtils._newServicePort();
+    List request = new List(3);
+    request[0] = _TYPE_REQUEST;
+    request[1] = path;
+    request[2] = followLinks;
+    return service.call(request).then((response) {
+      if (_isErrorResponse(response)) {
+        throw _exceptionFromResponse(response, "Error getting type", path);
+      }
+      return response;
+    });
+  }
 
   static _throwIfError(Object result, String msg, [String path]) {
     if (result is OSError) {