getScopingInfo utility added

CHANGELOG.asciidoc

@@ -30,6 +30,7 @@ image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima
 [[release-4-0-0-beta-1]]
 === TinkerPop 4.0.0-beta.1 (January 17, 2025)
 
+* Added the `PopContaining` interface designed to get label and `Pop` combinations held in a `PopInstruction` object.
 * Added support for deserialization of `Set` for `gremlin-javascript`.
 * Added grammar-based `Translator` for all languages including explicit ones for Java and anonymization.
 * Removed old `Translator` infrastructure.

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/PopContaining.java

@@ -0,0 +1,103 @@
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you under the Apache License, Version 2.0 (the
+ *  "License"); you may not use this file except in compliance
+ *  with the License.  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License.
+ */
+package org.apache.tinkerpop.gremlin.process.traversal.step;
+
+import java.util.Objects;
+import java.util.Set;
+
+import org.apache.tinkerpop.gremlin.process.traversal.Pop;
+
+/**
+ * The {@code PopContaining} interface is implemented by traversal steps that maintain Pop instructions
+ * for label access. It provides a mechanism to track and manage how labeled elements should
+ * be accessed using {@link Pop} semantics (first, last, all, or mixed).
+ *
+ * In Gremlin traversals, various elements can be labeled and later accessed via these labels.
+ * The {@link Pop} enum determines how to access these labeled elements when there are multiple
+ * values associated with the same label.
+ *
+ * <pre>
+ * {@code
+ * // Simple example with default Pop.last behavior
+ * gremlin> g.V().as("a").out().as("a").select("a")
+ * ==>[v[2]]  // returns the last element labeled "a"
+ *
+ * // Using Pop.first to get the first labeled element
+ * gremlin> g.V().as("a").out().as("a").select(first, "a")
+ * ==>[v[1]]  // returns the first element labeled "a"
+ *
+ * // Using Pop.all to get all labeled elements
+ * gremlin> g.V().as("a").out().as("a").select(all, "a")
+ * ==>[v[1], v[2]]  // returns all elements labeled "a"
+ * }
+ * </pre>
+ *
+ * Steps implementing this interface maintain a collection of {@link PopInstruction} objects, each containing
+ * a label and a {@link Pop} value that specifies how to access elements with that label.
+ *
+ */
+public interface PopContaining {
+    public Set<PopInstruction> getPopInstructions();
+    /**
+     * A class for storing the Scope Context. It has two elements:
+     * - label: String
+     * - pop: Pop value
+     */
+    class PopInstruction {
+        private final Pop pop;
+        private final String label;
+
+        public PopInstruction(String label, Pop pop) {
+            this.pop = pop;
+            this.label = label;
+        }
+
+        public PopInstruction(final Pop pop, final String label) {
+            this.pop = pop;
+            this.label = label;
+        }
+
+        public PopInstruction() {
+           this.pop = null;
+           this.label = "";
+        }
+
+    public String getLabel() {
+            return label;
+        }
+
+        public Pop getPop() {
+            return pop;
+        }
+
+        @Override
+        public boolean equals(Object o) {
+            if (o == null || getClass() != o.getClass()) {
+                return false;
+            }
+            final PopInstruction that = (PopInstruction) o;
+            return getPop() == that.getPop() && Objects.equals(getLabel(), that.getLabel());
+        }
+
+        @Override
+        public int hashCode() {
+            return Objects.hash(getPop(), getLabel());
+        }
+    }
+}

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/Scoping.java

@@ -23,6 +23,7 @@
 import org.apache.tinkerpop.gremlin.process.traversal.Step;
 import org.apache.tinkerpop.gremlin.process.traversal.Traverser;
 
+import java.util.HashSet;
 import java.util.Map;
 import java.util.Set;
 
