Merge branch '3.8-dev'

Author: spmallette

CHANGELOG.asciidoc

@@ -129,6 +129,11 @@ This release also includes changes from <<release-3-7-XXX, 3.7.XXX>>.
 * Added integer overflow checks.
 * Added missing strategies to the `TraversalStrategies` global cache as well as `CoreImports` in `gremlin-groovy`.
 * Added missing strategies to `strategies.py` in `gremlin-python`.
+* Preferred use of `TokenTraversal` when using `T` with `choose` instead of `LambdaMapTraversal` which treats `T` more abstractly as a `Function`.
+* Preferred use of `is()` when using `P` with `choose` instead of a `PredicateTraverser` which allows `P` to be used more concretely rather than as a `Function`.
+* Changed `choose` to only use the first `option` matched.
+* Added `Pick.unproductive` to allow for matches on unproductive predicates.
+* Changed `choose` to pass through traversers of unproductive predicates and unmatched choices.
 * Updated `OptionsStrategy` in `gremlin-python` to take options directly as keyword arguments.
 * Added static `instance()` method to `ElementIdStrategy` to an instance with the default configuration.
 * Updated `ElementIdStrategy.getConfiguration()` to help with serialization.

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

@@ -827,6 +827,37 @@ Incoming date remains unchanged.
 See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AsDateStep.java[source],
 link:https://tinkerpop.apache.org/docs/x.y.z/reference/#asDate-step[reference]
 
+[[asString-step]]
+=== asString()
+
+*Description:* Returns the value of incoming traverser as strings, or if `Scope.local` is specified, returns each element inside
+incoming list traverser as string.
+
+*Syntax:* `asString()` | `asString(Scope scope)`
+
+[width="100%",options="header"]
+|=========================================================
+|Start Step |Mid Step |Modulated |Domain |Range
+|N |Y |N |`any` |`String`/`List`
+|=========================================================
+
+*Arguments:*
+
+* `scope` - Determines the type of traverser it operates on. Both scopes will operate on the level of individual traversers.
+The `global` scope will operate on individual traverser, casting all (except `null`) to string. The `local` scope will behave like
+`global` for everything except lists, where it will cast individual non-`null` elements inside the list into string and return a
+list of string instead.
+
+Null values from the incoming traverser are not processed and remain as null when returned.
+
+*Exceptions*
+None
+
+See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AsStringGlobalStep.java[source],
+link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AsStringLocalStep.java[source (local)],
+link:https://tinkerpop.apache.org/docs/x.y.z/reference/#asString-step[reference]
+
+
 [[barrier-step]]
 === barrier()
 
@@ -1030,36 +1061,6 @@ None
 See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/sideEffect/SideEffectCapStep.java[source],
 link:https://tinkerpop.apache.org/docs/x.y.z/reference/#cap-step[reference]
 
-[[asString-step]]
-=== asString()
-
-*Description:* Returns the value of incoming traverser as strings, or if `Scope.local` is specified, returns each element inside
-incoming list traverser as string.
-
-*Syntax:* `asString()` | `asString(Scope scope)`
-
-[width="100%",options="header"]
-|=========================================================
-|Start Step |Mid Step |Modulated |Domain |Range
-|N |Y |N |`any` |`String`/`List`
-|=========================================================
-
-*Arguments:*
-
-* `scope` - Determines the type of traverser it operates on. Both scopes will operate on the level of individual traversers.
-The `global` scope will operate on individual traverser, casting all (except `null`) to string. The `local` scope will behave like
-`global` for everything except lists, where it will cast individual non-`null` elements inside the list into string and return a
-list of string instead.
-
-Null values from the incoming traverser are not processed and remain as null when returned.
-
-*Exceptions*
-None
-
-See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AsStringGlobalStep.java[source],
-link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AsStringLocalStep.java[source (local)],
-link:https://tinkerpop.apache.org/docs/x.y.z/reference/#asString-step[reference]
-
 [[call-step]]
 === call()
 
@@ -1145,6 +1146,67 @@ link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/o
 link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/service/ServiceRegistry.java[ServiceRegistry],
 link:https://tinkerpop.apache.org/docs/x.y.z/reference/#call-step[reference]
 
