/*******************************************************************************
 * Copyright (c) 2000, 2004 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/

package org.eclipse.jface.text.source.translation;

import java.io.IOException;


/**
 * A tag handler is responsible to
 * - handle the attributes for the tags it supports
 * - translate the tag sequence including attributes to another language
 * - back-translate relative line offsets.
 * <p>
 * Tag handlers are used by translators via tag handler factories. The factory
 * can either return a new tag or one that already has some attributes. </p>
 * 
 * @see org.eclipse.jface.text.source.translation.ITranslator
 * @see org.eclipse.jface.text.source.translation.ITagHandlerFactory
 * @since 3.0
 */
public interface ITagHandler {
	
	/**
	 * Tells whether this handler can handle the given tag.
	 * 
	 * @param tag the tag to check
	 * @return <code>true</code> if this handler handles the given tag
	 */
	boolean canHandleTag(String tag);
	
	/**
	 * Tells whether this handler can handle the given text. Most
	 * likely the handler will check if the text contains a tag
	 * that he can handle.
	 * 
	 * @param text the text to check
	 * @return <code>true</code> if this handler handles the given text
	 */
	boolean canHandleText(String text);
	
	/**
	 * Adds an attribute to this tag handler.
	 * 
	 * @param name				the name of the attribute
	 * @param value			the attribute value
	 * @param sourceLineNumber the line number of the attribute in the source or <code>-1</code> if unknown
	 */
	void addAttribute(String name, String value, int sourceLineNumber);
	
	/**
	 * Resets this handler and sets the current tag to the given tag.
	 * A handler can handle more than one tag but only one tag at a time.
	 * <p>
	 * Resetting the handler clears the attributes.</p>
	 * 
	 * @param tag the tag to check
	 */
	void reset(String tag);
	
	/**
	 * Writes the tag and line mapping information to the 
	 * given translator result collector.
	 * 
	 * @param resultCollector the translator's result collector
	 * @param sourceLineNumber the line number of the attribute in the source or <code>-1</code> if unknown
	 * @throws IOException
	 */
	void processEndTag(ITranslatorResultCollector resultCollector, int sourceLineNumber) throws IOException;
	
	/**
	 * Computes the offset in the source line that corresponds
	 * to the given offset in the translated line. 
	 * 
	 * @param sourceLine				the source line
	 * @param translatedLine			the translated line
	 * @param offsetInTranslatedLine	the offset in the translated line
	 * @return the offset in the source line or <code>-1</code> if
	 * 			it was not possible to compute the offset
	 */
	int backTranslateOffsetInLine(String sourceLine, String translatedLine, int offsetInTranslatedLine);
}