feat: Adds unique serializable path for each CtElement from Root Element.

src/main/java/spoon/reflect/declaration/CtElement.java

@@ -19,6 +19,8 @@
 import spoon.processing.FactoryAccessor;
 import spoon.reflect.code.CtComment;
 import spoon.reflect.cu.SourcePosition;
+import spoon.reflect.path.CtPath;
+import spoon.reflect.path.CtPathException;
 import spoon.reflect.path.CtRole;
 import spoon.reflect.reference.CtTypeReference;
 import spoon.reflect.visitor.CtVisitable;
@@ -349,4 +351,10 @@ <E extends CtElement> List<E> getAnnotatedChildren(
 	 * @param value to be assigned to this field.
 	 */
 	<E extends CtElement, T> E  setValueByRole(CtRole role, T value);
+
+	/**
+	 * Gets a unique path from models root to the CtElement.
+	 */
+	CtPath getPath();
+
 }

src/main/java/spoon/reflect/path/CtElementPathBuilder.java

@@ -0,0 +1,67 @@
+package spoon.reflect.path;
+
+import spoon.reflect.declaration.CtElement;
+import spoon.reflect.declaration.CtNamedElement;
+import spoon.reflect.path.impl.CtPathElement;
+import spoon.reflect.path.impl.CtPathImpl;
+import spoon.reflect.path.impl.CtUniqueRolePathElement;
+import spoon.reflect.reference.CtReference;
+
+import java.util.Collection;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+public class CtElementPathBuilder {
+    public CtPath fromElement(CtElement el, CtElement root) throws CtPathException {
+        CtPathImpl path = new CtPathImpl();
+        CtElement cur = el;
+        while(cur != root) {
+            CtElement parent = cur.getParent();
+            CtRole role = cur.getRoleInParent();
+            if(parent == null || role == null) throw new CtPathException();
+            CtPathElement pathElement = new CtUniqueRolePathElement(role);
+            if(parent.getValueByRole(role) instanceof List) {
+                //Element needs to be differentiated from its brothers
+                List list = parent.getValueByRole(role);
+                //Assumes that List's order is deterministic.
+                int index = 0;
+                for(Object o : list) {
+                    if(o == cur) break;
+                    index++;
+                }
+                pathElement.addArgument("index", index + "");
+            } else if (parent.getValueByRole(role) instanceof Set){
+                if(!(cur instanceof CtNamedElement) && !(cur instanceof CtReference)) throw new CtPathException();
+                //Element needs to be differentiated from its brothers
+                Set set = parent.getValueByRole(role);
+                String name = null;
+                for(Object o : set) {
+                    if(o == cur) {
+                        if(cur instanceof CtNamedElement)
+                            name = ((CtNamedElement) cur).getSimpleName();
+                        else name = ((CtReference) cur).getSimpleName();
+                        break;
+                    }
+                }
+                if(name == null) throw new CtPathException();
+                else pathElement.addArgument("name", name);
+
+            } else if (parent.getValueByRole(role) instanceof Map){
+                Map map = parent.getValueByRole(role);
+                String key = null;
+                for(Object o : map.keySet()) {
+                    if(map.get(o) == cur) {
+                        key = (String) o;
+                        break;
+                    }
+                }
+                if(key == null) throw new CtPathException();
+                else pathElement.addArgument("key", key);
+            }
+            cur = parent;
+            path.addFirst(pathElement);
+        }
+        return path;
+    }
+}

src/main/java/spoon/reflect/path/CtPathStringBuilder.java

@@ -16,11 +16,7 @@
  */
 package spoon.reflect.path;
 
