feature CtScannerListener listens for nodes of EarlyTerminatingScanner

src/main/java/spoon/reflect/visitor/EarlyTerminatingScanner.java

@@ -17,15 +17,29 @@
 package spoon.reflect.visitor;
 
 import spoon.reflect.declaration.CtElement;
+import spoon.reflect.visitor.chain.CtScannerListener;
+import spoon.reflect.visitor.chain.ScanningMode;
 
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Map;
 
+/**
+ * Extends {@link CtScanner}, to support early termination of scanning process and scan listeners.
+ * It is useful when your algorithm is searching for a specific node only.
+ * In this case, you can call {@link #terminate()}, which ensures that no more AST nodes are visited,
+ *<br>
+ * It is possible to register an implementation of {@link CtScannerListener},
+ * whose {@link CtScannerListener#enter(CtElement)}/{@link CtScannerListener#exit(CtElement)}
+ * methods are called before/after each AST node is visited.<br>
+ *
+ * @param <T> the type of the result produced by this scanner.
+ */
 public class EarlyTerminatingScanner<T> extends CtScanner {
 
 	private boolean terminate = false;
 	private T result;
+	private CtScannerListener listener;
 
 	protected void terminate() {
 		terminate = true;
@@ -39,10 +53,30 @@ protected void setResult(T result) {
 		this.result = result;
 	}
 
+	/**
+	 * @return the result of scanning - the value, which was stored by a previous call of {@link #setResult(Object)}
+	 */
 	public T getResult() {
 		return result;
 	}
 
+	/**
+	 * @return null or the implementation of {@link CtScannerListener}, which is registered to listen for enter/exit of nodes during scanning of the AST
+	 */
+	public CtScannerListener getListener() {
+		return listener;
+	}
+
+	/**
+	 * @param listener the implementation of {@link CtScannerListener}, which will be called back when entering/exiting
+	 * odes during scanning.
+	 * @return this to support fluent API
+	 */
+	public EarlyTerminatingScanner<T> setListener(CtScannerListener listener) {
+		this.listener = listener;
+		return this;
+	}
+
 	@Override
 	public void scan(Collection<? extends CtElement> elements) {
 		if (isTerminated() || elements == null) {
@@ -60,9 +94,30 @@ public void scan(Collection<? extends CtElement> elements) {
 
 	@Override
 	public void scan(CtElement element) {
-		if (isTerminated()) {
+		if (element == null || isTerminated()) {
 			return;
 		}
+		if (listener == null) {
+			//the listener is not defined
+			//visit this element and may be children
+			doScan(element, ScanningMode.NORMAL);
+		} else {
+			//the listener is defined, call it's enter method first
+			ScanningMode mode = listener.enter(element);
+			if (mode != ScanningMode.SKIP_ALL) {
+				//the listener decided to visit this element and may be children
+				doScan(element, mode);
+				//then call exit, only if enter returned true
+				listener.exit(element);
+			} //else the listener decided to skip this element and all children. Do not call exit.
+		}
+	}
+
+	/**
+	 * This method is called ONLY when the listener decides that the current element and children should be visited.
+	 * Subclasses can override it to react accordingly.
+	 */
+	protected void doScan(CtElement element, ScanningMode mode) {
 		super.scan(element);
 	}
 

src/main/java/spoon/reflect/visitor/chain/CtScannerListener.java

@@ -0,0 +1,42 @@
+/**
+ * Copyright (C) 2006-2017 INRIA and contributors
+ * Spoon - http://spoon.gforge.inria.fr/
+ *
+ * This software is governed by the CeCILL-C License under French law and
+ * abiding by the rules of distribution of free software. You can use, modify
+ * and/or redistribute the software under the terms of the CeCILL-C license as
+ * circulated by CEA, CNRS and INRIA at http://www.cecill.info.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the CeCILL-C License for more details.
+ *
+ * The fact that you are presently reading this means that you have had
+ * knowledge of the CeCILL-C license and that you accept its terms.
+ */
+package spoon.reflect.visitor.chain;
+
+import spoon.reflect.declaration.CtElement;
+
+/**
+ * Responsible for performing an action when a scanner enters/exits a node while scanning the AST.
+ */
+public interface CtScannerListener {
+	/**
+	 * Called before the scanner enters an element
+	 *
+	 * @param element the element about to be scanned.
+	 * @return a {@link ScanningMode} that drives how the scanner processes this element and its children.
+	 * For instance, returning {@link ScanningMode#SKIP_ALL} causes that element and all children to be skipped and {@link #exit(CtElement)} are be NOT called for that element.
+	 */
+	ScanningMode enter(CtElement element);
+
+	/**
+	 * This method is called after the element and all its children have been visited.
+	 * This method is NOT called if an exception is thrown in {@link #enter(CtElement)} or during the scanning of the element or any of its children element.
+	 * This method is NOT called for an element for which {@link #enter(CtElement)} returned {@link ScanningMode#SKIP_ALL}.
+	 *
+	 * @param element the element that has just been scanned.
+	 */
+	void exit(CtElement element);
+}

src/main/java/spoon/reflect/visitor/chain/ScanningMode.java

@@ -0,0 +1,43 @@
+/**
+ * Copyright (C) 2006-2017 INRIA and contributors
+ * Spoon - http://spoon.gforge.inria.fr/
+ *
+ * This software is governed by the CeCILL-C License under French law and
+ * abiding by the rules of distribution of free software. You can use, modify
+ * and/or redistribute the software under the terms of the CeCILL-C license as
+ * circulated by CEA, CNRS and INRIA at http://www.cecill.info.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the CeCILL-C License for more details.
+ *
+ * The fact that you are presently reading this means that you have had
+ * knowledge of the CeCILL-C license and that you accept its terms.
+ */
+package spoon.reflect.visitor.chain;
+
+/**
+ * Defines how a {@link CtScannerListener} drives the scanning of {@link spoon.reflect.visitor.EarlyTerminatingScanner}
+ */
+public enum ScanningMode {
+	/**
+	 * Continue with scanning in a normal way, the current element and all children are visited.
+	 */
+	NORMAL(true, true),
+	/**
+	 * Skip the current element and skip all its children.
+	 */
+	SKIP_ALL(false, false),
+	/**
+	 * Visit current element but skips all its children.
+	 */
+	SKIP_CHILDREN(true, false);
+
+	public final boolean visitElement;
+	public final boolean visitChildren;
+
+	ScanningMode(boolean visitElement, boolean visitChildren) {
+		this.visitElement = visitElement;
+		this.visitChildren = visitChildren;
+	}
+}