This is an automated email from the ASF dual-hosted git repository.
spmallette pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
The following commit(s) were added to refs/heads/master by this push:
new 02fbfbf1 Minor adjustments to the language variants tutorial given
restructing of reference docs CTR
02fbfbf1 is described below
commit 02fbfbf1b3a94c7654a5668c0b01ae8952347e9a
Author: Stephen Mallette <[email protected]>
AuthorDate: Thu Dec 20 11:25:36 2018 -0500
Minor adjustments to the language variants tutorial given restructing of
reference docs CTR
---
.../gremlin-language-variants/index.asciidoc | 130 +++++++++++----------
1 file changed, 70 insertions(+), 60 deletions(-)
diff --git a/docs/src/tutorials/gremlin-language-variants/index.asciidoc
b/docs/src/tutorials/gremlin-language-variants/index.asciidoc
index 065657a..d7ab25e 100644
--- a/docs/src/tutorials/gremlin-language-variants/index.asciidoc
+++ b/docs/src/tutorials/gremlin-language-variants/index.asciidoc
@@ -32,15 +32,15 @@ where the `MyApplication` Java class contains both
application-level and databas
image::gremlin-house-of-mirrors.png[width=1024]
-WARNING: This is an advanced tutorial intended for experts knowledgeable in
Gremlin in particular and TinkerPop in general.
-Moreover, the audience should understand advanced programming language
concepts such as reflection, meta-programming,
-source code generation, and virtual machines.
+WARNING: This is an advanced tutorial intended for experts knowledgeable in
Gremlin in particular and TinkerPop in
+general. Moreover, the audience should understand advanced programming
language concepts such as reflection,
+meta-programming, source code generation, and virtual machines.
[source,java]
----
public class MyApplication {
- public static void run(final String[] args) {
+ public static void run(String[] args) {
// assumes args[0] is a configuration file location
Graph graph = GraphFactory.open(args[0]);
@@ -62,8 +62,8 @@ public class MyApplication {
----
In query languages like link:https://en.wikipedia.org/wiki/SQL[SQL], the user
must construct a string representation of
-their query and submit it to the database for evaluation. This is because SQL
cannot be expressed in Java as they use fundamentally
-different constructs in their expression. The same example above is presented
below using SQL and the
+their query and submit it to the database for evaluation. This is because SQL
cannot be expressed in Java as they use
+fundamentally different constructs in their expression. The same example above
is presented below using SQL and the
link:https://en.wikipedia.org/wiki/Java_Database_Connectivity[JDBC] interface.
The take home point is that Gremlin does
not exist outside the programming language in which it will be used. Gremlin
was designed to be able to be
embedded in any modern programming language and thus, always free from the
complexities of string manipulation as seen
@@ -100,10 +100,11 @@ public class MyApplication {
}
----
-The purpose of this tutorial is to explain how to develop a _Gremlin language
variant_. That is, for those developers that
-are interested in supporting Gremlin in their native language and there
currently does not exist a (good) Gremlin variant in
-their language, they can develop one for the Apache TinkerPop community (and
their language community in general). In this
-tutorial, link:https://www.python.org/[Python] will serve as the host language
and two typical implementation models will be presented.
+The purpose of this tutorial is to explain how to develop a _Gremlin language
variant_. That is, for those developers
+who are interested in supporting Gremlin in their native language and there
currently does not exist a (good) Gremlin
+variant in their language, they can develop one for the Apache TinkerPop
community (and their language community in
+general). In this tutorial, link:https://www.python.org/[Python] will serve as
the host language and two typical
+implementation models will be presented.
1. <<using-jython-and-the-jvm,**Using Jython and the JVM**>>: This is perhaps
the easiest way to produce a Gremlin
language variant. With link:https://www.jcp.org/en/jsr/detail?id=223[JSR-223],
any language compiler written for the JVM
@@ -119,40 +120,42 @@ host language, be in 1-to-1 correspondence with
Gremlin-Java. This ensures that
consistent and easily leveraged by anyone versed in Gremlin.
IMPORTANT: The "Gremlin-Python" presented in this tutorial is basic and
provided to show the primary techniques used to
-construct a Gremlin language variant. Apache TinkerPop distributes with a full
fledged Gremlin-Python variant
-that uses many of the techniques presented in this tutorial.
+construct a Gremlin language variant. Apache TinkerPop distributes with a full
fledged
+link:http://tinkerpop.apache.org/docs/x.y.z/reference/#gremlin-python[Gremlin-Python]
variant that uses many of the
+techniques presented in this tutorial.
[[language-drivers-vs-language-variants]]
== Language Drivers vs. Language Variants
-Before discussing how to implement a Gremlin language variant in Python, it is
necessary to understand two concepts related to
-Gremlin language development. There is a difference between a _language
driver_ and a _language variant_ and it is important
-that these two concepts (and their respective implementations) remain separate.
+Before discussing how to implement a Gremlin language variant in Python, it is
necessary to understand two concepts
+related to Gremlin language development. There is a difference between a
_language driver_ and a _language variant_
+and it is important that these two concepts (and their respective
implementations) remain separate.
=== Language Drivers
image:language-drivers.png[width=375,float=right] A Gremlin language driver is
a software library that is able to
communicate with a TinkerPop-enabled graph system whether directly via the JVM
or indirectly via
-link:http://tinkerpop.apache.org/docs/x.y.z/reference/#gremlin-server[Gremlin
Server] GremlinServer or some other
-link:http://tinkerpop.apache.org/docs/x.y.z/reference/#connecting-via-remotegraph[RemoteConnection]
enabled graph system.
+link:http://tinkerpop.apache.org/docs/x.y.z/reference/#connecting-gremlin-server[Gremlin
Server] Gremlin Server or some
+other
link:http://tinkerpop.apache.org/docs/x.y.z/reference/#connecting-rgp[RemoteConnection]
enabled graph system.
Language drivers are responsible for submitting Gremlin traversals to a
TinkerPop-enabled graph system and
returning results to the developer that are within the developer's language's
type system.
For instance, resultant doubles should be coerced to floats in Python.
-This tutorial is not about language drivers, but about language variants.
Moreover, community libraries should make this
-distinction clear and **should not** develop libraries that serve both roles.
Language drivers will be useful to a collection
-of Gremlin variants within a language community -- able to support
`GraphTraversal`-variants as well as also other
-link:https://en.wikipedia.org/wiki/Domain-specific_language[DSL]-variants
(e.g. `SocialTraversal`).
+This tutorial is not about language drivers, but about language variants.
Moreover, community libraries should make
+this distinction clear and **should not** develop libraries that serve both
roles. Language drivers will be useful to
+a collection of Gremlin variants within a language community -- able to
support `GraphTraversal`-variants as well as
+also other
link:https://en.wikipedia.org/wiki/Domain-specific_language[DSL]-variants (e.g.
`SocialTraversal`).
NOTE: `GraphTraversal` is a particular Gremlin domain-specific language
(link:https://en.wikipedia.org/wiki/Domain-specific_language[DSL]),
-albeit the most popular and foundational DSL. If another DSL is created, then
the same techniques discussed in this tutorial
-for `GraphTraversal` apply to `XXXTraversal`.
+albeit the most popular and foundational DSL. If another DSL is created, then
the same techniques discussed in this
+tutorial for `GraphTraversal` apply to `XXXTraversal`.
=== Language Variants
-image:language-variants.png[width=375,float=right] A Gremlin language variant
is a software library that allows a developer
-to write a Gremlin traversal within their native programming language. The
language variant is responsible for
-creating Gremlin `Bytecode` that will ultimately be translated and compiled to
a `Traversal` by a TinkerPop-enabled graph system.
+image:language-variants.png[width=375,float=right] A Gremlin language variant
is a software library that allows a
+developer to write a Gremlin traversal within their native programming
language. The language variant is responsible
+for creating Gremlin `Bytecode` that will ultimately be translated and
compiled to a `Traversal` by a
+TinkerPop-enabled graph system.
Every language variant, regardless of the implementation details, will have to
account for the four core concepts below:
@@ -161,27 +164,30 @@ Every language variant, regardless of the implementation
details, will have to a
2. `GraphTraversalSource` (**compiler**): This is the typical `g` reference. A
`GraphTraversalSource` maintains the
`withXXX()`-strategy methods as well as the "traversal spawn"-methods such as
`V()`, `E()`, `addV()`, etc.
-A traversal source's registered `TraversalStrategies` determine how the
submitted traversal will be ultimately evaluated.
+A traversal source's registered `TraversalStrategies` determine how the
submitted traversal will be ultimately
+evaluated.
3. `GraphTraversal` (**function composition**): A graph traversal maintains
the computational steps such as `out()`, `groupCount()`,
-`match()`, etc. This fluent interface supports method chaining and thus, a
linear "left-to-right" representation of a traversal/query.
+`match()`, etc. This fluent interface supports method chaining and thus, a
linear "left-to-right" representation of a
+traversal/query.
-4. `__` (**function nesting**) : The anonymous traversal class is used for
passing a traversal as an argument to a parent step.
-For example, in `repeat(__.out())`, `__.out()` is an anonymous traversal
passed to the traversal parent `repeat()`.
-Anonymous traversals enable the "top-to-bottom" representation of a traversal.
+4. `__` (**function nesting**) : The anonymous traversal class is used for
passing a traversal as an argument to a
+parent step. For example, in `repeat(__.out())`, `__.out()` is an anonymous
traversal passed to the traversal parent
+`repeat()`. Anonymous traversals enable the "top-to-bottom" representation of
a traversal.
5. `Bytecode` (**language agnostic encoding**): The source and traversal steps
and their arguments are encoded in a
-language agnostic representation called Gremlin bytecode. This representation
is a nested list of the form `[step,[args*]]*`.
+language agnostic representation called Gremlin bytecode. This representation
is a nested list of the form
+`[step,[args*]]*`.
-Both `GraphTraversal` and `__` define the structure of the Gremlin language.
Gremlin is a _two-dimensional language_ supporting
-linear, nested step sequences. Historically, many Gremlin language variants
have failed to make the distinctions above clear
-and in doing so, either complicate their implementations or yield variants
that are not in 1-to-1 correspondence with Gremlin-Java.
-By keeping these concepts clear when designing a language variant, the
construction of the Gremlin bytecode representation is
-easy.
+Both `GraphTraversal` and `__` define the structure of the Gremlin language.
Gremlin is a _two-dimensional language_
+supporting linear, nested step sequences. Historically, many Gremlin language
variants have failed to make the
+distinctions above clear and in doing so, either complicate their
implementations or yield variants that are not in
+1-to-1 correspondence with Gremlin-Java. By keeping these concepts clear when
designing a language variant, the
+construction of the Gremlin bytecode representation is easy.
IMPORTANT: The term "Gremlin-Java" denotes the language that is defined by
`GraphTraversalSource`, `GraphTraversal`,
-and `__`. These three classes exist in
`org.apache.tinkerpop.gremlin.process.traversal.dsl.graph` and form the
definitive
-representation of the Gremlin traversal language.
+and `__`. These three classes exist in
`org.apache.tinkerpop.gremlin.process.traversal.dsl.graph` and form the
+definitive representation of the Gremlin traversal language.
== Gremlin-Jython and Gremlin-Python
@@ -241,17 +247,17 @@ list of implementations is provided
link:https://en.wikipedia.org/wiki/List_of_J
==== Traversal Wrappers
-While it is possible to simply interact with Java classes in a `ScriptEngine`
implementation, such Gremlin language variants
-will not leverage the unique features of the host language. It is for this
reason that JVM-based language variants such as
-link:https://github.com/mpollmeier/gremlin-scala[Gremlin-Scala] were
developed. Scala provides many syntax niceties not
-available in Java. To leverage these niceties, Gremlin-Scala "wraps"
`GraphTraversal` in order to provide Scala-idiomatic extensions.
-Another example is Apache TinkerPop's Gremlin-Groovy which does the same via
the
+While it is possible to simply interact with Java classes in a `ScriptEngine`
implementation, such Gremlin language
+variants will not leverage the unique features of the host language. It is for
this reason that JVM-based language
+variants such as
link:https://github.com/mpollmeier/gremlin-scala[Gremlin-Scala] were developed.
Scala provides many
+syntax niceties not available in Java. To leverage these niceties,
Gremlin-Scala "wraps" `GraphTraversal` in order to
+provide Scala-idiomatic extensions. Another example is Apache TinkerPop's
Gremlin-Groovy which does the same via the
link:http://tinkerpop.apache.org/docs/x.y.z/reference/#sugar-plugin[Sugar
plugin], but uses
-link:http://groovy-lang.org/metaprogramming.html[meta-programming] instead of
object wrapping, where "behind the scenes,"
-Groovy meta-programming is doing object wrapping.
+link:http://groovy-lang.org/metaprogramming.html[meta-programming] instead of
object wrapping, where "behind the
+scenes," Groovy meta-programming is doing object wrapping.
-The Jython example below uses Python meta-programming to add functionality to
`GraphTraversal`.
-In particular, the `__getitem__` and `__getattr__` "magic methods" are
leveraged.
+The Jython example below uses Python meta-programming to add functionality to
`GraphTraversal`. In particular, the
+`__getitem__` and `__getattr__` "magic methods" are leveraged.
[source,python]
----
@@ -266,8 +272,9 @@ GraphTraversal.__getitem__ = getitem_bypass
GraphTraversal.__getattr__ = lambda self, key: self.values(key)
----
-The two methods `__getitem__` and `__getattr__` support Python _slicing_ and
_object attribute interception_, respectively.
-In this way, the host language is able to use its native constructs in a
meaningful way within a Gremlin traversal.
+The two methods `__getitem__` and `__getattr__` support Python _slicing_ and
_object attribute interception_,
+respectively. In this way, the host language is able to use its native
constructs in a meaningful way within a
+Gremlin traversal.
IMPORTANT: Gremlin-Java serves as the standard/default representation of the
Gremlin traversal language. Any Gremlin
language variant **must** provide all the same functionality (methods) as
`GraphTraversal`, but **can** extend it
@@ -279,10 +286,11 @@ to have the extension added to a future release of
Gremlin.
[[using-python-and-remoteconnection]]
=== Using Python and RemoteConnection
-image:python-logo.png[width=125,float=left,link="https://www.python.org/";] The
JVM is a powerful piece of technology that has, over the years,
-become a meeting ground for developers from numerous language communities.
However, not all applications will use the JVM.
-Given that Apache TinkerPop is a Java-framework, there must be a way for two
different virtual machines to communicate
-traversals and their results. This section presents the second Gremlin
language variant implementation model which does just that.
+image:python-logo.png[width=125,float=left,link="https://www.python.org/";] The
JVM is a powerful piece of technology
+that has, over the years, become a meeting ground for developers from numerous
language communities. However, not all
+applications will use the JVM. Given that Apache TinkerPop is a
Java-framework, there must be a way for two different
+virtual machines to communicate traversals and their results. This section
presents the second Gremlin language
+variant implementation model which does just that.
NOTE: Apache TinkerPop is a JVM-based graph computing framework. Most graph
databases and processors today are built
on the JVM. This makes it easy for these graph system providers to implement
Apache TinkerPop. However, TinkerPop is more
@@ -291,8 +299,8 @@ machine was written for the JVM, its constructs are simple
and can/should be por
that are not JVM-based. A theoretical review of the concepts behind the
Gremlin traversal machine is provided in
link:http://arxiv.org/abs/1508.03843[this article].
-This section's Gremlin language variant design model does not leverage the JVM
directly. Instead, it constructs a `Bytecode`
-representation of a `Traversal` that will ultimately be evaluated by
`RemoteConnection` (e.g. GremlinServer).
+This section's Gremlin language variant design model does not leverage the JVM
directly. Instead, it constructs a
+`Bytecode` representation of a `Traversal` that will ultimately be evaluated
by `RemoteConnection` (e.g. GremlinServer).
It is up to the language variant designer to choose a _language driver_ to use
for submitting the generated bytecode and
coercing its results. The language driver is the means by which, for this
example, the CPython
VM communicates with the JVM.
@@ -445,9 +453,11 @@ class GraphTraversalSourceGenerator {
----
When the above Groovy script is evaluated (e.g. in GremlinConsole),
**Gremlin-Python** is born. The generated Python
-file is available at
link:https://github.com/apache/tinkerpop/blob/x.y.z/gremlin-python/src/main/jython/gremlin_python/process/graph_traversal.py[graph_traversal.py].
-It is important to note that there is a bit more to Gremlin-Python in that
there also exists Python implementations of `TraversalStrategies`, `Traversal`,
`Bytecode`, etc.
-Please review the full implementation of Gremlin-Python
link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-python/src/main/jython/gremlin_python[here].
+file is similar to the one available at
+link:https://github.com/apache/tinkerpop/blob/x.y.z/gremlin-python/src/main/jython/gremlin_python/process/graph_traversal.py[graph_traversal.py].
+It is important to note that there is a bit more to Gremlin-Python in that
there also exists Python implementations
+of `TraversalStrategies`, `Traversal`, `Bytecode`, etc. Please review the full
implementation of Gremlin-Python
+link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-python/src/main/jython/gremlin_python[here].
NOTE: In practice, TinkerPop uses the Groovy's `GStringTemplateEngine` to help
with the code generation task described
above and automates that generation as part of the standard build with Maven
using the `gmavenplus-plugin`. See the
@@ -595,4 +605,4 @@ language. Two ways of doing this for the Python language
were presented in this
the reflection-based source code generation technique presented. This method
ensures that the language
variant is always in sync with the corresponding Apache TinkerPop Gremlin-Java
release version. Moreover, it reduces
the chance of missing methods or creating poorly implemented methods. While
Gremlin is simple, there are nearly 200
-steps in `GraphTraversal`. As such, mechanical means of host language
embedding are strongly advised.
+step variations in `GraphTraversal`. As such, mechanical means of host
language embedding are strongly advised.
