[
https://issues.apache.org/jira/browse/TINKERPOP-3178?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18011024#comment-18011024
]
ASF GitHub Bot commented on TINKERPOP-3178:
-------------------------------------------
spmallette commented on code in PR #3170:
URL: https://github.com/apache/tinkerpop/pull/3170#discussion_r2243806888
##########
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:
well, (1) it was always like that 🙂 but (2) i suppose i might say that if
you were unproductive it means the `choose` wasn't even meant for that
traverser, but if it was productive you had matches in mind and if those
weren't satisfied then you'd expect it to fall through to `none` and would
actively capture that.
i'll admit that i thoroughly backed my way into (2) but doesn't sound too
bad??? haha
> 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)
