Merge branch '3.8-dev'

Author: xiazcy

CHANGELOG.asciidoc

@@ -154,6 +154,7 @@ This release also includes changes from <<release-3-7-XXX, 3.7.XXX>>.
 * Moved all lambda oriented Gremlin tests to `LambdaStepTest` in the Java test suite.
 * Removed the `@RemoteOnly` testing tag in Gherkin as lambda tests have all been moved to the Java test suite.
 * Updated gremlin-javascript to use GraphBinary as default instead of GraphSONv3
+* Added the `asNumber()` step to perform number conversion.
 * Renamed many types in the grammar for consistent use of terms "Literal", "Argument", and "Varargs"
 * Changed `gremlin-net` so that System.Text.Json is only listed as an explicit dependency when it is not available from the framework.
 * Fixed translation of numeric literals for Go losing type definitions

docs/src/dev/provider/gremlin-semantics.asciidoc

@@ -828,37 +828,33 @@ Incoming date remains unchanged.
 See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AsDateStep.java[source],
 link:https://tinkerpop.apache.org/docs/x.y.z/reference/#asDate-step[reference]
 
-[[asString-step]]
-=== asString()
+[[asNumber-step]]
+=== asNumber()
 
-*Description:* Returns the value of incoming traverser as strings, or if `Scope.local` is specified, returns each element inside
-incoming list traverser as string.
+*Description:* converts the incoming traverser to the nearest parsable type if no argument is provided, or to the desired numerical type, based on the number token (`N`) provided.
 
-*Syntax:* `asString()` | `asString(Scope scope)`
+*Syntax:* `asNumber()` | `asNumber(N numberToken)`
 
 [width="100%",options="header"]
 |=========================================================
 |Start Step |Mid Step |Modulated |Domain |Range
-|N |Y |N |`any` |`String`/`List`
+|N |Y |N |`Number`/`String` |`Number`
 |=========================================================
 
 *Arguments:*
 
-* `scope` - Determines the type of traverser it operates on. Both scopes will operate on the level of individual traversers.
-The `global` scope will operate on individual traverser, casting all (except `null`) to string. The `local` scope will behave like
-`global` for everything except lists, where it will cast individual non-`null` elements inside the list into string and return a
-list of string instead.
+* `numberToken` - The enum `N` to denote the desired type to parse/cast to.
 
-Null values from the incoming traverser are not processed and remain as null when returned.
+If no type token is provided, the incoming number remains unchanged.
 
 *Exceptions*
 
-None
-
-See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AsStringGlobalStep.java[source],
-link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AsStringLocalStep.java[source (local)],
-link:https://tinkerpop.apache.org/docs/x.y.z/reference/#asString-step[reference]
+* If any overflow occurs during narrowing of types, then an `ArithmeticException` will be thrown.
+* If the incoming string cannot be parsed into a valid number format, then a `NumberFormatException` will be thrown.
+* If the incoming traverser is a non-String/Number (including `null`) value then an `IllegalArgumentException` will be thrown.
 
+See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AsNumberStep.java[source],
+link:https://tinkerpop.apache.org/docs/x.y.z/reference/#asNumber-step[reference]
 
 [[barrier-step]]
 === barrier()
@@ -1063,6 +1059,36 @@ None
 See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/sideEffect/SideEffectCapStep.java[source],
 link:https://tinkerpop.apache.org/docs/x.y.z/reference/#cap-step[reference]
 
+[[asString-step]]
+=== asString()
+
+*Description:* Returns the value of incoming traverser as strings, or if `Scope.local` is specified, returns each element inside
+incoming list traverser as string.
+
+*Syntax:* `asString()` | `asString(Scope scope)`
+
+[width="100%",options="header"]
+|=========================================================
+|Start Step |Mid Step |Modulated |Domain |Range
+|N |Y |N |`any` |`String`/`List`
+|=========================================================
+
+*Arguments:*
+
+* `scope` - Determines the type of traverser it operates on. Both scopes will operate on the level of individual traversers.
+The `global` scope will operate on individual traverser, casting all (except `null`) to string. The `local` scope will behave like
+`global` for everything except lists, where it will cast individual non-`null` elements inside the list into string and return a
+list of string instead.
+
+Null values from the incoming traverser are not processed and remain as null when returned.
+
+*Exceptions*
+None
+
+See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AsStringGlobalStep.java[source],
+link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AsStringLocalStep.java[source (local)],
+link:https://tinkerpop.apache.org/docs/x.y.z/reference/#asString-step[reference]
+
 [[call-step]]
 === call()
 

