/*******************************************************************************
 * Copyright (c) 2008 Wind River Systems, Inc. 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:
 *    Markus Schorn - initial API and implementation
 *******************************************************************************/ 
package org.eclipse.cdt.core.dom.rewrite;

import org.eclipse.cdt.core.dom.ast.IASTFileLocation;
import org.eclipse.cdt.core.dom.ast.IASTTranslationUnit;
import org.eclipse.cdt.core.dom.ast.IMacroBinding;
import org.eclipse.cdt.internal.core.parser.scanner.MultiMacroExpansionExplorer;
import org.eclipse.jface.text.IRegion;
import org.eclipse.text.edits.ReplaceEdit;

/**
 * Allows to understand macro expansions step by step.
 * @since 5.0
 */
public abstract class MacroExpansionExplorer {
	
	/**
	 * Representation of a single expansion step or a complete expansion.
	 */
	public interface IMacroExpansionStep {
		/**
		 * Returns the code before this step.
		 */
		String getCodeBeforeStep();
		/**
		 * Returns the code after this step.
		 */
		String getCodeAfterStep();

		/**
		 * Returns an array of replacements representing the change from the code before
		 * this step to the code after this step.
		 */
		ReplaceEdit[] getReplacements();
		
		/**
		 * Returns the macro that gets expanded in this step, or <code>null</code> for
		 * a step representing a full expansion. 
		 */
		IMacroBinding getExpandedMacro();
		
		/**
		 * Returns the location of the macro-definition that gets expanded in this step, 
		 * or <code>null</code> for built-in macros or for a step representing a full expansion. 
		 */
		IASTFileLocation getLocationOfExpandedMacroDefinition();
	}
	
	/**
	 * Creates a macro expansion explorer for a given file location in a translation unit.
	 */
	public static MacroExpansionExplorer create(IASTTranslationUnit tu, IASTFileLocation loc) {
		return new MultiMacroExpansionExplorer(tu, loc);
	}

	/**
	 * Creates a macro expansion explorer for a given region in the outermost file of a 
	 * translation unit.
	 */
	public static MacroExpansionExplorer create(IASTTranslationUnit tu, IRegion loc) {
		return new MultiMacroExpansionExplorer(tu, loc);
	}

	/**
	 * Returns the full expansion for the region of this expansion explorer.
	 */
	public abstract IMacroExpansionStep getFullExpansion();

	/**
	 * Returns the total number of available steps for expanding the region of this expansion
	 * explorer.
	 */
	public abstract int getExpansionStepCount();
	
	/**
	 * Returns a description for the requested step within the expansion of the region of this
	 * expansion explorer.
	 * @throws IndexOutOfBoundsException if step < 0 or step >= getExpansionStepCount().
	 */
	public abstract IMacroExpansionStep getExpansionStep(int step) throws IndexOutOfBoundsException;
}