Added some javadoc on Scoping as taken from the mailing list
Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/ea10316e Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/ea10316e Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/ea10316e Branch: refs/heads/TINKERPOP-1784 Commit: ea10316e744476b12a68a07491d0db2b028ec65c Parents: 5e4ae46 Author: Stephen Mallette <[email protected]> Authored: Mon Oct 16 07:32:09 2017 -0400 Committer: Stephen Mallette <[email protected]> Committed: Mon Oct 16 07:32:09 2017 -0400 ---------------------------------------------------------------------- .../gremlin/process/traversal/step/Scoping.java | 71 ++++++++++++++++++++ 1 file changed, 71 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/ea10316e/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/Scoping.java ---------------------------------------------------------------------- diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/Scoping.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/Scoping.java index 683e661..65cac93 100644 --- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/Scoping.java +++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/Scoping.java @@ -30,6 +30,77 @@ import java.util.Set; * This interface is implemented by {@link Step} implementations that access labeled path steps, side-effects or * {@code Map} values by key, such as {@code select('a')} step. Note that a step like {@code project()} is non-scoping * because while it creates a {@code Map} it does not introspect them. + * <p/> + * There are four types of scopes: + * <ol> + * <li>Current scope</li> â the current data referenced by the traverser (âpath headâ). + * <li>Path scope</li> â a particular piece of data in the path of the traverser (âpath historyâ). + * <li>Side-effect scope</li> â a particular piece of data in the global traversal blackboard. + * <li>Map scope</li> â a particular piece of data in the current scope map (âmap value by keyâ). + * </ol> + * + * The current scope refers to the current object referenced by the traverser. That is, the {@code traverser.get()} + * object. Another way to think about the current scope is to think in terms of the path of the traverser where the + * current scope is the head of the path. With the math()-step, the variable {@code _} refers to the current scope. + * + * <pre> + * {@code + * gremlin> g.V().values("age").math("sin _") + * ==>-0.6636338842129675 + * ==>0.956375928404503 + * ==>0.5514266812416906 + * ==>-0.428182669496151 + * } + * </pre> + * + * The path scope refers to data previously seen by the traverser. That is, data in the traverserâs path history. + * Paths can be accessed by {@code path()}, however, individual parts of the path can be labeled using {@code as()} + * and accessed later via the path label name. Thus, in the traversal below, âaâ and âbâ refer to objects previously + * traversed by the traverser. + * + * <pre> + * {@code + * gremlin> g.V().as("a").out("knows").as("bâ). + * math("a / b").by("age") + * ==>1.0740740740740742 + * ==>0.90625 + * } + * </pre> + * + * The side-effect scope refers objects in the global side-effects of the traversal. Side-effects are not local to the + * traverser, but instead, global to the traversal. In the traversal below you can see how âxâ is being referenced in + * the math()-step and thus, the side-effect data is being used. + * + * <pre> + * {@code + * gremlin> g.withSideEffect("x",100).V().values("age").math("_ / x") + * ==>0.29 + * ==>0.27 + * ==>0.32 + * ==>0.35 + * } + * </pre> + * + * Map scope refers to objects within the current map object. Thus, its like current scope, but a bit âdeeper.â In the + * traversal below the {@code project()}-step generates a map with keys âaâ and âbâ. The subsequent {@code math()}-step + * is then able to access the âaâ and âbâ values in the respective map and use them for the division operation. + * + * <pre> + * {@code gremlin> + * g.V().hasLabel("personâ). + * project("a","bâ). + * by("ageâ). + * by(bothE().count()). + * math("a / b") + * ==>9.666666666666666 + * ==>27.0 + * ==>10.666666666666666 + * ==>35.0 + * } + * </pre> + * + * Scoping is all about variable data access and forms the fundamental interface for access to the memory structures + * of Gremlin. * * @author Marko A. Rodriguez (http://markorodriguez.com) * @author Stephen Mallette (http://stephen.genoprime.com)
