TokenMaker.java

/*
 * 02/24/2004
 *
 * TokenMaker.java - An object that can take a chunk of text and return a
 * linked list of <code>Token</code>s representing it.
 * Copyright (C) 2004 Robert Futrell
 * robert_futrell at users.sourceforge.net
 * http://fifesoft.com/rsyntaxtextarea
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library 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
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; 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 javax.swing.Action;
import javax.swing.text.Segment;

/**
 * An implementation of <code>TokenMaker</code> is a class that turns text into a linked list of <code>Token</code>s for
 * syntax highlighting in a particular language.
 * 
 * @see Token
 * @see AbstractTokenMaker
 * 
 * @author Robert Futrell
 * @version 0.2
 */
public interface TokenMaker {

    /**
     * Adds a null token to the end of the current linked list of tokens. This should be put at the end of the linked
     * list whenever the last token on the current line is NOT a multiline token.
     */
    public void addNullToken();

    /**
     * Adds the token specified to the current linked list of tokens.
     * 
     * @param array
     *            The character array from which to get the text.
     * @param start
     *            Start offset in <code>segment</code> of token.
     * @param end
     *            End offset in <code>segment</code> of token.
     * @param tokenType
     *            The token's type.
     * @param startOffset
     *            The offset in the document at which this token occurs.
     */
    public void addToken(char[] array, int start, int end, int tokenType,
            int startOffset);

    /**
     * Returns whether this programming language uses curly braces ('<tt>{</tt>' and '<tt>}</tt>') to denote code
     * blocks.
     * 
     * @return Whether curly braces denote code blocks.
     */
    public boolean getCurlyBracesDenoteCodeBlocks();

    /**
     * Returns the last token on this line's type if the token is "unfinished", or {@link Token#NULL} if it was
     * finished. For example, if C-style syntax highlighting is being implemented, and <code>text</code> contained a
     * line of code that contained the beginning of a comment but no end-comment marker ("*\/"), then this method would
     * return {@link Token#COMMENT_MULTILINE} for that line. This is useful for doing syntax highlighting.
     * 
     * @param text
     *            The line of tokens to examine.
     * @param initialTokenType
     *            The token type to start with (i.e., the value of <code>getLastTokenTypeOnLine</code> for the line
     *            before <code>text</code>).
     * @return The last token on this line's type, or {@link Token#NULL} if the line was completed.
     */
    public int getLastTokenTypeOnLine(Segment text, int initialTokenType);

    /**
     * Returns the text to place at the beginning and end of a line to "comment" it in a this programming language.
     * 
     * @return The start and end strings to add to a line to "comment" it out. A <code>null</code> value for either
     *         means there is no string to add for that part. A value of <code>null</code> for the array means this
     *         language does not support commenting/uncommenting lines.
     */
    public String[] getLineCommentStartAndEnd();

    /**
     * Returns an action to handle "insert break" key presses (i.e. Enter).
     * 
     * @return The action, or <code>null</code> if the default action should be used.
     */
    public Action getInsertBreakAction();

    /**
     * Returns whether tokens of the specified type should have "mark occurrences" enabled for the current programming
     * language.
     * 
     * @param type
     *            The token type.
     * @return Whether tokens of this type should have "mark occurrences" enabled.
     */
    public boolean getMarkOccurrencesOfTokenType(int type);

    /**
     * If a line ends in the specified token, this method returns whether a new line inserted after that line should be
     * indented.
     * 
     * @param token
     *            The token the previous line ends with.
     * @return Whether the next line should be indented.
     */
    public boolean getShouldIndentNextLineAfter(Token token);

    /**
     * Returns the first token in the linked list of tokens generated from <code>text</code>. This method must be
     * implemented by subclasses so they can correctly implement syntax highlighting.
     * 
     * @param text
     *            The text from which to get tokens.
     * @param initialTokenType
     *            The token type we should start with.
     * @param startOffset
     *            The offset into the document at which <code>text</code> starts.
     * @return The first <code>Token</code> in a linked list representing the syntax highlighted text.
     */
    public Token getTokenList(Segment text, int initialTokenType,
            int startOffset);

    /**
     * Returns whether this language is a markup language.
     * 
     * @return Whether this language is markup.
     */
    public boolean isMarkupLanguage();

    /**
     * Sets whether tokens are generated that "show" whitespace.
     * 
     * @param visible
     *            Whether whitespace should be visible.
     */
    public void setWhitespaceVisible(boolean visible, RSyntaxTextArea textArea);

}