/*******************************************************************************
 * Copyright (c) 2005, 2007 IBM Corporation and others.
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 * 
 * SPDX-License-Identifier: EPL-2.0
 *
 
 *******************************************************************************/
package org.eclipse.dltk.javascript.scriptdoc;

import org.eclipse.dltk.compiler.InvalidInputException;


public interface IScanner {

	/**
	 * Answers the current identifier source, after unicode escape sequences have
	 * been translated into unicode characters.
	 * For example, if original source was <code>\\u0061bc</code> then it will answer <code>abc</code>.
	 * 
	 * @return the current identifier source, after unicode escape sequences have
	 * been translated into unicode characters
	 */
	char[] getCurrentTokenSource();
	
	/**
	 * Answers the current identifier source, before unicode escape sequences have
	 * been translated into unicode characters.
	 * For example, if original source was <code>\\u0061bc</code> then it will answer <code>\\u0061bc</code>.
	 * 
	 * @return the current identifier source, before unicode escape sequences have
	 * been translated into unicode characters
	 * @since 2.1
	 */
	char[] getRawTokenSource();	

	/**
	 * Answers the starting position of the current token inside the original source.
	 * This position is zero-based and inclusive. It corresponds to the position of the first character 
	 * which is part of this token. If this character was a unicode escape sequence, it points at the first 
	 * character of this sequence.
	 * 
	 * @return the starting position of the current token inside the original source
	 */
	int getCurrentTokenStartPosition();

	/**
	 * Answers the ending position of the current token inside the original source.
	 * This position is zero-based and inclusive. It corresponds to the position of the last character
	 * which is part of this token. If this character was a unicode escape sequence, it points at the last 
	 * character of this sequence.
	 * 
	 * @return the ending position of the current token inside the original source
	 */
	int getCurrentTokenEndPosition();

	/**
	 * Answers the starting position of a given line number. This line has to have been encountered
	 * already in the tokenization process (in other words, it cannot be used to compute positions of lines beyond
	 * current token). Once the entire source has been processed, it can be used without any limit.
	 * Line starting positions are zero-based, and start immediately after the previous line separator (if any).
	 * 
	 * @param lineNumber the given line number
	 * @return the starting position of a given line number
	 */
	int getLineStart(int lineNumber);

	/**
	 * Answers the ending position of a given line number. This line has to have been encountered
	 * already in the tokenization process (in other words, it cannot be used to compute positions of lines beyond
	 * current token). Once the entire source has been processed, it can be used without any limit.
	 * Line ending positions are zero-based, and correspond to the last character of the line separator 
	 * (in case multi-character line separators).	 
	 * 
	 * @param lineNumber the given line number
	 * @return the ending position of a given line number
	 **/
	int getLineEnd(int lineNumber);

	/**
	 * Answers an array of the ending positions of the lines encountered so far. Line ending positions
	 * are zero-based, and correspond to the last character of the line separator (in case multi-character
	 * line separators).
	 * 
	 * @return an array of the ending positions of the lines encountered so far
	 */
	int[] getLineEnds();

	/**
	 * Answers a 1-based line number using the lines which have been encountered so far. If the position
	 * is located beyond the current scanned line, then the last line number will be answered.
	 * 
	 * @param charPosition the given character position
	 * @return a 1-based line number using the lines which have been encountered so far
	 */
	int getLineNumber(int charPosition);

	/**
	 * Read the next token in the source, and answers its ID as specified by <code>ITerminalSymbols</code>.
	 * Note that the actual token ID values are subject to change if new keywords were added to the language
	 * (for instance, 'assert' is a keyword in 1.4).
	 * 
	 * @throws InvalidInputException in case a lexical error was detected while reading the current token
	 * @return the next token
	 */
	int getNextToken() throws InvalidInputException;

	/**
	 * Answers the original source being processed (not a copy of it). 
	 * 
	 * @return the original source being processed
	 */
	char[] getSource();

	/**
	 * Reposition the scanner on some portion of the original source. The given endPosition is the last valid position.
	 * Beyond this position, the scanner will answer EOF tokens (<code>ITerminalSymbols.TokenNameEOF</code>).
	 * 
	 * @param startPosition the given start position
	 * @param endPosition the given end position
	 */
	void resetTo(int startPosition, int endPosition);

	/**
	 * Set the scanner source to process. By default, the scanner will consider starting at the beginning of the
	 * source until it reaches its end.
	 * If the given source is <code>null</code>, this clears the source.
	 * 
	 * @param source the given source
	 */
	void setSource(char[] source);
}