Merge branch '3.8-dev'

Author: Cole-Greer

docs/src/dev/provider/gremlin-semantics.asciidoc

@@ -535,6 +535,12 @@ The `addE()` step can be used as both a start step and a mid-traversal step. Whe
 and `to()` must be specified. When used as a mid-traversal step, the current traverser becomes the source vertex and
 only `to()` needs to be specified.
 
+The gremlin-lang grammar only permits `Traversal` and `String` (alias for `__.select(String)`) arguments in `from()` and
+`to()`. The `Traversal` must either produce a `Vertex` which is attachable to the graph, or it must produce the id of an
+existing `Vertex` in the graph. `GraphTraversal` implementations in GLVs may optionally support `from(Vertex)` and
+`to(Vertex)` as syntactic sugar. If translating to gremlin-lang scripts, these sugared modulators must be converted to
+`from(__.V(vertex.id()))` or `from(__.constant(vertex.id()))` (and equivalents for `to()`).
+
 *Exceptions*
 
 * If the edge label is null, an `IllegalArgumentException` will be thrown.

docs/src/reference/the-traversal.asciidoc

@@ -557,6 +557,7 @@ vMarko = g.V().has('name','marko').next()
 vPeter = g.V().has('name','peter').next()
 g.V(vMarko).addE('knows').to(vPeter) <6>
 g.addE('knows').from(vMarko).to(vPeter) <7>
+g.addE('knows').from(__.V(1)).to(__.constant(6)) <8>
 ----
 
 <1> Add a co-developer edge with a year-property between marko and his collaborators.
@@ -567,6 +568,7 @@ g.addE('knows').from(vMarko).to(vPeter) <7>
 supports user provided ids.
 <6> Add an edge between marko and peter given the directed (detached) vertex references.
 <7> Add an edge between marko and peter given the directed (detached) vertex references.
+<8> Use child traversals producing either a vertex, or vertex id to add an edge between marko and peter.
 
 *Additional References*
 

docs/src/upgrade/release-3.8.x.asciidoc

@@ -737,41 +737,44 @@ after construction. All usages of `P.getOriginalValue()` should be replaced with
 
 A number of changes have been introduced to the Gremlin grammar to help make it be more consistent and easier to use.
 
-*Removed Vertex References for Grammar*
+*Removed StructureVertex from Grammar*
 
 The grammar allowed the construction of a `Vertex` by way of syntax like `new Vertex(1,'person')` (or with similar
 arguments to `ReferenceVertex`). This syntax has been removed as it served little purpose within the grammar as it
 merely adds more characters to wrap around the identifier, which could simply be used by itself.
 
 The `V()` step, as well as the `from()` and `to()` modulators used with `addE()`, previously accepted `Vertex` as
-arguments in the grammar. In its place, the `from()` and `to()` modulators can now directly accept a vertex id in place
-of a `Vertex` when used with `addE()` (`V()` has always accepted ids in addition to vertices). When using these steps in
-`gremlin-lang` scripts, the vertex id must be used directly.
+arguments in the grammar. The `V()` step has always accepted vertex ids as arguments, and continues to do so. The
+`from()` and `to()` modulators for `addE()` continue to accept `String` arguments (which are a shorthand for
+`__.select(String)`), as well as `Traversal` arguments. As always, these `Traversal` arguments may produce `Vertex`
+objects (such as `__.V(1)`) to directly bind to from/to. Newly added in 3.8.0, the `Traversal` may also produce the id
+of a vertex present in the graph (such as `__.constant(1)`), which will then bind to from/to.
 
-This change has no effect on the `GraphTraversal` API, nor on `gremlin-groovy` scripts. Vertices can continue to be used
-directly in those contexts.
+When using these steps in `gremlin-lang` scripts, a `Traversal` or `String` argument must be used directly. This change
+has no effect on the `GraphTraversal` API, nor on `gremlin-groovy` scripts. Vertices can continue to be used directly in
+those contexts.
 
 [source,text]
 ----
-// 3.7.3
+// 3.7.4
 gremlin> v1 = g.V(1).next()
 ==>v[1]