+[[choose-step]]
+=== choose()
+
+*Description:* A branch step that routes the traverser to different paths based on a choice criterion.
+
+*Syntax:* `choose(Traversal|T choice)` | `choose(Traversal|P choice, Traversal trueChoice)` |`choose(Traversal|P choice, Traversal trueChoice, Traversal falseChoice)`
+
+[width="100%",options="header"]
+|=========================================================
+|Start Step |Mid Step |Modulated |Domain |Range
+|N |Y |Y |`any` |`any`
+|=========================================================
+
+*Arguments:*
+
+* `choice` - A `Traversal`, or `T` that produces a value used to determine which option to take. In the `if-then` forms, this value may be a `P` to determine `true` or `false`.
+* `trueChoice` - The traversal to take if the predicate traversal returns a value (has a next element).
+* `falseChoice` - The traversal to take if the predicate traversal returns no value (has no next element).
+
+*Modulation:*
+
+* `option(pickToken, traversalOption)` - Adds a traversal option to the `choose` step. The `pickToken` is matched
+against the result of the choice traversal. The `pickToken` may be a literal value, a predicate `P`, a `Traversal`
+(whose first returned value is used for matching) or a `Pick` enum value. If a match is found, the traverser is routed
+to the corresponding `traversalOption`.
+
+*Considerations:*
+
+The `choose()` step is a branch step that routes the traverser to different paths based on a choice criterion. There are
+two main forms of the `choose()` step:
+
+1. *if-then form*: `choose(predicate, trueChoice, falseChoice)` - If the predicate traversal or `P` returns a value
+(has a next element), the traverser is routed to the trueChoice traversal. Otherwise, it is routed to the falseChoice
+traversal. If the predicate is unproductive or if the falseChoice is not specified, then the traverser passes through.
+
+2. *switch form*: `choose(choice).option(pickValue, resultTraversal)` - The choice which may be a `Traversal` or
+`T` produces a value that is matched against the pickValue of each option. If a match is found, the traverser is routed
+to the corresponding resultTraversal and no further matches are attempted. If no match is found then the traverser
+passes through by default or can be matched on `Pick.none`. If the choiceTraversal is unproductive, then the traverser
+passes through by default or can be matched on `Pick.unproductive`.
+
+`choose` does not allow more than one traversal to be assigned to a single `Pick`. The first `Pick` assigned via
+`option` is the one that will be used, similar to how the first pickValue match that is found is used.
+
+The `choose()` step ensures that only one option is selected for each traverser, unlike other branch steps like
+`union()` that can route a traverser to multiple paths. As it is like `union()`, note that each `option` stream will
+behave like one:
+
+[gremlin-groovy,modern]
+----
+g.V().union(__.has("name", "vadas").values('age').fold(), __.has('name',neq('vadas')).values('name').fold())
+g.V().choose(__.has("name", "vadas"), __.values('age').fold(), __.values('name').fold())
+----
+
+*Exceptions*
+
+* `IllegalArgumentException` - If `Pick.any` is used as an option token, as only one option per traverser is allowed.
+
+See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/branch/ChooseStep.java[source],
+link:https://tinkerpop.apache.org/docs/x.y.z/reference/#choose-step[reference]
+
 [[combine-step]]
 === combine()
 

docs/src/reference/the-traversal.asciidoc

@@ -1081,24 +1081,33 @@ link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gre
 image::choose-step.png[width=700]
 
 The `choose()`-step (*branch*) routes the current traverser to a particular traversal branch option. With `choose()`,
-it is possible to implement if/then/else-semantics as well as more complicated selections.
+it is possible to implement two different types of semantics: if-then-else (conditional branching) and switch
+(value-based selection).
+
+==== If-Then-Else
+
+The if-the-else semantics of `choose()` evaluate a predicate traversal and route the traverser to either the "true"
+branch or the "false" branch based on the result.
 
 [gremlin-groovy,modern]
 ----
 g.V().hasLabel('person').
       choose(values('age').is(lte(30)),
-        __.in(),
-        __.out()).values('name') <1>
+             __.in(),
+             __.out()).values('name') <1>
 g.V().hasLabel('person').
-      choose(values('age')).
-        option(27, __.in()).
-        option(32, __.out()).values('name') <2>
+      choose(outE('knows').count().is(gt(0)),
+             __.out('knows'),
+             __.identity()).values('name') <2>
 ----
 
-<1> If the traversal yields an element, then do `in`, else do `out` (i.e. true/false-based option selection).
-<2> Use the result of the traversal as a key to the map of traversal options (i.e. value-based option selection).
+<1> If the person's age is less than or equal to 30, then traverse to incoming vertices, else traverse to outgoing
+vertices.
+<2> If the person has outgoing "knows" edges, then traverse to those known vertices, else return the person vertex
+itself.
 
