/*******************************************************************************
 * Copyright (c) 2004, 2005 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.jem.internal.instantiation;
 
/**
 * A visitor for abstract parse expression trees.
 * <p>
 * For each different concrete Expression node type <it>T</it> there are
 * a pair of methods:
 * <ul>
 * <li><code>public boolean visit(<it>T</it> node)</code> - Visits
 * the given node to perform some arbitrary operation. If <code>true</code>
 * is returned, the given node's child nodes will be visited next; however,
 * if <code>false</code> is returned, the given node's child nodes will 
 * not be visited. The default implementation provided by this class does
 * nothing and returns <code>true</code>. Subclasses may reimplement
 * this method as needed.</li>
 * <li><code>public void endVisit(<it>T</it> node)</code> - Visits
 * the given node to perform some arbitrary operation. When used in the
 * conventional way, this method is called after all of the given node's
 * children have been visited (or immediately, if <code>visit</code> returned
 * <code>false</code>). The default implementation provided by this class does
 * nothing. Subclasses may reimplement this method as needed.</li>
 * </ul>
 * </p>
 * In addition, there are a pair of methods for visiting AST nodes in the 
 * abstract, regardless of node type:
 * <ul>
 * <li><code>public void preVisit(ASTNode node)</code> - Visits
 * the given node to perform some arbitrary operation. 
 * This method is invoked prior to the appropriate type-specific
 * <code>visit</code> method.
 * The default implementation of this method does nothing.
 * Subclasses may reimplement this method as needed.</li>
 * <li><code>public void postVisit(ASTNode node)</code> - Visits
 * the given node to perform some arbitrary operation. 
 * This method is invoked after the appropriate type-specific
 * <code>endVisit</code> method.
 * The default implementation of this method does nothing.
 * Subclasses may reimplement this method as needed.</li>
 * </ul>
 * <p>
 * For nodes with list-valued properties, the child nodes within the list
 * are visited in order. For nodes with multiple properties, the child nodes
 * are visited in the order that most closely corresponds to the lexical
 * reading order of the source program. For instance, for a type declaration
 * node, the child ordering is: name, superclass, superinterfaces, and 
 * body declarations.
 * </p>
 * <p>
 * While it is possible to modify the tree in the visitor, care is required to
 * ensure that the consequences are as expected and desirable.
 * During the course of an ordinary visit starting at a given node, every node
 * in the subtree is visited exactly twice, first with <code>visit</code> and
 * then with <code>endVisit</code>. During a traversal of a stationary tree, 
 * each node is either behind (after <code>endVisit</code>), ahead (before 
 * <code>visit</code>), or in progress (between <code>visit</code> and
 * the matching <code>endVisit</code>). Changes to the "behind" region of the
 * tree are of no consequence to the visit in progress. Changes to the "ahead"
 * region will be taken in stride. Changes to the "in progress" portion are
 * the more interesting cases. With a node, the various properties are arranged
 * in a linear list, with a cursor that separates the properties that have
 * been visited from the ones that are still to be visited (the cursor
 * is between the elements, rather than on an element). The cursor moves from
 * the head to the tail of this list, advancing to the next position just
 * <it>before</it> <code>visit</code> if called for that child. After the child
 * subtree has been completely visited, the visit moves on the child 
 * immediately after the cursor. Removing a child while it is being visited
 * does not alter the course of the visit. But any children added at positions
 * after the cursor are considered in the "ahead" portion and will be visited.
 * </p>
 * <p>
 * Cases to watch out for:
 * <ul>
 * <li>Moving a child node further down the list. This could result in the
 * child subtree being visited multiple times; these visits are sequential.</li>
 * <li>Moving a child node up into an ancestor. If the new home for
 * the node is in the "ahead" portion, the subtree will be visited 
 * a second time; again, these visits are sequential.</li>
 * <li>Moving a node down into a child. If the new home for
 * the node is in the "ahead" portion, the subtree will be visited 
 * a second time; in this case, the visits will be nested. In some cases,
 * this can lead to a stack overflow or out of memory condition.</li>
 * </ul>
 * </p>
 *
 * Note: This is based upon the visit concept in org.eclipse.jdt.core.dom.ASTVisitor. 
 *
 * @see Expression#accept
 *  
 * @since 1.0.0
 */
public class ParseVisitor {
	
	/**
	 * Exception to throw to just stop visiting a parse visit. It doesn't mean error, it
	 * just means stop visiting. ParseVisitors should throw this when they want to stop
	 * visiting further without an explicit error.
	 * <p>
	 * If they want to indicate an error, parse visitors can throw any other RuntimeException. 
	 * Those will also stop visiting, but the exception will be passed on out of the 
	 * {@link PTExpression#accept(ParseVisitor)}. StopVisiting will not be passed on
	 * but will be caught inside accept.
	 * 
	 * @since 1.1.0.1
	 */
	public static class StopVisiting extends RuntimeException {

