Migrate dart2js stubs for dart:io

tool/input_sdk/lib/io/directory.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.
+
+part of dart.io;
+
+/**
+ * A reference to a directory (or _folder_) on the file system.
+ *
+ * A Directory instance is an object holding a [path] on which operations can
+ * be performed. The path to the directory can be [absolute] or [relative].
+ * You can get the parent directory using the getter [parent],
+ * a property inherited from [FileSystemEntity].
+ *
+ * In addition to being used as an instance to access the file system,
+ * Directory has a number of static properties, such as [systemTemp],
+ * which gets the system's temporary directory, and the getter and setter
+ * [current], which you can use to access or change the current directory.
+ *
+ * Create a new Directory object with a pathname to access the specified
+ * directory on the file system from your program.
+ *
+ *     var myDir = new Directory('myDir');
+ *
+ * Most methods in this class occur in synchronous and asynchronous pairs,
+ * for example, [create] and [createSync].
+ * Unless you have a specific reason for using the synchronous version
+ * of a method, prefer the asynchronous version to avoid blocking your program.
+ *
+ * ## Create a directory
+ *
+ * The following code sample creates a directory using the [create] method.
+ * By setting the `recursive` parameter to true, you can create the
+ * named directory and all its necessary parent directories,
+ * if they do not already exist.
+ *
+ *     import 'dart:io';
+ *
+ *     void main() {
+ *       // Creates dir/ and dir/subdir/.
+ *       new Directory('dir/subdir').create(recursive: true)
+ *         // The created directory is returned as a Future.
+ *         .then((Directory directory) {
+ *           print(directory.path);
+ *       });
+ *     }
+ *
+ * ## List a directory
+ *
+ * Use the [list] or [listSync] methods to get the files and directories
+ * contained by a directory.
+ * Set `recursive` to true to recursively list all subdirectories.
+ * Set `followLinks` to true to follow symbolic links.
+ * The list method returns a [Stream] that provides FileSystemEntity
+ * objects. Use the listen callback function to process each object
+ * as it become available.
+ *
+ *     import 'dart:io';
+ *
+ *     void main() {
+ *       // Get the system temp directory.
+ *       var systemTempDir = Directory.systemTemp;
+ *
+ *       // List directory contents, recursing into sub-directories,
+ *       // but not following symbolic links.
+ *       systemTempDir.list(recursive: true, followLinks: false)
+ *         .listen((FileSystemEntity entity) {
+ *           print(entity.path);
+ *         });
+ *     }
+ *
+ * ## The use of Futures
+ *
+ * I/O operations can block a program for some period of time while it waits for
+ * the operation to complete. To avoid this, all
+ * methods involving I/O have an asynchronous variant which returns a [Future].
+ * This future completes when the I/O operation finishes. While the I/O
+ * operation is in progress, the Dart program is not blocked,
+ * and can perform other operations.
+ *
+ * For example,
+ * the [exists] method, which determines whether the directory exists,
+ * returns a boolean value using a Future.
+ * Use `then` to register a callback function, which is called when
+ * the value is ready.
+ *
+ *     import 'dart:io';
+ *
+ *     main() {
+ *       final myDir = new Directory('dir');
+ *       myDir.exists().then((isThere) {
+ *         isThere ? print('exists') : print('non-existent');
+ *       });
+ *     }
+ *
+ *
+ * In addition to exists, the [stat], [rename], and
+ * other methods, return Futures.
+ *
+ * ## Other resources
+ *
+ * * [Dart by Example](https://www.dartlang.org/dart-by-example/#files-directories-and-symlinks)
+ *   provides additional task-oriented code samples that show how to use
+ *   various API from the Directory class and the related [File] class.
+ *
+ * * [I/O for Command-Line
+ *   Apps](https://www.dartlang.org/docs/dart-up-and-running/ch03.html#dartio---io-for-command-line-apps)
+ *   a section from _A Tour of the Dart Libraries_ covers files and directories.
+ *
+ * * [Write Command-Line Apps](https://www.dartlang.org/docs/tutorials/cmdline/),
+ *   a tutorial about writing command-line apps, includes information about
+ *   files and directories.
+ */
+abstract class Directory implements FileSystemEntity {
+  /**
+   * Gets the path of this directory.
+   */
+  final String path;
+
+  /**
+   * Creates a [Directory] object.
+   *
+   * If [path] is a relative path, it will be interpreted relative to the
+   * current working directory (see [Directory.current]), when used.
+   *
+   * If [path] is an absolute path, it will be immune to changes to the
+   * current working directory.
+   */
+  factory Directory(String path) => new _Directory(path);
+
+  /**
+   * Create a Directory object from a URI.
+   *
+   * If [uri] cannot reference a directory this throws [UnsupportedError].
+   */
+  factory Directory.fromUri(Uri uri) => new Directory(uri.toFilePath());
+
+  /**
+   * Creates a directory object pointing to the current working
+   * directory.
+   */
+  static Directory get current => _Directory.current;
+
+  /**
+   * Returns a [Uri] representing the directory's location.
+   *
+   * The returned URI's scheme is always "file" if the entity's [path] is
+   * absolute, otherwise the scheme will be empty.
+   * The returned URI's path always ends in a slash ('/').
+   */
+  Uri get uri;
+
+  /**
+   * Sets the current working directory of the Dart process including
+   * all running isolates. The new value set can be either a [Directory]
+   * or a [String].
+   *
+   * The new value is passed to the OS's system call unchanged, so a
+   * relative path passed as the new working directory will be
+   * resolved by the OS.
+   *
+   * Note that setting the current working directory is a synchronous
+   * operation and that it changes the working directory of *all*
+   * isolates.
+   *
+   * Use this with care - especially when working with asynchronous
+   * operations and multiple isolates. Changing the working directory,
+   * while asynchronous operations are pending or when other isolates
+   * are working with the file system, can lead to unexpected results.
+   */
+  static void set current(path) {
+    _Directory.current = path;
+  }
+
+  /**
+   * Creates the directory with this name.
+   *
+   * If [recursive] is false, only the last directory in the path is
+   * created. If [recursive] is true, all non-existing path components
+   * are created. If the directory already exists nothing is done.
+   *
+   * Returns a [:Future<Directory>:] that completes with this
+   * directory once it has been created. If the directory cannot be
+   * created the future completes with an exception.
+   */
+  Future<Directory> create({bool recursive: false});
+
+  /**
+   * Synchronously creates the directory with this name.
+   *
+   * If [recursive] is false, only the last directory in the path is
+   * created. If [recursive] is true, all non-existing path components
+   * are created. If the directory already exists nothing is done.
+   *
+   * If the directory cannot be created an exception is thrown.
+   */
+  void createSync({bool recursive: false});
+
+  /**
+   * Gets the system temp directory.
+   *
+   * Gets the directory provided by the operating system for creating
+   * temporary files and directories in.
+   * The location of the system temp directory is platform-dependent,
+   * and may be set by an environment variable.
+   */
+  static Directory get systemTemp => _Directory.systemTemp;
+
+  /**
+   * Creates a temporary directory in this directory. Additional random
+   * characters are appended to [prefix] to produce a unique directory
+   * name. If [prefix] is missing or null, the empty string is used
+   * for [prefix].
+   *
+   * Returns a [:Future<Directory>:] that completes with the newly
+   * created temporary directory.
+   */
+  Future<Directory> createTemp([String prefix]);
+
+  /**
+   * Synchronously creates a temporary directory in this directory.
+   * Additional random characters are appended to [prefix] to produce
+   * a unique directory name. If [prefix] is missing or null, the empty
+   * string is used for [prefix].
+   *
+   * Returns the newly created temporary directory.
+   */
+  Directory createTempSync([String prefix]);
+
+  Future<String> resolveSymbolicLinks();
+
+  String resolveSymbolicLinksSync();
+
+  /**
+   * Renames this directory. Returns a [:Future<Directory>:] that completes
+   * with a [Directory] instance for the renamed directory.
+   *
+   * If newPath identifies an existing directory, that directory is
+   * replaced. If newPath identifies an existing file, the operation
+   * fails and the future completes with an exception.
+   */
+  Future<Directory> rename(String newPath);
+
+  /**
+   * Synchronously renames this directory. Returns a [Directory]
+   * instance for the renamed directory.
+   *
+   * If newPath identifies an existing directory, that directory is
+   * replaced. If newPath identifies an existing file the operation
+   * fails and an exception is thrown.
+   */
+  Directory renameSync(String newPath);
+
+  /**
+   * Returns a [Directory] instance whose path is the absolute path to [this].
+   *
+   * The absolute path is computed by prefixing
+   * a relative path with the current working directory, and returning
+   * an absolute path unchanged.
+   */
+  Directory get absolute;
+
+  /**
+   * Lists the sub-directories and files of this [Directory].
+   * Optionally recurses into sub-directories.
+   *
+   * If [followLinks] is false, then any symbolic links found
+   * are reported as [Link] objects, rather than as directories or files,
+   * and are not recursed into.
+   *
+   * If [followLinks] is true, then working links are reported as
+   * directories or files, depending on
+   * their type, and links to directories are recursed into.
+   * Broken links are reported as [Link] objects.
+   * If a symbolic link makes a loop in the file system, then a recursive
+   * listing will not follow a link twice in the
+   * same recursive descent, but will report it as a [Link]
+   * the second time it is seen.
+   *
+   * The result is a stream of [FileSystemEntity] objects
+   * for the directories, files, and links.
+   */
+  Stream<FileSystemEntity> list({bool recursive: false,
+                                 bool followLinks: true});
+
+  /**
+   * Lists the sub-directories and files of this [Directory].
+   * Optionally recurses into sub-directories.
+   *
+   * If [followLinks] is false, then any symbolic links found
+   * are reported as [Link] objects, rather than as directories or files,
+   * and are not recursed into.
+   *
+   * If [followLinks] is true, then working links are reported as
+   * directories or files, depending on
+   * their type, and links to directories are recursed into.
+   * Broken links are reported as [Link] objects.
+   * If a link makes a loop in the file system, then a recursive
+   * listing will not follow a link twice in the
+   * same recursive descent, but will report it as a [Link]
+   * the second time it is seen.
+   *
+   * Returns a [List] containing [FileSystemEntity] objects for the
+   * directories, files, and links.
+   */
+  List<FileSystemEntity> listSync({bool recursive: false,
+                                   bool followLinks: true});
+
+  /**
+   * Returns a human readable string for this Directory instance.
+   */
+  String toString();
+}