Repository: tinkerpop Updated Branches: refs/heads/TINKERPOP-1588 [created] 31ec68a09
added Terminal Steps section to the-traversal.asciidoc docs. Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/31ec68a0 Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/31ec68a0 Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/31ec68a0 Branch: refs/heads/TINKERPOP-1588 Commit: 31ec68a09e41037b73af0512a6e04847af4797c9 Parents: 3064b93 Author: Marko A. Rodriguez <okramma...@gmail.com> Authored: Thu Jan 5 08:33:39 2017 -0700 Committer: Marko A. Rodriguez <okramma...@gmail.com> Committed: Thu Jan 5 08:33:39 2017 -0700 ---------------------------------------------------------------------- CHANGELOG.asciidoc | 1 + docs/src/reference/the-traversal.asciidoc | 35 +++++++++++++++++++++++++- 2 files changed, 35 insertions(+), 1 deletion(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/31ec68a0/CHANGELOG.asciidoc ---------------------------------------------------------------------- diff --git a/CHANGELOG.asciidoc b/CHANGELOG.asciidoc index 34e81c4..35b1320 100644 --- a/CHANGELOG.asciidoc +++ b/CHANGELOG.asciidoc @@ -26,6 +26,7 @@ image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima TinkerPop 3.2.4 (Release Date: NOT OFFICIALLY RELEASED YET) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* Added documentation around "terminal steps" in Gremlin: `hasNext()`, `next()`, `toList()`, etc. * Fixed minor bug in `gremlin-driver` where closing a session-based `Client` without initializing it could generate an error. * `TinkerGraph` Gryo and GraphSON deserialization is now configured to use multi-properties. * Changed behavior of `ElementHelper.areEqual(Property, Property)` to not throw exceptions with `null` arguments. http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/31ec68a0/docs/src/reference/the-traversal.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/reference/the-traversal.asciidoc b/docs/src/reference/the-traversal.asciidoc index bbffb0e..52cebf8 100644 --- a/docs/src/reference/the-traversal.asciidoc +++ b/docs/src/reference/the-traversal.asciidoc @@ -141,6 +141,39 @@ g.V().choose(has('name','marko'), <2> The same operation, but using the traversal represention of `branch()`. <3> The more specific boolean-based `choose()`-step is implemented as a `branch()`. +[[terminal-steps]] +Terminal Steps +~~~~~~~~~~~~~~ + +Typically, when a step is concatenated to a traversal a traversal is returned. In this way, a traversal is built up +in a link:https://en.wikipedia.org/wiki/Fluent_interface[fluent], link:https://en.wikipedia.org/wiki/Monoid[monadic] fashion. +However, some steps do not return a traversal, but instead, execute the traversal and return a result. These steps are known +as terminal steps (*terminal*) and they are explained via the examples below. + +[gremlin-groovy,modern] +---- +g.V().out('created').hasNext() <1> +g.V().out('created').next() <2> +g.V().out('created').next(2) <3> +g.V().out('nothing').tryNext() <4> +g.V().out('created').toList() <5> +g.V().out('created').toSet() <6> +g.V().out('created').toBulkSet() <7> +results = ['blah',3] +g.V().out('created').fill(results) <8> +---- + +<1> `hasNext()` determines whether there are available results. +<2> `next()` will return the next result. +<3> `next(n)` will return the next `n` results in a list. +<4> `tryNext()` will return an `Optional` and thus, is a composite of `hasNext()`/`next()`. +<5> `toList()` will return all results in a list. +<6> `toSet()` will return all results in a set (thus, duplicates removed). +<7> `toBulkSet()` will return all results in a weighted set (thus, duplicates preserved via weighting). +<8> `fill(collection)` will put all results in the provided collection and return the collection when complete. + +Finally, <<explain-step,`explain()`>>-step is also a terminal step and is described in its own section. + [[addedge-step]] AddEdge Step ~~~~~~~~~~~~ @@ -607,7 +640,7 @@ g.V() Explain Step ~~~~~~~~~~~~ -The `explain()`-step (*sideEffect*) will return a `TraversalExplanation`. A traversal explanation details how the +The `explain()`-step (*terminal*) will return a `TraversalExplanation`. A traversal explanation details how the traversal (prior to `explain()`) will be compiled given the registered <<traversalstrategy,traversal strategies>>. A `TraversalExplanation` has a `toString()` representation with 3-columns. The first column is the traversal strategy being applied. The second column is the traversal strategy category: [D]ecoration, [O]ptimization,