		/**
		 * Comment for <code>serialVersionUID</code>
		 * 
		 * @since 1.1.0.1
		 */
		private static final long serialVersionUID = -5246860806568355520L;
		
	}
	/**
	 * Visits the given parse node prior to the type-specific visit. (before <code>visit</code>).
	 * <p>
	 * The default implementation does nothing. Subclasses may reimplement.
	 * </p>
	 * 
	 * @param node
	 *            the node to visit
	 */
	public void preVisit(PTExpression node) {
		// default implementation: do nothing
	}

	/**
	 * Visits the given parse node following the type-specific visit (after <code>endVisit</code>).
	 * <p>
	 * The default implementation does nothing. Subclasses may reimplement.
	 * </p>
	 * 
	 * @param node
	 *            the node to visit
	 */
	public void postVisit(PTExpression node) {
		// default implementation: do nothing
	}

	public boolean visit(PTAnonymousClassDeclaration node) {
		return true;
	}
	public boolean visit(PTArrayAccess node) {
		return true;
	}
	public boolean visit(PTArrayCreation node) {
		return true;
	}
	public boolean visit(PTArrayInitializer node) {
		return true;
	}
	public boolean visit(PTBooleanLiteral node) {
		return true;
	}
	public boolean visit(PTCastExpression node) {
		return true;
	}
	public boolean visit(PTCharacterLiteral node) {
		return true;
	}
	public boolean visit(PTClassInstanceCreation node) {
		return true;
	}
	public boolean visit(PTConditionalExpression node) {
		return true;
	}
	public boolean visit(PTFieldAccess node) {
		return true;
	}
	public boolean visit(PTInfixExpression node) {
		return true;
	}
	public boolean visit(PTInstanceof node) {
		return true;
	}
	public boolean visit(PTInvalidExpression node) {
		return true;
	}
	public boolean visit(PTMethodInvocation node) {
		return true;
	}
	public boolean visit(PTName node) {
		return true;
	}
	public boolean visit(PTNullLiteral node) {
		return true;
	}
	public boolean visit(PTNumberLiteral node) {
		return true;
	}
	public boolean visit(PTParenthesizedExpression node) {
		return true;
	}
	public boolean visit(PTPrefixExpression node) {
		return true;
	}
	public boolean visit(PTStringLiteral node) {
		return true;
	}
	public boolean visit(PTThisLiteral node) {
		return true;
	}
	public boolean visit(PTTypeLiteral node) {
		return true;
	}
	public boolean visit(PTInstanceReference node) {
		return true;
	}
	public void endVisit(PTAnonymousClassDeclaration node) {
		// default implementation: do nothing
	}
	public void endVisit(PTArrayAccess node) {
		// default implementation: do nothing
	}
	public void endVisit(PTArrayCreation node) {
		// default implementation: do nothing
	}
	public void endVisit(PTArrayInitializer node) {
		// default implementation: do nothing
	}
	public void endVisit(PTBooleanLiteral node) {
		// default implementation: do nothing
	}
	public void endVisit(PTCastExpression node) {
		// default implementation: do nothing
	}
	public void endVisit(PTCharacterLiteral node) {
		// default implementation: do nothing
	}
	public void endVisit(PTClassInstanceCreation node) {
		// default implementation: do nothing
	}
	public void endVisit(PTConditionalExpression node) {
		// default implementation: do nothing
	}
	public void endVisit(PTFieldAccess node) {
		// default implementation: do nothing
	}
	public void endVisit(PTInfixExpression node) {
		// default implementation: do nothing
	}
	public void endVisit(PTInstanceof node) {
		// default implementation: do nothing
	}
	public void endVisit(PTInvalidExpression node) {
		// default implementation: do nothing
	}
	public void endVisit(PTMethodInvocation node) {
		// default implementation: do nothing
	}
	public void endVisit(PTName node) {
		// default implementation: do nothing
	}
	public void endVisit(PTNullLiteral node) {
		// default implementation: do nothing
	}
	public void endVisit(PTNumberLiteral node) {
		// default implementation: do nothing
	}
	public void endVisit(PTParenthesizedExpression node) {
		// default implementation: do nothing
	}
	public void endVisit(PTPrefixExpression node) {
		// default implementation: do nothing
	}
	public void endVisit(PTStringLiteral node) {
		// default implementation: do nothing
	}
	public void endVisit(PTThisLiteral node) {
		// default implementation: do nothing
	}
	public void endVisit(PTTypeLiteral node) {
		// default implementation: do nothing
	}
	public void endVisit(PTInstanceReference node) {
		// default implementation: do nothing
	}
	
}