(tinkerpop) 01/01: add asBool() step proposal

[xi...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

xiazcy pushed a commit to branch asbool-proposal
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git

commit 67e06a04e05b2c8740360f0b059c4d2c35e2b282
Author: xiazcy <xi...@gmail.com>
AuthorDate: Thu Jun 12 14:49:04 2025 -0700

    add asBool() step proposal
---
 docs/src/dev/future/index.asciidoc                 | 11 ++--
 .../src/dev/future/proposal-asbool-step-7.asciidoc | 70 ++++++++++++++++++++++
 2 files changed, 76 insertions(+), 5 deletions(-)

diff --git a/docs/src/dev/future/index.asciidoc b/docs/src/dev/future/index.asciidoc
index 97bdc62260..f66a4ce9a4 100644
--- a/docs/src/dev/future/index.asciidoc
+++ b/docs/src/dev/future/index.asciidoc
@@ -161,11 +161,12 @@ story.
 |=========================================================
 |Proposal |Description |Targets |Resolved
 |link:https://github.com/apache/tinkerpop/blob/master/docs/src/dev/future/proposal-equality-1.asciidoc[Proposal 1] |Equality, Equivalence, Comparability and Orderability Semantics - Documents existing Gremlin semantics along with clarifications for ambiguous behaviors and recommendations for consistency. |3.6.0 |Y
-|link:https://github.com/apache/tinkerpop/blob/master/docs/src/dev/future/proposal-arrow-flight-2[Proposal 2] |Gremlin Arrow Flight. |Future |N
-|link:https://github.com/apache/tinkerpop/blob/master/docs/src/dev/future/proposal-3-remove-closures[Proposal 3] |Removing the Need for Closures/Lambda in Gremlin |3.7.0 |Y
-|link:https://github.com/apache/tinkerpop/blob/master/docs/src/dev/future/proposal-transaction-4[Proposal 4] |TinkerGraph Transaction Support |3.7.0 |Y
-|link:https://github.com/apache/tinkerpop/blob/master/docs/src/dev/future/proposal-scoping-5[Proposal 5] |Lazy vs. Eager Evaluation|3.8.0 |N
-|link:https://github.com/apache/tinkerpop/blob/master/docs/src/dev/future/proposal-scoping-5[Proposal 6] |asNumber() Step|3.8.0 |N
+|link:https://github.com/apache/tinkerpop/blob/master/docs/src/dev/future/proposal-arrow-flight-2.asciidoc[Proposal 2] |Gremlin Arrow Flight. |Future |N
+|link:https://github.com/apache/tinkerpop/blob/master/docs/src/dev/future/proposal-3-remove-closures.asciidoc[Proposal 3] |Removing the Need for Closures/Lambda in Gremlin |3.7.0 |Y
+|link:https://github.com/apache/tinkerpop/blob/master/docs/src/dev/future/proposal-transaction-4.asciidoc[Proposal 4] |TinkerGraph Transaction Support |3.7.0 |Y
+|link:https://github.com/apache/tinkerpop/blob/master/docs/src/dev/future/proposal-scoping-5.asciidoc[Proposal 5] |Lazy vs. Eager Evaluation|3.8.0 |N
+|link:https://github.com/apache/tinkerpop/blob/master/docs/src/dev/future/proposal-asnumber-step-6.asciidoc[Proposal 6] |asNumber() Step|3.8.0 |N
+|link:https://github.com/apache/tinkerpop/blob/master/docs/src/dev/future/proposal-asbool-step-7.asciidoc[Proposal 7] |asBool() Step|3.8.0 |N
 |=========================================================
 
 = Appendix
diff --git a/docs/src/dev/future/proposal-asbool-step-7.asciidoc b/docs/src/dev/future/proposal-asbool-step-7.asciidoc
new file mode 100644
index 0000000000..0c935c35c4
--- /dev/null
+++ b/docs/src/dev/future/proposal-asbool-step-7.asciidoc
@@ -0,0 +1,70 @@
+////
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+////
+
+image::apache-tinkerpop-logo.png[width=500,link="https://tinkerpop.apache.org"]
+
+*x.y.z - Proposal 7*
+
+== asBool() Step
+
+=== Motivation
+
+Given the additions of the `asString()` and `asDate()` steps in the 3.7 line, this proposal seeks to bridge another gap in language functionality, which is boolean parsing.
+
+=== Definition
+
+The `asBool()` step will convert the incoming traverser into a Boolean value.
+
+If the incoming traverser is `null`, then `null` will be returned.
+
+The incoming traverser can be of type:
+
+*Boolean* - No change will happen, the Boolean will be returned as is.
+
+*Number* - All non-zero values are considered `true`, zero values are considered `false`, `NaN` and `null` values are considered `null`, for example:
+[cols=",",options="header",]
+|===
+|Numerical Value |Boolean Value
+|3.14 |true
+|1 |true
+|0 |false
+|0.0 |false
+|-0.0 |false
+|-1 |true
+|-3.14 |true
+|NaN |null
+|null |null
+|===
+
+*String* - Strings will not be parsable into bool, except boolean strings. Non-parsable strings will return `null`:
+[cols=",",options="header",]
+|===
+|Sting Value |Boolean Value
+|"true" |true
+|"false" |false
+|"True" |true
+|"False" |false
+|"TRUE" |true
+|"FALSE" |false
+|"trUE" |true
+|"faLSe" |false
+|"null"|null
+|"1" |null
+|"hello" |null
+|===
+
+*All other types* - Invalid input into the step, an `IllegalArgumentException` will be thrown.