/*
* Copyright (c) 2008-2010 Nokia Corporation and/or its subsidiary(-ies). 
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:
*
* Parser for C++ source files
*
*/
package com.nokia.tracecompiler.source;

import java.util.ArrayList;
import java.util.List;

/**
 * Parser for C++ source files. Commented and quoted areas are located during
 * the construction of this object and those areas are excluded from the
 * searches.
 * 
 */
public class SourceParser {

	/**
	 * Skip white spaces. Does not apply to string searches
	 */
	public final static int SKIP_WHITE_SPACES = 0x01; // CodForChk_Dis_Magic

	/**
	 * Skip string areas
	 */
	public final static int SKIP_STRINGS = 0x02; // CodForChk_Dis_Magic

	/**
	 * Search / iterate backwards
	 */
	public final static int BACKWARD_SEARCH = 0x04; // CodForChk_Dis_Magic

	/**
	 * Ignore character case in string searches
	 */
	public final static int IGNORE_CASE = 0x08; // CodForChk_Dis_Magic

	/**
	 * Skip commented areas
	 */
	public final static int SKIP_COMMENTS = 0x10; // CodForChk_Dis_Magic

	/**
	 * Skip preprocessor definitions
	 */
	public final static int SKIP_PREPROCESSOR = 0x80; // CodForChk_Dis_Magic

	/**
	 * Match beginning of word flag
	 */
	public final static int MATCH_WORD_BEGINNING = 0x20; // CodForChk_Dis_Magic

	/**
	 * Match end of word flag
	 */
	public final static int MATCH_WORD_END = 0x40; // CodForChk_Dis_Magic

	/**
	 * Match whole word flag
	 */
	public final static int MATCH_WHOLE_WORD = MATCH_WORD_BEGINNING
			| MATCH_WORD_END;

	/**
	 * Ignore all special areas during search
	 */
	public final static int SKIP_ALL = SKIP_WHITE_SPACES | SKIP_STRINGS
			| SKIP_COMMENTS | SKIP_PREPROCESSOR;

	/**
	 * Data to be searched.
	 */
	private SourceDocumentInterface source;

	/**
	 * List of source locations
	 */
	private ArrayList<SourceLocation> locations;

	/**
	 * Document factory for creating locations
	 */
	private SourceDocumentFactory documentFactory;

	/**
	 * Excluded area parser
	 */
	private ExcludedAreaParser excludedAreaParser;

	/**
	 * Context area parser
	 */
	private ContextAreaParser contextAreaParser;

	/**
	 * Function return value parser
	 */
	private FunctionReturnValueParser returnValueParser;

	/**
	 * Creates a new parser for given data
	 * 
	 * @param factory
	 *            the document factory
	 * @param sourceData
	 *            the source data
	 */
	public SourceParser(SourceDocumentFactory factory, String sourceData) {
		this(factory, factory.createDocument(sourceData));
	}

	/**
	 * Creates a source parser from source document
	 * 
	 * @param factory
	 *            the document factory
	 * @param source
	 *            the source document
	 */
	public SourceParser(SourceDocumentFactory factory,
			SourceDocumentInterface source) {
		this.documentFactory = factory;
		this.source = source;
		excludedAreaParser = new ExcludedAreaParser(this);
		contextAreaParser = new ContextAreaParser(this);
		returnValueParser = new FunctionReturnValueParser(this);
		try {
			findExcludedAreas();
		} catch (SourceParserException e) {
		}
	}

	/**
	 * Gets the source document
	 * 
	 * @return the source
	 */
	public SourceDocumentInterface getSource() {
		return source;
	}

	/**
	 * Gets part of the source document data
	 * 
	 * @param start
	 *            the start offset
	 * @param length
	 *            the data length
	 * @return the data or null if offsets are not valid
	 */
	public String getData(int start, int length) {
		String retval;
		try {
			retval = source.get(start, length);
		} catch (SourceParserException e) {
			retval = null;
		}
		return retval;
	}

	/**
	 * Gets a character at given offset
	 * 
	 * @param offset
	 *            the offset
	 * @return the character
	 */
	public char getData(int offset) {
		char retval;
		try {
			retval = source.getChar(offset);
		} catch (SourceParserException e) {
			retval = '\0';
		}
		return retval;
	}

