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

sdk/lib/io/file_system_entity.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;
 
 class FileSystemEntityType {
   static const FILE = const FileSystemEntityType._internal(0);
   static const DIRECTORY = const FileSystemEntityType._internal(1);
   static const LINK = const FileSystemEntityType._internal(2);
@@ skipping 150 matching lines @@
  *
  * [FileSystemEntity] objects are returned from directory listing
  * operations. To determine if a FileSystemEntity is a [File] or a
  * [Directory], perform a type check:
  *
  *     if (entity is File) (entity as File).readAsStringSync();
  */
 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.
    *
    * Since FileSystemEntity is abstract, every FileSystemEntity object
    * is actually an instance of one of the subclasses [File],
    * [Directory], and [Link].  Calling [exists] on an instance of one
    * of these subclasses checks whether the object exists in the file
    * system object exists and is of the correct type (file, directory,
    * or link).  To check whether a path points to an object on the
@@ skipping 57 matching lines @@
    * [path] of this [FileSystemEntity].
    * Identical to [:FileStat.statSync(this.path):].
    *
    * Returns a [FileStat] object containing the data returned by stat().
    *
    * If the call fails, returns a [FileStat] object with .type set to
    * FileSystemEntityType.NOT_FOUND and the other fields invalid.
    */
   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);
 
 
   /**
    * Start watch the [FileSystemEntity] for changes.
    *
    * The implementation uses platform-depending event-based APIs for receiving
    * file-system notifixations, thus behvaiour depends on the platform.
    *
    *   * `Windows`: Uses `ReadDirectoryChangesW`. The implementation supports
    *     only watching dirctories but supports recursive watching.
    *   * `Linux`: Uses `inotify`. The implementation supports watching both
    *     files and dirctories, but doesn't support recursive watching.
    *   * `Mac OS`: Uses `FSEvents`. The implementation supports watching both
    *     files and dirctories, and also recursive watching. Note that FSEvents
    *     always use recursion internally, so when disabled, some events are
    *     ignored.
    *
    * The system will start listen for events once the returned [Stream] is
    * being listened to, not when the call to [watch] is issued. Note that the
    * returned [Stream] is endless. To stop the [Stream], simply cancel the
    * subscription.
    */
   Stream<FileSystemEvent> watch({int events: FileSystemEvent.ALL,
                                  bool recursive: false})
      => new _FileSystemWatcher(_trimTrailingPathSeparators(path),
                                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.
    *
    * Mac OS 10.6 and below is not supported.
    */
   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.
    *
    * [FileSystemEntityType] has the constant instances FILE, DIRECTORY,
    * LINK, and NOT_FOUND.  [type] will return LINK only if the optional
    * named argument [followLinks] is false, and [path] points to a link.
    * If the path does not point to a file system object, or any other error
    * occurs in looking up the path, NOT_FOUND is returned.  The only
    * error or exception that may be put on the returned future is ArgumentError,
@@ skipping 11 matching lines @@
    * LINK, and NOT_FOUND.  [type] will return LINK only if the optional
    * named argument [followLinks] is false, and [path] points to a link.
    * If the path does not point to a file system object, or any other error
    * occurs in looking up the path, NOT_FOUND is returned.  The only
    * error or exception that may be thrown is ArgumentError,
    * caused by passing the wrong type of arguments to the function.
    */
   static FileSystemEntityType typeSync(String path, {bool followLinks: true})
       => FileSystemEntityType._lookup(_getTypeSync(path, followLinks));
 
-
   /**
    * Checks if type(path, followLinks: false) returns
    * FileSystemEntityType.LINK.
    */
   static Future<bool> isLink(String path) => _getTypeAsync(path, false)
       .then((type) => (type == FileSystemEntityType.LINK._type));
 
   /**
    * Checks if type(path) returns FileSystemEntityType.FILE.
    */
@@ skipping 20 matching lines @@
   static bool isFileSync(String path) =>
       (_getTypeSync(path, true) == FileSystemEntityType.FILE._type);
 
   /**
    * Synchronously checks if typeSync(path) returns
    * FileSystemEntityType.DIRECTORY.
    */
   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) {
       throw new FileException(msg, path, result);
     } else if (result is ArgumentError) {
       throw result;
     }
   }
 
   static String _trimTrailingPathSeparators(String path) {
@@ skipping 104 matching lines @@
   }
 }
 
 
 abstract class _FileSystemWatcher {
   external factory _FileSystemWatcher(String path, int events, bool recursive);
   external static bool get isSupported;
 
   Stream<FileSystemEvent> get stream;
 }