docs/src/reference/the-traversal.asciidoc

@@ -854,6 +854,52 @@ g.inject(datetime("2023-08-24T00:00:00Z")).asDate() <3>
 
 link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#asDate()++[`asDate()`]
 
+[[asNumber-step]]
+=== AsNumber Step
+
+The `asNumber()`-step (*map*) converts the incoming traverser to the nearest parsable type if no argument is provided, or to the desired numerical type, based on the number token (`N`) provided.
+
+Numerical input will pass through unless a type is specified by the number token. `ArithmeticException` will be thrown for any overflow during narrowing of types.
+
+String inputs are parsed into numeric values. By default, the value will be parsed as an integer if it represents a whole number, or as a double if it contains a decimal point. A `NumberFormatException` will be thrown if the string cannot be parsed into a valid number format.
+
+All other input types will result in `IllegalArgumentException`.
+
+[gremlin-groovy,modern]
+----
+g.inject(1234).asNumber() <1>
+g.inject(1.76).asNumber() <2>
+g.inject(1.76).asNumber(N.int_) <3>
+g.inject("1b").asNumber() <4>
+g.inject(33550336).asNumber(N.byte_) <5>
+----
+
+<1> An int will be passed through.
+<2> A double will be passed through.
+<3> A double is converted into an int.
+<4> String containing any character other than numerical ones will result in `NumberFormatException`.
+<5> Narrowing of int to byte that overflows will throw `ArithmeticException`.
+
+[NOTE, caption=Java]
+====
+The enums values `byte`, `short`, `int`, `long`, `float`, `double` are reserved word in Java, and therefore must be referred to in Gremlin with an underscore appended as a suffix: `byte_`, `short_`, `int_`, `long_`, `float_`, `double_`.
+====
+
+[NOTE, caption=Groovy & Gremlin Console]
+====
+The enums values `byte`, `short`, `int`, `long`, `float`, `double` are reserved word in Groovy, therefore as the Gremlin Console is Groovy-based, they must be referred to in Gremlin with an underscore appended as a suffix: `byte_`, `short_`, `int_`, `long_`, `float_`, `double_`.
+====
+
+[NOTE, caption=JavaScript]
+====
+The enums values `byte`, `short`, `int`, `long`, `float`, `double` are reserved word in Javascript, and therefore must be referred to in Gremlin with an underscore appended as a suffix: `byte_`, `short_`, `int_`, `long_`, `float_`, `double_`.
+====
+
+*Additional References*
+
+link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#asNumber()++[`asNumber()`]
+link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#asNumber(org.apache.tinkerpop.gremlin.process.traversal.N)++[`asNumber(N)`]
+
 [[barrier-step]]
 === Barrier Step
 

docs/src/upgrade/release-3.8.x.asciidoc

@@ -30,6 +30,69 @@ complete list of all the modifications that are part of this release.
 
 === Upgrading for Users
 
+==== Number Conversion Step
+
+We have been iteratively introducing new language features into Gremlin, with the most recent major additions being string, list and date manipulation
+steps introduced in the 3.7 line. In 3.8.0, we are now introducing a number conversion step, `asNumber()`, to bridge
+a gap in casting functionalities.
+
+The new `asNumber()` serves as an umbrella step that parses strings and casts numbers into desired types. For the convenience of remote traversals in GLVs, these number types are denoted by a set of number tokens (`N`).
+
+This new step will allow users to normalize their data by converting string numbers and mixed numeric types to a consistent format, making it easier to perform downstream mathematical operations. As an example:
+
+[source,text]
+----
+// sum() step can only take numbers
+gremlin> g.inject(1.0, 2l, 3, "4", "0x5").sum()
+class java.lang.String cannot be cast to class java.lang.Number
+
+// use asNumber() to avoid casting exceptions
+gremlin> g.inject(1.0, 2l, 3, "4", "0x5").asNumber().sum()
+==>15.0
+
+// given sum() step returned a double, one can use asNumber() to further cast the result into desired type
+gremlin> g.inject(1.0, 2l, 3, "4", "0x5").asNumber().sum().asNumber(N.int_)
+==>15
+----
+
+Semantically, the `asNumber()` step will convert the incoming traverser to a logical parsable type if no argument is provided, or to the desired numerical type, based on the number token (`N`) provided.
+
+Numerical input will pass through unless a type is specified by the number token. `ArithmeticException` will be thrown for any overflow as a result of narrowing of types:
+
+[source,text]
+----
+gremlin> g.inject(5.0).asNumber(N.int_)
+==> 5    // casts double to int
+gremlin> g.inject(12).asNumber(N.byte_)
+==> 12
+gremlin> g.inject(128).asNumber(N.byte_)
+==> ArithmeticException
+----
+
+String input will be parsed. By default, the smalled unit of number to be parsed into is `int` if no number token is provided. `NumberFormatException` will be thrown for any unparsable strings:
+
+[source,text]
+----
+gremlin> g.inject("5").asNumber()
+==> 5
+gremlin> g.inject("5.7").asNumber(N.int_)
+==> 5
+gremlin> g.inject("1,000").asNumber(N.int_)
+==> NumberFormatException
+gremlin> g.inject("128").asNumber(N.byte_)
+==> ArithmeticException
+----
+
+All other input types will result in `IllegalArgumentException`:
+[source,text]
+----
+gremlin> g.inject([1, 2, 3, 4]).asNumber()
+==> IllegalArgumentException
+----
+
+See: link:https://tinkerpop.apache.org/docs/3.8.0/reference/#asNumber-step[asNumber()-step]
+See: link:https://issues.apache.org/jira/browse/TINKERPOP-3166[TINKERPOP-3166]
+
 ==== Boolean Conversion Step
 
 The `asBool()` step bridges another gap in Gremlin's casting functionalities. Users now have the ability to parse strings and 

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/jsr223/CoreImports.java

@@ -61,6 +61,7 @@
 import org.apache.tinkerpop.gremlin.process.traversal.DT;
 import org.apache.tinkerpop.gremlin.process.traversal.IO;
 import org.apache.tinkerpop.gremlin.process.traversal.Merge;
+import org.apache.tinkerpop.gremlin.process.traversal.N;
 import org.apache.tinkerpop.gremlin.process.traversal.Operator;
 import org.apache.tinkerpop.gremlin.process.traversal.Order;
 import org.apache.tinkerpop.gremlin.process.traversal.P;
