New FileWriter proposal

Hi all; it's been a bit quiet on the FileWriter/Filesystem API topic
since December.  I hope everyone's now recovered from the holidays and
ready to try it again ;'>.

I've gone through the feedback that folks gave Robin's FileWriter API
[1], mashed it together with the general organization of Arun's
FileReader API [2], and come up with the following alternative
proposal.  I've just put it together here in plaintext form for now,
but if people like the general gist of it, I'll put up an
official-looking draft of it on w3.org and start rolling in feedback
there.

On the reading side, you create a FileReader in order to read from a Blob.  On
the writing side, you're handed a FileWriter, and then give it data in the form
of a Blob.  You can get a FileWriter through an HTML input element via user
interaction; it's a "Save As" just like the current "Load" <input type=file>
element.  This is a bit different from the read case, but I didn't see a need to
differentiate between a FileWriter and a WriteableFile, since any information on
the WriteableFile [name, path, size] would be a security problem.

Since this API is granting write access, not read/write access, in this case
you'll get a FileWriter that can only overwrite, not append, and that won't tell
you anything about the size [or even existence] of any file you may be
overwriting.  The position, seek, and truncate methods will act as if the file's
empty but for what you put there.  A FileWriter obtained from another interface,
such as the filesystem API I'm about to post, would allow for appends and
partial overwrites.

If I'm reading the spec correctly, there's no reason you couldn't reuse a
FileReader on a new File once your first use has completed.  FileWriter, on the
other hand, needs to have an affinity with a particular file on disk, so that
you can follow a seek() with a write() and it'll hold the state for you.

I've moved all the encoding stuff to a BlobBuilder [as Peter O. Ussuri and Jonas
Sicking suggested].

Here's a simple example comparing FileReader and FileWriter with files encoded
in UTF-16.

Read:

  var blob; // Gotten from the user.
  var reader = new FileReader();
  reader.readAsText(blob, "UTF-16");
  reader.onload = done;
  reader.onerror = error;

Write:

  var writer; // Gotten from the user.
  var bb = new BlobBuilder();
  bb.encoding = "UTF-16";
  bb.appendText("Lorem ipsum");
  writer.write(bb.getBlob());
  writer.onwrite = done;
  writer.onerror = error;

[NoInterfaceObject]
interface FileWriter {
  void abort();

  // states
  const unsigned short INIT = 0;
  const unsigned short WRITING = 1;
  const unsigned short DONE = 2;

  readonly attribute unsigned short readyState;

  readonly attribute FileError error;

  // event handler attributes
  attribute Function onwritestart;
  attribute Function onprogress;
  attribute Function onwrite;
  attribute Function onabort;
  attribute Function onerror;
  attribute Function onwriteend;

  readonly attribute position;
  readonly attribute length;

  void write(in Blob data);
  void seek(long long position); // Works as in Robin's proposal [1].
  void truncate(long long size);
};
FileWriter implements EventTarget;

[Constructor]
interface FileWriterSync {
  // Position, seek, and truncate are all clipped at length.
  // If you don't have read access to the file, length starts at 0.

  readonly attribute position;
  readonly attribute length;

  // raise FileException
  void write(in Blob data);
  void seek(long long position);
  void truncate(long long size);
};

[Constructor]
interface BlobBuilder {
  attribute DOMString endings; // As in Robin's proposal [1]
  attribute DOMString encoding;

  Blob getBlob();

  // appendText will use the current settings of endings and encoding
  void appendText(in DOMString text);
}

We may want a bunch of ways to add data to a BlobBuilder, but this satisfies the
immediate use case of writing text to a file.

[1] http://dev.w3.org/2009/dap/file-system/file-writer.html
[2] http://dev.w3.org/2006/webapi/FileAPI

Received on Friday, 29 January 2010 21:18:10 UTC