Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(535)

Side by Side Diff: runtime/bin/file.dart

Issue 10392023: Change dart:io to use Future for one-shot operations. (Closed) Base URL: https://dart.googlecode.com/svn/branches/bleeding_edge/dart
Patch Set: Minor cleanup Created 8 years, 7 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch | Annotate | Revision Log
OLDNEW
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
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
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 }
OLDNEW

Powered by Google App Engine
This is Rietveld 408576698