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 /** | 6 /** |
7 * FileMode describes the modes in which a file can be opened. | 7 * FileMode describes the modes in which a file can be opened. |
8 */ | 8 */ |
9 class FileMode { | 9 class FileMode { |
10 static final READ = const FileMode._internal(0); | 10 static final READ = const FileMode._internal(0); |
(...skipping 11 matching lines...) Expand all Loading... |
22 * streams using [openInputStream] and [openOutputStream] or open the | 22 * streams using [openInputStream] and [openOutputStream] or open the |
23 * file for random access operations using [open]. | 23 * file for random access operations using [open]. |
24 */ | 24 */ |
25 interface File default _File { | 25 interface File default _File { |
26 /** | 26 /** |
27 * Create a File object. | 27 * Create a File object. |
28 */ | 28 */ |
29 File(String name); | 29 File(String name); |
30 | 30 |
31 /** | 31 /** |
32 * Check if the file exists. The callback is called with the result | 32 * Check if the file exists. Does not block and returns a |
33 * when the operation completes. The [onError] function registered | 33 * [:Future<bool>:]. |
34 * on the file object is called if an error occurs. | |
35 */ | 34 */ |
36 void exists(void callback(bool exists)); | 35 Future<bool> exists(); |
37 | 36 |
38 /** | 37 /** |
39 * Synchronously check if the file exists. | 38 * Synchronously check if the file exists. |
40 */ | 39 */ |
41 bool existsSync(); | 40 bool existsSync(); |
42 | 41 |
43 /** | 42 /** |
44 * Create the file. The callback is called when the file has been | 43 * Create the file. Returns a [:Future<File>:] that completes with |
45 * created. The [onError] function registered on the file object is | 44 * the file when it has been created. |
46 * called if the file cannot be created. Existing files are left | 45 * |
47 * untouched by create. Calling create on an existing file might | 46 * Existing files are left untouched by create. Calling create on an |
48 * fail if there are restrictive permissions on the file. | 47 * existing file might fail if there are restrictive permissions on |
| 48 * the file. |
49 */ | 49 */ |
50 void create(void callback()); | 50 Future<File> create(); |
51 | 51 |
52 /** | 52 /** |
53 * Synchronously create the file. Existing files are left untouched | 53 * Synchronously create the file. Existing files are left untouched |
54 * by create. Calling create on an existing file might fail if there | 54 * by create. Calling create on an existing file might fail if there |
55 * are restrictive permissions on the file. | 55 * are restrictive permissions on the file. |
56 */ | 56 */ |
57 void createSync(); | 57 void createSync(); |
58 | 58 |
59 /** | 59 /** |
60 * Delete the file. The callback is called when the file has been | 60 * Delete the file. Returns a [:Future<File>:] that completes with |
61 * successfully deleted. The [onError] function registered on the | 61 * the file when it has been deleted. |
62 * file object is called if the file cannot be deleted. | |
63 */ | 62 */ |
64 void delete(void callback()); | 63 Future<File> delete(); |
65 | 64 |
66 /** | 65 /** |
67 * Synchronously delete the file. | 66 * Synchronously delete the file. |
68 */ | 67 */ |
69 void deleteSync(); | 68 void deleteSync(); |
70 | 69 |
71 /** | 70 /** |
72 * Get a Directory object for the directory containing this | 71 * Get a Directory object for the directory containing this |
73 * file. When the operation completes the callback is called with | 72 * file. Returns a [:Future<Directory>:] that completes with the |
74 * the result. If the file does not exist the [onError] function | 73 * directory. |
75 * registered on the file object is called. | |
76 */ | 74 */ |
77 void directory(void callback(Directory dir)); | 75 Future<Directory> directory(); |
78 | 76 |
79 /** | 77 /** |
80 * Synchronously get a Directory object for the directory containing | 78 * Synchronously get a Directory object for the directory containing |
81 * this file. | 79 * this file. |
82 */ | 80 */ |
83 Directory directorySync(); | 81 Directory directorySync(); |
84 | 82 |
85 /** | 83 /** |
86 * Get the length of the file. When the operation completes the | 84 * Get the length of the file. Returns a [:Future<int>:] that |
87 * callback is called with the length. | 85 * completes with the length in bytes. |
88 */ | 86 */ |
89 void length(void callback(int length)); | 87 Future<int> length(); |
90 | 88 |
91 /** | 89 /** |
92 * Synchronously get the length of the file. | 90 * Synchronously get the length of the file. |
93 */ | 91 */ |
94 int lengthSync(); | 92 int lengthSync(); |
95 | 93 |
96 /** | 94 /** |
97 * Open the file for random access operations. When the file is | 95 * Open the file for random access operations. Returns a |
98 * opened the callback is called with the resulting | 96 * [:Future<RandomAccessFile>:] that completes with the opened |
99 * RandomAccessFile. RandomAccessFiles must be closed using the | 97 * random access file. RandomAccessFiles must be closed using the |
100 * [close] method. If the file cannot be opened [onError] is called. | 98 * [close] method. |
101 * | 99 * |
102 * Files can be opened in three modes: | 100 * Files can be opened in three modes: |
103 * | 101 * |
104 * FileMode.READ: open the file for reading. If the file does not | 102 * FileMode.READ: open the file for reading. If the file does not |
105 * exist [onError] is called. | 103 * exist [onError] is called. |
106 * | 104 * |
107 * FileMode.WRITE: open the file for both reading and writing and | 105 * FileMode.WRITE: open the file for both reading and writing and |
108 * truncate the file to length zero. If the file does not exist the | 106 * truncate the file to length zero. If the file does not exist the |
109 * file is created. | 107 * file is created. |
110 * | 108 * |
111 * FileMode.APPEND: same as FileMode.WRITE except that the file is | 109 * FileMode.APPEND: same as FileMode.WRITE except that the file is |
112 * not truncated. | 110 * not truncated. |
113 */ | 111 */ |
114 void open(FileMode mode, void callback(RandomAccessFile opened)); | 112 Future<RandomAccessFile> open(FileMode mode); |
115 | 113 |
116 /** | 114 /** |
117 * Synchronously open the file for random access operations. The | 115 * Synchronously open the file for random access operations. The |
118 * result is a RandomAccessFile on which random access operations | 116 * result is a RandomAccessFile on which random access operations |
119 * can be performed. Opened RandomAccessFiles must be closed using | 117 * can be performed. Opened RandomAccessFiles must be closed using |
120 * the [close] method. | 118 * the [close] method. |
121 * | 119 * |
122 * The default value for [mode] is [:FileMode.READ:]. | 120 * The default value for [mode] is [:FileMode.READ:]. |
123 * | 121 * |
124 * See [open] for information on the [mode] argument. | 122 * See [open] for information on the [mode] argument. |
125 */ | 123 */ |
126 RandomAccessFile openSync([FileMode mode]); | 124 RandomAccessFile openSync([FileMode mode]); |
127 | 125 |
128 /** | 126 /** |
129 * Get the canonical full path corresponding to the file name. The | 127 * Get the canonical full path corresponding to the file name. |
130 * callback is called with the result when the | 128 * Returns a [:Future<String>:] that completes with the path. |
131 * fullPath operation completes. If the operation fails the | |
132 * [onError] function registered on the file object is called. | |
133 */ | 129 */ |
134 void fullPath(void callback(String path)); | 130 Future<String> fullPath(); |
135 | 131 |
136 /** | 132 /** |
137 * Synchronously get the canonical full path corresponding to the file name. | 133 * Synchronously get the canonical full path corresponding to the file name. |
138 */ | 134 */ |
139 String fullPathSync(); | 135 String fullPathSync(); |
140 | 136 |
141 /** | 137 /** |
142 * Create a new independent input stream for the file. The file | 138 * Create a new independent input stream for the file. The file |
143 * input stream must be closed when no longer used to free up system | 139 * input stream must be closed when no longer used to free up system |
144 * resources. | 140 * resources. |
(...skipping 11 matching lines...) Expand all Loading... |
156 * file to length zero. | 152 * file to length zero. |
157 * | 153 * |
158 * FileMode.APPEND: create the stream and set the position to the end of | 154 * FileMode.APPEND: create the stream and set the position to the end of |
159 * the underlying file. | 155 * the underlying file. |
160 * | 156 * |
161 * By default the mode is FileMode.WRITE. | 157 * By default the mode is FileMode.WRITE. |
162 */ | 158 */ |
163 OutputStream openOutputStream([FileMode mode]); | 159 OutputStream openOutputStream([FileMode mode]); |
164 | 160 |
165 /** | 161 /** |
166 * Read the entire file contents as a list of bytes. When the | 162 * Read the entire file contents as a list of bytes. Returns a |
167 * operation completes the callback is called. The [onError] | 163 * [:Future<List<int>>:] that completes with the list of bytes that |
168 * function registered on the file object is called if the operation | 164 * is the contents of the file. |
169 * fails. | |
170 */ | 165 */ |
171 void readAsBytes(void callback(List<int> bytes)); | 166 Future<List<int>> readAsBytes(); |
172 | 167 |
173 /** | 168 /** |
174 * Synchronously read the entire file contents as a list of bytes. | 169 * Synchronously read the entire file contents as a list of bytes. |
175 */ | 170 */ |
176 List<int> readAsBytesSync(); | 171 List<int> readAsBytesSync(); |
177 | 172 |
178 /** | 173 /** |
179 * Read the entire file contents as text using the given | 174 * Read the entire file contents as text using the given |
180 * [encoding]. The default encoding is UTF-8 - [:Encoding.UTF_8:]. | 175 * [encoding]. The default encoding is UTF-8 - [:Encoding.UTF_8:]. |
181 * | 176 * |
182 * When the operation completes the callback is called. The | 177 * Returns a [:Future<String>:] that completes with the string once |
183 * [onError] function registered on the file object is called if the | 178 * the file contents has been read. |
184 * operation fails. | |
185 */ | 179 */ |
186 void readAsText(Encoding encoding, void callback(String text)); | 180 Future<String> readAsText(Encoding encoding); |
187 | 181 |
188 /** | 182 /** |
189 * Synchronously read the entire file contents as text using the | 183 * Synchronously read the entire file contents as text using the |
190 * given [encoding]. The default encoding is UTF-8 - [:Encoding.UTF_8:]. | 184 * given [encoding]. The default encoding is UTF-8 - [:Encoding.UTF_8:]. |
191 */ | 185 */ |
192 String readAsTextSync([Encoding encoding]); | 186 String readAsTextSync([Encoding encoding]); |
193 | 187 |
194 /** | 188 /** |
195 * Read the entire file contents as lines of text using the give | 189 * Read the entire file contents as lines of text using the give |
196 * [encoding]. The default encoding is UTF-8 - [:Encoding.UTF_8:]. | 190 * [encoding]. The default encoding is UTF-8 - [:Encoding.UTF_8:]. |
197 * | 191 * |
198 * When the operation completes the callback is called. The | 192 * Returns a [:Future<List<String>>:] that completes with the lines |
199 * [onError] function registered on the file object is called if the | 193 * once the file contents has been read. |
200 * operation fails. | |
201 */ | 194 */ |
202 void readAsLines(Encoding encoding, void callback(List<String> lines)); | 195 Future<List<String>> readAsLines(Encoding encoding); |
203 | 196 |
204 /** | 197 /** |
205 * Synchronously read the entire file contents as lines of text | 198 * Synchronously read the entire file contents as lines of text |
206 * using the given [encoding] The default encoding is UTF-8 - | 199 * using the given [encoding] The default encoding is UTF-8 - |
207 * [:Encoding.UTF_8:]. | 200 * [:Encoding.UTF_8:]. |
208 */ | 201 */ |
209 List<String> readAsLinesSync([Encoding encoding]); | 202 List<String> readAsLinesSync([Encoding encoding]); |
210 | 203 |
211 /** | 204 /** |
212 * Get the name of the file. | 205 * Get the name of the file. |
213 */ | 206 */ |
214 String get name(); | 207 String get name(); |
215 | |
216 /** | |
217 * Sets the handler that gets called when errors occur during | |
218 * operations on this file. | |
219 */ | |
220 void set onError(void handler(e)); | |
221 } | 208 } |
222 | 209 |
223 | 210 |
224 /** | 211 /** |
225 * [RandomAccessFile] provides random access to the data in a | 212 * [RandomAccessFile] provides random access to the data in a |
226 * file. [RandomAccessFile] objects are obtained by calling the | 213 * file. [RandomAccessFile] objects are obtained by calling the |
227 * [:open:] method on a [File] object. | 214 * [:open:] method on a [File] object. |
228 */ | 215 */ |
229 interface RandomAccessFile { | 216 interface RandomAccessFile { |
230 /** | 217 /** |
231 * Close the file. When the file is closed the callback is called. | 218 * Close the file. Returns a [:Future<RandomAccessFile>:] that |
| 219 * completes with this RandomAccessFile when it has been closed. |
232 */ | 220 */ |
233 void close(void callback()); | 221 Future<RandomAccessFile> close(); |
234 | 222 |
235 /** | 223 /** |
236 * Synchronously close the file. | 224 * Synchronously close the file. |
237 */ | 225 */ |
238 void closeSync(); | 226 void closeSync(); |
239 | 227 |
240 /** | 228 /** |
241 * Read a byte from the file. When the byte has been read the | 229 * Read a byte from the file. Returns a [:Future<int>:] that |
242 * callback is called with the value. If end of file has been | 230 * completes with the byte or -1 if end of file has been reached. |
243 * reached the value will be -1. | |
244 */ | 231 */ |
245 void readByte(void callback(int byte)); | 232 Future<int> readByte(); |
246 | 233 |
247 /** | 234 /** |
248 * Synchronously read a single byte from the file. If end of file | 235 * Synchronously read a single byte from the file. If end of file |
249 * has been reached -1 is returned. | 236 * has been reached -1 is returned. |
250 */ | 237 */ |
251 int readByteSync(); | 238 int readByteSync(); |
252 | 239 |
253 /** | 240 /** |
254 * Read a List<int> from the file. When the list has been read the | 241 * Read a List<int> from the file. Returns a [:Future<int>:] that |
255 * callback is called with an integer indicating how much was read. | 242 * completes with an indication of how much was read. |
256 */ | 243 */ |
257 void readList(List<int> buffer, int offset, int bytes, | 244 Future<int> readList(List<int> buffer, int offset, int bytes); |
258 void callback(int read)); | |
259 | 245 |
260 /** | 246 /** |
261 * Synchronously read a List<int> from the file. Returns the number | 247 * Synchronously read a List<int> from the file. Returns the number |
262 * of bytes read. | 248 * of bytes read. |
263 */ | 249 */ |
264 int readListSync(List<int> buffer, int offset, int bytes); | 250 int readListSync(List<int> buffer, int offset, int bytes); |
265 | 251 |
266 /** | 252 /** |
267 * Write a single byte to the file. If the byte cannot be written | 253 * Write a single byte to the file. Returns a |
268 * [onError] is called. When all pending write operations have | 254 * [:Future<RandomAccessFile>:] that completes with this |
269 * finished [onNoPendingWrites] is called. | 255 * RandomAccessFile when the write completes. |
270 */ | 256 */ |
271 void writeByte(int value); | 257 Future<RandomAccessFile> writeByte(int value); |
272 | 258 |
273 /** | 259 /** |
274 * Synchronously write a single byte to the file. Returns the | 260 * Synchronously write a single byte to the file. Returns the |
275 * number of bytes successfully written. | 261 * number of bytes successfully written. |
276 */ | 262 */ |
277 int writeByteSync(int value); | 263 int writeByteSync(int value); |
278 | 264 |
279 /** | 265 /** |
280 * Write a List<int> to the file. If the list cannot be written the | 266 * Write a List<int> to the file. Returns a |
281 * [onError] is called. When all pending write operations have | 267 * [:Future<RandomAccessFile>:] that completes with this |
282 * finished [onNoPendingWrites] is called. | 268 * RandomAccessFile when the write completes. |
283 */ | 269 */ |
284 void writeList(List<int> buffer, int offset, int bytes); | 270 Future<RandomAccessFile> writeList(List<int> buffer, int offset, int bytes); |
285 | 271 |
286 /** | 272 /** |
287 * Synchronously write a List<int> to the file. Returns the number | 273 * Synchronously write a List<int> to the file. Returns the number |
288 * of bytes successfully written. | 274 * of bytes successfully written. |
289 */ | 275 */ |
290 int writeListSync(List<int> buffer, int offset, int bytes); | 276 int writeListSync(List<int> buffer, int offset, int bytes); |
291 | 277 |
292 /** | 278 /** |
293 * Write a string to the file using the given [encoding]. If the | 279 * Write a string to the file using the given [encoding]. The |
294 * string cannot be written [onError] is called. The default | 280 * default encoding is UTF-8 - [:Encoding.UTF_8:]. Returns a |
295 * encoding is UTF-8 - [:Encoding.UTF_8:]. | 281 * [:Future<RandomAccessFile>:] that completes with this |
296 * | 282 * RandomAccessFile when the write completes. |
297 * When all pending write operations have finished | |
298 * [onNoPendingWrites] is called. | |
299 */ | 283 */ |
300 void writeString(String string, [Encoding encoding]); | 284 Future<RandomAccessFile> writeString(String string, [Encoding encoding]); |
301 | 285 |
302 /** | 286 /** |
303 * Synchronously write a single string to the file using the given | 287 * Synchronously write a single string to the file using the given |
304 * [encoding]. Returns the number of characters successfully | 288 * [encoding]. Returns the number of characters successfully |
305 * written. The default encoding is UTF-8 - [:Encoding.UTF_8:]. | 289 * written. The default encoding is UTF-8 - [:Encoding.UTF_8:]. |
306 */ | 290 */ |
307 int writeStringSync(String string, [Encoding encoding]); | 291 int writeStringSync(String string, [Encoding encoding]); |
308 | 292 |
309 /** | 293 /** |
310 * Get the current byte position in the file. When the operation | 294 * Get the current byte position in the file. Returns a |
311 * completes the callback is called with the position. | 295 * [:Future<int>:] that completes with the position. |
312 */ | 296 */ |
313 void position(void callback(int position)); | 297 Future<int> position(); |
314 | 298 |
315 /** | 299 /** |
316 * Synchronously get the current byte position in the file. | 300 * Synchronously get the current byte position in the file. |
317 */ | 301 */ |
318 int positionSync(); | 302 int positionSync(); |
319 | 303 |
320 /** | 304 /** |
321 * Set the byte position in the file. When the operation completes | 305 * Set the byte position in the file. Returns a |
322 * the callback is called. | 306 * [:Future<RandomAccessFile>:] that completes with this |
| 307 * RandomAccessFile when the position has been set. |
323 */ | 308 */ |
324 void setPosition(int position, void callback()); | 309 Future<RandomAccessFile> setPosition(int position); |
325 | 310 |
326 /** | 311 /** |
327 * Synchronously set the byte position in the file. | 312 * Synchronously set the byte position in the file. |
328 */ | 313 */ |
329 void setPositionSync(int position); | 314 void setPositionSync(int position); |
330 | 315 |
331 /** | 316 /** |
332 * Truncate (or extend) the file to [length] bytes. When the | 317 * Truncate (or extend) the file to [length] bytes. Returns a |
333 * operation completes successfully the callback is called. | 318 * [:Future<RandomAccessFile>:] that completes with this |
| 319 * RandomAccessFile when the truncation has been performed. |
334 */ | 320 */ |
335 void truncate(int length, void callback()); | 321 Future<RandomAccessFile> truncate(int length); |
336 | 322 |
337 /** | 323 /** |
338 * Synchronously truncate (or extend) the file to [length] bytes. | 324 * Synchronously truncate (or extend) the file to [length] bytes. |
339 */ | 325 */ |
340 void truncateSync(int length); | 326 void truncateSync(int length); |
341 | 327 |
342 /** | 328 /** |
343 * Get the length of the file. When the operation completes the | 329 * Get the length of the file. Returns a [:Future<int>:] that |
344 * callback is called with the length. | 330 * completes with the length in bytes. |
345 */ | 331 */ |
346 void length(void callback(int length)); | 332 Future<int> length(); |
347 | 333 |
348 /** | 334 /** |
349 * Synchronously get the length of the file. | 335 * Synchronously get the length of the file. |
350 */ | 336 */ |
351 int lengthSync(); | 337 int lengthSync(); |
352 | 338 |
353 /** | 339 /** |
354 * Flush the contents of the file to disk. The callback is | 340 * Flush the contents of the file to disk. Returns a |
355 * called when the flush operation completes. | 341 * [:Future<RandomAccessFile>:] that completes with this |
| 342 * RandomAccessFile when the flush operation completes. |
356 */ | 343 */ |
357 void flush(void callback()); | 344 Future<RandomAccessFile> flush(); |
358 | 345 |
359 /** | 346 /** |
360 * Synchronously flush the contents of the file to disk. | 347 * Synchronously flush the contents of the file to disk. |
361 */ | 348 */ |
362 void flushSync(); | 349 void flushSync(); |
363 | 350 |
364 /** | 351 /** |
365 * Get the name of the file. | 352 * Get the name of the file. |
366 */ | 353 */ |
367 String get name(); | 354 String get name(); |
368 | |
369 /** | |
370 * Sets the handler that gets called when there are no more write | |
371 * operations pending for this file. | |
372 */ | |
373 void set onNoPendingWrites(void handler()); | |
374 | |
375 /** | |
376 * Sets the handler that gets called when errors occur when | |
377 * operating on this file. | |
378 */ | |
379 void set onError(void handler(e)); | |
380 } | 355 } |
381 | 356 |
382 | 357 |
383 class FileIOException implements Exception { | 358 class FileIOException implements Exception { |
384 const FileIOException([String this.message = "", | 359 const FileIOException([String this.message = "", |
385 OSError this.osError = null]); | 360 OSError this.osError = null]); |
386 String toString() { | 361 String toString() { |
387 StringBuffer sb = new StringBuffer(); | 362 StringBuffer sb = new StringBuffer(); |
388 sb.add("FileIOException"); | 363 sb.add("FileIOException"); |
389 if (!message.isEmpty()) { | 364 if (!message.isEmpty()) { |
390 sb.add(": $message"); | 365 sb.add(": $message"); |
391 if (osError != null) { | 366 if (osError != null) { |
392 sb.add(" ($osError)"); | 367 sb.add(" ($osError)"); |
393 } | 368 } |
394 } else if (osError != null) { | 369 } else if (osError != null) { |
395 sb.add(": osError"); | 370 sb.add(": osError"); |
396 } | 371 } |
397 return sb.toString(); | 372 return sb.toString(); |
398 } | 373 } |
399 final String message; | 374 final String message; |
400 final OSError osError; | 375 final OSError osError; |
401 } | 376 } |
OLD | NEW |