need higher level read/write apis in dart:io for scripting

[jmesserly]

RandomAccessFile is a nice low-level building block, but it'd be really great to have some convenience methods.

For example .NET has APIs like[1]:

class File {
  static FileStream Open(String path, [FileMode mode]);
  static String ReadAllText(String path, [Encoding encoding]);
  static String[] ReadAllLines(String path, [Encoding encoding]);
  static byte[] ReadAllBytes(String path);
  // ... and various equivalents for writing, and lots more ...
}

Usage is very simple:
  String theData = File.ReadAllText('path/to/data.txt');

Python[2], Ruby[3] also have very simple ways to do IO:
  # Python
  f = open('path/to/data.txt', 'r')
  lines = f.readlines()
  f.close()

  # Ruby
  IO.foreach('path/to/data.txt') { |line| puts line }

[1] http://msdn.microsoft.com/en-us/library/3z2ck8eh.aspx
[2] http://docs.python.org/tutorial/inputoutput.html
[3] http://ruby-doc.org/core-1.9.3/IO.html#method-c-foreach

[jmesserly]

Also RandomAccessFile has writeStringSync but not readStringSync

[madsager]

I agree, we need to provide shortcuts for reading an entire file as a string. Thanks for filing the bug report.

---

cc @sgjesse.
cc @whesse.
Removed Type-Defect label.
Added Type-Enhancement, Accepted labels.

[madsager]

Removed Area-Library label.
Added Area-IO label.

[madsager]

Added Started label.

[madsager]

Landed File.{readAsBytes, readAsText, readAsLines}. Example usage:

String text = new File('myfile.txt').readAsTextSync('UTF-8');

var f = new File('myfile.txt');
f.readAsText('UTF-8');
f.readAsTextHandler = (String text) {
  ...
};

  /**
   * Read the entire file contents as a list of bytes. When the
   * operation completes the [readAsBytesHandler] is called.
   * The [errorHandler] is called if the operation fails.
   */
  void readAsBytes();

  /**
   * Synchronously read the entire file contents as a list of bytes.
   */
  List<int> readAsBytesSync();

  /**
   * Read the entire file contents as text using the give [encoding]
   * ('UTF-8', 'ISO-8859-1', 'ASCII'). By default the encoding is
   * 'UTF-8'.
   *
   * When the operation completes the [readAsTextHandler] is called
   * with the resulting string. The [errorHandler] is called if the
   * operation fails.
   */
  void readAsText([String encoding]);

  /**
   * Synchronously read the entire file contents as text using the
   * give encoding. By default the
   * encoding is 'UTF-8'.
   */
  String readAsTextSync([String encoding]);

  /**
   * Read the entire file contents as lines of text using the give
   * encoding. By default the
   * encoding is 'UTF-8'.
   *
   * When the operation completes the [readAsLinesHandler] is called
   * with the resulting string. The [errorHandler] is called if the
   * operation fails.
   */
  void readAsLines();

  /**
   * Synchronously read the entire file contents as lines of text
   * using the give encoding. By
   * default the encoding is 'UTF-8'.
   */
  List<String> readAsLinesSync([String encoding]);

---

Added Fixed label.

[DartBot]

This comment was originally written by ama...@gmail.com

---

Why readAsBytes, readAsText and readAsLuines does not return promises?

[madsager]

None of the APIs in dart:io do. You can easily build that on top (this code is not tested):

class FutureFile {
  var _name;
  FutureFile(this._name);

  Future<List<int>> readAsBytes() {
    var completer = new Completer();
    var f = new File(_name);
    f.readAsBytes();
    f.readAsBytesHandler = (bytes) {
      completer.complete(bytes);
    };
    return completer.future;
  }
}

[DartBot]

This comment was originally written by amatia...@gmail.com

---

I supposed "higher level" mean I haven't to do things like that.

I don't like it because when I hear "higher level" I thought I could read a file with a line:

new File(path).readAsBytes().then((data) => ... );

With that implementation I need at least three lines.

var f = new File(path);
f.readAllBytes();
f.readAsBytesHandler = () => ... ;

[DartBot]

This comment was originally written by amatias...@gmail.com

---

That means I can't do this inside a arrow-function, compare

div.on.click.add(() =>
  new File(path).readAsBytes().then((data) => parse(data));

div.on.click.add(() {
  var f = new File(path)
  f.readAsBytes()
  f.readAsByteshandler = (data) => parse(data);
}

[sethladd]

Why doesn't File use Future?

[madsager]

To keep the dart:io interfaces consistent. We are using an evented model because we need repeatedly firing data events for the streaming APIs. In order to have a consistent API we are using events and 'handlers' for everything. This is a fairly low-level API on which we can built other abstractions later.

[DartBot]

This comment was originally written by amatiasq...@gmail.com

---

I asked for a high-level library to not be forced to build abstractions everywhere I use it. If I have to build a abstraction for this I dont need this abstraction from low-level.

Why the high-level API has to be consistent with low-level? If we ask for a high-level it's because low-level API isn't high-level enought.

[DartBot]

This comment was originally written by @seaneagan

---

@ager see my comment in issue #1786 for why this is an undesirable form of consistency. If anything, the consistency should be between dart:io and the APIs provided for this exact purpose in dart:core (Future and possibly Event (see issue #1873)).

[kevmoo]

Removed Area-IO label.
Added Area-Library, Library-IO labels.