/*
 * 02/21/2004
 *
 * Token.java - A token used in syntax highlighting.
 * Copyright (C) 2004 Robert Futrell
 * email@address.com
 * www.website.com
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
package org.fife.ui.rsyntaxtextarea;

import java.awt.Color;
import java.awt.Font;
import java.awt.FontMetrics;
import java.awt.Graphics2D;
import java.awt.Rectangle;
import java.awt.geom.Rectangle2D;
import javax.swing.text.TabExpander;

import org.fife.RUtilities;


/**
 * A generic token that functions as a node in a linked list of syntax
 * highlighted tokens for some language.<p>
 *
 * A <code>Token</code> is a piece of text representing some logical token in
 * source code for a programming language.  For example, the line of C code:<p>
 * <pre>
 * int i = 0;
 * </pre>
 * would be broken into 8 <code>Token</code>s: the first representing
 * <code>int</code>, the second whitespace, the third <code>i</code>, the fourth
 * whitespace, the fifth <code>=</code>, etc.<p>
 *
 * @author Robert Futrell
 * @version 0.3
 */
public abstract class Token {

	/**
	 * The text this token represents.  This is implemented as a segment so we
	 * can point directly to the text in the document without having to make a
	 * copy of it.
	 */
	public char[] text;
	public int textOffset;
	public int textCount;
	
	/**
	 * The offset into the document at which this token resides.
	 */
	public int offset;

	/**
	 * The type of token this is; for example, <code>Token.FUNCTION</code>.
	 */
	public int type;

	/**
	 * The next token in this linked list.
	 */
	private Token nextToken;


/*****************************************************************************/


	// NOTE: All valid token types are >= 0, so extensions of the TokenMaker
	// class are free to internally use all ints < 0 ONLY for "end-of-line"
	// style markers; they are ignored by painting implementations.

	public static final int NULL							= 0;	// Marks EOL with no multiline token at end.

	public static final int COMMENT						= 1;	// Generic.
	public static final int COMMENT_EOL					= 2;
	public static final int COMMENT_MULTILINE				= 3;
	public static final int COMMENT_DOCUMENTATION			= 4;

	public static final int RESERVED_WORD					= 5;

	public static final int FUNCTION						= 6;

	public static final int LITERAL						= 7;	// Generic.
	public static final int LITERAL_BOOLEAN					= 8;
	public static final int LITERAL_NUMBER_DECIMAL_INT		= 9;
	public static final int LITERAL_NUMBER_FLOAT				= 10;
	public static final int LITERAL_NUMBER_HEXADECIMAL		= 11;
	public static final int LITERAL_STRING_DOUBLE_QUOTE		= 12;
	public static final int LITERAL_CHAR					= 13;	// Char or single-quote string.
	public static final int LITERAL_BACKQUOTE				= 14;	// Used in UNIX/Perl scripts.

	public static final int DATA_TYPE						= 15;

	public static final int VARIABLE						= 16;

	public static final int IDENTIFIER						= 17;

	public static final int WHITESPACE						= 18;

	public static final int SEPARATOR						= 19;

	public static final int OPERATOR						= 20;

	public static final int PREPROCESSOR					= 21;

	public static final int ERROR							= 22;	// Generic.
	public static final int ERROR_IDENTIFIER				= 23;
	public static final int ERROR_NUMBER_FORMAT				= 24;
	public static final int ERROR_STRING_DOUBLE 				= 25;
	public static final int ERROR_CHAR						= 26;	// Char or single-quote string.

	public static final int NUM_TOKEN_TYPES					= 27;


/*****************************************************************************/


	/**
	 * Creates a "null token."  The token itself is not null; rather, it
	 * signifies that it is the last token in a linked list of tokens and
	 * that it is not part of a "multiline token."
	 */
	public Token() {
		this.text = null;
		this.textOffset = -1;
		this.textCount = -1;
		this.type = NULL;
		offset = -1;
		nextToken = null;
	}


/*****************************************************************************/


	/**
	 * Constructor.
	 *
	 * @param line The segment from which to get the token.
	 * @param beg The first character's position in <code>line</code>.
	 * @param end The last character's position in <code>line</code>.
	 * @param startOffset The offset into the document at which this
	 *                    token begins.
	 * @param type A token type listed as "generic" above.
	 */
	public Token(final char[] line, final int beg, final int end,
							final int startOffset, final int type) {
		this();
		set(line, beg,end, startOffset, type);
	}


/*****************************************************************************/


	/**
	 * Creates this token as a deep copy of the passed-in token.
	 *
	 * @param t2 The token from which to make a copy.
	 */
	public Token(Token t2) {
		this();
		copyFrom(t2);
	}


/*****************************************************************************/


