001/*-------------------------------------------------------------------------+
002|                                                                          |
003| Copyright 2005-2011 The ConQAT Project                                   |
004|                                                                          |
005| Licensed under the Apache License, Version 2.0 (the "License");          |
006| you may not use this file except in compliance with the License.         |
007| You may obtain a copy of the License at                                  |
008|                                                                          |
009|    http://www.apache.org/licenses/LICENSE-2.0                            |
010|                                                                          |
011| Unless required by applicable law or agreed to in writing, software      |
012| distributed under the License is distributed on an "AS IS" BASIS,        |
013| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
014| See the License for the specific language governing permissions and      |
015| limitations under the License.                                           |
016+-------------------------------------------------------------------------*/
017package eu.cqse.check.framework.scanner;
018
019import java.io.Serializable;
020
021/**
022 * Object of type {@link IToken} are returned by the scanners. {@link IToken}s
023 * are immutable.
024 */
025public interface IToken extends Serializable {
026
027        /**
028         * Obtain the original input text for a token (copied verbatim from the source).
029         */
030        String getText();
031
032        /**
033         * Get the number of characters before this token in the text. The offset is
034         * 0-based and inclusive.
035         */
036        int getOffset();
037
038        /**
039         * Get the number of characters before the end of this token in the text (i.e.
040         * the 0-based index of the last character, inclusive).
041         */
042        int getEndOffset();
043
044        /**
045         * Obtain number of line this token was found at. Counting starts at 0. For
046         * tokens spanning multiple lines, this is the number of the line in which the
047         * first character of the token is.
048         */
049        int getLineNumber();
050
051        /**
052         * Get string that identifies the origin of this token. This can, e.g., be a
053         * uniform path to the resource. Its actual content depends on how the token
054         * gets constructed.
055         */
056        String getOriginId();
057
058        /**
059         * Obtain type of token.
060         */
061        ETokenType getType();
062
063        /**
064         * Obtain language.
065         */
066        ELanguage getLanguage();
067
068        /**
069         * Create new token. Can be used to clone or create modified copies of tokens.
070         * 
071         * @param type
072         *            Token type of new token
073         * @param offset
074         *            Offset of new token
075         * @param lineNumber
076         *            LineNumber of new token
077         * @param text
078         *            Text of new token
079         * @param originId
080         *            Origin id of new token
081         * @return New token with set values of the same java type as the token on which
082         *         the method was called.
083         */
084        IToken newToken(ETokenType type, int offset, int lineNumber, String text, String originId);
085}