-gremlin> v2 = g.V(2).next()
-==>v[2]
-gremlin> script = String.format("g.V(new Vertex(%s)).outE().where(inV().is(new Vertex(%s)))", v1.id(), v2.id())
-==>g.V(new Vertex(1)).outE().where(inV().is(new Vertex(2)))
+gremlin> v6 = g.V(6).next()
+==>v[6]
+gremlin> script = String.format("g.addE('knows').from(new Vertex(%s)).to(new ReferenceVertex(%s))", v1.id(), v6.id())
+==>g.addE('knows').from(new Vertex(1)).to(new ReferenceVertex(6))
 gremlin> client.submit(script).all().get().get(0).getEdge()
-==>e[7][1-knows->2]
+==>e[0][1-knows->6]
 
 // 3.8.0
 gremlin> v1 = g.V(1).next()
 ==>v[1]
-gremlin> v2 = g.V(2).next()
-==>v[2]
-gremlin> script = String.format("g.V(%s).outE().where(inV().id().is(%s))", v1.id(), v2.id())
-==>g.V(1).outE().where(inV().id().is(2))
+gremlin> v6 = g.V(6).next()
+==>v[6]
+gremlin> script = String.format("g.addE('knows').from(__.V(%s)).to(__.constant(%s))", v1.id(), v6.id())
+==>g.addE('knows').from(__.V(1)).to(__.constant(6))
 gremlin> client.submit(script).all().get().get(0).getEdge()
-==>e[7][1-knows->2]
+==>e[0][1-knows->6]
 ----
 
 *`new` keyword is now optional*

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/language/grammar/DefaultGremlinBaseVisitor.java

