[cli] Enable negative expressions as positional arguments (#202)

This PR updates the Decimo CLI argument parsing so expressions that
start with `-` (e.g., negative numbers / negative expressions) can be
passed as the positional `<EXPR>` more naturally, and documents/tests
the behavior.

**Changes:**
- Enable hyphen-prefixed values for the `expr` positional argument via
ArgMojo (`allow_hyphen=True`) and remove the older command-level
negative-number allowance.
- Expand CLI integration tests to cover negative expressions, mixed
option/positional ordering, and `--` separator cases.
- Add user-manual documentation for “Negative Expressions” and update
the CLI calculator plan checklist accordingly.

Author: forfudan

docs/plans/cli_calculator.md

@@ -311,23 +311,25 @@ Format the final `BigDecimal` result based on CLI flags:
 6. Documentation and examples in README (include shell completion setup).
 7. Build and distribute as a single binary.
 
-| #    | Task                                                            | Status | Notes                                                                                                              |
-| ---- | --------------------------------------------------------------- | :----: | ------------------------------------------------------------------------------------------------------------------ |
-| 3.1  | Error messages with position info + caret display               |   ✓    | Colored stderr: red `Error:`, green `^` caret                                                                      |
-| 3.2  | Edge cases (div-by-zero, negative sqrt, empty expression, etc.) |   ✓    | 27 error-handling tests                                                                                            |
-| 3.3  | ArgMojo v0.5.0 declarative API migration                        |   ✓    | `Parsable` struct, `add_tip()`, `mutually_exclusive()`, `choices`, `--version` all working                         |
-| 3.4  | Built-in features (free with ArgMojo v0.5.0)                    |   ✓    | Typo suggestions, `NO_COLOR`, CJK full-width correction, prefix matching, `--` stop marker                         |
-| 3.5  | Shell completion (`--completions bash\|zsh\|fish`)              |   ✓    | Built-in — zero code; needs documentation in user manual and README                                                |
-| 3.6  | `allow_negative_numbers()` to allow pure negative numbers       |   ✓    | Explicit opt-in in hybrid bridge; `decimo "-3"` works, expressions need quoting or `--`                            |
-| 3.7  | Numeric range on `precision`                                    |   ✓    | `has_range=True, range_min=1, range_max=1000000000`; rejects `--precision 0` or `-5`                               |
-| 3.8  | Value names for help readability                                |   ✓    | `--precision <N>`, `--delimiter <CHAR>`, `--rounding-mode <MODE>`                                                  |
-| 3.9  | Argument groups in help output                                  |   ✓    | `Computation` and `Formatting` groups in `--help`                                                                  |
-| 3.10 | Custom usage line                                               |   ✓    | `Usage: decimo [OPTIONS] <EXPR>`                                                                                   |
-| 3.11 | `Parsable.run()` override                                       |   ✗    | Move eval logic into `DecimoArgs.run()` for cleaner separation                                                     |
-| 3.12 | Performance validation                                          |   ✗    | No CLI-level benchmarks yet                                                                                        |
-| 3.13 | Documentation (user manual for CLI)                             |   ✗    | `docs/user_manual_cli.md`; include shell completion setup                                                          |
-| 3.14 | Build and distribute as single binary                           |   ✗    |                                                                                                                    |
-| 3.15 | Allow negative expressions                                      |   ✗    | This needs ArgMojo to regard arguments with a hyphen and followed by more than one letter as a positional argument |
+| #    | Task                                                            | Status | Notes                                                                                      |
+| ---- | --------------------------------------------------------------- | :----: | ------------------------------------------------------------------------------------------ |
+| 3.1  | Error messages with position info + caret display               |   ✓    | Colored stderr: red `Error:`, green `^` caret                                              |
+| 3.2  | Edge cases (div-by-zero, negative sqrt, empty expression, etc.) |   ✓    | 27 error-handling tests                                                                    |
+| 3.3  | ArgMojo v0.5.0 declarative API migration                        |   ✓    | `Parsable` struct, `add_tip()`, `mutually_exclusive()`, `choices`, `--version` all working |
+| 3.4  | Built-in features (free with ArgMojo v0.5.0)                    |   ✓    | Typo suggestions, `NO_COLOR`, CJK full-width correction, prefix matching, `--` stop marker |
+| 3.5  | Shell completion (`--completions bash\|zsh\|fish`)              |   ✓    | Built-in — zero code; needs documentation in user manual and README                        |
+| 3.6  | `allow_negative_numbers()` to allow pure negative numbers       |   ✓    | Superseded by 3.15 `allow_hyphen=True`; removed in favour of the more general approach     |
+| 3.7  | Numeric range on `precision`                                    |   ✓    | `has_range=True, range_min=1, range_max=1000000000`; rejects `--precision 0` or `-5`       |
+| 3.8  | Value names for help readability                                |   ✓    | `--precision <N>`, `--delimiter <CHAR>`, `--rounding-mode <MODE>`                          |
+| 3.9  | Argument groups in help output                                  |   ✓    | `Computation` and `Formatting` groups in `--help`                                          |
+| 3.10 | Custom usage line                                               |   ✓    | `Usage: decimo [OPTIONS] <EXPR>`                                                           |
+| 3.11 | `Parsable.run()` override                                       |   ✗    | Move eval logic into `DecimoArgs.run()` for cleaner separation                             |
+| 3.12 | Performance validation                                          |   ✗    | No CLI-level benchmarks yet                                                                |
+| 3.13 | Documentation (user manual for CLI)                             |   ✗    | `docs/user_manual_cli.md`; include shell completion setup                                  |
+| 3.14 | Build and distribute as single binary                           |   ✗    |                                                                                            |
+| 3.15 | Allow negative expressions                                      |   ✓    | `allow_hyphen=True` on `Positional`; `decimo "-3*pi*(sin(1))"` works                       |
+| 3.16 | Make short names upper cases to avoid expression collisions     |   ✗    | `-sin(1)` clashes with `-s` (scientific), `-e` clashes with `--engineering`                |
+| 3.17 | Define `allow_hyphen_values` in declarative API                 |   ✗    | When argmojo supports it                                                                   |
 
 ### Phase 4: Interactive REPL & Subcommands
 

docs/user_manual_cli.md

@@ -20,6 +20,7 @@
   - [Rounding Mode (`--rounding-mode`, `-r`)](#rounding-mode---rounding-mode--r)
 - [Shell Integration](#shell-integration)
   - [Quoting Expressions](#quoting-expressions)
+  - [Negative Expressions](#negative-expressions)
   - [Using noglob](#using-noglob)
 - [Examples](#examples)
   - [Basic Arithmetic](#basic-arithmetic)
@@ -87,8 +88,11 @@ decimo "2^256"
 - **Integers:** `42`, `-7`, `1000000`
 - **Decimals:** `3.14`, `0.001`, `.5`
 - **Negative numbers:** `-3`, `-3.14`, `(-5 + 2)`
+- **Negative expressions:** `-3*pi`, `-3*pi*(sin(1))`
 - **Unary minus:** `2 * -3`, `sqrt(-1 + 2)`
 
+Negative numbers and many expressions starting with `-` can be passed directly as the positional argument. However, if the expression token looks like a CLI flag (e.g., `-e`), use `--` to force positional parsing. See [Negative Expressions](#negative-expressions) for details.
+
 ### Operators
 
 | Operator | Description    | Example       | Result      |
@@ -255,6 +259,38 @@ decimo "2 * (3 + 4)"
 decimo 2 * (3 + 4)
 ```
 
+### Negative Expressions
+
+Most expressions starting with a hyphen (`-`) are treated as positional arguments, not as option flags:
+
+```bash
+# Negative number
+decimo "-3.14"
+# → -3.14
+
+# Negative expression
+decimo "-3*2"
+# → -6
+
+# Complex negative expression
+decimo "-3*pi*(sin(1))"
+# → -7.930677192244368536658197969…
+
+# Options can appear before or after the expression
+decimo -p 10 "-3*pi"
+decimo "-3*pi" -p 10
+```
+
+**Caveat:** If the expression looks like an existing CLI flag (e.g., `-e` matches `--engineering`), ArgMojo will consume it as an option. Use `--` to force positional parsing in those cases:
+
+```bash
+# -e is the engineering flag, so use -- to treat it as an expression
+decimo -- "-e"
+# → -2.71828…
+```
+
+> **Note:** A future release will rename short flags to uppercase (`-S`, `-E`) to eliminate these collisions entirely.
+
 ### Using noglob
 
 On zsh, you can use `noglob` to prevent shell interpretation:

src/cli/main.mojo

@@ -102,8 +102,13 @@ def main():
 def _run() raises:
     var cmd = DecimoArgs.to_command()
     cmd.usage("decimo [OPTIONS] <EXPR>")
-    cmd.allow_negative_numbers()
     cmd.mutually_exclusive(["scientific", "engineering"])
+    # Allow expressions starting with '-' (e.g. "-3*pi*(sin(1))") to be
+    # treated as positional values rather than option flags.
+    for i in range(len(cmd.args)):
+        if cmd.args[i].name == "expr":
+            cmd.args[i]._allow_hyphen_values = True
+            break
     cmd.add_tip(
         'If your expression contains *, ( or ), quote it: decimo "2 * (3 + 4)"'
     )

tests/test_cli.sh

@@ -55,6 +55,47 @@ assert_output "rounding mode ceiling" "0.33334" "$BINARY" "1/3" -p 5 -r ceiling
 # Pad flag (--pad / -P)
 assert_output "pad trailing zeros" "0.33333" "$BINARY" "1/3" -p 5 --pad
 
+# ── Negative expressions (allow_hyphen) ───────────────────────────────────
+assert_output "negative number" "-3.14" "$BINARY" "-3.14"
+assert_output "negative integer" "-42" "$BINARY" "-42"
+assert_output "negative expression" "-6" "$BINARY" "-3*2"
+assert_output "negative expression with pi" "-9.424777961" "$BINARY" "-3*pi" -p 10
+assert_output "negative expr with abs()" "-3" "$BINARY" "-abs(3)" -p 10
+assert_output "negative expression complex" "17.32428719" "$BINARY" "-3*pi/sin(10)" -p 10
+assert_output "negative expression with parens" "-7.9306771922443685366581979690091558499739419154171" "$BINARY" "-3*pi*(sin(1))" -p 50
+assert_output "negative zero" "-0" "$BINARY" "-0"
+assert_output "negative minus negative" "1" "$BINARY" "-1*-1"
+assert_output "negative power" "-8" "$BINARY" "-2^3"
+assert_output "negative cancel out" "0" "$BINARY" "-1+1"
+assert_output "negative subtraction" "-50" "$BINARY" "-100+50"
+
+# ── Option/positional ordering ────────────────────────────────────────────
+assert_output "options before expr" "0.3333333333" "$BINARY" -p 10 "1/3"
+assert_output "options after expr" "0.3333333333" "$BINARY" "1/3" -p 10
+assert_output "multiple options before expr" "1.732428719E+1" "$BINARY" -s -p 10 "-3*pi/sin(10)"
+assert_output "mixed order: flag expr option" "1.732428719E+1" "$BINARY" -s "-3*pi/sin(10)" -p 10
+assert_output "mixed order: option expr flag" "1.732428719E+1" "$BINARY" -p 10 "-3*pi/sin(10)" -s
+assert_output "engineering before expr" "-12.345678E+3" "$BINARY" -e "-12345.678"
+assert_output "engineering after expr" "-12.345678E+3" "$BINARY" "-12345.678" -e
+assert_output "delimiter before expr" "3.141_592_654" "$BINARY" -d _ -p 10 "pi"
+assert_output "delimiter after expr" "3.141_592_654" "$BINARY" "pi" -p 10 -d _
+assert_output "rounding before expr" "0.33334" "$BINARY" -p 5 -r ceiling "1/3"
+assert_output "all options before expr" "0.33334" "$BINARY" -p 5 -r ceiling --pad "1/3"
+assert_output "all options after expr" "0.33334" "$BINARY" "1/3" -p 5 -r ceiling --pad
+
+# ── Double-dash separator ─────────────────────────────────────────────────
+assert_output "-- with negative expr" "-6" "$BINARY" -- "-3*2"
+assert_output "-- with negative number" "-3.14" "$BINARY" -- "-3.14"
+assert_output "-- with -e as expr" "-2.7182818284590452353602874713526624977572470937000" "$BINARY" -- "-e"
+
+# ── Bare hyphen rejection ─────────────────────────────────────────────────
+if "$BINARY" -- - >/dev/null 2>&1; then
+    echo "FAIL: bare hyphen should be rejected"
+    FAIL=$((FAIL + 1))
+else
+    PASS=$((PASS + 1))
+fi
+
 echo ""
 echo "CLI integration tests: $PASS passed, $FAIL failed"