OLD | NEW |
| (Empty) |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | |
2 // for details. All rights reserved. Use of this source code is governed by a | |
3 // BSD-style license that can be found in the LICENSE file. | |
4 | |
5 part of dart.io; | |
6 | |
7 /** | |
8 * A reference to a directory (or _folder_) on the file system. | |
9 * | |
10 * A Directory instance is an object holding a [path] on which operations can | |
11 * be performed. The path to the directory can be [absolute] or [relative]. | |
12 * You can get the parent directory using the getter [parent], | |
13 * a property inherited from [FileSystemEntity]. | |
14 * | |
15 * In addition to being used as an instance to access the file system, | |
16 * Directory has a number of static properties, such as [systemTemp], | |
17 * which gets the system's temporary directory, and the getter and setter | |
18 * [current], which you can use to access or change the current directory. | |
19 * | |
20 * Create a new Directory object with a pathname to access the specified | |
21 * directory on the file system from your program. | |
22 * | |
23 * var myDir = new Directory('myDir'); | |
24 * | |
25 * Most methods in this class occur in synchronous and asynchronous pairs, | |
26 * for example, [create] and [createSync]. | |
27 * Unless you have a specific reason for using the synchronous version | |
28 * of a method, prefer the asynchronous version to avoid blocking your program. | |
29 * | |
30 * ## Create a directory | |
31 * | |
32 * The following code sample creates a directory using the [create] method. | |
33 * By setting the `recursive` parameter to true, you can create the | |
34 * named directory and all its necessary parent directories, | |
35 * if they do not already exist. | |
36 * | |
37 * import 'dart:io'; | |
38 * | |
39 * void main() { | |
40 * // Creates dir/ and dir/subdir/. | |
41 * new Directory('dir/subdir').create(recursive: true) | |
42 * // The created directory is returned as a Future. | |
43 * .then((Directory directory) { | |
44 * print(directory.path); | |
45 * }); | |
46 * } | |
47 * | |
48 * ## List a directory | |
49 * | |
50 * Use the [list] or [listSync] methods to get the files and directories | |
51 * contained by a directory. | |
52 * Set `recursive` to true to recursively list all subdirectories. | |
53 * Set `followLinks` to true to follow symbolic links. | |
54 * The list method returns a [Stream] that provides FileSystemEntity | |
55 * objects. Use the listen callback function to process each object | |
56 * as it become available. | |
57 * | |
58 * import 'dart:io'; | |
59 * | |
60 * void main() { | |
61 * // Get the system temp directory. | |
62 * var systemTempDir = Directory.systemTemp; | |
63 * | |
64 * // List directory contents, recursing into sub-directories, | |
65 * // but not following symbolic links. | |
66 * systemTempDir.list(recursive: true, followLinks: false) | |
67 * .listen((FileSystemEntity entity) { | |
68 * print(entity.path); | |
69 * }); | |
70 * } | |
71 * | |
72 * ## The use of Futures | |
73 * | |
74 * I/O operations can block a program for some period of time while it waits for | |
75 * the operation to complete. To avoid this, all | |
76 * methods involving I/O have an asynchronous variant which returns a [Future]. | |
77 * This future completes when the I/O operation finishes. While the I/O | |
78 * operation is in progress, the Dart program is not blocked, | |
79 * and can perform other operations. | |
80 * | |
81 * For example, | |
82 * the [exists] method, which determines whether the directory exists, | |
83 * returns a boolean value using a Future. | |
84 * Use `then` to register a callback function, which is called when | |
85 * the value is ready. | |
86 * | |
87 * import 'dart:io'; | |
88 * | |
89 * main() { | |
90 * final myDir = new Directory('dir'); | |
91 * myDir.exists().then((isThere) { | |
92 * isThere ? print('exists') : print('non-existent'); | |
93 * }); | |
94 * } | |
95 * | |
96 * | |
97 * In addition to exists, the [stat], [rename], and | |
98 * other methods, return Futures. | |
99 * | |
100 * ## Other resources | |
101 * | |
102 * * [Dart by Example](https://www.dartlang.org/dart-by-example/#files-directori
es-and-symlinks) | |
103 * provides additional task-oriented code samples that show how to use | |
104 * various API from the Directory class and the related [File] class. | |
105 * | |
106 * * [I/O for Command-Line | |
107 * Apps](https://www.dartlang.org/docs/dart-up-and-running/ch03.html#dartio---
io-for-command-line-apps) | |
108 * a section from _A Tour of the Dart Libraries_ covers files and directories. | |
109 * | |
110 * * [Write Command-Line Apps](https://www.dartlang.org/docs/tutorials/cmdline/)
, | |
111 * a tutorial about writing command-line apps, includes information about | |
112 * files and directories. | |
113 */ | |
114 abstract class Directory implements FileSystemEntity { | |
115 /** | |
116 * Gets the path of this directory. | |
117 */ | |
118 final String path; | |
119 | |
120 /** | |
121 * Creates a [Directory] object. | |
122 * | |
123 * If [path] is a relative path, it will be interpreted relative to the | |
124 * current working directory (see [Directory.current]), when used. | |
125 * | |
126 * If [path] is an absolute path, it will be immune to changes to the | |
127 * current working directory. | |
128 */ | |
129 factory Directory(String path) => new _Directory(path); | |
130 | |
131 /** | |
132 * Create a Directory object from a URI. | |
133 * | |
134 * If [uri] cannot reference a directory this throws [UnsupportedError]. | |
135 */ | |
136 factory Directory.fromUri(Uri uri) => new Directory(uri.toFilePath()); | |
137 | |
138 /** | |
139 * Creates a directory object pointing to the current working | |
140 * directory. | |
141 */ | |
142 static Directory get current => _Directory.current; | |
143 | |
144 /** | |
145 * Returns a [Uri] representing the directory's location. | |
146 * | |
147 * The returned URI's scheme is always "file" if the entity's [path] is | |
148 * absolute, otherwise the scheme will be empty. | |
149 * The returned URI's path always ends in a slash ('/'). | |
150 */ | |
151 Uri get uri; | |
152 | |
153 /** | |
154 * Sets the current working directory of the Dart process including | |
155 * all running isolates. The new value set can be either a [Directory] | |
156 * or a [String]. | |
157 * | |
158 * The new value is passed to the OS's system call unchanged, so a | |
159 * relative path passed as the new working directory will be | |
160 * resolved by the OS. | |
161 * | |
162 * Note that setting the current working directory is a synchronous | |
163 * operation and that it changes the working directory of *all* | |
164 * isolates. | |
165 * | |
166 * Use this with care - especially when working with asynchronous | |
167 * operations and multiple isolates. Changing the working directory, | |
168 * while asynchronous operations are pending or when other isolates | |
169 * are working with the file system, can lead to unexpected results. | |
170 */ | |
171 static void set current(path) { | |
172 _Directory.current = path; | |
173 } | |
174 | |
175 /** | |
176 * Creates the directory with this name. | |
177 * | |
178 * If [recursive] is false, only the last directory in the path is | |
179 * created. If [recursive] is true, all non-existing path components | |
180 * are created. If the directory already exists nothing is done. | |
181 * | |
182 * Returns a [:Future<Directory>:] that completes with this | |
183 * directory once it has been created. If the directory cannot be | |
184 * created the future completes with an exception. | |
185 */ | |
186 Future<Directory> create({bool recursive: false}); | |
187 | |
188 /** | |
189 * Synchronously creates the directory with this name. | |
190 * | |
191 * If [recursive] is false, only the last directory in the path is | |
192 * created. If [recursive] is true, all non-existing path components | |
193 * are created. If the directory already exists nothing is done. | |
194 * | |
195 * If the directory cannot be created an exception is thrown. | |
196 */ | |
197 void createSync({bool recursive: false}); | |
198 | |
199 /** | |
200 * Gets the system temp directory. | |
201 * | |
202 * Gets the directory provided by the operating system for creating | |
203 * temporary files and directories in. | |
204 * The location of the system temp directory is platform-dependent, | |
205 * and may be set by an environment variable. | |
206 */ | |
207 static Directory get systemTemp => _Directory.systemTemp; | |
208 | |
209 /** | |
210 * Creates a temporary directory in this directory. Additional random | |
211 * characters are appended to [prefix] to produce a unique directory | |
212 * name. If [prefix] is missing or null, the empty string is used | |
213 * for [prefix]. | |
214 * | |
215 * Returns a [:Future<Directory>:] that completes with the newly | |
216 * created temporary directory. | |
217 */ | |
218 Future<Directory> createTemp([String prefix]); | |
219 | |
220 /** | |
221 * Synchronously creates a temporary directory in this directory. | |
222 * Additional random characters are appended to [prefix] to produce | |
223 * a unique directory name. If [prefix] is missing or null, the empty | |
224 * string is used for [prefix]. | |
225 * | |
226 * Returns the newly created temporary directory. | |
227 */ | |
228 Directory createTempSync([String prefix]); | |
229 | |
230 Future<String> resolveSymbolicLinks(); | |
231 | |
232 String resolveSymbolicLinksSync(); | |
233 | |
234 /** | |
235 * Renames this directory. Returns a [:Future<Directory>:] that completes | |
236 * with a [Directory] instance for the renamed directory. | |
237 * | |
238 * If newPath identifies an existing directory, that directory is | |
239 * replaced. If newPath identifies an existing file, the operation | |
240 * fails and the future completes with an exception. | |
241 */ | |
242 Future<Directory> rename(String newPath); | |
243 | |
244 /** | |
245 * Synchronously renames this directory. Returns a [Directory] | |
246 * instance for the renamed directory. | |
247 * | |
248 * If newPath identifies an existing directory, that directory is | |
249 * replaced. If newPath identifies an existing file the operation | |
250 * fails and an exception is thrown. | |
251 */ | |
252 Directory renameSync(String newPath); | |
253 | |
254 /** | |
255 * Returns a [Directory] instance whose path is the absolute path to [this]. | |
256 * | |
257 * The absolute path is computed by prefixing | |
258 * a relative path with the current working directory, and returning | |
259 * an absolute path unchanged. | |
260 */ | |
261 Directory get absolute; | |
262 | |
263 /** | |
264 * Lists the sub-directories and files of this [Directory]. | |
265 * Optionally recurses into sub-directories. | |
266 * | |
267 * If [followLinks] is false, then any symbolic links found | |
268 * are reported as [Link] objects, rather than as directories or files, | |
269 * and are not recursed into. | |
270 * | |
271 * If [followLinks] is true, then working links are reported as | |
272 * directories or files, depending on | |
273 * their type, and links to directories are recursed into. | |
274 * Broken links are reported as [Link] objects. | |
275 * If a symbolic link makes a loop in the file system, then a recursive | |
276 * listing will not follow a link twice in the | |
277 * same recursive descent, but will report it as a [Link] | |
278 * the second time it is seen. | |
279 * | |
280 * The result is a stream of [FileSystemEntity] objects | |
281 * for the directories, files, and links. | |
282 */ | |
283 Stream<FileSystemEntity> list({bool recursive: false, | |
284 bool followLinks: true}); | |
285 | |
286 /** | |
287 * Lists the sub-directories and files of this [Directory]. | |
288 * Optionally recurses into sub-directories. | |
289 * | |
290 * If [followLinks] is false, then any symbolic links found | |
291 * are reported as [Link] objects, rather than as directories or files, | |
292 * and are not recursed into. | |
293 * | |
294 * If [followLinks] is true, then working links are reported as | |
295 * directories or files, depending on | |
296 * their type, and links to directories are recursed into. | |
297 * Broken links are reported as [Link] objects. | |
298 * If a link makes a loop in the file system, then a recursive | |
299 * listing will not follow a link twice in the | |
300 * same recursive descent, but will report it as a [Link] | |
301 * the second time it is seen. | |
302 * | |
303 * Returns a [List] containing [FileSystemEntity] objects for the | |
304 * directories, files, and links. | |
305 */ | |
306 List<FileSystemEntity> listSync({bool recursive: false, | |
307 bool followLinks: true}); | |
308 | |
309 /** | |
310 * Returns a human readable string for this Directory instance. | |
311 */ | |
312 String toString(); | |
313 } | |
OLD | NEW |