/*
 * Copyright (c) 2003-2004 Christopher Lenz and others.
 * All rights reserved. This program and the accompanying materials 
 * are made available under the terms of the Common Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/cpl-v10.html
 * 
 * Contributors:
 *     Christopher Lenz - initial API
 * 
 * $Id: ICssParser.java,v 1.1 2004-09-02 18:07:12 jsurfer Exp $
 */

package net.sourceforge.phpeclipse.css.core.parser;

import net.sourceforge.phpeclipse.core.model.ISourceReference;
import net.sourceforge.phpeclipse.css.core.model.IDeclaration;
import net.sourceforge.phpeclipse.css.core.model.IRule;
import net.sourceforge.phpeclipse.css.core.model.IStyleSheet;

import org.eclipse.jface.text.IDocument;

/**
 * Interface for classes that implement the parsing of CSS source code into a
 * syntax tree.
 * 
 * TODO Add a way to only parse a specific range of an IDocument
 */
public interface ICssParser extends IProblemReporter {

	/**
	 * Parses the given document as a CSS style sheet. If a problem collector
	 * is provided, lexical and syntax errors are reported to it rather than
	 * throwing exceptions.
	 * 
	 * @return a list containing the parsed style rules
	 * @throws LexicalErrorException if a lexical error is reported by the
	 *         lexical scanner
	 * @throws SyntaxErrorException if a syntax error has been encountered from
	 *         which recovery is not possible
	 */
	IRule[] parseRules(IStyleSheet styleSheet)
		throws LexicalErrorException, SyntaxErrorException;

	/**
	 * Parses the source at the current position to extract a single rule.
	 * 
	 * @param parentRule the parent of the rule to parse, or <code>null</code>
	 *        if there is no parent
	 * @return the parsed rule
	 * @throws LexicalErrorException if a lexical error is reported by the
	 *         lexical scanner
	 * @throws SyntaxErrorException if a syntax error has been encountered from
	 *         which recovery is not possible
	 */
	IRule parseRule(IStyleSheet styleSheet, IRule parentRule)
		throws LexicalErrorException, SyntaxErrorException;

	/**
	 * Parses the source at the current position to extract a selector.
	 * 
	 * @return the parsed selector
	 * @throws LexicalErrorException if a lexical error is reported by the
	 *         lexical scanner
	 * @throws SyntaxErrorException if a syntax error has been encountered from
	 *         which recovery is not possible
	 */
	ISourceReference parseSelector(IRule rule)
		throws LexicalErrorException, SyntaxErrorException;

	/**
	 * Parses the source at the current position to extract a single
	 * declaration.
	 * 
	 * @return the parsed declaration
	 * @throws LexicalErrorException if a lexical error is reported by the
	 *         lexical scanner
	 * @throws SyntaxErrorException if a syntax error has been encountered from
	 *         which recovery is not possible
	 */
	IDeclaration parseDeclaration(IRule rule)
		throws LexicalErrorException, SyntaxErrorException;

	/**
	 * Sets the document containing the style sheet source to process.
	 * 
	 * @param document the document containing the source
	 */
	void setSource(IDocument document);

}