import java.io.IOException;

/**
 * An interface for a generic, table-driven lexical analyzer.  This analyzer
 * presents a sequential view of the token stream.  It supports hasNext() and
 * next() methods, much like {@link java.util.Iterator}, but it does not
 * actually extend Iterator because it specializes {@link #next()} to return
 * {@link Token} objects.  All classes implementing this interface should
 * provide a constructor that accepts a {@link java.io.Reader}.
 *
 * @author Terran Lane
 * @version 1.0
 */

public interface Lexer {

  /**
   * Returns <code>true</code> iff there is still another token on the input
   * stream.  This may require reading from the underlying stream, so
   * <code>IOException</code>s or <code>IllegalCharException</code>s are
   * possible.
   *
   * @return <code>true</code> if there is at least one token remaining on
   * the input stream; otherwise <code>false</code>.
   * @exception IOException If an error occurs on the underlying input stream
   * @exception IllegalCharException If a character outside the legal range
   * is encountered.
   */
  public boolean hasNext() throws IOException, IllegalCharException;

  /**
   * Retrieve and return the next token from either the pushback buffer (if
   * it is non-empty) ir the input stream (if it is not at end-of-file).
   *
   * @return Most recent token.
   * @exception IOException If a problem is encountered with the underlying
   * input stream
   * @exception IllegalCharException If a character outside the legal range
   * (7-bit ASCII, for this lexer) is encountered
   */
  public Token next() throws IOException, IllegalCharException;

  /**
   * This method provides a way to push at least one token back onto the
   * token stream.  It may optionally support multi-token push back as well.
   * Later calls to {@link #next()} will return any tokens pushed back (in
   * LIFO order) before any new tokens from the underlying data stream.
   *
   * @param t Token to push back onto the stream.
   * @return Number of tokens available in the pushBack buffer after
   * insertion of this Token.
   */
  public int pushBack(Token t);
}