OLD | NEW |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 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 | 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. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 /** | 5 /** |
6 * [Directory] objects are used for working with directories. | 6 * [Directory] objects are used for working with directories. |
7 */ | 7 */ |
8 interface Directory default _Directory { | 8 interface Directory default _Directory { |
9 /** | 9 /** |
10 * Creates a directory object. The path is either a full path or | 10 * Creates a directory object. The path is either a full path or |
11 * relative to the directory in which the Dart VM was | 11 * relative to the directory in which the Dart VM was |
12 * started. | 12 * started. |
13 */ | 13 */ |
14 Directory(String path); | 14 Directory(String path); |
15 | 15 |
16 /** | 16 /** |
17 * Creates a directory object pointing to the current working | 17 * Creates a directory object pointing to the current working |
18 * directory. | 18 * directory. |
19 */ | 19 */ |
20 Directory.current(); | 20 Directory.current(); |
21 | 21 |
22 /** | 22 /** |
23 * Check whether a directory with this name already exists. If the | 23 * Check whether a directory with this name already exists. Returns |
24 * operation completes successfully the callback is called with the | 24 * a [:Future<bool>:] that completes with the result. |
25 * result. Otherwise [onError] is called. | |
26 */ | 25 */ |
27 void exists(void callback(bool exists)); | 26 Future<bool> exists(); |
28 | 27 |
29 /** | 28 /** |
30 * Synchronously check whether a directory with this name already exists. | 29 * Synchronously check whether a directory with this name already exists. |
31 */ | 30 */ |
32 bool existsSync(); | 31 bool existsSync(); |
33 | 32 |
34 /** | 33 /** |
35 * Creates the directory with this name if it does not exist. If | 34 * Creates the directory with this name if it does not |
36 * the directory is successfully created the callback is | 35 * exist. Returns a [:Future<Directory>:] that completes with this |
37 * called. Otherwise [onError] is called. | 36 * directory once it has been created. |
38 */ | 37 */ |
39 void create(void callback()); | 38 Future<Directory> create(); |
40 | 39 |
41 /** | 40 /** |
42 * Synchronously creates the directory with this name if it does not exist. | 41 * Synchronously creates the directory with this name if it does not exist. |
43 * Throws an exception if the directory already exists. | 42 * Throws an exception if the directory already exists. |
44 */ | 43 */ |
45 void createSync(); | 44 void createSync(); |
46 | 45 |
47 /** | 46 /** |
48 * Creates a temporary directory with a name based on the current | 47 * Creates a temporary directory with a name based on the current |
49 * path. This name and path is used as a template, and additional | 48 * path. This name and path is used as a template, and additional |
50 * characters are appended to it by the call to make a unique | 49 * characters are appended to it by the call to make a unique |
51 * directory name. If the path is the empty string, a default | 50 * directory name. If the path is the empty string, a default |
52 * system temp directory and name are used for the template. | 51 * system temp directory and name are used for the template. |
53 * | 52 * |
54 * The path is modified to be the path of the new directory. After | 53 * Returns a [:Future<Directory>:] that completes with the newly |
55 * the new directory is created, and the path modified, the callback | 54 * created temporary directory. |
56 * will be called. The error handler is called if the temporary | |
57 * directory cannot be created. | |
58 */ | 55 */ |
59 void createTemp(void callback()); | 56 Future<Directory> createTemp(); |
60 | 57 |
61 /** | 58 /** |
62 * Synchronously creates a temporary directory with a name based on the | 59 * Synchronously creates a temporary directory with a name based on the |
63 * current path. This name and path is used as a template, and additional | 60 * current path. This name and path is used as a template, and additional |
64 * characters are appended to it by the call to make a unique directory name. | 61 * characters are appended to it by the call to make a unique directory name. |
65 * If the path is the empty string, a default system temp directory and name | 62 * If the path is the empty string, a default system temp directory and name |
66 * are used for the template. | 63 * are used for the template. Returns the newly created temporary directory. |
67 * The path is modified to be the path of the new directory. | |
68 */ | 64 */ |
69 void createTempSync(); | 65 Directory createTempSync(); |
70 | 66 |
71 /** | 67 /** |
72 * Deletes the directory with this name. The directory must be | 68 * Deletes the directory with this name. The directory must be |
73 * empty. If the operation completes successfully the callback is | 69 * empty. Returns a [:Future<Directory>:] that completes with |
74 * called. Otherwise [onError] is called. | 70 * this directory when the deletion is done. |
75 */ | 71 */ |
76 void delete(void callback()); | 72 Future<Directory> delete(); |
77 | |
78 /** | |
79 * Deletes this directory and all sub-directories and files in the | |
80 * directories. If the operation completes successfully the callback | |
81 * is called. Otherwise [onError] is called. | |
82 */ | |
83 void deleteRecursively(void callback()); | |
84 | 73 |
85 /** | 74 /** |
86 * Synchronously deletes the directory with this name. The directory | 75 * Synchronously deletes the directory with this name. The directory |
87 * must be empty. Throws an exception if the directory cannot be | 76 * must be empty. Throws an exception if the directory cannot be |
88 * deleted. | 77 * deleted. |
89 */ | 78 */ |
90 void deleteSync(); | 79 void deleteSync(); |
91 | 80 |
92 /** | 81 /** |
| 82 * Deletes this directory and all sub-directories and files in the |
| 83 * directories. Returns a [:Future<Directory>:] that completes with |
| 84 * this directory when the deletion is done. |
| 85 */ |
| 86 Future<Directory> deleteRecursively(); |
| 87 |
| 88 /** |
93 * Synchronously deletes this directory and all sub-directories and | 89 * Synchronously deletes this directory and all sub-directories and |
94 * files in the directories. Throws an exception if the directory | 90 * files in the directories. Throws an exception if the directory |
95 * cannot be deleted. | 91 * cannot be deleted. |
96 */ | 92 */ |
97 void deleteRecursivelySync(); | 93 void deleteRecursivelySync(); |
98 | 94 |
99 /** | 95 /** |
100 * List the sub-directories and files of this | 96 * List the sub-directories and files of this |
101 * [Directory]. Optionally recurse into sub-directories. For each | 97 * [Directory]. Optionally recurse into sub-directories. Returns a |
102 * file and directory, the file or directory handler is called. When | 98 * [DirectoryLister] object representing the active listing |
103 * all directories have been listed the done handler is called. If | 99 * operation. Handlers for files and directories should be |
104 * the listing operation is recursive, the error handler is called | 100 * registered on this DirectoryLister object. |
105 * if a subdirectory cannot be opened for listing. | |
106 */ | 101 */ |
107 // TODO(ager): Should we change this to return an event emitting | 102 DirectoryLister list([bool recursive]); |
108 // DirectoryLister object. Alternatively, pass in one callback that | |
109 // gets called with an indication of whether what it is called with | |
110 // is a file, a directory or an indication that the listing is over. | |
111 void list([bool recursive]); | |
112 | |
113 /** | |
114 * Sets the directory handler that is called for all directories | |
115 * during listing operations. The directory handler is called with | |
116 * the full path of the directory. | |
117 */ | |
118 void set onDir(void onDir(String dir)); | |
119 | |
120 /** | |
121 * Sets the handler that is called for all files during listing | |
122 * operations. The file handler is called with the full path of the | |
123 * file. | |
124 */ | |
125 void set onFile(void onFile(String file)); | |
126 | |
127 /** | |
128 * Set the handler that is called when a directory listing is | |
129 * done. The handler is called with an indication of whether or not | |
130 * the listing operation completed. | |
131 */ | |
132 void set onDone(void onDone(bool completed)); | |
133 | |
134 /** | |
135 * Sets the handler that is called if there is an error while listing | |
136 * or creating directories. | |
137 */ | |
138 void set onError(void onError(e)); | |
139 | 103 |
140 /** | 104 /** |
141 * Gets the path of this directory. | 105 * Gets the path of this directory. |
142 */ | 106 */ |
143 final String path; | 107 final String path; |
144 } | 108 } |
145 | 109 |
146 | 110 |
| 111 /** |
| 112 * A [DirectoryLister] represents an actively running listing operation. |
| 113 * |
| 114 * For each file and directory, the file or directory handler is |
| 115 * called. When all directories have been listed the done handler is |
| 116 * called. If the listing operation is recursive, the error handler is |
| 117 * called if a subdirectory cannot be opened for listing. |
| 118 */ |
| 119 interface DirectoryLister default _DirectoryLister { |
| 120 /** |
| 121 * Sets the directory handler that is called for all directories |
| 122 * during listing. The directory handler is called with the full |
| 123 * path of the directory. |
| 124 */ |
| 125 void set onDir(void onDir(String dir)); |
| 126 |
| 127 /** |
| 128 * Sets the handler that is called for all files during listing. The |
| 129 * file handler is called with the full path of the file. |
| 130 */ |
| 131 void set onFile(void onFile(String file)); |
| 132 |
| 133 /** |
| 134 * Set the handler that is called when a listing is done. The |
| 135 * handler is called with an indication of whether or not the |
| 136 * listing operation completed. |
| 137 */ |
| 138 void set onDone(void onDone(bool completed)); |
| 139 |
| 140 /** |
| 141 * Sets the handler that is called if there is an error while |
| 142 * listing directories. |
| 143 */ |
| 144 void set onError(void onError(e)); |
| 145 } |
| 146 |
| 147 |
147 class DirectoryIOException implements Exception { | 148 class DirectoryIOException implements Exception { |
148 const DirectoryIOException([String this.message = "", | 149 const DirectoryIOException([String this.message = "", |
149 String this.path = "", | 150 String this.path = "", |
150 OSError this.osError = null]); | 151 OSError this.osError = null]); |
151 String toString() { | 152 String toString() { |
152 StringBuffer sb = new StringBuffer(); | 153 StringBuffer sb = new StringBuffer(); |
153 sb.add("DirectoryIOException"); | 154 sb.add("DirectoryIOException"); |
154 if (!message.isEmpty()) { | 155 if (!message.isEmpty()) { |
155 sb.add(": $message"); | 156 sb.add(": $message"); |
156 if (path != null) { | 157 if (path != null) { |
157 sb.add(", path = $path"); | 158 sb.add(", path = $path"); |
158 } | 159 } |
159 if (osError != null) { | 160 if (osError != null) { |
160 sb.add(" ($osError)"); | 161 sb.add(" ($osError)"); |
161 } | 162 } |
162 } else if (osError != null) { | 163 } else if (osError != null) { |
163 sb.add(": $osError"); | 164 sb.add(": $osError"); |
164 if (path != null) { | 165 if (path != null) { |
165 sb.add(", path = $path"); | 166 sb.add(", path = $path"); |
166 } | 167 } |
167 } | 168 } |
168 return sb.toString(); | 169 return sb.toString(); |
169 } | 170 } |
170 final String message; | 171 final String message; |
171 final String path; | 172 final String path; |
172 final OSError osError; | 173 final OSError osError; |
173 } | 174 } |
OLD | NEW |