	/**
	 * Gets the source document length
	 * 
	 * @return the source length
	 */
	public int getDataLength() {
		return source.getLength();
	}

	/**
	 * Gets the line number of given offset
	 * 
	 * @param offset
	 *            the offset
	 * @return the line number or -1 if offset is not valid
	 */
	public int getLineNumber(int offset) {
		int retval;
		try {
			retval = source.getLineOfOffset(offset) + 1;
		} catch (SourceParserException e) {
			retval = -1;
		}
		return retval;
	}

	/**
	 * Starts a new string search from given offset
	 * 
	 * @param searchString
	 *            the string to be searched
	 * @param startOffset
	 *            the offset to start of search
	 * @param endOffset
	 *            the end of search or -1 to search the whole document
	 * @param searchFlags
	 *            the search flags
	 * @return the search object
	 */
	public SourceStringSearch startStringSearch(String searchString,
			int startOffset, int endOffset, int searchFlags) {
		return new SourceStringSearch(this, searchString, startOffset,
				endOffset, searchFlags);
	}

	/**
	 * Tokenizes the parameter list starting from next bracket. White spaces are
	 * discarded. For example (a, b , c ) returns { "a", "b", "c" }. This method
	 * is independent of the current string search and thus can be used during
	 * one.
	 * 
	 * @param startIndex
	 *            the index where to start
	 * @param list
	 *            the list where the parameters are added
	 * @param findSeparator
	 *            if true, the processing stops after ';' or '{' character. If
	 *            false, processing stops after ')' at end of parameters
	 * @return the offset at end of the parameters
	 * @throws SourceParserException
	 *             if parameters are not valid
	 */
	public int tokenizeParameters(int startIndex, List<String> list,
			boolean findSeparator) throws SourceParserException {
		SourceParameterTokenizer tokenizer = new SourceParameterTokenizer(this,
				startIndex);
		return tokenizer.tokenize(list, findSeparator);
	}

	/**
	 * Parses the parameter list of given source context. Each entry added into
	 * the list will be an instance of SourceParameter class. This method is
	 * independent of the current string search and thus can be used during one.
	 * 
	 * @param parameterIndex
	 *            the index where to start
	 * @param list
	 *            the list where the parameters are added
	 * @return the offset at end of the parameters
	 * @throws SourceParserException
	 *             if context is not valid
	 */
	public int parseFunctionParameters(int parameterIndex, List<SourceParameter> list)
			throws SourceParserException {
		SourceParameterTokenizer tokenizer = new SourceParameterTokenizer(this,
				parameterIndex);
		return tokenizer.tokenizeTyped(list);
	}

	/**
	 * Parses the return values of given source context
	 * 
	 * @param context
	 *            the context to be parsed
	 * @param list
	 *            the list of return values
	 */
	void parseReturnValues(SourceContext context, List<SourceReturn> list) {
		returnValueParser.parseReturnValues(context, list);
	}

	/**
	 * Checks if the offset if within an excluded area
	 * 
	 * @param offset
	 *            the offset
	 * @return true if in excluded area
	 */
	public boolean isInExcludedArea(int offset) {
		return findExcludedAreaIndex(offset) >= 0;
	}

	/**
	 * Gets an excluded area
	 * 
	 * @param offset
	 *            the data offset
	 * @return the area or null
	 */
	public SourceExcludedArea getExcludedArea(int offset) {
		return excludedAreaParser.getArea(offset);
	}

	/**
	 * Creates a new source iterator
	 * 
	 * @param offset
	 *            the offset where to start
	 * @param iteratorFlags
	 *            the flags for the iterator
	 * @return the new iterator
	 */
	public SourceIterator createIterator(int offset, int iteratorFlags) {
		return new SourceIterator(this, offset, iteratorFlags);
	}

	/**
	 * Returns the context at given offset. This parses the source if it has not
	 * been parsed before.
	 * 
	 * @param offset
	 *            the offset to the source data
	 * @return the context at the offset or null if no context exists
	 */
	public SourceContext getContext(int offset) {
		SourceContext retval;
		try {
			retval = contextAreaParser.parseAndGet(offset);
		} catch (SourceParserException e) {
			retval = null;
		}
		return retval;
	}

