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 2017/01/09 14:59:03 UTC
[42/50] tinkerpop git commit: added Terminal Steps section to
the-traversal.asciidoc docs.
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-1545-tp32
Commit: 31ec68a09e41037b73af0512a6e04847af4797c9
Parents: 3064b93
Author: Marko A. Rodriguez <ok...@gmail.com>
Authored: Thu Jan 5 08:33:39 2017 -0700
Committer: Marko A. Rodriguez <ok...@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,