@@ -407,10 +407,6 @@ protected void notImplemented(final ParseTree ctx) {
 	 * {@inheritDoc}
 	 */
 	@Override public T visitTraversalMethod_from_String(final GremlinParser.TraversalMethod_from_StringContext ctx) { notImplemented(ctx); return null; }
-	/**
-	 * {@inheritDoc}
-	 */
-	@Override public T visitTraversalMethod_from_GenricArgument(final GremlinParser.TraversalMethod_from_GenricArgumentContext ctx) { return null; }
 	/**
 	 * {@inheritDoc}
 	 */
@@ -839,10 +835,6 @@ protected void notImplemented(final ParseTree ctx) {
 	 * {@inheritDoc}
 	 */
 	@Override public T visitTraversalMethod_to_String(final GremlinParser.TraversalMethod_to_StringContext ctx) { notImplemented(ctx); return null; }
-	/**
-	 * {@inheritDoc}
-	 */
-	@Override public T visitTraversalMethod_to_GenricArgument(final GremlinParser.TraversalMethod_to_GenricArgumentContext ctx) { notImplemented(ctx); return null; }
 	/**
 	 * {@inheritDoc}
 	 */

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/language/grammar/TraversalMethodVisitor.java

@@ -1864,22 +1864,6 @@ public Traversal visitTraversalMethod_option_Predicate_Traversal(final GremlinPa
                 antlr.tvisitor.visitNestedTraversal(ctx.nestedTraversal()));
     }
 
-    /**
-     * {@inheritDoc}
-     */
-    @Override
-    public GraphTraversal visitTraversalMethod_from_GenricArgument(final GremlinParser.TraversalMethod_from_GenricArgumentContext ctx) {
-        return graphTraversal.from(antlr.argumentVisitor.visitGenericArgument(ctx.genericArgument()));
-    }
-
-    /**
-     * {@inheritDoc}
-     */
-    @Override
-    public Traversal visitTraversalMethod_to_GenricArgument(final GremlinParser.TraversalMethod_to_GenricArgumentContext ctx) {
-        return graphTraversal.to(antlr.argumentVisitor.visitGenericArgument(ctx.genericArgument()));
-    }
-
     /**
      * {@inheritDoc}
      */

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.java

@@ -1615,14 +1615,14 @@ public default GraphTraversal<S, E> from(final String fromStepLabel) {
      * @see <a href="http://tinkerpop.apache.org/docs/${project.version}/reference/#addedge-step" target="_blank">Reference Documentation - From Step</a>
      * @since 3.8.0
      */
-    public default GraphTraversal<S, E> from(final GValue<Vertex> fromVertex) {
+    public default GraphTraversal<S, E> from(final GValue<?> fromVertex) {
         final Step<?,?> prev = this.asAdmin().getEndStep();
         if (!(prev instanceof FromToModulating))
             throw new IllegalArgumentException(String.format(
                     "The from() step cannot follow %s", prev.getClass().getSimpleName()));
 
         this.asAdmin().getGremlinLang().addStep(Symbols.from, fromVertex);
-        ((FromToModulating) prev).addFrom(new GValueConstantTraversal<S, Vertex>(fromVertex));
+        ((FromToModulating) prev).addFrom(new GValueConstantTraversal<>(fromVertex));
         return this;
     }
 
@@ -1636,150 +1636,98 @@ public default GraphTraversal<S, E> from(final GValue<Vertex> fromVertex) {
      * @since 3.3.0
      */
     public default GraphTraversal<S, E> from(final Vertex fromVertex) {
-        final Step<?,?> prev = this.asAdmin().getEndStep();
-        if (!(prev instanceof FromToModulating))
-            throw new IllegalArgumentException(String.format(
-                    "The from() step cannot follow %s", prev.getClass().getSimpleName()));
-
-        this.asAdmin().getGremlinLang().addStep(Symbols.from, fromVertex);
-        ((FromToModulating) prev).addFrom(__.constant(fromVertex).asAdmin());
-        return this;
+        return this.from(__.V(fromVertex.id()));
     }
 
     /**
      * When used as a modifier to {@link #addE(String)} this method specifies the traversal to use for selecting the
-     * outgoing vertex of the newly added {@link Edge}.
+     * incoming vertex of the newly added {@link Edge}.
      *
-     * @param fromVertex the traversal for selecting the outgoing vertex
+     * @param toVertex the vertex for selecting the incoming vertex
      * @return the traversal with the modified {@link AddEdgeStepContract}
      * @see <a href="http://tinkerpop.apache.org/docs/${project.version}/reference/#addedge-step" target="_blank">Reference Documentation - From Step</a>
-     * @since 3.1.0-incubating
+     * @since 3.8.0
      */
-    public default GraphTraversal<S, E> from(final Traversal<?, Object> fromVertex) {
+    public default GraphTraversal<S, E> to(final GValue<?> toVertex) {
         final Step<?,?> prev = this.asAdmin().getEndStep();
         if (!(prev instanceof FromToModulating))
             throw new IllegalArgumentException(String.format(
-                    "The from() step cannot follow %s", prev.getClass().getSimpleName()));
+                    "The to() step cannot follow %s", prev.getClass().getSimpleName()));
 
-        this.asAdmin().getGremlinLang().addStep(Symbols.from, fromVertex);
-        ((FromToModulating) prev).addFrom(fromVertex.asAdmin());
+        this.asAdmin().getGremlinLang().addStep(Symbols.to, toVertex);
+        ((FromToModulating) prev).addTo(new GValueConstantTraversal<>(toVertex));
         return this;
     }
 
     /**
      * When used as a modifier to {@link #addE(String)} this method specifies the traversal to use for selecting the
      * incoming vertex of the newly added {@link Edge}.
      *
-     * @param toVertex the vertex for selecting the incoming vertex
+     * @param toVertex the traversal for selecting the incoming vertex
      * @return the traversal with the modified {@link AddEdgeStepContract}
      * @see <a href="http://tinkerpop.apache.org/docs/${project.version}/reference/#addedge-step" target="_blank">Reference Documentation - From Step</a>
-     * @since 3.8.0
+     * @since 3.1.0-incubating
      */
-    public default GraphTraversal<S, E> to(final GValue<Vertex> toVertex) {
+    public default GraphTraversal<S, E> to(final Traversal<?, ?> toVertex) {
         final Step<?,?> prev = this.asAdmin().getEndStep();
         if (!(prev instanceof FromToModulating))
             throw new IllegalArgumentException(String.format(
                     "The to() step cannot follow %s", prev.getClass().getSimpleName()));
 
         this.asAdmin().getGremlinLang().addStep(Symbols.to, toVertex);
-        ((FromToModulating) prev).addTo(new GValueConstantTraversal<S, Vertex>(toVertex));
+        ((FromToModulating) prev).addTo(toVertex.asAdmin());
         return this;
     }
 
     /**
      * When used as a modifier to {@link #addE(String)} this method specifies the traversal to use for selecting the
      * outgoing vertex of the newly added {@link Edge}.
      *
-     * @param fromVertexOrId the vertex for selecting the outgoing vertex
+     * @param fromVertex the traversal for selecting the outgoing vertex
      * @return the traversal with the modified {@link AddEdgeStepContract}
      * @see <a href="http://tinkerpop.apache.org/docs/${project.version}/reference/#addedge-step" target="_blank">Reference Documentation - From Step</a>
-     * @since 3.3.0
-     */
-    public default GraphTraversal<S, E> from(final Object fromVertexOrId) {
-        if (fromVertexOrId instanceof String) {
-            return this.from((String) fromVertexOrId);
-        } else if (fromVertexOrId instanceof Traversal) {
-            this.from((Traversal<?, Object>)fromVertexOrId);
-            return this;
-        }
-        final Step<?,?> prev = this.asAdmin().getEndStep();
-        if (!(prev instanceof FromToModulating))
-            throw new IllegalArgumentException(String.format(
-                    "The from() step cannot follow %s", prev.getClass().getSimpleName()));
-
-        // Convert vertex to id for the purposes of GremlinLang
-        Object fromId = fromVertexOrId instanceof Vertex ? ((Vertex) fromVertexOrId).id() : fromVertexOrId;
-        this.asAdmin().getGremlinLang().addStep(Symbols.from, fromId);
-        ((FromToModulating) prev).addFrom(fromVertexOrId instanceof GValue ?
-                new GValueConstantTraversal<>((GValue<Object>) fromVertexOrId) :
-                __.constant(fromVertexOrId).asAdmin());
-        return this;
-    }
-
-    /**
-     * Provide {@code to()}-modulation to respective steps.
-     *
-     * @param toStepLabel the step label to modulate to.
-     * @return the traversal with the modified {@link FromToModulating} step.
-     * @see <a href="http://tinkerpop.apache.org/docs/${project.version}/reference/#to-step" target="_blank">Reference Documentation - To Step</a>
      * @since 3.1.0-incubating
      */
-    public default GraphTraversal<S, E> to(final String toStepLabel) {
+    public default GraphTraversal<S, E> from(final Traversal<?, ?> fromVertex) {
         final Step<?,?> prev = this.asAdmin().getEndStep();
         if (!(prev instanceof FromToModulating))
             throw new IllegalArgumentException(String.format(
-                    "The to() step cannot follow %s", prev.getClass().getSimpleName()));
+                    "The from() step cannot follow %s", prev.getClass().getSimpleName()));
 
-        this.asAdmin().getGremlinLang().addStep(Symbols.to, toStepLabel);
-        ((FromToModulating) prev).addTo(toStepLabel);
+        this.asAdmin().getGremlinLang().addStep(Symbols.from, fromVertex);
+        ((FromToModulating) prev).addFrom(fromVertex.asAdmin());
         return this;
     }
 
     /**
      * When used as a modifier to {@link #addE(String)} this method specifies the traversal to use for selecting the
      * incoming vertex of the newly added {@link Edge}.
      *
-     * @param toVertex the traversal for selecting the incoming vertex
-     * @return the traversal with the modified {@link AddEdgeStep}
+     * @param toVertex the vertex for selecting the incoming vertex
+     * @return the traversal with the modified {@link AddEdgeStepContract}
      * @see <a href="http://tinkerpop.apache.org/docs/${project.version}/reference/#addedge-step" target="_blank">Reference Documentation - From Step</a>
-     * @since 3.1.0-incubating
+     * @since 3.8.0
      */
-    public default GraphTraversal<S, E> to(final Traversal<?, Object> toVertex) {
-        final Step<?,?> prev = this.asAdmin().getEndStep();
-        if (!(prev instanceof FromToModulating))
-            throw new IllegalArgumentException(String.format(
-                    "The to() step cannot follow %s", prev.getClass().getSimpleName()));
-
-        this.asAdmin().getGremlinLang().addStep(Symbols.to, toVertex);
-        ((FromToModulating) prev).addTo(toVertex.asAdmin());
-        return this;
+     public default GraphTraversal<S, E> to(final Vertex toVertex) {
+        return this.to(__.V(toVertex.id()));
     }
 
     /**
-     * When used as a modifier to {@link #addE(String)} this method specifies the traversal to use for selecting the
-     * incoming vertex of the newly added {@link Edge}.
+     * Provide {@code to()}-modulation to respective steps.
      *
-     * @param toVertexOrId the vertex for selecting the incoming vertex
-     * @return the traversal with the modified {@link AddEdgeStep}
-     * @see <a href="http://tinkerpop.apache.org/docs/${project.version}/reference/#addedge-step" target="_blank">Reference Documentation - From Step</a>
-     * @since 3.3.0
+     * @param toStepLabel the step label to modulate to.
+     * @return the traversal with the modified {@link FromToModulating} step.
+     * @see <a href="http://tinkerpop.apache.org/docs/${project.version}/reference/#to-step" target="_blank">Reference Documentation - To Step</a>
+     * @since 3.1.0-incubating
      */
-    public default GraphTraversal<S, E> to(final Object toVertexOrId) {
-        if (toVertexOrId instanceof String) {
-            return this.to((String) toVertexOrId);
-        } else if (toVertexOrId instanceof Traversal) {
-            this.to((Traversal<?, Object>)toVertexOrId);
-            return this;
-        }
+    public default GraphTraversal<S, E> to(final String toStepLabel) {
         final Step<?,?> prev = this.asAdmin().getEndStep();
         if (!(prev instanceof FromToModulating))
             throw new IllegalArgumentException(String.format(
                     "The to() step cannot follow %s", prev.getClass().getSimpleName()));
 
-        this.asAdmin().getGremlinLang().addStep(Symbols.to, toVertexOrId);
-        ((FromToModulating) prev).addTo(toVertexOrId instanceof GValue ?
-                new GValueConstantTraversal<>((GValue<Object>) toVertexOrId) :
-                __.constant(toVertexOrId).asAdmin());
+        this.asAdmin().getGremlinLang().addStep(Symbols.to, toStepLabel);
+        ((FromToModulating) prev).addTo(toStepLabel);
         return this;
     }
 

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

@@ -20,7 +20,6 @@
 
 import org.apache.tinkerpop.gremlin.process.traversal.Traversal;
 import org.apache.tinkerpop.gremlin.process.traversal.Traverser;
-import org.apache.tinkerpop.gremlin.process.traversal.lambda.ConstantTraversal;
 import org.apache.tinkerpop.gremlin.process.traversal.lambda.GValueConstantTraversal;
 import org.apache.tinkerpop.gremlin.process.traversal.step.GValue;
 import org.apache.tinkerpop.gremlin.process.traversal.step.GValueHolder;

gremlin-core/src/test/java/org/apache/tinkerpop/gremlin/process/traversal/GremlinLangTest.java

@@ -93,7 +93,7 @@ public static Iterable<Object[]> generateTestParameters() {
                 {g.V(1).out("knows").values("name"), "g.V(1).out(\"knows\").values(\"name\")"},
                 {g.V().has(T.label, "person"), "g.V().has(T.label,\"person\")"},
                 {g.addE("knows").from(new DetachedVertex(1, "test1", Collections.emptyList())).to(new DetachedVertex(6, "test2", Collections.emptyList())),
-                        "g.addE(\"knows\").from(1).to(6)"},
+                        "g.addE(\"knows\").from(__.V(1)).to(__.V(6))"},
                 {newG().E(new ReferenceEdge(1, "test label", new ReferenceVertex(1, "v1"), new ReferenceVertex(1, "v1"))),
                         "g.E(_0)"},
                 {g.V().hasId(P.within(Collections.emptyList())).count(), "g.V().hasId(P.within([])).count()"},

gremlin-core/src/test/java/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversalTest.java

@@ -165,7 +165,7 @@ public void shouldExtractIdFromVertex() {
         assertEquals("g.inject(\"foo\").V(1,2)", VMid.asAdmin().getGremlinLang().getGremlin());
 
         GraphTraversal fromTo = g.addE("Edge").from(new ReferenceVertex(1)).to(new ReferenceVertex(2));
-        assertEquals("g.addE(\"Edge\").from(1).to(2)", fromTo.asAdmin().getGremlinLang().getGremlin());
+        assertEquals("g.addE(\"Edge\").from(__.V(1)).to(__.V(2))", fromTo.asAdmin().getGremlinLang().getGremlin());
 
         Map mergeMap = new LinkedHashMap();
         mergeMap.put(T.label, "knows");