Token.java

/*
 * Reference ETL Parser for Java
 * Copyright (c) 2000-2009 Constantine A Plotnikov
 *
 * Permission is hereby granted, free of charge, to any person 
 * obtaining a copy of this software and associated documentation 
 * files (the "Software"), to deal in the Software without restriction,
 * including without limitation the rights to use, copy, modify, merge, 
 * publish, distribute, sublicense, and/or sell copies of the Software, 
 * and to permit persons to whom the Software is furnished to do so, 
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be 
 * included in all copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 
 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 
 * SOFTWARE. 
 */
package net.sf.etl.parsers;

/**
 * Objects of this class represent tokens in token stream. The object is
 * immutable provided that error arguments are immutable if it is a error token.
 * 
 * @author const
 */
public final class Token extends AbstractToken {
	/** kind of token or would-be-kind in case of error */
	private final TokenKey key;
	/** full text of token */
	private final String text;

	/**
	 * A constructor for token with or without special value
	 * 
	 * @param kind
	 *            a kind of token
	 * @param text
	 *            a token text
	 * @param start
	 *            a start of token in text
	 * @param end
	 *            an end of token in text
	 * @throws IllegalArgumentException
	 *             when special value cannot be associated with token.
	 */
	public Token(TokenKey kind, String text, TextPos start, TextPos end) {
		super(start, end);
		if (kind.kind() == Tokens.ERROR) {
			throw new IllegalArgumentException(
					"This constructor cannot be used to construct error tokens");
		}
		this.key = kind;
		this.text = text;
	}

	/**
	 * A constructor for error tokens
	 * 
	 * @param wouldBeKind
	 *            a would-be-kind of token. This is a token kind that token
	 *            would had if there were no error.
	 * @param text
	 *            a token text
	 * @param start
	 *            a start of token in text
	 * @param end
	 *            an end of token in text
	 * @param systemId
	 *            a system identifier
	 * @param errorId
	 *            an id of the error
	 * @param errorArgs
	 *            arguments of the error
	 * @throws IllegalArgumentException
	 *             when special value cannot be associated with token.
	 */
	public Token(TokenKey wouldBeKind, String text, TextPos start, TextPos end,
			String systemId, String errorId, Object errorArgs[]) {
		super(start, end, systemId, errorId, errorArgs);
		if (wouldBeKind.kind() == Tokens.ERROR) {
			throw new IllegalArgumentException(
					"Would-be-kind cannot be a error");
		}
		this.key = wouldBeKind;
		this.text = text;
	}

	/**
	 * @return the key for the token
	 */
	public TokenKey key() {
		return key;
	}

	/**
	 * @return kind of token
	 */
	public Tokens kind() {
		return errorInfo() == null ? key.kind() : Tokens.ERROR;
	}

	/**
	 * @return would-be-kind of token if token is error token
	 * @throws IllegalStateException
	 *             if token is not error token
	 */
	public Tokens wouldBeKind() {
		if (errorInfo() == null) {
			throw new IllegalStateException(
					"Would-be-kind is only available for error tokens");
		} else {
			return key.kind();
		}
	}

	/**
	 * @return token text
	 */
	public String text() {
		return text;
	}

	/**
	 * @return quote character for string
	 */
	public String quote() {
		return key.startQuote();
	}

	/**
	 * @return suffix for numeric literal with suffix
	 */
	public String suffix() {
		return key.suffix();
	}

	/**
	 * {@inheritDoc}
	 */
	@Override
	public String toString() {
		return "Token["
				+ key
				+ ":"
				+ text
				+ ", "
				+ start()
				+ " - "
				+ end()
				+ (errorInfo() != null ? ", errorId=" + errorInfo().errorId()
						: "") + "]";
	}
}