//==============================================================================
// tribble/io/ParserI.java
//------------------------------------------------------------------------------

package tribble.io;


// System imports

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


// Local imports

import tribble.io.LexerI;


/*******************************************************************************
* Generic parser interface.
*
* <p>
* This interface is used to implement any kind of parser which reads tokens
* from an input source stream (implementing the {@link LexerI} interface).
*
* @version	$Revision: 1.2 $ $Date: 2003/01/25 19:01:18 $
* @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	LexerI
* @see	ParseTreeI
* @see	SymbolTableI
* @see	ParserWithParseTreeI
* @see	ParserWithSymbolTableI
*/

public interface ParserI
{
// Identification

    /** Revision information. */
    static final String		REV =
        "@(#)tribble/io/ParserI.java $Revision: 1.2 $ $Date: 2003/01/25 19:01:18 $\n";


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

    /***************************************************************************
    * Establishes the lexical analyzer (lexer) input stream from which to read 
    * tokens during parsing.
    *
    * @param	in
    * The lexer input stream from which to read tokens.
    *
    * @since	1.1, 2001-04-16
    */

    public void setInput(LexerI in);


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

    public void setSourceName(String fname);


    /***************************************************************************
    * Closes the input stream.
    *
    * <p>
    * It is typically not necessary to invoke this method since the input
    * stream is usually closed automatically once parsing has completed, unless
    * it is necessary to close the input stream deliberately or prematurely.
    *
    * <p>
    * Note that this method does not throw any exceptions.
    *
    * @since	1.1, 2001-04-16
    */

    public void close();


    /***************************************************************************
    * Parses the input stream, performing syntactical analysis on the stream of
    * input tokens.
    *
    * @return
    * True if the parsing was successful, otherwise false.
    *
    * @throws	Exception
    * Thrown if an I/O error or parsing error occurs.
    *
    * @since	1.1, 2001-04-16
    */

    public boolean parse()
        throws Exception;
}

// End ParserI.java