Consistent format of step references should use a dash CTR
Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/dde73e42 Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/dde73e42 Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/dde73e42 Branch: refs/heads/TINKERPOP-1990 Commit: dde73e42bc1aed1e73b71a38aa51a9c4641ef562 Parents: 0bd9b5a Author: Stephen Mallette <sp...@genoprime.com> Authored: Fri Jul 27 07:16:11 2018 -0400 Committer: Stephen Mallette <sp...@genoprime.com> Committed: Fri Jul 27 07:16:11 2018 -0400 ---------------------------------------------------------------------- docs/src/dev/developer/for-committers.asciidoc | 2 +- docs/src/recipes/between-vertices.asciidoc | 6 +++--- docs/src/recipes/collections.asciidoc | 18 +++++++++--------- docs/src/recipes/pagination.asciidoc | 2 +- .../recipes/traversal-component-reuse.asciidoc | 4 ++-- docs/src/recipes/tree.asciidoc | 2 +- docs/src/reference/the-traversal.asciidoc | 2 +- docs/src/tutorials/getting-started/index.asciidoc | 12 ++++++------ .../src/tutorials/gremlins-anatomy/index.asciidoc | 16 ++++++++-------- .../tutorials/the-gremlin-console/index.asciidoc | 2 +- 10 files changed, 33 insertions(+), 33 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/dde73e42/docs/src/dev/developer/for-committers.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/dev/developer/for-committers.asciidoc b/docs/src/dev/developer/for-committers.asciidoc index 43c9ce3..82b3609 100644 --- a/docs/src/dev/developer/for-committers.asciidoc +++ b/docs/src/dev/developer/for-committers.asciidoc @@ -366,7 +366,7 @@ in it * "the result should be ordered" - the exact results and should appear in the order presented * "the result should be unordered" - the exact results but can appear any order * "the result should be of" - results can be any of the specified values and in any order (use when guarantees -regarding the exact results cannot be pre-determined easily - see the `range()` step tests for examples) +regarding the exact results cannot be pre-determined easily - see the `range()`-step tests for examples) These final three types of assertions mentioned above should be followed by a Gherkin table that has one column, where each row value in that column represents a value to assert in the result. These values are type notation respected as http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/dde73e42/docs/src/recipes/between-vertices.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/recipes/between-vertices.asciidoc b/docs/src/recipes/between-vertices.asciidoc index a947d3b..b32d323 100644 --- a/docs/src/recipes/between-vertices.asciidoc +++ b/docs/src/recipes/between-vertices.asciidoc @@ -33,7 +33,7 @@ g.V(1).out().where(__.in().hasId(6)) <6> ---- <1> There are three edges from the vertex with the identifier of "1". -<2> Filter those three edges using the `where()` step using the identifier of the vertex returned by `otherV()` to +<2> Filter those three edges using the `where()`-step using the identifier of the vertex returned by `otherV()` to ensure it matches on the vertex of concern, which is the one with an identifier of "2". <3> Note that the same traversal will work if there are actual `Vertex` instances rather than just vertex identifiers. <4> The vertex with identifier "1" has all outgoing edges, so it would also be acceptable to use the directional steps @@ -43,7 +43,7 @@ vertices with identifiers "2" and "3". <6> There's no reason why the same pattern of exclusion used for edges with `where()` can't work for a vertex between two vertices. -The basic pattern of using `where()` step to find the "other" known vertex can be applied in far more complex +The basic pattern of using `where()`-step to find the "other" known vertex can be applied in far more complex scenarios. For one such example, consider the following traversal that finds all the paths between a group of defined vertices: @@ -113,6 +113,6 @@ g.V(vRexsterJob1, vBlueprintsJob1).as('job'). ---- While the traversals above are more complex, the pattern for finding "things" between two vertices is largely the same. -Note the use of the `where()` step to terminate the traversers for a specific user. It is embedded in a `coalesce()` +Note the use of the `where()`-step to terminate the traversers for a specific user. It is embedded in a `coalesce()` step to handle situations where the specified user did not complete an application for the specified job and will return `false` in those cases. http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/dde73e42/docs/src/recipes/collections.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/recipes/collections.asciidoc b/docs/src/recipes/collections.asciidoc index 257d661..2b1b169 100644 --- a/docs/src/recipes/collections.asciidoc +++ b/docs/src/recipes/collections.asciidoc @@ -86,7 +86,7 @@ g.V(). ---- The call to `local()` executes its anonymous sub-traversal over each individual `List` iterator and as the -sub-traversal ends with a `fold()` step, the results are reduced back into a `List` to preserve the original structure, +sub-traversal ends with a `fold()`-step, the results are reduced back into a `List` to preserve the original structure, thus maintaining two traverser results. This pattern for unfolding and folding `List` traversers ends up having other applications: @@ -112,7 +112,7 @@ g.V().union(limit(3).fold(),tail(3).fold()). <3> with the highest degree (i.e. number of edges). By ending with `fold()` the `List` traverser structure is preserved thus returning two `List` objects. Consider this a method for choosing a "max" or a highly ranked vertex. In this case the rank was determined by the number of edges, but it could have just as easily been determined by a vertex property, -edge property, a calculated value, etc. - one simply needs to alter the `by()` step modulator to `order()`. +edge property, a calculated value, etc. - one simply needs to alter the `by()`-step modulator to `order()`. <3> For each `List` of vertices, filter that `List` to only include vertices that have an "age" property with a value greater than or equal to "29" and then average the results of each list. More generally, consider how this approach performs some kind of reducing calculation on each `List` traverser. In this case, an average was calculated, @@ -194,11 +194,11 @@ the `mean()` to store in a `List` called "c". Note that `aggregate()` was used h the former is an eager collection of the elements in the stream (`store()` is lazy) and will force the traversal to be iterated up to that point before moving forward. Without that eager collection, "v" and "e" would not contain the complete information required for the production of "b" and "c". -<6> Adding `fold()` step here is a bit of a trick. To see the trick, copy and paste all lines of Gremlin up to but -not including this `fold()` step and run them against the "modern" graph. The output is three vertices and if the -`profile()` step was added one would also see that the traversal contained three traversers. These three traversers -with a vertex in each one were produced from the `repeat()` step (i.e. those vertices that had the "lang" of "java" -when traversing away from "marko"). The `aggregate()` steps are side-effects and just allow the traversers to pass +<6> Adding `fold()`-step here is a bit of a trick. To see the trick, copy and paste all lines of Gremlin up to but +not including this `fold()`-step and run them against the "modern" graph. The output is three vertices and if the +`profile()`-step was added one would also see that the traversal contained three traversers. These three traversers +with a vertex in each one were produced from the `repeat()`-step (i.e. those vertices that had the "lang" of "java" +when traversing away from "marko"). The `aggregate()`-steps are side-effects and just allow the traversers to pass through them unchanged. The `fold()` obviously converts those three traversers to a single `List` to make one traverser with a `List` inside. That means that the remaining steps following the `fold()` will only be executed one time each instead of three, which, as will be shown, is critical to the proper result. @@ -212,7 +212,7 @@ presents an override to include "c" into the result. All of the above code and explanation show that `store()` can be used to construct `List` objects as side-effects which can then be used as a result. Note that `aggregate()` can be used to similar effect, should it make sense that lazy `List` creation is not acceptable with respect to the nature of the traversal. An interesting sub-pattern that -emerges here is that the `by()` step can modulate its step to completely override the current traverser and ignore its +emerges here is that the `by()`-step can modulate its step to completely override the current traverser and ignore its contents for purpose of that step. This ability to override a traverser acts as a powerful and flexible tool as it means that each traverser can effectively become a completely different object as determined by a sub-traversal. @@ -361,7 +361,7 @@ g.V(). <1> The `valueMap(true)` of a `Vertex` can be extended with the "degree" of the `Vertex` by performing a `union()` of the two traversals that produce that output (both produce `Map` objects). -<2> The `unfold()` step is used to decompose the `Map` objects into key/value entries that are then constructed back +<2> The `unfold()`-step is used to decompose the `Map` objects into key/value entries that are then constructed back into a single new `Map` given the patterns shown earlier. The `Map` objects of both traversals in the `union()` are essentially merged together. http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/dde73e42/docs/src/recipes/pagination.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/recipes/pagination.asciidoc b/docs/src/recipes/pagination.asciidoc index c26a1fc..7e7da8d 100644 --- a/docs/src/recipes/pagination.asciidoc +++ b/docs/src/recipes/pagination.asciidoc @@ -64,7 +64,7 @@ NOTE: The first traversal above could also be written as `g.V().hasLabel('person In this case, there is no way to know the total count so the only way to know if the end of the results have been reached is to count the results from each paged result to see if there's less than the number expected or simply zero results. In that case, further requests for additional pages would be unnecessary. Of course, this approach is not -free of problems either. Most graph databases will not optimize the `range()` step, meaning that the second traversal +free of problems either. Most graph databases will not optimize the `range()`-step, meaning that the second traversal will repeat the iteration of the first two vertices to get to the second set of two vertices. In other words, for the second traversal, the graph will still read four vertices even though there was only a request for two. http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/dde73e42/docs/src/recipes/traversal-component-reuse.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/recipes/traversal-component-reuse.asciidoc b/docs/src/recipes/traversal-component-reuse.asciidoc index 3b9b408..c623531 100644 --- a/docs/src/recipes/traversal-component-reuse.asciidoc +++ b/docs/src/recipes/traversal-component-reuse.asciidoc @@ -20,7 +20,7 @@ limitations under the License. Good software development practices require reuse to keep software maintainable. In Gremlin, there are often bits of traversal logic that could be represented as components that might be tested independently and utilized as part of other traversals. One approach to doing this would be to extract such logic into an anonymous traversal -and provide it to a parent traversal through `flatMap()` step. +and provide it to a parent traversal through `flatMap()`-step. Using the modern toy graph as an example, assume that there are number of traversals that are interested in filtering on edges where the "weight" property is greater than "0.5". A query like that might look like this: @@ -42,7 +42,7 @@ g.V(1).flatMap(weightFilter).both() The `weightFilter` is an anonymous traversal and it is created by way `__` class. The `__` is omitted above from initalization of `weightFilter` because it is statically imported to the Gremlin Console. The `weightFilter` gets -passed to the "full" traversal by way for `flatMap()` step and the results are the same. Of course, there is a problem. +passed to the "full" traversal by way for `flatMap()`-step and the results are the same. Of course, there is a problem. If there is an attempt to use that `weightFilter` a second time, the traversal with thrown an exception because both the `weightFilter` and parent traversal have been "compiled" which prevents their re-use. A simple fix to this would be to clone the `weightFilter`. http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/dde73e42/docs/src/recipes/tree.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/recipes/tree.asciidoc b/docs/src/recipes/tree.asciidoc index f87784f..879b26e 100644 --- a/docs/src/recipes/tree.asciidoc +++ b/docs/src/recipes/tree.asciidoc @@ -154,7 +154,7 @@ single result. The previous approaches to calculating the maximum depth use path calculations to achieve the answer. Path calculations can be expensive and if possible avoided if they are not needed. Another way to express a traversal that calculates -the maximum depth is to use the `sack()` step: +the maximum depth is to use the `sack()`-step: [gremlin-groovy,existing] ---- http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/dde73e42/docs/src/reference/the-traversal.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/reference/the-traversal.asciidoc b/docs/src/reference/the-traversal.asciidoc index 057ec6a..970dfca 100644 --- a/docs/src/reference/the-traversal.asciidoc +++ b/docs/src/reference/the-traversal.asciidoc @@ -437,7 +437,7 @@ g.V().both().both().both().count().iterate().toString() <2> ---- <1> `LazyBarrierStrategy` is a default strategy and thus, does not need to be explicitly activated. -<2> With `LazyBarrierStrategy` activated, `barrier()` steps are automatically inserted where appropriate. +<2> With `LazyBarrierStrategy` activated, `barrier()`-steps are automatically inserted where appropriate. *Additional References* http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/dde73e42/docs/src/tutorials/getting-started/index.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/tutorials/getting-started/index.asciidoc b/docs/src/tutorials/getting-started/index.asciidoc index 11e2533..5d98c59 100644 --- a/docs/src/tutorials/getting-started/index.asciidoc +++ b/docs/src/tutorials/getting-started/index.asciidoc @@ -228,7 +228,7 @@ for the creation of link:http://tinkerpop.apache.org/docs/x.y.z/reference/#graph Second, don't forget that you are working with TinkerGraph which allows for identifier assignment. That is _not_ the case with most graph databases. -Finally, the `as()` steps label the value held at a particular step so that you can reference back to it later in the +Finally, the `as()`-steps label the value held at a particular step so that you can reference back to it later in the traversal. In this case, that allows you to reference both vertices as "v1" and "v2" during edge creation. === Graph Traversal - Staying Simple @@ -333,7 +333,7 @@ graph = TinkerFactory.createModern() g = graph.traversal() ---- -Earlier we'd used the `has()` step to tell Gremlin how to find the "marko" vertex. Let's look at some other ways to +Earlier we'd used the `has()`-step to tell Gremlin how to find the "marko" vertex. Let's look at some other ways to use `has()`. What if we wanted Gremlin to find the "age" values of both "vadas" and "marko"? In this case we could use the `within` comparator with `has()` as follows: @@ -393,13 +393,13 @@ g.V().has('name','marko').as('exclude'). ---- We made two additions to the traversal to make it exclude "marko" from the results. First, we added the -link:http://tinkerpop.apache.org/docs/x.y.z/reference/#as-step[as()] step. The `as()` step is not really a "step", +link:http://tinkerpop.apache.org/docs/x.y.z/reference/#as-step[as()] step. The `as()`-step is not really a "step", but a "step modulator" - something that adds features to a step or the traversal. Here, the `as('exclude')` labels -the `has()` step with the name "exclude" and all values that pass through that step are held in that label for later +the `has()`-step with the name "exclude" and all values that pass through that step are held in that label for later use. In this case, the "marko" vertex is the only vertex to pass through that point, so it is held in "exclude". -The other addition that was made was the `where()` step which is a filter step like `has()`. The `where()` is -positioned after the `in()` step that has "person" vertices, which means that the `where()` filter is occurring +The other addition that was made was the `where()`-step which is a filter step like `has()`. The `where()` is +positioned after the `in()`-step that has "person" vertices, which means that the `where()` filter is occurring on the list of "marko" collaborators. The `where()` specifies that the "person" vertices passing through it should not equal (i.e. `neq()`) the contents of the "exclude" label. As it just contains the "marko" vertex, the `where()` filters out the "marko" that we get when we traverse back _in_ on the "created" edges. http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/dde73e42/docs/src/tutorials/gremlins-anatomy/index.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/tutorials/gremlins-anatomy/index.asciidoc b/docs/src/tutorials/gremlins-anatomy/index.asciidoc index b36d881..998ff68 100644 --- a/docs/src/tutorials/gremlins-anatomy/index.asciidoc +++ b/docs/src/tutorials/gremlins-anatomy/index.asciidoc @@ -102,11 +102,11 @@ g.V(). by(label()).next() ---- -the `GraphTraversal` components are represented by the `has()`, `outE()` and `groupCount()` steps. The key to reading +the `GraphTraversal` components are represented by the `has()`, `outE()` and `groupCount()`-steps. The key to reading this Gremlin is to realize that the output of one step becomes the input to the next. Therefore, if you consider the start step of `V()` and realize that it returns vertices in the graph, the input to `has()` is going to be a `Vertex`. -The `has()` step is a filtering step and will take the vertices that are passed into it and block any that do not -meet the criteria it has specified. In this case, that means that the output of the `has()` step is vertices that have +The `has()`-step is a filtering step and will take the vertices that are passed into it and block any that do not +meet the criteria it has specified. In this case, that means that the output of the `has()`-step is vertices that have the label of "person" and the "name" property value of "josh" or "marko". image::gremlin-anatomy-filter.png[width=600] @@ -118,7 +118,7 @@ incoming "marko" and "josh" vertices and traverse their outgoing edges as the ou image::gremlin-anatomy-navigate.png[width=600] Now that it is clear that the output of `outE()` is an edge, you are aware of the input to `groupCount()` - edges. -The `groupCount()` step requires a bit more discussion of other Gremlin components and will thus be examined in the +The `groupCount()`-step requires a bit more discussion of other Gremlin components and will thus be examined in the following sections. At this point, it is simply worth noting that the output of `groupCount()` is a `Map` and if a Gremlin step followed it, the input to that step would therefore be a `Map`. @@ -130,7 +130,7 @@ remaining pieces. === Step Modulators It's been explained in several ways now that the output of one step becomes the input to the next, so surely the `Map` -produced by `groupCount()` will feed the `by()` step. As alluded to at the end of the previous section, that +produced by `groupCount()` will feed the `by()`-step. As alluded to at the end of the previous section, that expectation is not correct. Technically, `by()` is not a step. It is a step modulator. A step modulator modifies the behavior of the previous step. In this case, it is telling Gremlin how the key for the `groupCount()` should be determined. Or said another way in the context of the example, it answers this question: What do you want the "marko" @@ -148,7 +148,7 @@ methods, thus allowing `__.label()` to be referred to simply as `label()`. NOTE: In Java, the full package name for the `__` is `org.apache.tinkerpop.gremlin.process.traversal.dsl.graph`. -In the context of the example traversal, you can imagine Gremlin getting to the `groupCount()` step with a "marko" or +In the context of the example traversal, you can imagine Gremlin getting to the `groupCount()`-step with a "marko" or "josh" outgoing edge, checking the `by()` modulator to see "what to group by", and then putting edges into buckets by their `label()` and incrementing a counter on each bucket. @@ -160,7 +160,7 @@ The output is thus an edge label distribution for the outgoing edges of the "mar Terminal steps are different from the `GraphTraversal` steps in that terminal steps do not return a `GraphTraversal` instance, but instead return the result of the `GraphTraversal`. In the case of the example, `next()` is the terminal -step and it returns the `Map` constructed in the `groupCount()` step. Other examples of terminal steps include: +step and it returns the `Map` constructed in the `groupCount()`-step. Other examples of terminal steps include: `hasNext()`, `toList()`, and `iterate()`. Without terminal steps, you don't have a result. You only have a `GraphTraversal` @@ -169,7 +169,7 @@ link:http://tinkerpop.apache.org/docs/x.y.z/tutorials/the-gremlin-console/#resul === Expressions -It is worth backing up a moment to re-examine the `has()` step. Now that you have come to understand anonymous +It is worth backing up a moment to re-examine the `has()`-step. Now that you have come to understand anonymous traversals, it would be reasonable to make the assumption that the `within()` argument to `has()` falls into that category. It does not. The `within()` option is not a step either, but instead, something called an expression. An expression typically refers to anything not mentioned in the previously described Gremlin component categories that http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/dde73e42/docs/src/tutorials/the-gremlin-console/index.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/tutorials/the-gremlin-console/index.asciidoc b/docs/src/tutorials/the-gremlin-console/index.asciidoc index cc090d9..b34be6c 100644 --- a/docs/src/tutorials/the-gremlin-console/index.asciidoc +++ b/docs/src/tutorials/the-gremlin-console/index.asciidoc @@ -353,7 +353,7 @@ public final class Traversals { ---- Of course, this won't work and you will likely be left wondering why your unit test for "removeByName" is failing, but -the identical line of code in the console is doing what is expected. The `drop()` step is not some special form +the identical line of code in the console is doing what is expected. The `drop()`-step is not some special form of terminating step that iterates the traversal - it is just one more step that vertices will pass through. Outside of the console you must add `iterate()` as follows:
