Update of the input stream interface

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
- * on a given input.
+ * An input stream is used to read data sequentially from a data source.
  */
 interface InputStream {
   /**
-   * Reads data from the stream. Returns a system allocated buffer
-   * with up to [len] bytes. If no value is passed for [len] all
-   * available data will be returned. If no data is available null will
-   * be returned.
+   * Reads data from the stream. If no encoding is set fir the stream

[Mads Ager (google), 2011/11/30 10:44:07]

fir -> for

+   * it returns a system allocated buffer with up to [len] bytes. If
+   * encoding is set it returns a [String] with up to [len]
+   * characters. If no value is passed for [len] all available data
+   * will be returned. If no data is available null will be returned.
    */
-  List<int> read([int len]);
+  Object read([int len]);
+
+  /**
+   * Reads a line of characters from the stream. If a full line is not
+   * available the return value is null. If no encoding is set for the
+   * stream an exception is thrown.
+   */
+  String readLine();
 
   /**
    * Reads up to [len] bytes into buffer [buffer] starting at offset
    * [offset]. Returns the number of bytes actually read which might
    * be zero. If [offset] is not specified 0 is used. If [len] is not
-   * specified the length of [buffer] is used.
+   * specified the length of [buffer] is used. If an encoding is set
+   * for the stream an exception is thrown.
    */
   int readInto(List<int> buffer, [int offset, int len]);
 
   /**
+   * Reads data from the stream until the pattern [pattern] is
+   * encountered.
+   */
+  Object readUntil(Object pattern);

[Mads Ager (google), 2011/11/30 10:44:07]

Should pattern have type Pattern?

+
+  /**
+   * Pipe the data from this input stream directly to the
+   * [destination] [OutputStream]. After the input stream has been
+   * connected to an output stream data cannot be read from it
+   * anymore. When there is no more data in the input stream [close]
+   * will be called on the connected output stream.
+   */
+  void pipe(OutputStream destination);
+
+  /**
    * Returns the number of bytes available for immediate reading.

[Mads Ager (google), 2011/11/30 10:44:07]

Hmm, bytes or characters depending on the encoding?

    */
   int available();
 
   /**
+   * Sets the encoding used by the stream for turning bytes into
+   * characters. If encoding is set then calling the [read] method
+   * will return a [String] instead of a [List] of bytes. Currently
+   * the encodings "UTF-8", "ISO-8859-1" and "ASCII" are supported.

[Mads Ager (google), 2011/11/30 10:44:07]

Maybe there should always be an encoding? A default 'RAW' encoding that means
that you just want to read the bytes?

+   */
+  void set encoding(String encoding);
+  String get encoding();
+
+  /**
+   * Sets the minimum number of bytes required to trigger a the

[Mads Ager (google), 2011/11/30 10:44:07]

Again, is this bytes or characters depending on the encoding or is it just
bytes?

+   * [dataHandler] ...
+   */
+  void set chunkSize(int chunkSize);
+  int get chunkSize();
+
+  /**
+   * Sets the data pattern to expect before triggering the
+   * [dataHandler] ...
+   */
+  void set dataPattern(Object pattern);
+  get dataPattern();
+
+  /**
    * Returns whether the stream is closed. There will be no more data
    * to read.
    */
   bool get closed();
 
   /**
    * Sets the handler that gets called when data is available.
    */
   void set dataHandler(void callback());
-
-  /**
-   * Sets the handler that gets called when there will be no more data
-   * available in the stream.
-   */
-  void set closeHandler(void callback());
-
-  /**
-   * Sets the handler that gets called when the underlying
-   * communication channel gets into some kind of error situation.
-   */
-  void set errorHandler(void callback());
-}
-
-
-interface StringInputStream factory _StringInputStream {
-  /**
-   * Decodes a binary input stream into characters using the specified
-   * encoding.
-   */
-  StringInputStream(InputStream input, [String encoding]);
-
-  /**
-   * Reads as many characters as is available from the stream. If no data is
-   * available null will be returned.
-   */
-  String read();
-
-  /**
-   * Reads the next line from the stream. The line ending characters
-   * will not be part og the returned string. If a full line is not
-   * available null will be returned.
-   */
-  String readLine();
-
-  /**
-   * Returns whether the stream has been closed. There might still be
-   * more data to read.
-   */
-  bool get closed();
-
-  /**
-   * Returns the encoding used to decode the binary data into characters.
-   */
-  String get encoding();
-
-  /**
-   * Sets the handler that gets called when data is available.
-   */
-  void set dataHandler(void callback());
 
   /**
    * Sets the handler that gets called when there will be no more data
    * available in the stream.
    */
   void set closeHandler(void callback());
 
   /**
    * Sets the handler that gets called when the underlying
    * communication channel gets into some kind of error situation.
    */
   void set errorHandler(void callback());
 }
 
 
 class StreamException implements Exception {
   const StreamException([String this.message = ""]);
   String toString() => "StreamException: $message";
   final String message;
 }