Merge branch 'tp32'
Conflicts:
docs/src/reference/the-traversal.asciidoc
Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo
Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/abfa44fc
Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/abfa44fc
Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/abfa44fc
Branch: refs/heads/master
Commit: abfa44fced98d123e47203792c2f31d66e6734cf
Parents: b86b183 df3d6d7
Author: Stephen Mallette <[email protected]>
Authored: Fri Feb 2 14:21:40 2018 -0500
Committer: Stephen Mallette <[email protected]>
Committed: Fri Feb 2 14:21:40 2018 -0500
----------------------------------------------------------------------
docs/src/reference/the-traversal.asciidoc | 422 ++++++++++++++++++++++++-
1 file changed, 413 insertions(+), 9 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/abfa44fc/docs/src/reference/the-traversal.asciidoc
----------------------------------------------------------------------
diff --cc docs/src/reference/the-traversal.asciidoc
index 0376255,a7b1e29..1139306
--- a/docs/src/reference/the-traversal.asciidoc
+++ b/docs/src/reference/the-traversal.asciidoc
@@@ -214,9 -210,11 +214,14 @@@ g.addE('knows').from(marko).to(peter) <
<4> The newly created edge is a traversable object.
<5> Two arbitrary bindings in a traversal can be joined `from()`->`to()`,
where `id` can be provided for graphs that
supports user provided ids.
+<6> Add an edge between marko and peter given the directed (detached) vertex
references.
+<7> Add an edge between marko and peter given the directed (detached) vertex
references.
+ *Additional References*
+
-link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#addE-java.lang.String-[`addEdge(String)`]
++link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#addE-java.lang.String-[`addEdge(String)`],
++link:http://tinkerpop.apache.org/javadocs/3.3.2-SNAPSHOT/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#addE-org.apache.tinkerpop.gremlin.process.traversal.Traversal-[`addE(Traversal)`]
+
[[addvertex-step]]
=== AddVertex Step
@@@ -232,6 -230,11 +237,12 @@@ g.V().has('name','nothing'
g.V().has('name','nothing').bothE()
----
+ *Additional References*
+
+
link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#addV--[`addV()`],
-link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#addV-java.lang.String-[`addV(String)`])
++link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#addV-java.lang.String-[`addV(String)`]),
++link:http://tinkerpop.apache.org/javadocs/3.3.2-SNAPSHOT/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#addV-org.apache.tinkerpop.gremlin.process.traversal.Traversal-[`addV(Traversal)`]
+
[[addproperty-step]]
=== AddProperty Step
@@@ -345,6 -361,10 +369,10 @@@ g.V().hasLabel('software').as('a','b','
by(__.in('created').values('name').fold())
----
+ *Additional References*
+
-link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#as-java.lang.String-java.lang.String...-[`as(String...)`]
++link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#as-java.lang.String-java.lang.String...-[`as(String,
String...)`]
+
[[barrier-step]]
=== Barrier Step
@@@ -521,6 -576,10 +584,10 @@@ g.V(1).property('nickname', 'okram'
g.V().hasLabel('person').coalesce(values('nickname'), values('name'))
----
+ *Additional References*
+
-link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#coalesce-org.apache.tinkerpop.gremlin.process.traversal.Traversal...-[`coalesce(Traversal)`]
++link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#coalesce-org.apache.tinkerpop.gremlin.process.traversal.Traversal...-[`coalesce(Traversal...)`]
+
[[coin-step]]
=== Coin Step
@@@ -731,6 -833,11 +841,12 @@@ means by which they are added. The gene
The list of steps that support `from()`-modulation are:
<<simplepath-step,`simplePath()`>>, <<cyclicpath-step,`cyclicPath()`>>,
<<path-step,`path()`>>, and <<addedge-step,`addE()`>>.
+ *Additional References*
+
+
link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#from-java.lang.String-[`from(String)`],
-link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#from-org.apache.tinkerpop.gremlin.process.traversal.Traversal-[`from(Traversal)`]
++link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#from-org.apache.tinkerpop.gremlin.process.traversal.Traversal-[`from(Traversal)`],
++link:http://tinkerpop.apache.org/javadocs/3.3.2-SNAPSHOT/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#from-org.apache.tinkerpop.gremlin.structure.Vertex-[`from(Vertex)`]
+
[[group-step]]
=== Group Step
@@@ -893,6 -1056,27 +1065,27 @@@ g.V().where(__.in('created').values('ag
<2> Find projects having two or more contributors.
<3> Find projects whose contributors average age is between 30 and 35.
+ *Additional References*
+
+
link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#is-java.lang.Object-[`is(Object)`],
+
link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#is-org.apache.tinkerpop.gremlin.process.traversal.P-[`is(P)`],
-link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/P.html[`P`]
++link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/P.html[`P`]
+
+ [[key-step]]
+ === Key Step
+
+ The `key()`-step (*map*) takes a `Property` and extracts the key from it.
+
+ [gremlin-groovy,theCrew]
+ ----
+ g.V(1).properties().key()
+ g.V(1).properties().properties().key()
+ ----
+
+ *Additional References*
+
+
link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#key--[`key()`]
+
[[label-step]]
=== Label Step
@@@ -1212,50 -1404,10 +1412,58 @@@ system to leverage the filter for inde
IMPORTANT: A `where()`-step is a filter and thus, variables within a
`where()` clause are not globally bound to the
path of the traverser in `match()`. As such, `where()`-steps in `match()` are
used for filtering, not binding.
+ *Additional References*
+
+
link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#match-org.apache.tinkerpop.gremlin.process.traversal.Traversal...-[`match(Traversal...)`]
+
+[[math-step]]
+=== Math Step
+
+The `math()`-step (*math*) enables scientific calculator functionality within
Gremlin. This step deviates from the common
+function composition and nesting formalisms to provide an easy to read
string-based math processor. Variables within the
+equation map to scopes in Gremlin -- e.g. path labels, side-effects, or
incoming map keys. This step supports
+`by()`-modulation where the `by()`-modulators are applied in the order in
which the variables are first referenced
+within the equation. Note that the reserved variable `_` refers to the
current numeric traverser object incoming to the
+`math()`-step.
+
+[gremlin-groovy,modern]
+----
+g.V().as('a').out('knows').as('b').math('a + b').by('age')
+g.V().as('a').out('created').as('b').
+ math('b + a').
+ by(both().count().math('_ + 100')).
+ by('age')
+g.withSideEffect('x',10).V().values('age').math('_ / x')
+g.withSack(1).V(1).repeat(sack(sum).by(constant(1))).times(10).emit().sack().math('sin
_')
+----
+
+The operators supported by the calculator include: `*`, `+`, `\`, `^`, and
`%`.
+Furthermore, the following built in functions are provided:
+
+* `abs`: absolute value
+* `acos`: arc cosine
+* `asin`: arc sine
+* `atan`: arc tangent
+* `cbrt`: cubic root
+* `ceil`: nearest upper integer
+* `cos`: cosine
+* `cosh`: hyperbolic cosine
+* `exp`: euler's number raised to the power (`e^x`)
+* `floor`: nearest lower integer
+* `log`: logarithmus naturalis (base e)
+* `log10`: logarithm (base 10)
+* `log2`: logarithm (base 2)
+* `sin`: sine
+* `sinh`: hyperbolic sine
+* `sqrt`: square root
+* `tan`: tangent
+* `tanh`: hyperbolic tangent
+* `signum`: signum function
+
++*Additional References*
++
++link:http://tinkerpop.apache.org/javadocs/3.3.2-SNAPSHOT/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#math-java.lang.String-[`math(String)`]
++
[[max-step]]
=== Max Step
@@@ -1316,7 -1486,11 +1542,11 @@@ g.V().hasLabel('person')
----
<1> josh created two projects and vadas none
-
+
+ *Additional References*
+
+
link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#not-org.apache.tinkerpop.gremlin.process.traversal.Traversal-[`not(Traversal)`]
+
[[option-step]]
=== Option Step
@@@ -1529,8 -1727,12 +1783,12 @@@ path.
path.b
path.c
path.d == path.e
-----
+----
+ *Additional References*
+
+
link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#path--[`path()`]
+
[[peerpressure-step]]
=== PeerPressure Step
@@@ -2109,34 -2361,10 +2417,44 @@@ g.V('A').as('a')
<3> Traverse all acyclic 3-hop paths starting from vertex `A` and from there
again all 3-hop paths. The second path may
cross the vertices from the first path.
+ *Additional References*
+
+
link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#simplePath--[`simplePath()`]
+
+[[skip-step]]
+=== Skip Step
+
+The `skip()`-step is analogous to <<range-step,`range()`-step>> save that the
higher end range is set to -1.
+
+[gremlin-groovy,modern]
+----
+g.V().values('age').order()
+g.V().values('age').order().skip(2)
+g.V().values('age').order().range(2, -1)
+----
+
+The `skip()`-step can also be applied with `Scope.local`, in which case it
operates on the incoming collection.
+
+[gremlin-groovy,modern]
+----
+g.V().hasLabel('person').filter(outE('created')).as('p'). <1>
+ map(out('created').values('name').fold()).
+ project('person','primary','other').
+ by(select('p').by('name')).
+ by(limit(local, 1)). <2>
+ by(skip(local, 1)) <3>
+----
+
+<1> For each person who created something...
+<2> ...select the first project (random order) as `primary` and...
+<3> ...select all other projects as `other`.
+
++*Additional References*
++
++link:http://tinkerpop.apache.org/javadocs/3.3.2-SNAPSHOT/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#skip-long-[`skip(long)`],
++link:http://tinkerpop.apache.org/javadocs/3.3.2-SNAPSHOT/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#skip-org.apache.tinkerpop.gremlin.process.traversal.Scope-long-[`skip(Scope,long)`],
++link:http://tinkerpop.apache.org/javadocs/3.3.2-SNAPSHOT/core/org/apache/tinkerpop/gremlin/process/traversal/Scope.html[`Scope`]
++
[[store-step]]
=== Store Step
@@@ -2255,6 -2497,13 +2587,14 @@@ g.V().valueMap().tail(local) <4
<3> `List<String>` for each path containing the last two names from the 'a'
step.
<4> `Map<String, Object>` for each vertex, but containing only the last
property value.
+ *Additional References*
+
-link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#tail--[`tail(long)`],
-link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#tail-long-[`tail(Scope)`],
-link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#tail-org.apache.tinkerpop.gremlin.process.traversal.Scope-long-[tail(Scope,long)`]
++link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#tail--[`tail()`],
++link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#tail-long-[`tail(long)`],
++link:http://tinkerpop.apache.org/javadocs/3.3.2-SNAPSHOT/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#tail-org.apache.tinkerpop.gremlin.process.traversal.Scope-[`tail(Scope)`]
++link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#tail-org.apache.tinkerpop.gremlin.process.traversal.Scope-long-[`tail(Scope,long)`]
+
link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/Scope.html[`Scope`]
+
[[timelimit-step]]
=== TimeLimit Step
@@@ -2291,7 -2544,16 +2635,17 @@@ means by which they are added. The gene
The list of steps that support `to()`-modulation are:
<<simplepath-step,`simplePath()`>>, <<cyclicpath-step,`cyclicPath()`>>,
<<path-step,`path()`>>, and <<addedge-step,`addE()`>>.
-
+
+ *Additional References*
+
+
link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#to-org.apache.tinkerpop.gremlin.process.traversal.Traversal-[`to(Direction,String...)`],
+
link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#to-org.apache.tinkerpop.gremlin.process.traversal.Traversal-[`to(String)`],
+
link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#to-org.apache.tinkerpop.gremlin.process.traversal.Traversal-[`to(Traversal)`],
++link:http://tinkerpop.apache.org/javadocs/3.3.2-SNAPSHOT/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#to-org.apache.tinkerpop.gremlin.structure.Vertex-[`to(Vertex)`],
+
link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#toE-org.apache.tinkerpop.gremlin.structure.Direction-java.lang.String...-[`toE(Direction,String)`],
+
link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#toV-org.apache.tinkerpop.gremlin.structure.Direction-[`toV(Direction)`],
-link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/structure/Direction.html[`Direction`]
++link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/structure/Direction.html[`Direction`]
+
[[tree-step]]
=== Tree Step
