TINKERPOP-3178 choose semantics consistency improvements

Only match on first option for switch semantics. Introduced Pick.unproductive when the choice ends up being unproductive. Pass through unproductive choices for switch semantics so that they are like if-else. Introduce ChooseSemantics enum to inform on whether the step is in if-else or switch form. Lots of documentation improvements.

Author: spmallette

CHANGELOG.asciidoc

@@ -60,6 +60,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

@@ -1077,24 +1077,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]
 ----
@@ -1103,9 +1112,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]
 ----
@@ -1114,19 +1126,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)`],