@@ -105,7 +106,7 @@
  * @author Marko A. Rodriguez (http://markorodriguez.com)
  * @author Stephen Mallette (http://stephen.genoprime.com)
  */
-public interface Scoping {
+public interface Scoping extends PopContaining {
 
     public enum Variable {START, END}
 
@@ -166,6 +167,23 @@ public default <S> S getNullableScopeValue(final Pop pop, final String key, fina
      */
     public Set<String> getScopeKeys();
 
+    /**
+     * Used to get PopInstruction of a Step that implements Scoping. PopInstruction includes the labels it needs, and the
+     * pop type for each label.
+     *
+     * @return A Set of {@link PopInstruction} values which contain the label and Pop value
+     */
+    @Override
+    public default HashSet<PopInstruction> getPopInstructions() {
+        final Set<String> labels = this.getScopeKeys();
+        final HashSet<PopInstruction> scopingInfoSet = new HashSet<>();
+        for (final String label : labels) {
+            final PopInstruction scopingInfo = new PopInstruction(Pop.last, label);
+            scopingInfoSet.add(scopingInfo);
+        }
+        return scopingInfoSet;
+    }
+
     public static class KeyNotFoundException extends Exception {
 
         private final Object key;

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/TraversalParent.java

@@ -21,16 +21,18 @@
 import org.apache.tinkerpop.gremlin.process.traversal.Step;
 import org.apache.tinkerpop.gremlin.process.traversal.Traversal;
 import org.apache.tinkerpop.gremlin.process.traversal.traverser.TraverserRequirement;
+import org.apache.tinkerpop.gremlin.process.traversal.util.TraversalHelper;
 
 import java.util.Collections;
 import java.util.EnumSet;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
 
 /**
  * @author Marko A. Rodriguez (http://markorodriguez.com)
  */
-public interface TraversalParent extends AutoCloseable {
+public interface TraversalParent extends PopContaining, AutoCloseable {
 
     public default <S, E> List<Traversal.Admin<S, E>> getGlobalChildren() {
         return Collections.emptyList();
@@ -95,4 +97,16 @@ default void close() throws Exception {
             traversal.close();
         }
     }
+
+    @Override
+    public default HashSet<PopInstruction> getPopInstructions() {
+        final HashSet<PopInstruction> scopingInfos = new HashSet<>();
+        for (final Traversal.Admin local: this.getLocalChildren()) {
+            scopingInfos.addAll(TraversalHelper.getPopInstructions(local));
+        }
+        for (final Traversal.Admin global: this.getGlobalChildren()) {
+            scopingInfos.addAll(TraversalHelper.getPopInstructions(global));
+        }
+        return scopingInfos;
+    }
 }

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/filter/DedupGlobalStep.java

@@ -189,6 +189,14 @@ public Set<String> getScopeKeys() {
         return null == this.dedupLabels ? Collections.emptySet() : this.dedupLabels;
     }
 
+    @Override
+    public HashSet<PopInstruction> getPopInstructions() {
+        final HashSet<PopInstruction> popInstructions = new HashSet<>();
+        popInstructions.addAll(Scoping.super.getPopInstructions());
+        popInstructions.addAll(TraversalParent.super.getPopInstructions());
+        return popInstructions;
+    }
+
     @Override
     public void processAllStarts() {
 

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/filter/WherePredicateStep.java

@@ -132,6 +132,14 @@ public Set<String> getScopeKeys() {
         return Collections.unmodifiableSet(this.scopeKeys);
     }
 
+    @Override
+    public HashSet<PopInstruction> getPopInstructions() {
+        final HashSet<PopInstruction> popInstructions = new HashSet<>();
+        popInstructions.addAll(Scoping.super.getPopInstructions());
+        popInstructions.addAll(TraversalParent.super.getPopInstructions());
+        return popInstructions;
+    }
+
     @Override
     public WherePredicateStep<S> clone() {
         final WherePredicateStep<S> clone = (WherePredicateStep<S>) super.clone();

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/filter/WhereTraversalStep.java

@@ -147,6 +147,14 @@ public Set<String> getKeepLabels() {
         return this.keepLabels;
     }
 
+    @Override
+    public HashSet<PopInstruction> getPopInstructions() {
+        final HashSet<PopInstruction> popInstructions = new HashSet<>();
+        popInstructions.addAll(Scoping.super.getPopInstructions());
+        popInstructions.addAll(TraversalParent.super.getPopInstructions());
+        return popInstructions;
+    }
+
     //////////////////////////////
 
     public static class WhereStartStep<S> extends ScalarMapStep<S, Object> implements Scoping {

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AddEdgeStartStep.java

@@ -43,6 +43,7 @@
 import org.apache.tinkerpop.gremlin.structure.util.StringFactory;
 import org.apache.tinkerpop.gremlin.structure.util.empty.EmptyGraph;
 
+import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
 
@@ -89,6 +90,13 @@ public Set<String> getScopeKeys() {
         return this.parameters.getReferencedLabels();
     }
 
+    @Override
+    public HashSet<PopInstruction> getPopInstructions() {
+        final HashSet<PopInstruction> popInstructions = new HashSet<>();
+        popInstructions.addAll(TraversalParent.super.getPopInstructions());
+        return popInstructions;
+    }
+
     @Override
     public void configure(final Object... keyValues) {
         this.parameters.set(this, keyValues);

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AddEdgeStep.java

@@ -40,6 +40,7 @@
 import org.apache.tinkerpop.gremlin.structure.util.StringFactory;
 import org.apache.tinkerpop.gremlin.structure.util.empty.EmptyGraph;
 
+import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
 
@@ -86,6 +87,13 @@ public Set<String> getScopeKeys() {
         return this.parameters.getReferencedLabels();
     }
 
+    @Override
+    public HashSet<PopInstruction> getPopInstructions() {
+        final HashSet<PopInstruction> popInstructions = new HashSet<>();
+        popInstructions.addAll(TraversalParent.super.getPopInstructions());
+        return popInstructions;
+    }
+
     @Override
     public void configure(final Object... keyValues) {
         this.parameters.set(this, keyValues);

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AddVertexStartStep.java

@@ -38,6 +38,7 @@
 import org.apache.tinkerpop.gremlin.structure.Vertex;
 import org.apache.tinkerpop.gremlin.structure.util.StringFactory;
 
+import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
 
@@ -85,6 +86,13 @@ public Set<String> getScopeKeys() {
         return this.parameters.getReferencedLabels();
     }
 
+    @Override
+    public HashSet<PopInstruction> getPopInstructions() {
+        final HashSet<PopInstruction> popInstructions = new HashSet<>();
+        popInstructions.addAll(TraversalParent.super.getPopInstructions());
+        return popInstructions;
+    }
+
     @Override
     public <S, E> List<Traversal.Admin<S, E>> getLocalChildren() {
         return this.parameters.getTraversals();

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AddVertexStep.java

@@ -34,6 +34,7 @@
 import org.apache.tinkerpop.gremlin.structure.Vertex;
 import org.apache.tinkerpop.gremlin.structure.util.StringFactory;
 
+import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
 
@@ -78,6 +79,13 @@ public Set<String> getScopeKeys() {
         return this.parameters.getReferencedLabels();
     }
 
+    @Override
+    public HashSet<PopInstruction> getPopInstructions() {
+        final HashSet<PopInstruction> popInstructions = new HashSet<>();
+        popInstructions.addAll(TraversalParent.super.getPopInstructions());
+        return popInstructions;
+    }
+
     @Override
     public <S, E> List<Traversal.Admin<S, E>> getLocalChildren() {
         return this.parameters.getTraversals();

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/FormatStep.java

@@ -34,6 +34,7 @@
 import org.apache.tinkerpop.gremlin.structure.Property;
 import org.apache.tinkerpop.gremlin.structure.util.StringFactory;
 
+import java.util.HashSet;
 import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Objects;
@@ -168,6 +169,14 @@ public Set<String> getScopeKeys() {
         return variables;
     }
 
+    @Override
+    public HashSet<PopInstruction> getPopInstructions() {
+        final HashSet<PopInstruction> popInstructions = new HashSet<>();
+        popInstructions.addAll(Scoping.super.getPopInstructions());
+        popInstructions.addAll(TraversalParent.super.getPopInstructions());
+        return popInstructions;
+    }
+
     @Override
     public void setKeepLabels(final Set<String> labels) {
         this.keepLabels = labels;

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/MatchStep.java

@@ -218,6 +218,14 @@ public Set<String> getScopeKeys() {
         return this.scopeKeys;
     }
 
+    @Override
+    public HashSet<PopInstruction> getPopInstructions() {
+        final HashSet<PopInstruction> popInstructions = new HashSet<>();
+        popInstructions.addAll(Scoping.super.getPopInstructions());
+        popInstructions.addAll(TraversalParent.super.getPopInstructions());
+        return popInstructions;
+    }
+
     @Override
     public String toString() {
         return StringFactory.stepString(this, this.dedupLabels, this.connective, this.matchTraversals);

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/MathStep.java

@@ -165,6 +165,14 @@ public Set<String> getScopeKeys() {
             return this.expression.getVariables();
     }
 
+    @Override
+    public HashSet<PopInstruction> getPopInstructions() {
+        final HashSet<PopInstruction> popInstructions = new HashSet<>();
+        popInstructions.addAll(Scoping.super.getPopInstructions());
+        popInstructions.addAll(TraversalParent.super.getPopInstructions());
+        return popInstructions;
+    }
+
     @Override
     public void setKeepLabels(final Set<String> labels) {
         this.keepLabels = labels;

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/SelectOneStep.java

@@ -134,6 +134,18 @@ public Set<String> getScopeKeys() {
         return Collections.singleton(this.selectKey);
     }
 
+    @Override
+    public HashSet<PopInstruction> getPopInstructions() {
+        final HashSet<PopInstruction> popInstructions = new HashSet<>();
+        final Set<String> labels = this.getScopeKeys();
+        for (String label : labels) {
+            final PopInstruction scopingInfo = new PopInstruction(this.getPop(), label);
+            popInstructions.add(scopingInfo);
+        }
+        popInstructions.addAll(TraversalParent.super.getPopInstructions());
+        return popInstructions;
+    }
+
     public Pop getPop() {
         return this.pop;
     }