You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by dk...@apache.org on 2016/09/16 14:27:42 UTC
tinkerpop git commit: Added documentation for the traversal
representations of general steps (map, flatMap, filter, sideEffect, branch).
Repository: tinkerpop
Updated Branches:
refs/heads/TINKERPOP-1115 [created] 54c08a7ff
Added documentation for the traversal representations of general steps (map, flatMap, filter, sideEffect, branch).
Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo
Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/54c08a7f
Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/54c08a7f
Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/54c08a7f
Branch: refs/heads/TINKERPOP-1115
Commit: 54c08a7ff68e08f8c1f8b9f850086260e39d1b2d
Parents: 75baf01
Author: Daniel Kuppitz <da...@hotmail.com>
Authored: Fri Sep 16 16:26:19 2016 +0200
Committer: Daniel Kuppitz <da...@hotmail.com>
Committed: Fri Sep 16 16:26:19 2016 +0200
----------------------------------------------------------------------
docs/src/reference/the-traversal.asciidoc | 49 ++++++++++++++++----------
1 file changed, 30 insertions(+), 19 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/54c08a7f/docs/src/reference/the-traversal.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/reference/the-traversal.asciidoc b/docs/src/reference/the-traversal.asciidoc
index 9309e23..3530be3 100644
--- a/docs/src/reference/the-traversal.asciidoc
+++ b/docs/src/reference/the-traversal.asciidoc
@@ -55,27 +55,27 @@ for an anonymous traversal, it is possible to simply write `inE()`. Be aware of
when using anonymous traversals. For example, `in` and `as` are reserved keywords in Groovy, therefore you must use
the verbose syntax `__.in()` and `__.as()` to avoid collisions.
-[[lambda-steps]]
-Lambda Steps
-~~~~~~~~~~~~
-
-WARNING: Lambda steps are presented for educational purposes as they represent the foundational constructs of the
-Gremlin language. In practice, lambda steps should be avoided and traversal verification strategies exist to disallow t
-heir use unless explicitly "turned off." For more information on the problems with lambdas, please read
-<<a-note-on-lambdas,A Note on Lambdas>>.
+[[general-steps]]
+General Steps
+~~~~~~~~~~~~~
-There are four generic steps by which all other specific steps described later extend.
+There are five general steps, each having a traversal and a lambda representation, by which all other specific steps described later extend.
[width="100%",cols="10,12",options="header"]
|=========================================================
| Step| Description
-| `map(Function<Traverser<S>, E>)` | map the traverser to some object of type `E` for the next step to process.
-| `flatMap(Function<Traverser<S>, Iterator<E>>)` | map the traverser to an iterator of `E` objects that are streamed to the next step.
-| `filter(Predicate<Traverser<S>>)` | map the traverser to either true or false, where false will not pass the traverser to the next step.
-| `sideEffect(Consumer<Traverser<S>>)` | perform some operation on the traverser and pass it to the next step.
-| `branch(Function<Traverser<S>,M>)` | split the traverser to all the traversals indexed by the `M` token.
+| `map(Traversal<S, E>)` <br> `map(Function<Traverser<S>, E>)` | map the traverser to some object of type `E` for the next step to process.
+| `flatMap(Traversal<S, E>)` <br> `flatMap(Function<Traverser<S>, Iterator<E>>)` | map the traverser to an iterator of `E` objects that are streamed to the next step.
+| `filter(Traversal<?, ?>)` <br> `filter(Predicate<Traverser<S>>)` | map the traverser to either true or false, where false will not pass the traverser to the next step.
+| `sideEffect(Traversal<S, S>)` <br> `sideEffect(Consumer<Traverser<S>>)` | perform some operation on the traverser and pass it to the next step.
+| `branch(Traversal<S, M>)` <br> `branch(Function<Traverser<S>,M>)` | split the traverser to all the traversals indexed by the `M` token.
|=========================================================
+WARNING: Lambda steps are presented for educational purposes as they represent the foundational constructs of the
+Gremlin language. In practice, lambda steps should be avoided in favor of their traversals representation and traversal
+verification strategies exist to disallow their use unless explicitly "turned off." For more information on the problems
+with lambdas, please read <<a-note-on-lambdas,A Note on Lambdas>>.
+
The `Traverser<S>` object provides access to:
. The current traversed `S` object -- `Traverser.get()`.
@@ -92,43 +92,54 @@ image:map-lambda.png[width=150,float=right]
----
g.V(1).out().values('name') <1>
g.V(1).out().map {it.get().value('name')} <2>
+g.V(1).out().map(values('name')) <3>
----
<1> An outgoing traversal from vertex 1 to the name values of the adjacent vertices.
<2> The same operation, but using a lambda to access the name property values.
+<3> Again the same operation, but using the traversal representation of `map()`.
image:filter-lambda.png[width=160,float=right]
[gremlin-groovy,modern]
----
g.V().filter {it.get().label() == 'person'} <1>
-g.V().hasLabel('person') <2>
+g.V().filter(label().is('person')) <2>
+g.V().hasLabel('person') <3>
----
<1> A filter that only allows the vertex to pass if it has an age-property.
-<2> The more specific `has()`-step is implemented as a `filter()` with respective predicate.
+<2> The same operation, but using the traversal represention of `filter()`.
+<3> The more specific `has()`-step is implemented as a `filter()` with respective predicate.
image:side-effect-lambda.png[width=175,float=right]
[gremlin-groovy,modern]
----
g.V().hasLabel('person').sideEffect(System.out.&println) <1>
+g.V().sideEffect(outE().count().store("o")).
+ sideEffect(inE().count().store("i")).cap("o","i") <2>
----
<1> Whatever enters `sideEffect()` is passed to the next step, but some intervening process can occur.
+<2> Compute the out- and in-degree for each vertex. Both `sideEffect()` are fed with the same vertex.
image:branch-lambda.png[width=180,float=right]
[gremlin-groovy,modern]
----
-g.V().branch(values('name')).
+g.V().branch {it.get().value('name')}.
option('marko', values('age')).
option(none, values('name')) <1>
+g.V().branch(values('name')).
+ option('marko', values('age')).
+ option(none, values('name')) <2>
g.V().choose(has('name','marko'),
values('age'),
- values('name')) <2>
+ values('name')) <3>
----
<1> If the vertex is "marko", get his age, else get the name of the vertex.
-<2> The more specific boolean-based `choose()`-step is implemented as a `branch()`.
+<2> The same operation, but using the traversal represention of `branch()`.
+<3> The more specific boolean-based `choose()`-step is implemented as a `branch()`.
[[addedge-step]]
AddEdge Step
Re: tinkerpop git commit: Added documentation for the traversal representations of general steps (map, flatMap, filter, sideEffect, branch).
Posted by Marko Rodriguez <ok...@gmail.com>.
Hey Kuppitz,
Thank you for this. These are very nice additions.
In general people, one of the best things you can do to help is add little snippet PRs to our docs.
“This example doesn’t show the full power of this step, I’ll add another example.”
“I think there should be more verbage about strategies — why is explain() not mentioned and linked to in the traversal strategies section?”
“…”
Like a Wiki, many micro additions will build up nicely to leave our users a full, well-rounded reference doc.
Thanks,
Marko.
http://markorodriguez.com
> On Sep 16, 2016, at 8:27 AM, dkuppitz@apache.org wrote:
>
> Repository: tinkerpop
> Updated Branches:
> refs/heads/TINKERPOP-1115 [created] 54c08a7ff
>
>
> Added documentation for the traversal representations of general steps (map, flatMap, filter, sideEffect, branch).
>
>
> Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo
> Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/54c08a7f
> Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/54c08a7f
> Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/54c08a7f
>
> Branch: refs/heads/TINKERPOP-1115
> Commit: 54c08a7ff68e08f8c1f8b9f850086260e39d1b2d
> Parents: 75baf01
> Author: Daniel Kuppitz <da...@hotmail.com>
> Authored: Fri Sep 16 16:26:19 2016 +0200
> Committer: Daniel Kuppitz <da...@hotmail.com>
> Committed: Fri Sep 16 16:26:19 2016 +0200
>
> ----------------------------------------------------------------------
> docs/src/reference/the-traversal.asciidoc | 49 ++++++++++++++++----------
> 1 file changed, 30 insertions(+), 19 deletions(-)
> ----------------------------------------------------------------------
>
>
> http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/54c08a7f/docs/src/reference/the-traversal.asciidoc
> ----------------------------------------------------------------------
> diff --git a/docs/src/reference/the-traversal.asciidoc b/docs/src/reference/the-traversal.asciidoc
> index 9309e23..3530be3 100644
> --- a/docs/src/reference/the-traversal.asciidoc
> +++ b/docs/src/reference/the-traversal.asciidoc
> @@ -55,27 +55,27 @@ for an anonymous traversal, it is possible to simply write `inE()`. Be aware of
> when using anonymous traversals. For example, `in` and `as` are reserved keywords in Groovy, therefore you must use
> the verbose syntax `__.in()` and `__.as()` to avoid collisions.
>
> -[[lambda-steps]]
> -Lambda Steps
> -~~~~~~~~~~~~
> -
> -WARNING: Lambda steps are presented for educational purposes as they represent the foundational constructs of the
> -Gremlin language. In practice, lambda steps should be avoided and traversal verification strategies exist to disallow t
> -heir use unless explicitly "turned off." For more information on the problems with lambdas, please read
> -<<a-note-on-lambdas,A Note on Lambdas>>.
> +[[general-steps]]
> +General Steps
> +~~~~~~~~~~~~~
>
> -There are four generic steps by which all other specific steps described later extend.
> +There are five general steps, each having a traversal and a lambda representation, by which all other specific steps described later extend.
>
> [width="100%",cols="10,12",options="header"]
> |=========================================================
> | Step| Description
> -| `map(Function<Traverser<S>, E>)` | map the traverser to some object of type `E` for the next step to process.
> -| `flatMap(Function<Traverser<S>, Iterator<E>>)` | map the traverser to an iterator of `E` objects that are streamed to the next step.
> -| `filter(Predicate<Traverser<S>>)` | map the traverser to either true or false, where false will not pass the traverser to the next step.
> -| `sideEffect(Consumer<Traverser<S>>)` | perform some operation on the traverser and pass it to the next step.
> -| `branch(Function<Traverser<S>,M>)` | split the traverser to all the traversals indexed by the `M` token.
> +| `map(Traversal<S, E>)` <br> `map(Function<Traverser<S>, E>)` | map the traverser to some object of type `E` for the next step to process.
> +| `flatMap(Traversal<S, E>)` <br> `flatMap(Function<Traverser<S>, Iterator<E>>)` | map the traverser to an iterator of `E` objects that are streamed to the next step.
> +| `filter(Traversal<?, ?>)` <br> `filter(Predicate<Traverser<S>>)` | map the traverser to either true or false, where false will not pass the traverser to the next step.
> +| `sideEffect(Traversal<S, S>)` <br> `sideEffect(Consumer<Traverser<S>>)` | perform some operation on the traverser and pass it to the next step.
> +| `branch(Traversal<S, M>)` <br> `branch(Function<Traverser<S>,M>)` | split the traverser to all the traversals indexed by the `M` token.
> |=========================================================
>
> +WARNING: Lambda steps are presented for educational purposes as they represent the foundational constructs of the
> +Gremlin language. In practice, lambda steps should be avoided in favor of their traversals representation and traversal
> +verification strategies exist to disallow their use unless explicitly "turned off." For more information on the problems
> +with lambdas, please read <<a-note-on-lambdas,A Note on Lambdas>>.
> +
> The `Traverser<S>` object provides access to:
>
> . The current traversed `S` object -- `Traverser.get()`.
> @@ -92,43 +92,54 @@ image:map-lambda.png[width=150,float=right]
> ----
> g.V(1).out().values('name') <1>
> g.V(1).out().map {it.get().value('name')} <2>
> +g.V(1).out().map(values('name')) <3>
> ----
>
> <1> An outgoing traversal from vertex 1 to the name values of the adjacent vertices.
> <2> The same operation, but using a lambda to access the name property values.
> +<3> Again the same operation, but using the traversal representation of `map()`.
>
> image:filter-lambda.png[width=160,float=right]
> [gremlin-groovy,modern]
> ----
> g.V().filter {it.get().label() == 'person'} <1>
> -g.V().hasLabel('person') <2>
> +g.V().filter(label().is('person')) <2>
> +g.V().hasLabel('person') <3>
> ----
>
> <1> A filter that only allows the vertex to pass if it has an age-property.
> -<2> The more specific `has()`-step is implemented as a `filter()` with respective predicate.
> +<2> The same operation, but using the traversal represention of `filter()`.
> +<3> The more specific `has()`-step is implemented as a `filter()` with respective predicate.
>
>
> image:side-effect-lambda.png[width=175,float=right]
> [gremlin-groovy,modern]
> ----
> g.V().hasLabel('person').sideEffect(System.out.&println) <1>
> +g.V().sideEffect(outE().count().store("o")).
> + sideEffect(inE().count().store("i")).cap("o","i") <2>
> ----
>
> <1> Whatever enters `sideEffect()` is passed to the next step, but some intervening process can occur.
> +<2> Compute the out- and in-degree for each vertex. Both `sideEffect()` are fed with the same vertex.
>
> image:branch-lambda.png[width=180,float=right]
> [gremlin-groovy,modern]
> ----
> -g.V().branch(values('name')).
> +g.V().branch {it.get().value('name')}.
> option('marko', values('age')).
> option(none, values('name')) <1>
> +g.V().branch(values('name')).
> + option('marko', values('age')).
> + option(none, values('name')) <2>
> g.V().choose(has('name','marko'),
> values('age'),
> - values('name')) <2>
> + values('name')) <3>
> ----
>
> <1> If the vertex is "marko", get his age, else get the name of the vertex.
> -<2> The more specific boolean-based `choose()`-step is implemented as a `branch()`.
> +<2> The same operation, but using the traversal represention of `branch()`.
> +<3> The more specific boolean-based `choose()`-step is implemented as a `branch()`.
>
> [[addedge-step]]
> AddEdge Step
>