//==============================================================================
// tribble/io/TokenI.java
//------------------------------------------------------------------------------

package tribble.io;


// System imports

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


// Local imports

// (None)


/*******************************************************************************
* Generic lexical token interface.
*
* <p>
* This interface is used to implement any kind of lexical token object, which
* is constructed by some form of lexical analyzer (lexer) such as any that
* implements the {@link LexerI} interface.  A token object represents a single
* lexical entity read from an input source text stream.  A lexer provides a
* stream of tokens read from such an input stream, which can then be used by a
* syntactical parser (such as any that implements the {@link ParserI}
* interface) for parsing sequences of source tokens into a symbol table or
* parse tree.
*
* <p>
* A token object has the following attributes:
*
* <dl>
*  <dd>
*   <dl>
*    <p>
*    <dt> text
*    <dd>
*     The textual contents of the token, which is typically the characters it is
*     composed of as it occurs in the source text stream.
*
*    <p>
*    <dt> type code
*    <dd>
*     A code used to indicate what kind of token it is.
*
*    <p>
*    <dt> line number
*    <dd>
*     The source line number, corresponding to the physical text line that the
*     token was read from.
*
*    <p>
*    <dt> column number
*    <dd>
*     The source column number, corresponding to the physical text column that
*     the token was read from.  This can be either the column number at which
*     the token starts or ends.
*
*    <p>
*    <dt> filename
*    <dd>
*     The source filename, corresponding to the name of the physical file or
*     stream that the token was read from.
*   </dl>
*  </dd>
* </dl>
*
* @version	$Revision: 1.3 $ $Date: 2003/02/23 03:09:58 $
* @since	2001-04-22
* @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	TokenAdapter
* @see	LexerI
* @see	ParserI
*/

public interface TokenI
{
// Identification

    /** Revision information. */
    static final String		REV =
        "@(#)tribble/io/TokenI.java $Revision: 1.3 $ $Date: 2003/02/23 03:09:58 $\n";


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Public constants

    // (None)


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

    /***************************************************************************
    * Establish the textual contents of this token.
    *
    * @param	text
    * The string containing the textual contents for this token.
    *
    * @since	1.1, 2001-04-22
    */

    public void setText(String text);


    /***************************************************************************
    * Retrieve the textual contents of this token.
    *
    * @return
    * A string containing the textual contents for this token.
    *
    * @since	1.1, 2001-04-22
    */

    public String getText();


    /***************************************************************************
    * Establish the token type code of this token.
    *
    * @param	type
    * The token type code for this token.
    *
    * @since	1.1, 2001-04-22
    */

    public void setType(int type);


    /***************************************************************************
    * Retrieve the type code of this token.
    *
    * @return
    * The type code for this token.
    *
    * @since	1.1, 2001-04-22
    */

    public int getType();


    /***************************************************************************
    * Establish the source line number number of this token.
    *
    * @param	lineNo
    * The source line number for this token.
    *
    * @since	1.3, 2003-02-22
    */

    public void setLineNumber(int lineNo);


    /***************************************************************************
    * Retrieve the source line number of this token.
    *
    * @return
    * The source line number for this token.
    *
    * @since	1.3, 2003-02-22
    */

    public int getLineNumber();


    /***************************************************************************
    * Establish the source column number of this token.
    *
    * @param	colNo
    * The source column number for this token.
    *
    * @since	1.3, 2003-02-22
    */

    public void setColumnNumber(int colNo);


    /***************************************************************************
    * Retrieve the source column number of this token.
    *
    * @return
    * The source column number for this token.
    *
    * @since	1.3, 2003-02-22
    */

    public int getColumnNumber();


    /***************************************************************************
    * Establishe the source filename of this token.
    *
    * @param	fname
    * The source filename for this token.
    *
    * @since	1.1, 2001-04-22
    */

    public void setFileName(String fname);


    /***************************************************************************
    * Retrieve the source filename of this token.
    *
    * @return
    * The source filename for this token.
    *
    * @since	1.1, 2001-04-22
    */

    public String getFileName();
}

// End TokenI.java