-If the "false"-branch is not provided, then if/then-semantics are implemented.
+If the "false"-branch is not provided, then simple if-then-semantics are implemented, where traversers that don't match
+the condition are passed through unchanged.
 
 [gremlin-groovy,modern]
 ----
@@ -1107,9 +1116,12 @@ g.V().choose(hasLabel('person'), out('created'), identity()).values('name') <2>
 ----
 
 <1> If the vertex is a person, emit the vertices they created, else emit the vertex.
-<2> If/then/else with an `identity()` on the false-branch is equivalent to if/then with no false-branch.
+<2> if-the-else with an `identity()` on the false-branch is equivalent to if-then with no false-branch.
 
-Note that `choose()` can have an arbitrary number of options and moreover, can take an anonymous traversal as its choice function.
+==== Switch
+
+The switch semantics of `choose()` use the result of a traversal as a key to select from multiple traversal options.
+This allows for more complex branching logic beyond simple true/false conditions.
 
 [gremlin-groovy,modern]
 ----
@@ -1118,19 +1130,89 @@ g.V().hasLabel('person').
         option('marko', values('age')).
         option('josh', values('name')).
         option('vadas', elementMap()).
-        option('peter', label())
+        option('peter', label()) <1>
+g.V().hasLabel('person').
+      choose(values('age')).
+        option(27, __.in().values('name')).
+        option(32, __.out().values('name')) <2>
 ----
 
-The `choose()`-step can leverage the `Pick.none` option match. For anything that does not match a specified option, the `none`-option is taken.
+<1> Use the person's name to select which property or operation to return.
+<2> Use the person's age value to select which traversal to apply, noting that traversers matching no age values simply
+pass through.
+
+The `choose()`-step can use predicates with options to match ranges of values or other conditions.
 
 [gremlin-groovy,modern]
 ----
 g.V().hasLabel('person').
-      choose(values('name')).
-        option('marko', values('age')).
-        option(none, values('name'))
+      choose(values('age')).
+        option(P.between(26, 30), constant('younger')).
+        option(P.gt(30), constant('older')).
+        option(Pick.none, constant('unknown')) <1>
+----
+
+<1> If the person's age is between 26 and 30, classify them as 'younger', if greater than 30, classify as 'older',
+otherwise 'unknown'.
+
+The token `T.label` can be used as shorthand for `__.label()` when selecting options based on element labels.
+
+[gremlin-groovy,modern]
+----
+g.V().choose(T.label).
+        option('person', out('created')).
+        option('software', in('created')).
+        values('name') <1>
 ----
 
+<1> For person vertices, traverse to the software they created; for software vertices, traverse to the people who
+created them.
+
+The `Pick` enum was introduced in an example earlier to handle non-matching scenarios. The following `Pick` options may
+be used with `choose()`:
+
+* `Pick.none` - Matches when no other options match
+* `Pick.unproductive` - Matches when the choice in `choose()` produces no results
+
+[gremlin-groovy,modern]
+----
+g.V().choose(values('age')).
+        option(P.between(26, 30), values('name')).
+        option(Pick.none, values('name')).
+        option(Pick.unproductive, label()) <1>
+g.V().hasLabel('person').
+      choose(out('knows').count()).
+        option(0, constant('noFriends')).
+        option(Pick.none, constant('hasFriends')) <2>
+g.V().choose(values('age')).
+        option(27, __.in().values('name')).
+        option(32, __.out().values('name')).
+        option(Pick.unproductive, discard()).
+        option(Pick.none, discard()) <3>
+----
+
+<1> For vertices with age between 26-30, return the name. For vertices with age outside that range, return the name.
+For vertices without an age property, return the label.
+<2> For people with no outgoing "knows" edges, return 'noFriends', otherwise return 'hasFriends'.
+<3> Use `none()` step in combination with `Pick.none` and `Pick.unproductive` to filter unproductive traversals and
+unmatched values.
+
+IMPORTANT: It is important to think of `choose()` as a branching step and not a filter. The if-then semantics can
+intuitively lead to thinking the latter, where no match would mean to remove the traverser from the stream. As shown in
+the examples, this is not what happens.
+
+The `choose()`-step can be used within a `map()` step to apply the branching logic to each element in a collection.
+
+[gremlin-groovy,modern]
+----
+g.V().hasLabel('person').
+      map(choose(values('age')).
+            option(P.between(26, 30), values('name').fold()).
+            option(Pick.none, values('name').fold())) <1>
+----
+
+<1> For each person, create a list containing their name, using the same traversal regardless of age.
+
 *Additional References*
 
 link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#choose(java.util.function.Function)++[`choose(Function)`],