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, dkupp...@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 <daniel_kupp...@hotmail.com>
> Authored: Fri Sep 16 16:26:19 2016 +0200
> Committer: Daniel Kuppitz <daniel_kupp...@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
> 

Reply via email to