unfork DDC's copy of most SDK libraries

pkg/dev_compiler/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();
-}