-import spoon.reflect.path.impl.CtNamedPathElement;
-import spoon.reflect.path.impl.CtPathElement;
-import spoon.reflect.path.impl.CtPathImpl;
-import spoon.reflect.path.impl.CtRolePathElement;
-import spoon.reflect.path.impl.CtTypedNameElement;
+import spoon.reflect.path.impl.*;
 
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
@@ -30,7 +26,7 @@
  */
 public class CtPathStringBuilder {
 
-	private final Pattern pathPattern = Pattern.compile("([/.#])([^/.#\\[]+)(\\[([^/.#]*)\\])?");
+	private final Pattern pathPattern = Pattern.compile("([/.#@])([^/.#@\\[]+)(\\[([^/.#@]*)\\])?");
 	private final Pattern argumentPattern = Pattern.compile("(\\w+)=([^=\\]]+)");
 
 
@@ -66,6 +62,7 @@ private Class load(String name) throws CtPathException {
 	 * . :  match with the given name
 	 * # : match with a CtPathRole
 	 * / : match with a element type (for example, to match all classes, use /CtClass
+	 * @ : match with a CtUniqueRolePath
 	 */
 	public CtPath fromString(String pathStr) throws CtPathException {
 		Matcher matcher = pathPattern.matcher(pathStr);
@@ -81,6 +78,8 @@ public CtPath fromString(String pathStr) throws CtPathException {
 				pathElement = new CtTypedNameElement(load(matcher.group(2)));
 			} else if (CtRolePathElement.STRING.equals(kind)) {
 				pathElement = new CtRolePathElement(CtRole.fromName(matcher.group(2)));
+			} else if (CtUniqueRolePathElement.STRING.equals(kind)) {
+				pathElement = new CtUniqueRolePathElement(CtRole.fromName(matcher.group(2)));
 			}
 
 			String args = matcher.group(4);

src/main/java/spoon/reflect/path/impl/CtPathElement.java

@@ -17,6 +17,7 @@
 package spoon.reflect.path.impl;
 
 import spoon.reflect.declaration.CtElement;
+import spoon.reflect.path.CtPathException;
 
 import java.util.Collection;
 

src/main/java/spoon/reflect/path/impl/CtRolePathElement.java

@@ -20,6 +20,7 @@
 import spoon.reflect.declaration.CtElement;
 import spoon.reflect.declaration.CtExecutable;
 import spoon.reflect.declaration.CtField;
+import spoon.reflect.path.CtPathException;
 import spoon.reflect.path.CtRole;
 import spoon.reflect.visitor.CtInheritanceScanner;
 

src/main/java/spoon/reflect/path/impl/CtUniqueRolePathElement.java

@@ -0,0 +1,66 @@
+package spoon.reflect.path.impl;
+
+import spoon.reflect.declaration.CtElement;
+import spoon.reflect.declaration.CtNamedElement;
+import spoon.reflect.path.CtPathException;
+import spoon.reflect.path.CtRole;
+import spoon.reflect.reference.CtReference;
+
+import java.util.*;
+
+public class CtUniqueRolePathElement extends CtRolePathElement {
+    public static final String STRING = "@";
+
+    public CtUniqueRolePathElement(CtRole role) {
+        super(role);
+    }
+
+    @Override
+    public String toString() {
+        return STRING + getRole().toString() + getParamString();
+    }
+
+    public CtElement getFromSet(Set set, String name) throws CtPathException {
+        for(Object o: set) {
+            if(o instanceof CtNamedElement) {
+                if (((CtNamedElement) o).getSimpleName().equals(name)) return (CtElement) o;
+            } else if(o instanceof CtReference) {
+                if (((CtReference) o).getSimpleName().equals(name)) return (CtElement) o;
+            } else {
+                throw new CtPathException();
+            }
+        }
+        throw new CtPathException();
+    }
+
+    @Override
+    public Collection<CtElement> getElements(Collection<CtElement> roots) {
+        Collection<CtElement> matchs = new LinkedList<>();
+        for (CtElement root : roots) {
+            if(root.getValueByRole(getRole()) instanceof List) {
+                if(getArguments().containsKey("index")) {
+                    int index = Integer.parseInt(getArguments().get("index"));
+                    matchs.add((CtElement) ((List) root.getValueByRole(getRole())).get(index));
+                }
+            } else  if(root.getValueByRole(getRole()) instanceof Set) {
+                if(getArguments().containsKey("name")) {
+                    String name = getArguments().get("name");
+                    try {
+                        matchs.add(getFromSet(root.getValueByRole(getRole()), name));
+                    } catch (Exception e) {
+                        System.err.println("[ERROR] Element not found for name: " + name);
+                    }
+                }
+            } else if(root.getValueByRole(getRole()) instanceof Map) {
+                if(getArguments().containsKey("key")) {
+                    String name = getArguments().get("key");
+                    matchs.add((CtElement) ((Map) root.getValueByRole(getRole())).get(name));
+                }
+            } else {
+                CtElement el = root.getValueByRole(getRole());
+                matchs.add(el);
+            }
+        }
+        return matchs;
+    }
+}

src/main/java/spoon/support/reflect/declaration/CtElementImpl.java

@@ -17,6 +17,7 @@
 package spoon.support.reflect.declaration;
 
 import org.apache.log4j.Logger;
+import spoon.reflect.CtModelImpl;
 import spoon.reflect.annotations.MetamodelPropertyField;
 import spoon.reflect.code.CtComment;
 import spoon.reflect.code.CtJavaDoc;
@@ -31,6 +32,9 @@
 import spoon.reflect.factory.FactoryImpl;
 import spoon.reflect.meta.RoleHandler;
 import spoon.reflect.meta.impl.RoleHandlerHelper;
+import spoon.reflect.path.CtElementPathBuilder;
+import spoon.reflect.path.CtPath;
+import spoon.reflect.path.CtPathException;
 import spoon.reflect.path.CtRole;
 import spoon.reflect.declaration.CtImport;
 import spoon.reflect.reference.CtReference;
@@ -536,4 +540,12 @@ public <E extends CtElement, T> E setValueByRole(CtRole role, T value) {
 		rh.setValue(this, value);
 		return (E) this;
 	}
+
+	public CtPath getPath() {
+		try {
+			return new CtElementPathBuilder().fromElement(this, getParent(CtModelImpl.CtRootPackage.class));
+		} catch (CtPathException e) {
+		}
+		return null;
+	}
 }

src/test/java/spoon/test/main/MainTest.java

@@ -23,7 +23,7 @@
 import spoon.reflect.declaration.CtType;
 import spoon.reflect.declaration.CtTypeParameter;
 import spoon.reflect.declaration.ParentNotInitializedException;
-import spoon.reflect.path.CtRole;
+import spoon.reflect.path.*;
 import spoon.reflect.reference.CtArrayTypeReference;
 import spoon.reflect.reference.CtExecutableReference;
 import spoon.reflect.reference.CtFieldReference;
@@ -40,13 +40,9 @@
 import java.io.PrintStream;
 import java.io.PrintWriter;
 import java.io.StringWriter;
-import java.util.ArrayDeque;
-import java.util.Deque;
-import java.util.HashSet;
-import java.util.IdentityHashMap;
-import java.util.Map;
-import java.util.Set;
+import java.util.*;
 
+import static junit.framework.TestCase.fail;
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertFalse;
 import static org.junit.Assert.assertNotNull;
@@ -439,6 +435,35 @@ public void scan(CtRole role, CtElement element) {
 		});
 	}
 
+	@Test
+	public void testElementToPathToElementEquivalency() {
+
+		List<CtElement> list = new LinkedList<>();
+		list.add(rootPackage);
+
+		rootPackage.accept(new CtScanner() {
+			@Override
+			public void scan(CtRole role, CtElement element) {
+				if (element != null) {
+					CtPath path = element.getPath();
+					String pathStr = path.toString();
+					try {
+						CtPath pathRead = new CtPathStringBuilder().fromString(pathStr);
+						Collection<CtElement> returnedElements = pathRead.evaluateOn(list);
+						//contract: CtUniqueRolePathElement.evaluateOn() returns a unique elements if provided only a list of one inputs
+						assertEquals(returnedElements.size(), 1);
+						CtElement actualElement = (CtElement) returnedElements.toArray()[0];
+						//contract: Element -> Path -> String -> Path -> Element leads to the original element
+						assertEquals(element, actualElement);
+					} catch (CtPathException e) {
+						fail();
+					}
+				}
+				super.scan(role, element);
+			}
+		});
+	}
+
 	@Test
 	public void testTest() throws Exception {
 		// the tests should be spoonable