Skip to content

Clarify Gremlin-Groovy __. prefix guidance and datetime() return type - #3615

Open
spmallette wants to merge 1 commit into
apache:masterfrom
spmallette:tp-docs-gremlin-groovy-prefix-datetime
Open

Clarify Gremlin-Groovy __. prefix guidance and datetime() return type#3615
spmallette wants to merge 1 commit into
apache:masterfrom
spmallette:tp-docs-gremlin-groovy-prefix-datetime

Conversation

@spmallette

Copy link
Copy Markdown
Contributor

This is a small, conservative documentation fix touching two reference sections.

Gremlin-Groovy differences (reference/gremlin-variants.asciidoc)

The section previously stated that as, in, and not are reserved words that "must always be prefixed with __.". The recommendation to use the __. prefix is kept, but the justification is reframed: rather than a hard reserved-word parser rule, the reason to be explicit is to get deterministic, portable resolution — use __. for an anonymous traversal step, and P. when you actually want a predicate.

This is clarified especially for not: a bare not(...) resolves to P.not(P) (predicate negation), whereas __.not(traversal) is the filter step. Being explicit (__.not(...) for the step, P.not(...) for the predicate) avoids the ambiguity.

A note is also added that datetime() returns a java.time.OffsetDateTime, which the section did not previously state.

Canonical Gremlin literal types (reference/the-traversal.asciidoc)

The DateTime row now notes that the all-lowercase datetime form is also accepted (the grammar accepts datetime, DateTime, and DATETIME).

Testing

Built the rendered documentation locally (bin/process-docs.sh) and reviewed the affected pages in the HTML output; all three changes render as intended.

Reframe the as/in/not guidance in the Gremlin-Groovy differences section:
still recommend the __. prefix, but justify it as the way to get
deterministic, portable resolution rather than a hard reserved-word rule.
Clarify that a bare not(...) resolves to P.not(P) (predicate negation)
whereas __.not(traversal) is the filter step, and advise being explicit
(__.not(...) for the step, P.not(...) for the predicate). Note that
datetime() returns a java.time.OffsetDateTime, and record in the canonical
Gremlin literal types table that the all-lowercase 'datetime' form is also
accepted alongside 'DateTime'.

Assisted-by: Kiro:claude-opus-4.8
@codecov-commenter

codecov-commenter commented Aug 6, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.47%. Comparing base (a28cd1f) to head (a145110).
⚠️ Report is 438 commits behind head on master.

Additional details and impacted files
@@             Coverage Diff              @@
##             master    #3615      +/-   ##
============================================
+ Coverage     76.35%   76.47%   +0.12%     
- Complexity    13424    14297     +873     
============================================
  Files          1012     1036      +24     
  Lines         60341    64620    +4279     
  Branches       7075     7664     +589     
============================================
+ Hits          46076    49421    +3345     
- Misses        11548    12108     +560     
- Partials       2717     3091     +374     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants