//==============================================================================
// tribble/io/LexerI.java
//------------------------------------------------------------------------------

package tribble.io;


// System imports

import java.io.IOException;
import java.io.Reader;

import java.lang.Exception;
import java.lang.String;


// Local imports

import tribble.io.CharInputStreamI;
import tribble.io.TokenI;


/*******************************************************************************
* Generic lexical analyzer (lexer) interface.
*
* <p>
* This interface is used to implement any kind of lexical analyzer (lexer),
* which reads characters from an input source stream (implementing the
* <tt>java.io.Reader</tt> class) and converts it into a stream of tokens
* (which implement the {@link TokenI} interface).  Such a lexer stream can be
* used to read the underlying source text for a parser, such as those
* implementing the {@link ParserI} interface.
*
* @version	$Revision: 1.4 $ $Date: 2003/02/26 04:40:02 $
* @since	2001-04-16
* @author
*	David R. Tribble,
*	<a href="mailto:david@tribble.com">david@tribble.com</a>.
*	<br>
*	<a href="../Copyright.html">Copyright</a>
*	©2001-2003 by David R. Tribble all rights reserved.
*	<br>
*	Permission is granted to freely use and distribute this source code
*	provided that the original copyright and authorship notices remain
*	intact.
*
* @see	CharInputStreamI
* @see	ParserI
* @see	TokenI
*/

public interface LexerI
{
// Identification

    /** Revision information. */
    static final String		REV =
        "@(#)tribble/io/LexerI.java $Revision: 1.4 $ $Date: 2003/02/26 04:40:02 $\n";


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Public methods

    /***************************************************************************
    * Establish the input stream from which to read tokens.
    *
    * @param	in
    * A character input stream from which to read tokens.
    *
    * @since	1.4, 2003-02-25
    */

    public void setInput(Reader in);


    /***************************************************************************
    * Establish the input source filename.
    *
    * @param	fname
    * The source filename.
    *
    * @since	1.1, 2001-05-31
    */

    public void setSourceName(String fname);


    /***************************************************************************
    * Close the input stream.
    *
    * @since	1.1, 2001-04-16
    */

    public void close()
        throws IOException;


    /***************************************************************************
    * Read the next token from the input stream.
    *
    * <p>
    * Either this method or {@link #getToken(TokenI)} may be used
    * interchangeably.
    *
    * @return
    * The next token read from the input stream, or null if there are no more
    * tokens (i.e., the end of file was reached).
    *
    * @throws	IOException
    * Thrown if an I/O error or parsing error occurs.
    *
    * @since	1.1, 2001-04-16
    */

    public TokenI getToken()
        throws IOException;


    /***************************************************************************
    * Read the next token from the lexer input stream.
    *
    * <p>
    * Either this method or {@link #getToken()} may be used interchangeably.
    * This method might be more efficient, since a new token object does not
    * need to be allocated on each call.
    *
    * @param	tok
    * The token object which is filled in with the next token read from the
    * input stream.
    *
    * @return
    * True if a token was successfully read from the input stream, otherwise
    * false.
    *
    * @throws	IOException
    * Thrown if an I/O error or parsing error occurs.
    *
    * @since	1.1, 2001-04-16
    */

    public boolean getToken(TokenI tok)
        throws IOException;
}

// End LexerI.java