CivlcToken.java

package edu.udel.cis.vsl.abc.token.IF;

import org.antlr.runtime.Token;

import edu.udel.cis.vsl.abc.front.c.preproc.CPreprocessor;

/**
 * <p>
 * A post-preprocessor token. Each token belongs to at most one token source. A
 * token source is essentially an abstraction for a sequence of tokens. The
 * token has some index (position) in this sequence, and there are methods to
 * get the index of this token, and to get the next element in the sequence.
 * </p>
 * 
 * <p>
 * A token also carries detailed information about its formation history. This
 * can be obtained by method {@link #getFormation()}, which returns a
 * {@link Formation}.
 * </p>
 * 
 * @author siegel
 * 
 */
public interface CivlcToken extends Token {

	public enum TokenVocabulary {
		/**
		 * <code>this</code> token is a CIVL-C one.
		 */
		CIVLC,
		/**
		 * <code>this</code> token is a FORTRAN one.
		 */
		FORTRAN,
		/**
		 * <code>this</code> token is a PP-token (output from
		 * {@link CPreprocessor}).
		 */
		PREPROC,
		/**
		 * <code>this</code> token is a dummy token (generated by CIVL).
		 */
		DUMMY,
		/**
		 * The default enum-type for {@link TokenVocabulary}
		 */
		UNKNOWN,
	}

	/**
	 * A record of how this token was formed, through macro expansions, token
	 * concatenation, include directives, etc.
	 * 
	 * @return history of token formation
	 */
	Formation getFormation();

	/**
	 * Returns the file that actually contains the token.
	 * 
	 * @return the source file
	 */
	SourceFile getSourceFile();

	/**
	 * Sets the next token in the sequence. The next token, if non-null, should
	 * have index one greater than the index of this token.
	 * 
	 * @param nextToken
	 */
	void setNext(CivlcToken nextToken);

	/**
	 * Returns the "next" token, which, if non-null, should have index one
	 * greater than this token's index. Could be null.
	 * 
	 * @return the next token
	 */
	CivlcToken getNext();

	/**
	 * Sets the index of this token.
	 * 
	 * @param index
	 */
	void setIndex(int index);

	/**
	 * Returns the index of this token (among its siblings). Tokens are indexed
	 * from 0.
	 * 
	 * @return the index of this token
	 */
	int getIndex();

	/**
	 * Is this token expandable? This is used only for identifiers that could be
	 * macro invocations. The macro expansion procedure is complex and at a
	 * certain phase, a macro identifier becomes non-expandable. It is mostly to
	 * support self-referential macros.
	 * 
	 * Initially, every token is expandable.
	 * 
	 * @return value of expandable bit
	 */
	boolean isExpandable();

	/**
	 * Sets this token's expandable bit to false.
	 */
	void makeNonExpandable();

	int getStartIndex();

	int getStopIndex();

	void setStartIndex(int index);

	void setStopIndex(int index);

	/**
	 * Return this token's white text, which is used for Fortran lexer
	 * 
	 * @return the white text of this token.
	 */
	String getWhiteText();

	/**
	 * Set this token's white text, which is used for Fortran lexer
	 * 
	 * @param text
	 */
	void setWhiteText(String text);

	/**
	 * Return <code>this</code> token's {@link TokenVocabulary}
	 * 
	 * @return <code>this</code> token's {@link TokenVocabulary}
	 */
	TokenVocabulary getTokenVocab();

	/**
	 * Set the language kind of <code>this</code> token, when it is converted to
	 * a language-based token. The {@link TokenVocabulary} should be changed
	 * from <code>PREPROC</code> to a real language king (i.e.,
	 * <code>CIVLC</code> for Civl-C/C, <code>FORTRAN</code> for Fortran.)
	 * 
	 * @param newTokenVocab
	 */
	void setTokenVocab(TokenVocabulary newTokenVocab);
}