@@ -202,6 +203,7 @@ public final class CoreImports {
         CLASS_IMPORTS.add(Direction.class);
         CLASS_IMPORTS.add(DT.class);
         CLASS_IMPORTS.add(Merge.class);
+        CLASS_IMPORTS.add(N.class);
         CLASS_IMPORTS.add(Operator.class);
         CLASS_IMPORTS.add(Order.class);
         CLASS_IMPORTS.add(Pop.class);
@@ -358,6 +360,7 @@ public final class CoreImports {
         Collections.addAll(ENUM_IMPORTS, Direction.values());
         Collections.addAll(ENUM_IMPORTS, DT.values());
         Collections.addAll(ENUM_IMPORTS, Merge.values());
+        Collections.addAll(ENUM_IMPORTS, N.values());
         Collections.addAll(ENUM_IMPORTS, Operator.values());
         Collections.addAll(ENUM_IMPORTS, Order.values());
         Collections.addAll(ENUM_IMPORTS, Pop.values());

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/language/grammar/DefaultGremlinBaseVisitor.java

@@ -1082,6 +1082,14 @@ public T visitTraversalMethod_from_Traversal(GremlinParser.TraversalMethod_from_
 	 * {@inheritDoc}
 	 */
 	@Override public T visitTraversalMethod_dateDiff_Date(final GremlinParser.TraversalMethod_dateDiff_DateContext ctx) { notImplemented(ctx); return null; }
+	/**
+	 * {@inheritDoc}
+	 */
+	@Override public T visitTraversalMethod_asNumber_Empty(final GremlinParser.TraversalMethod_asNumber_EmptyContext ctx) { notImplemented(ctx); return null; }
+	/**
+	 * {@inheritDoc}
+	 */
+	@Override public T visitTraversalMethod_asNumber_traversalN(final GremlinParser.TraversalMethod_asNumber_traversalNContext ctx) { notImplemented(ctx); return null; }
 	/**
 	 * {@inheritDoc}
 	 */
@@ -1122,6 +1130,10 @@ public T visitTraversalMethod_from_Traversal(GremlinParser.TraversalMethod_from_
 	 * {@inheritDoc}
 	 */
 	@Override public T visitTraversalDT(GremlinParser.TraversalDTContext ctx) { notImplemented(ctx); return null; }
+	/**
+	 * {@inheritDoc}
+	 */
+	@Override public T visitTraversalN(GremlinParser.TraversalNContext ctx) { notImplemented(ctx); return null; }
 	/**
 	 * {@inheritDoc}
 	 */

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/language/grammar/GenericLiteralVisitor.java

@@ -601,6 +601,11 @@ public Object visitTraversalPick(final GremlinParser.TraversalPickContext ctx) {
         return TraversalEnumParser.parseTraversalEnumFromContext(Pick.class, ctx);
     }
 
+    @Override
+    public Object visitTraversalN(final GremlinParser.TraversalNContext ctx) {
+        return TraversalEnumParser.parseTraversalNFromContext(ctx);
+    }
+
     @Override
     public Object visitTraversalStrategy(final GremlinParser.TraversalStrategyContext ctx) {
         return antlr.traversalStrategyVisitor.visitTraversalStrategy(ctx);

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/language/grammar/TraversalEnumParser.java

@@ -19,6 +19,7 @@
 package org.apache.tinkerpop.gremlin.language.grammar;
 
 import org.antlr.v4.runtime.tree.ParseTree;
+import org.apache.tinkerpop.gremlin.process.traversal.N;
 import org.apache.tinkerpop.gremlin.process.traversal.Scope;
 import org.apache.tinkerpop.gremlin.structure.Column;
 import org.apache.tinkerpop.gremlin.structure.Direction;
@@ -79,4 +80,14 @@ public static Function parseTraversalFunctionFromContext(final GremlinParser.Tra
             throw new GremlinParserException("Unrecognized enum for traversal function");
         }
     }
+
+    /**
+     * Parsing of {@link N} requires some special handling because of java keyword collision.
+     */
+    public static N parseTraversalNFromContext(final GremlinParser.TraversalNContext context) {
+        String text = context.getText();
+        if (text.startsWith(N.class.getSimpleName()))
+            text = text.substring(N.class.getSimpleName().length() + 1);
+        return text.startsWith("big") ? N.valueOf(text) : N.valueOf(text + "_");
+    }
 }

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/language/grammar/TraversalMethodVisitor.java

@@ -20,6 +20,7 @@
 
 import org.apache.tinkerpop.gremlin.process.traversal.DT;
 import org.apache.tinkerpop.gremlin.process.traversal.Merge;
+import org.apache.tinkerpop.gremlin.process.traversal.N;
 import org.apache.tinkerpop.gremlin.process.traversal.Operator;
 import org.apache.tinkerpop.gremlin.process.traversal.Order;
 import org.apache.tinkerpop.gremlin.process.traversal.Pop;
@@ -2274,6 +2275,22 @@ public GraphTraversal visitTraversalMethod_dateDiff_Date(final GremlinParser.Tra
         return graphTraversal.dateDiff(antlr.genericVisitor.parseDate(ctx.dateLiteral()));
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public GraphTraversal visitTraversalMethod_asNumber_Empty(final GremlinParser.TraversalMethod_asNumber_EmptyContext ctx) {
+        return graphTraversal.asNumber();
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public GraphTraversal visitTraversalMethod_asNumber_traversalN(final GremlinParser.TraversalMethod_asNumber_traversalNContext ctx) {
+        return graphTraversal.asNumber(
+                TraversalEnumParser.parseTraversalNFromContext(ctx.traversalN()));
+    }
 
     public GraphTraversal[] getNestedTraversalList(final GremlinParser.NestedTraversalListContext ctx) {
         return ctx.nestedTraversalExpr().nestedTraversal()

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/language/translator/GroovyTranslateVisitor.java

@@ -46,6 +46,15 @@ public GroovyTranslateVisitor(final String graphTraversalSourceName) {
         super(graphTraversalSourceName);
     }
 
+    @Override
+    public Void visitTraversalN(GremlinParser.TraversalNContext ctx) {
+        final String[] split = ctx.getText().split("\\.");
+        sb.append(processGremlinSymbol(split[0])).append(".");
+        sb.append(processGremlinSymbol(split[1]));
+        if (!split[1].startsWith("big")) sb.append("_");
+        return null;
+    }
+
     @Override
     public Void visitIntegerLiteral(final GremlinParser.IntegerLiteralContext ctx) {
         final String integerLiteral = ctx.getText().toLowerCase();