First round of changes to the file interface.

runtime/bin/file.dart

Index: runtime/bin/file.dart
diff --git a/runtime/bin/file.dart b/runtime/bin/file.dart
index ebffd2c6008bf1966b9f3a007468e71dc107fa58..ff7a11d611bdf671addd0ac6b72bc6cf27887981 100644
--- a/runtime/bin/file.dart
+++ b/runtime/bin/file.dart
@@ -3,60 +3,199 @@
 // BSD-style license that can be found in the LICENSE file.
 
 interface File factory _File {
-  // Open a file.
-  File(String name, bool writable);
+  /**
+   * Create a File object.
+   */
+  File(String name);
+
+  /**
+   * Check if the file exists. The [existsHandler] is called with the
+   * result when the operation completes.
+   */
+  void exists();
+
+  /**
+   * Synchronously check if the file exists.
+   */
+  bool existsSync();
+
+  /**
+   * Create the file. The [createHandler] is called when the file has
+   * been created. The errorHandler is called if the file cannot be
+   * created.
+   */
+  void create();
+
+  /**
+   * Synchronously create the file.
+   */
+  void createSync();
+
+  /**
+   * Open the file for random access operations. When the file is
+   * opened the openHandler is called. Opened files must be closed
+   * using the [close] method. By default writable is false.
+   */
+  void open([bool writable]);

[Søren Gjesse, 2011/10/27 13:07:50]

[bool writable] -> [bool writable = false]

[Mads Ager (google), 2011/10/27 13:21:46]

You can only supply the default when you implement it.

+
+  /**
+   * Synchronously open the file for random access operations. Opened
+   * files must be closed using the [close] method. By default
+   * writable is false.
+   */
+  void openSync([bool writable]);

[Søren Gjesse, 2011/10/27 13:07:50]

Ditto.

[Mads Ager (google), 2011/10/27 13:21:46]

Same, can only supply the default value when you implement it.

 
-  // Close the file.
+  /**
+   * Close the file. When the file is closed the closeHandler is
+   * called.
+   */
   void close();
 
-  // Synchronously read a single byte from the file.
-  // TODO(jrgfogh): Remove this call.
-  int readByte();
+  /**
+   * Synchronously close the file.
+   */
+  void closeSync();
 
-  // Synchronously write a single byte to the file.
-  // TODO(jrgfogh): Remove this call.
-  int writeByte(int value);
+  /**
+   * Read a byte from the file. When the byte has been read the
+   * [readByteHandler] is called with the value.
+   */
+  void readByte();
 
-  // Synchronously write a single string to the file.
-  // TODO(jrgfogh): Remove this call.
-  int writeString(String string);
+  /**
+   * Synchronously read a single byte from the file.
+   */
+  int readByteSync();
 
-  // Synchronously read a List<int> from the file.
-  // TODO(jrgfogh): Remove this call.
-  int readList(List<int> buffer, int offset, int bytes);
+  /**
+   * Read a List<int> from the file. When the list has been read the
+   * [readListHandler] is called with an integer indicating how much
+   * was read.
+   */
+  void readList(List<int> buffer, int offset, int bytes);
 
-  // Synchronously write a List<int> to the file.
-  // TODO(jrgfogh): Remove this call.
-  int writeList(List<int> buffer, int offset, int bytes);
+  /**
+   * Synchronously read a List<int> from the file. Returns the number
+   * of bytes read.
+   */
+  int readListSync(List<int> buffer, int offset, int bytes);
 
-  // The current position of the file handle.
-  int get position();
+  /**
+   * Write a single byte to the file. If the byte cannot be written
+   * the [errorHandler] is called. When all pending write operations
+   * have finished the [noPendingWriteHandler] is called.
+   */
+  void writeByte(int value);
 
-  // The length of the file.
-  int get length();
+  /**
+   * Synchronously write a single byte to the file. Returns true if
+   * the byte was successfully written and false otherwise.
+   */
+  bool writeByteSync(int value);
+
+  /**
+   * Write a List<int> to the file. If the list cannot be written the
+   * [errorHandler] is called. When all pending write operations have
+   * finished the [noPendingWriteHandler] is called.
+   */
+  void writeList(List<int> buffer, int offset, int bytes);
 
-  // Flush the contents of the file to disk.
-  void flush();
+  /**
+   * Synchronously write a List<int> to the file. If the list cannot be

[Søren Gjesse, 2011/10/27 13:07:50]

Replace "If the list..." with !Returns true if the list was successfully written
and false otherwise."

[Mads Ager (google), 2011/10/27 13:21:46]

Thanks! Done.

+   * written the [errorHandler] is called. When all pending write
+   * operations have finished the [noPendingWriteHandler] is called.
+   */
+  bool writeListSync(List<int> buffer, int offset, int bytes);
 
-  // Each file has an unique InputStream.
-  InputStream get inputStream();
+  /**
+   * Write a string to the file. If the string cannot be written the
+   * [errorHandler] is called. When all pending write operations have
+   * finished the [noPendingWriteHandler] is called.
+   */
+  void writeString(String string);

[Søren Gjesse, 2011/10/27 13:07:50]

Shouldn't this have an encoding?

[Mads Ager (google), 2011/10/27 13:21:46]

Yes, it should. I'll add a TODO and address it in a separate changelist.

 
-  // Each file has an unique OutputStream.
-  OutputStream get outputStream();
+  /**
+   * Synchronously write a single string to the file. Returns true if
+   * the string was successfully written and false otherwise.
+   */
+  bool writeStringSync(String string);

[Søren Gjesse, 2011/10/27 13:07:50]

Ditto.

[Mads Ager (google), 2011/10/27 13:21:46]

Yes, I'll add a TODO.

+
+  /**
+   * Get the current position of the file. When the operation
+   * completes the [positionHandler] is called with the position.
+   */
+  void position();
+
+  /**
+   * Synchronously get the current position of the file.
+   */
+  int positionSync();
+
+  /**
+   * Get the length of the file. When the operation completes the
+   * [lengthHandler] is called with the length.
+   */
+  void length();
+
+  /**
+   * Get the length of the file. When the operation completes the
+   * [lengthHandler] is called with the length.
+   */
+  int lengthSync();
+
+  /**
+   * Flush the contents of the file to disk. If there are no pending
+   * write operation after the flush operation completes, the
+   * [noPendingWriteHandler] is called.
+   */
+   void flush();
+
+  /**
+   * Synchronously flush the contents of the file to disk.
+   */
+  void flushSync();
+
+  /**
+   * Create a new independent input stream for the file. The file
+   * input stream must be closed when no longer used.
+   */
+  FileInputStream openInputStream();
+
+  /**
+   * Creates a new independent output stream for the file. The file
+   * output stream must be closed when no longer used.
+   */
+  FileOutputStream openOutputStream();
+
+  /**
+   * Get the name of the file.
+   */
+  String get name();
+
+  // Event handlers.
+  void set existsHandler(void handler(bool exists));
+  void set createHandler(void handler());
+  void set openHandler(void handler());
+  void set closeHandler(void handler());
+  void set readByteHandler(void handler(int byte));
+  void set readListHandler(void handler(int read));
+  void set noPendingWriteHandler(void handler());
+  void set errorHandler(void handler(String error));
+}
+
+
+interface FileInputStream extends InputStream {
+  void close();
 }
 
 
-class FileUtil {
-  static bool fileExists(String name) native "File_Exists";
+interface FileOutputStream extends OutputStream {
+  void close();
 }
 
 
 class FileIOException implements Exception {
   const FileIOException([String this.message = ""]);
   String toString() => "FileIOException: $message";
-
-  /*
-   * Contains the exception message.
-   */
   final String message;
 }