[jira] [Commented] (TINKERPOP-3178) Clarify choose() with consistent semantics

["ASF GitHub Bot (Jira)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/TINKERPOP-3178?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18011426#comment-18011426 ] 

ASF GitHub Bot commented on TINKERPOP-3178:
-------------------------------------------

spmallette commented on code in PR #3170:
URL: https://github.com/apache/tinkerpop/pull/3170#discussion_r2247883780


##########
docs/src/dev/provider/gremlin-semantics.asciidoc:
##########
@@ -1145,6 +1146,77 @@ 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 is
+filtered, but, for these cases, the `Pick.none` option can be provided to match those cases. If the choiceTraversal is
+unproductive, then the traverser passes through by default or can be matched on `Pick.unproductive`.

Review Comment:
   after sleeping on it, i decided to change it. works as you suggested:
   
   ```
   gremlin> g.V().hasLabel('person').
   ......1>       choose(values('age')).
   ......2>         option(27, __.in().values('name')).
   ......3>         option(32, __.out().values('name')).
   ......4>         option(Pick.none, none()) 
   ==>marko
   ==>ripple
   ==>lop
   ```
   
   I think i like how that looks explicitly there. no convoluted explanations come with that.





> Clarify choose() with consistent semantics
> ------------------------------------------
>
>                 Key: TINKERPOP-3178
>                 URL: https://issues.apache.org/jira/browse/TINKERPOP-3178
>             Project: TinkerPop
>          Issue Type: Improvement
>          Components: process
>    Affects Versions: 3.7.3
>            Reporter: Stephen Mallette
>            Priority: Major
>              Labels: breaking
>
> h3. Match only a single case in {{choose()}}
> {code}
> gremlin> g.V().hasLabel('person').choose(values('age')).option(27, constant('x')).option(27, constant('y')).option(none, constant('z'))
> ==>z
> ==>x
> ==>y
> ==>z
> ==>z
> {code}
> There should be only 4 results above, one for each person, but {{choose}} is matching twice on 27.  {{choose}} should match the first item it finds only and no fall through. 
> h3. Consistent behavior for unmatched inputs
> {code}
> // This passes through unmatched inputs
> g.V().choose(values('age'), values('age'))
> ==>29
> ==>27
> ==>v[3]
> ==>32
> ==>v[5]
> ==>35
> // This throws exception for unmatched inputs  
> g.V().choose(values('age')).option(27, out()).option(none, in()).path()
> The provided traverser does not map to a value: v[3][TinkerVertex]->[PropertiesStep([age],value)][DefaultGraphTraversal] parent[[TinkerGraphStep(vertex,[]), ChooseStep([PropertiesStep([age],value)],[[none, [[VertexStep(IN,vertex), EndStep]]], [(eq(27)), [VertexStep(OUT,vertex), EndStep]]]), PathStep]]
> {code}
> Change the switch form to behave like the if-then form.



--
This message was sent by Atlassian Jira
(v8.20.10#820010)