From 515ce3752b5470ade8cd9f956f9d8f9cc80ac06f Mon Sep 17 00:00:00 2001
From: Paul Buetow <paul@buetow.org>
Date: Wed, 25 Mar 2026 16:47:47 +0200
Subject: docs: Update README.md and godoc for Boolean-to-Number coercion
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Added documentation section to README.md explaining automatic coercion
- Included usage examples: '5 3 == 1 +', '0 false +', 'true 2 *', '9 3 > 4 5 < +'
- Updated Value type godoc to explain coercion behavior (true→1, false→0)
- toNumber() function already had good documentation

The coercion allows boolean results to be used directly in arithmetic operations,
enabling expressions like '5 3 == 1 +' where '5 3 ==' produces false=0, then '0 + 1' produces 1.
---
 README.md                 | 24 ++++++++++++++++++++++++
 internal/rpn/variables.go |  8 ++++++++
 2 files changed, 32 insertions(+)

diff --git a/README.md b/README.md
index 5c8fcba..9f4de3e 100644
--- a/README.md
+++ b/README.md
@@ -179,6 +179,30 @@ To show the current stack without modifying it:
 45
 ```
 
+## Boolean-to-Number Coercion
+
+Boolean values are automatically coerced to numbers when used in arithmetic operations:
+- `true` is treated as `1`
+- `false` is treated as `0`
+
+This enables mixed boolean-numeric expressions:
+
+```bash
+gt 5 3 == 1 +      # 5 == 3 is false (0), 0 + 1 = 1
+# → 1
+
+gt 0 false +       # false is 0, 0 + 0 = 0
+# → 0
+
+gt true 2 *        # true is 1, 1 * 2 = 2
+# → 2
+
+gt 9 3 > 4 5 < +   # 9 > 3 is true (1), 4 < 5 is true (1), 1 + 1 = 2
+# → 2
+```
+
+Note: The boolean result is shown as `true`/`false` when printed, but when used as an operand it behaves as the corresponding numeric value.
+
 ## Hyper Operators
 
 Hyper operators work on all values on the stack simultaneously:
diff --git a/internal/rpn/variables.go b/internal/rpn/variables.go
index de98e2f..5214403 100644
--- a/internal/rpn/variables.go
+++ b/internal/rpn/variables.go
@@ -14,6 +14,14 @@ var (
 )
 
 // Value represents a variant type that can hold either a number (float64) or a boolean.
+//
+// When used in arithmetic operations, boolean values are automatically coerced:
+//   - true → 1
+//   - false → 0
+//
+// This allows boolean results from comparison operations to be used directly in
+// arithmetic expressions (e.g., "5 3 == 1 +" where "5 3 ==" produces false=0,
+// and "0 + 1" produces 1).
 type Value struct {
 	isBool bool
 	boolVal bool
-- 
cgit v1.2.3