Index: sdk/lib/io/directory.dart |
diff --git a/sdk/lib/io/directory.dart b/sdk/lib/io/directory.dart |
index c23307f01f98ecb66c95d9d929837e891c17b115..e977d2fe86b0cf2966c6f498b179f77e69ab72ba 100644 |
--- a/sdk/lib/io/directory.dart |
+++ b/sdk/lib/io/directory.dart |
@@ -6,6 +6,110 @@ 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/contents/ch03.html#ch03-dartio---file-and-socket-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 extends FileSystemEntity { |
/** |