(tinkerpop) branch master updated: Specify per-type asString() rendering in the Gremlin semantics

[sp...@apache.org]

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 d12eb5b314 Specify per-type asString() rendering in the Gremlin semantics
d12eb5b314 is described below

commit d12eb5b3145572803ee1ccc175117b6b20f42d9e
Author: Stephen Mallette <st...@amazon.com>
AuthorDate: Fri Sep 11 16:11:28 2026 +0000

    Specify per-type asString() rendering in the Gremlin semantics
    
    Replace the vague statement that each value is converted to its canonical
    String representation in the asString()-step Considerations section with an
    explicit per-type rendering table and examples. The table covers integer and
    long, floating-point, boolean, datetime, and vertex values, and two examples
    distinguish list rendering under the global scope from element-wise rendering
    under Scope.local. The null and scope Exceptions block is unchanged.
    
    Assisted-by: Kiro:claude-opus-4.8
---
 docs/src/dev/provider/gremlin-semantics.asciidoc | 30 +++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/docs/src/dev/provider/gremlin-semantics.asciidoc b/docs/src/dev/provider/gremlin-semantics.asciidoc
index 0c1e80a487..b99111f064 100644
--- a/docs/src/dev/provider/gremlin-semantics.asciidoc
+++ b/docs/src/dev/provider/gremlin-semantics.asciidoc
@@ -992,7 +992,35 @@ None
 
 *Considerations:*
 
-Each value is converted to its canonical String representation.
+Under the `global` scope the incoming value is rendered to its canonical String representation. That representation is
+defined per type as follows:
+
+[width="100%",options="header"]
+|=========================================================
+|Type |Rendering |Example
+|`INT`, `LONG` |The decimal value with no type suffix. |`123`, `5`
+|`FLOAT`, `DOUBLE`, `BIGDECIMAL` |The decimal value with no type suffix. The three types render identically and are
+indistinguishable once converted. |`1.5`
+|`BOOLEAN` |The literal `true` or `false`. |`true`
+|`DATETIME` |An ISO-8601 timestamp with trailing zero-valued components elided. |`2023-08-02T00:00Z`
+|`Vertex` |The vertex identifier wrapped as `v[<id>]`. |`v[1]`
+|=========================================================
+
+A `LIST` under the `global` scope is rendered as a whole, producing a single `STRING` in which the elements appear
+bracketed and comma-separated:
+
+[source,text]
+----
+[1, 2, 3] -> "[1, 2, 3]"
+----
+
+Under `Scope.local` the incoming value is a `LIST` and each element is rendered individually. The list structure is
+preserved, yielding a `LIST` of `STRING` rather than a single `STRING`:
+
+[source,text]
+----
+[1, 2, 3] -> ["1", "2", "3"]
+----
 
 *Exceptions:*