	/**
	 * Locates the start-of-line starting from given offset
	 * 
	 * @param offset
	 *            the offset
	 * @param cancelIfNotWhitespace
	 *            flag that tells to stop processing and return the original
	 *            value if a non-whitespace is found before start of line
	 * @param stayInContext
	 *            flag that tells to stay within the context offset currently
	 *            resides. If this would come out of the context, this locates
	 *            the start of the next line following offset
	 * @return the start-of-line
	 * @throws SourceParserException
	 *             if the offset is not valid
	 */
	public int findStartOfLine(int offset, boolean cancelIfNotWhitespace,
			boolean stayInContext) throws SourceParserException {
		int retval = offset == 0 ? offset : offset - 1;
		for (int i = retval; i >= 0; i--) {
			char c = source.getChar(i);
			if (source.getChar(i) == '\n') {
				retval = i + 1;
				i = -1;
			} else if (cancelIfNotWhitespace && !Character.isWhitespace(c)) {
				retval = offset;
				i = -1;
			}
		}
		if (stayInContext) {
			SourceContext context = getContext(offset);
			if (context != null && retval < context.getOffset()) {
				retval = context.getOffset();
				int end = context.getOffset() + context.getLength();
				for (int i = retval; i < end; i++) {
					if (source.getChar(i) == '\n') {
						retval = i + 1;
						i = end;
					}
				}
			}
		}
		return retval;
	}

	/**
	 * Finds the array index of the excluded area which contains the offset. If
	 * none of the areas contain the offset, returns negative integer indicating
	 * the index of the excluded area following the offset
	 * 
	 * @param offset
	 *            the offset to the data
	 * @return the excluded area index
	 */
	int findExcludedAreaIndex(int offset) {
		return excludedAreaParser.find(offset);
	}

	/**
	 * Finds the excluded source file areas. Excluded areas include comments and
	 * quoted strings. Overwrites possible old areas.
	 * 
	 * @throws SourceParserException
	 *             if parser fails
	 */
	public void findExcludedAreas() throws SourceParserException {
		excludedAreaParser.parseAll();
	}

	/**
	 * Gets the list of excluded areas
	 * 
	 * @return the list
	 */
	public List<SourceExcludedArea> getExcludedAreas() {
		return excludedAreaParser.getAreas();
	}

	/**
	 * Checks if the area is excluded with given flags
	 * 
	 * @param type
	 *            the area type
	 * @param flags
	 *            the flags
	 * @return true if skipped
	 */
	static boolean isExcluded(int type, int flags) {
		boolean string = ((flags & SKIP_STRINGS) != 0)
				&& (type == SourceExcludedArea.STRING);
		boolean comment = ((flags & SKIP_COMMENTS) != 0)
				&& (type == SourceExcludedArea.MULTILINE_COMMENT);
		boolean linecomment = ((flags & SKIP_COMMENTS) != 0)
				&& (type == SourceExcludedArea.LINE_COMMENT);
		boolean preProcessor = ((flags & SKIP_PREPROCESSOR) != 0)
				&& (type == SourceExcludedArea.PREPROCESSOR_DEFINITION);
		return string || comment || linecomment || preProcessor;
	}

	/**
	 * Adds a location to this parser
	 * 
	 * @param location
	 *            the location
	 */
	void addLocation(SourceLocation location) {
		if (locations == null) {
			locations = new ArrayList<SourceLocation>();
		}
		locations.add(location);
		if (source != null) {
			source.addLocation(location.getLocation());
		}
	}

	/**
	 * Removes a location from this parser
	 * 
	 * @param location
	 *            the location to be removed
	 */
	void removeLocation(SourceLocation location) {
		if (locations != null) {
			locations.remove(location);
		}
		if (source != null) {
			source.removeLocation(location.getLocation());
		}
	}

	/**
	 * Gets the document framework
	 * 
	 * @return the document framework
	 */
	public SourceDocumentFactory getDocumentFramework() {
		return documentFactory;
	}

}