package rebelsky.compiler.misc;

/**
 * A stream of characters.  Intended to serve as the input
 * to a tokenizer.  Might be implemented in a variety of ways
 * (e.g., taking input from a file or string).
 *
 * @author Samuel A. Rebelsky
 * @version 1.0 of October 2002
 */
public interface CharStream 
{
  // +-----------+----------------------------------------------------------
  // | Observers |
  // +-----------+

  /**
   * Determine if any more characters remain in the stream.
   *
   * Pre: (none).
   * Post: Returns true if characters remain and false o/w.
   */
  public boolean hasMore();

  /**
   * Look at the next character in the stream, but do not advance
   * the stream.
   *
   * Pre: The stream has a next character.
   * Post: Returns that character.  Does not affect the stream.
   *
   * @exception EndOfStream
   *   if no characters remain.
   * @exception Exception
   *   if an I/O error occurs.
   */
  public char peek() throws EndOfStream,Exception;

  // +-----------+----------------------------------------------------------
  // | Modifiers |
  // +-----------+

  /**
   * Get the next character from the stream and advance the stream.
   *
   * Pre: The stream has a next character.
   * Post: The stream has advanced beyond that character.
   *
   * @exception EndOfStream
   *   if no characters remain.
   * @exception Exception
   *   if an I/O error occurs.
   */
  public char next() throws EndOfStream,Exception;
} // interface CharStream