A string input stream wraps a basic input stream and supplies string data. This data can be read either as string chunks or as lines separated by line termination character sequences.

abstract class StringInputStream {
  /**
   * Decodes a binary input stream into characters using the specified
   * encoding.
   */
  factory StringInputStream(InputStream input,
                            [Encoding encoding = Encoding.UTF_8]) {
    return new _StringInputStream(input, encoding);
  }

  /**
   * Reads up to [len] characters from the stream. if [len] is not
   * specified reads as many characters as is available from the
   * stream. If no data is available null will be returned.
   */
  String read([int len]);

  /**
   * Reads the next line from the stream. The line ending characters
   * will not be part of the returned string. If a full line is not
   * available null will be returned.
   */
  String readLine();

  /**
   * Returns the number of characters available for immediate
   * reading. Note that this includes all characters that will be in
   * the String returned from [read] this includes line breaking
   * characters. If [readLine] is used for reading one can observe
   * less characters being returned as the line breaking characters
   * are discarded.
   */
  int available();

  /**
   * 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.
   */
  Encoding get encoding;

  /**
   * Sets the handler that gets called when data is available. The two
   * handlers [onData] and [onLine] are mutually exclusive
   * and setting one will remove the other.
   */
  void set onData(void callback());

  /**
   * Sets the handler that gets called when a line is available. The
   * two handlers [onData] and [onLine] are mutually
   * exclusive and setting one will remove the other.
   */
  void set onLine(void callback());

  /**
   * Sets the handler that gets called when there will be no more data
   * available in the stream.
   */
  void set onClosed(void callback());

  /**
   * Sets the handler that gets called when the underlying
   * communication channel gets into some kind of error situation.
   */
  void set onError(void callback(e));
}