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