	/**
	 * Returns whether the token straddles the specified position in the
	 * document.
	 *
	 * @param pos The position in the document to check.
	 * @return Whether the specified position is straddled by this token.
	 */
	public boolean containsPosition(int pos) {
		return pos>=offset && pos<offset+textCount;
	}


/*****************************************************************************/


	/**
	 * Makes one token point to the same text segment, and have the same value
	 * as another token.
	 *
	 * @param t2 The token from which to copy.
	 */
	public void copyFrom(Token t2) {
		text = t2.text;
		textOffset = t2.textOffset;
		textCount = t2.textCount;
		offset = t2.offset;
		type = t2.type;
		nextToken = t2.nextToken;
	}


/*****************************************************************************/


	/**
	 * Returns the position in the token's internal char array corresponding
	 * to the specified document position.<p>
	 * Note that this method does NOT do any bounds checking; you can pass in
	 * a document position that does not correspond to a position in this
	 * token, and you will not receive an Exception or any other notification;
	 * it is up to the caller to ensure valid input.
	 *
	 * @param pos A position in the document that is represented by this token.
	 * @return The corresponding token position >= <code>textOffset</code> and
	 *         < <code>textOffset+textCount</code>.
	 * @see #tokenToDocument
	 */
	public int documentToToken(int pos) {
		return pos + (textOffset-offset);
	}


/*****************************************************************************/


	/**
	 * Returns a <code>String</code> containing HTML code for painting this
	 * token, using the given text area's color scheme.
	 *
	 * @param textArea The text area whose color scheme to use.
	 * @return The HTML representation of the token.
	 */
	public String getHTMLRepresentation(final RSyntaxTextArea textArea) {
		final SyntaxHighlightingColorScheme colorScheme =
					textArea.getSyntaxHighlightingColorScheme();
		final SyntaxScheme scheme = colorScheme.syntaxSchemes[type];
		Font font = scheme.font;
		StringBuffer buf = new StringBuffer();
		if (font.isBold()) buf.append("<b>");
		if (font.isItalic()) buf.append("<em>");
		buf.append("<font face=\"").append(font.getFamily()).
		    append("\" color=\"").
		    append(RUtilities.getHTMLFormatForColor(scheme.foreground)).
		    append("\">");
		// NOTE: Don't use getLexeme().trim() because whitespace tokens will
		// be turned into NOTHING.
		String text = getLexeme()./*replaceAll(" ", "&nbsp;").
					replaceAll("\t", "&nbsp;").*/replaceAll("<", "&lt;").
					replaceAll(">", "&gt;");
		buf.append(text);
		buf.append("</font>");
		if (font.isItalic()) buf.append("</em>");
		if (font.isBold()) buf.append("</b>");
		return buf.toString();
	}


/*****************************************************************************/


	/**
	 * Returns the text of this token, as a string.<p>
	 *
	 * Note that this method isn't used much by the
	 * <code>rsyntaxtextarea</code> package internally, as it tries to limit
	 * memory allocation.
	 *
	 * @return The text of this token.
	 */
	public String getLexeme() {
		return new String(text, textOffset, textCount);
	}


/*****************************************************************************/


	/**
	 * Determines the offset into this token list (i.e., into the
	 * document) that covers pixel location <code>x</code> if the token list
	 * starts at pixel location <code>x0</code><p>.
	 * This method will return the document position "closest" to the
	 * x-coordinate (i.e., if they click on the "right-half" of the
	 * <code>w</code> in <code>awe</code>, the caret will be placed in
	 * between the <code>w</code> and <code>e</code>; similarly, clicking on
	 * the left-half places the caret between the <code>a</code> and
	 * <code>w</code>).  This makes it useful for methods such as
	 * <code>viewToModel</code> found in <code>javax.swing.text.View</code>
	 * subclasses.<p>
	 *
	 * This method is abstract so subclasses who paint themselves differently
	 * (i.e., {@link VisibleWhitespaceToken} is painted a tad differently than
	 * {@link DefaultToken} when rendering hints are enabled) can still return
	 * accurate results.
	 *
	 * @param textArea The text area from which the token list was derived.
	 * @param e How to expand tabs.
	 * @param x0 The pixel x-location that is the beginning of
	 *           <code>tokenList</code>.
	 * @param x The pixel-position for which you want to get the corresponding
	 *          offset.
	 * @return The position (in the document, NOT into the token list!) that
	 *         covers the pixel location.  If <code>tokenList</code> is
	 *         <code>null</code> or has type <code>Token.NULL</code>, then
	 *         <code>-1</code is returned; the caller should recognize this and
	 *         return the actual end position of the (empty) line.
	 */
	public abstract int getListOffset(RSyntaxTextArea textArea, TabExpander e,
								float x0, float x);


/*****************************************************************************/


	/**
	 * Returns the token after this one in the linked list.
	 *
	 * @return The next token.
	 * @see #setNextToken