Update the streams interfaces

runtime/bin/input_stream.dart

 // Copyright (c) 2011, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 /**
  * Input is read from a given input stream. Such an input stream can
  * be an endpoint, e.g., a socket or a file, or another input stream.
  * Multiple input streams can be chained together to operate collaboratively

[rchandia, 2011/10/17 21:53:46]

This does not seem to allow chaining.

[Søren Gjesse, 2011/10/18 15:23:20]

Chaining is now use for StringInputStream.

  * on a given input.
  */
 interface InputStream {

[dcarlson, 2011/10/17 21:05:20]

Is there a reason to not have a way to just register for reads? (e.g. just
provide a callback to the InputStream for data events -- in this context, a
readHandler).

[Søren Gjesse, 2011/10/18 15:23:20]

I think it will make sense to have a way of registering a callback for when data
is available, as having the "low-level" read function which might return data
directly or make a callback when data is available can be confusing.

We could then move the readFully and readUntil to a separate class which can be
chained with the "simple" input stream. Having all these different functions
which can do callbacks also provides the problem that whatever function is
called last will get the callback.

   /**
-   * Reads [len] bytes into [buffer] buffer starting at [offset] offset.
-   * [callback] callback is invoked on completion unless it is null.
-   */
-  bool read(List<int> buffer, int offset, int len, void callback());
+   * Reads [len] bytes from the stream. When the bytes have been read the
+   * specified [callback] is called with the data.

[dcarlson, 2011/10/17 21:05:20]

Address EOF case.

[Søren Gjesse, 2011/10/18 15:23:20]

The current handling of EOF is that if [len] characters are not read the
callback is not called.

+  void readFully(int len, void callback(List<int> buffer));

[dcarlson, 2011/10/17 21:05:20]

Seems like this is the most common case -- perhaps this could be read, and read
-> something low-level.

[Søren Gjesse, 2011/10/18 15:23:20]

I have not tried to split the stream interface and moved the "specialized" reads
out of the simplest interface.

 
   /**
-   * Reads data from the stream into a buffer until a given [pattern] occurs and
-   * hands that buffer over as an input to the registered [callback].
-   * The callback is not invoked if a read error occurs.
+   * Reads data from the stream into a buffer until the specified [pattern]

[rchandia, 2011/10/17 21:53:46]

When I hear pattern I think RegEx'es which is not the case here, right?

[Søren Gjesse, 2011/10/18 15:23:20]

Currently it is simple string matching.

+   * occurs. When the pattern occours the specified [callback] is called with
+   * the data including the pattern. If the pattern is not found before
+   * [maxLength] bytes have been received the error handler will be called.

[rchandia, 2011/10/17 21:53:46]

How can errorHandler recover?

[Søren Gjesse, 2011/10/18 15:23:20]

Currently not known.

    */

[dcarlson, 2011/10/17 21:05:20]

Also: clarify what happens when you hit EOF prior to a match.

[Søren Gjesse, 2011/10/18 15:23:20]

Currently there will be not callback if EOF is hit before match.

-  void readUntil(List<int> pattern, void callback(List<int> buffer));
+  void readUntil(List<int> pattern,
+                 void callback(List<int> buffer),
+                 [int maxLength = -1]);
+
+  /**
+   * Reads as much data as is available from the stream. If no data is
+   * available null will be returned and the specified callback will
+   * be called when data becomes available.

[rchandia, 2011/10/17 21:53:46]

What happens when readFully() is followed by read()? In other words, is this the
pattern to follow to read less than what was specified to readFully (perhaps
after a timeout or a close())?

[Søren Gjesse, 2011/10/18 15:23:20]

It is a problem with these different functions on the interface as they don't
interact very well. When the interface structure is finalized we will figure out
how they can be combined.

+   */
+  List<int> read(void callback());

[dcarlson, 2011/10/17 21:05:20]

make callback optional named param?

[Søren Gjesse, 2011/10/18 15:23:20]

Removed the callback in favor the dataHandler.

+
+  /**
+   * Close the stream. This will normally also close the underlying

[rchandia, 2011/10/17 21:53:46]

Does this prevent further reads?

[Søren Gjesse, 2011/10/18 15:23:20]

We should make it possible to read all data after a stream is closed. Maybe
there should only be a close method on an OutputStream. An Input stream can only
receive a close event when it is somehow closed by the other end and all data
have been received.

+   * communication channel.
+   */
+  void close();
+
+  /**
+   * The close handler gets called when the underlying communication
+   * channel gets closed. Not all types of communication channels will
+   * emit close events.
+   */
+  void set closeHandler(void callback());
+
+  /**
+   * The error handler gets called when the underlying communication
+   * channel gets into some kind of error situation.
+   */
+  void set errorHandler(void callback(StreamError error));
 }
+
+interface StringInputStream extends InputStream {
+  /**
+   * Reads [len] characters from the stream. When the bytes have been read the
+   * specified [callback] is called with the data.
+  void readFully(int len, void callback(String data));
+
+  /**
+   * Reads string data from the stream into a until the specified [pattern]
+   * occurs. When the pattern occours the specified [callback] is called with
+   * the string data including the pattern. If the pattern is not found before
+   * [maxLength] characters have been received the error handler will be
+   * called.
+   */
+  void readUntil(String pattern,
+                 void callback(String data),
+                 [int maxLength = -1]);
+
+  /**
+   * Reads as many characters as is available from the stream. If no data is
+   * available null will be returned and the specified callback will
+   * be called when data becomes available.
+   */
+  String read(void callback());

[dcarlson, 2011/10/17 21:05:20]

optional param -- see above.

[Søren Gjesse, 2011/10/18 15:23:20]

Removed the callback instead.

+
+  /**
+   * Sets the encoding to be used when reading string data to the
+   * stream. The default encoding is UTF-8.
+   */
+  void set encoding(String encoding);

[dcarlson, 2011/10/17 21:05:20]

getter?

[Søren Gjesse, 2011/10/18 15:23:20]

Only getter now - removed setter.

+}