[core] Add long option prefix matching and add --no-X negation flag

Author: forfudan

README.md

@@ -30,6 +30,7 @@ ArgMojo provides a builder-pattern API for defining and parsing command-line arg
 - **Hidden arguments**: exclude internal args from `--help` output
 - **Count flags**: `-vvv` → `get_count("verbose") == 3`
 - **Positional arg count validation**: reject extra positional args
+- **Negatable flags**: `--color` / `--no-color` paired flags with `.negatable()`
 - **Mutually exclusive groups**: prevent conflicting flags (e.g., `--json` vs `--yaml`)
 - **Required-together groups**: enforce that related flags are provided together (e.g., `--username` + `--password`)
 
@@ -81,17 +82,18 @@ fn main() raises:
         .long("format").short("f").choices(formats^).default("table")
     )
 
-    # Mutually exclusive flags
-    cmd.add_arg(Arg("color", help="Force colored output").long("color").flag())
-    cmd.add_arg(Arg("no-color", help="Disable colored output").long("no-color").flag())
-    var excl: List[String] = ["color", "no-color"]
-    cmd.mutually_exclusive(excl^)
+    # Negatable flag — --color enables, --no-color disables
+    cmd.add_arg(
+        Arg("color", help="Enable colored output")
+        .long("color").flag().negatable()
+    )
 
     # Parse and use
     var result = cmd.parse()
     print("pattern:", result.get_string("pattern"))
     print("verbose:", result.get_count("verbose"))
     print("format: ", result.get_string("format"))
+    print("color:  ", result.get_flag("color"))
 ```
 
 ## Usage Examples
@@ -161,14 +163,24 @@ The `--format` option only accepts `json`, `csv`, or `table`:
 ./demo "pattern" --format xml      # Error: Invalid value 'xml' for 'format'. Valid choices: json, csv, table
 ```
 
+### Negatable flags
+
+A negatable flag pairs `--X` (sets `True`) with `--no-X` (sets `False`) automatically:
+
+```bash
+./demo "pattern" --color           # color = True
+./demo "pattern" --no-color        # color = False
+./demo "pattern"                   # color = False (default)
+```
+
 ### Mutually exclusive groups
 
-`--color` and `--no-color` are mutually exclusive — using both is an error:
+`--json` and `--yaml` are mutually exclusive — using both is an error:
 
 ```bash
-./demo "pattern" --color           # OK
-./demo "pattern" --no-color        # OK
-./demo "pattern" --color --no-color  # Error: Arguments are mutually exclusive: '--color', '--no-color'
+./demo "pattern" --json            # OK
+./demo "pattern" --yaml            # OK
+./demo "pattern" --json --yaml     # Error: Arguments are mutually exclusive: '--json', '--yaml'
 ```
 
 ### `--` stop marker

docs/argmojo_overall_planning.md

@@ -36,27 +36,30 @@ These features appear across 3+ libraries and depend only on string operations a
 | `--` stop marker                 | ✓        | ✓     | ✓    | **Done** |
 | Auto `--help` / `-h`             | ✓        | ✓     | ✓    | **Done** |
 | Auto `--version` / `-V`          | ✓        | ✓     | ✓    | **Done** |
-| Short flag merging (`-abc`)      | ✓        | ✓     | ✓    | Phase 2  |
-| Choices / enum validation        | ✓        | —     | ✓    | Phase 2  |
-| Subcommands                      | ✓        | ✓     | ✓    | Phase 3  |
-| Mutually exclusive flags         | ✓        | ✓     | ✓    | Phase 3  |
-| Flags required together          | —        | ✓     | —    | Phase 3  |
-| Suggest on typo (Levenshtein)    | ✓ (3.14) | ✓     | ✓    | Phase 4  |
-| Metavar (display name for value) | ✓        | —     | ✓    | Phase 2  |
-| Positional arg count validation  | —        | ✓     | ✓    | Phase 2  |
-| `--no-X` negation flags          | ✓ (3.9)  | —     | ✓    | Phase 3  |
+| Short flag merging (`-abc`)      | ✓        | ✓     | ✓    | **Done** |
+| Metavar (display name for value) | ✓        | —     | ✓    | **Done** |
+| Positional arg count validation  | —        | ✓     | ✓    | **Done** |
+| Choices / enum validation        | ✓        | —     | ✓    | **Done** |
+| Mutually exclusive flags         | ✓        | ✓     | ✓    | **Done** |
+| Flags required together          | —        | ✓     | —    | **Done** |
+| `--no-X` negation flags          | ✓ (3.9)  | —     | ✓    | **Done** |
+| Long option prefix matching      | ✓        | —     | —    | Phase 3  |
+| Append / collect action          | ✓        | ✓     | ✓    | Phase 3  |
+| One-required group               | —        | ✓     | ✓    | Phase 3  |
+| Subcommands                      | ✓        | ✓     | ✓    | Phase 4  |
+| Suggest on typo (Levenshtein)    | ✓ (3.14) | ✓     | ✓    | Phase 5  |
 
 ### 2.3 Features Excluded (Infeasible or Inappropriate)
 
-| Feature                                       | Reason for Exclusion                                                               |
-| --------------------------------------------- | ---------------------------------------------------------------------------------- |
-| Derive / decorator API                        | Mojo has no macros or decorators                                                   |
-| Shell auto-completion generation              | Requires writing shell scripts; out of scope                                       |
-| Usage-string-driven parsing (docopt style)    | Too implicit; not a good fit for a typed systems language                          |
-| Type-conversion callbacks                     | Mojo has no first-class closures; use `get_int()` / `get_string()` pattern instead |
-| Config file reading (`fromfile_prefix_chars`) | Out of scope; users can pre-process argv                                           |
-| Environment variable fallback                 | Can be done externally; not core parser responsibility                             |
-| Template-customisable help (Go cobra style)   | Mojo has no template engine; help format is hardcoded                              |
+| Feature                                       | Reason for Exclusion                                      |
+| --------------------------------------------- | --------------------------------------------------------- |
+| Derive / decorator API                        | Mojo has no macros or decorators                          |
+| Shell auto-completion generation              | Requires writing shell scripts; out of scope              |
+| Usage-string-driven parsing (docopt style)    | Too implicit; not a good fit for a typed systems language |
+| Type-conversion callbacks                     | Use `get_int()` / `get_string()` pattern instead          |
+| Config file reading (`fromfile_prefix_chars`) | Out of scope; users can pre-process argv                  |
+| Environment variable fallback                 | Can be done externally; not core parser responsibility    |
+| Template-customisable help (Go cobra style)   | Mojo has no template engine; help format is hardcoded     |
 
 ## 3. Technical Foundations
 
@@ -105,7 +108,7 @@ src/argmojo/
 ├── command.mojo         # Command struct — command definition & parsing
 └── result.mojo          # ParseResult struct — parsed values
 tests/
-└── test_argmojo.mojo    # 38 tests, all passing ✓
+└── test_argmojo.mojo    # Unit tests for ArgMojo, ensure robustness
 examples/
 └── demo.mojo            # Demo CLI tool, compilable to binary
 ```
@@ -135,7 +138,10 @@ examples/
 | Count action (`-vvv` → 3)                                             | ✓      | ✓     |
 | Positional arg count validation                                       | ✓      | ✓     |
 | Clean exit for `--help` / `--version`                                 | ✓      | —     |
-| Mutually exclusive groups                                             | ✓      | ✓     |  | Required-together groups | ✓ | ✓ |
+| Mutually exclusive groups                                             | ✓      | ✓     |
+| Required-together groups                                              | ✓      | ✓     |
+| Negatable flags (`.negatable()` → `--no-X`)                           | ✓      | ✓     |
+
 ### 4.3 API Design (Current)
 
 ```mojo
@@ -209,7 +215,10 @@ pattern             # By order of add_arg() calls
 
 - [x] **Mutually exclusive flags** — `cmd.mutually_exclusive(["json", "yaml", "toml"])`
 - [x] **Flags required together** — `cmd.required_together(["username", "password"])`
-- [ ] **`--no-X` negation** — `--color` / `--no-color` paired flags (argparse BooleanOptionalAction)
+- [x] **`--no-X` negation** — `--color` / `--no-color` paired flags (argparse BooleanOptionalAction)
+- [ ] **Long option prefix matching** — `--verb` auto-resolves to `--verbose` when unambiguous (argparse `allow_abbrev`)
+- [ ] **Append / collect action** — `--tag x --tag y` → `["x", "y"]` collects repeated options into a list (argparse `append`, cobra `StringArrayVar`, clap `Append`)
+- [ ] **One-required group** — `cmd.one_required(["json", "yaml"])` requires at least one from the group (cobra `MarkFlagsOneRequired`, clap `ArgGroup::required`)
 - [ ] **Aliases** for long names — `.aliases(["colour"])` for `--color`
 - [ ] **Deprecated arguments** — `.deprecated("Use --format instead")` prints warning (argparse 3.13)
 
@@ -268,49 +277,14 @@ Input: ["demo", "yuhao", "./src", "--ling", "-i", "--max-depth", "3"]
 6. Return ParseResult
 ```
 
-## 7. Testing Strategy
-
-All tests use `cmd.parse_args(List[String])` to inject arguments without needing a real binary.
-
-Tests run via `mojo run -I src tests/test_argmojo.mojo` (mojo test is not available in 0.26.1).
-
-### Current tests (11, all passing ✓)
-
-| Test                           | What it verifies                        |
-| ------------------------------ | --------------------------------------- |
-| `test_flag_long`               | `--verbose` sets flag to True           |
-| `test_flag_short`              | `-v` sets flag to True                  |
-| `test_flag_default_false`      | Unset flag defaults to False            |
-| `test_key_value_long_space`    | `--output file.txt`                     |
-| `test_key_value_long_equals`   | `--output=file.txt`                     |
-| `test_key_value_short`         | `-o file.txt`                           |
-| `test_positional_args`         | Two positional args                     |
-| `test_positional_with_default` | Second positional uses default          |
-| `test_mixed_args`              | Positional + flags + key-value together |
-| `test_double_dash_stop`        | `--` stops option parsing               |
-| `test_has`                     | `has()` returns correct results         |
-
-### Tests to add (per roadmap)
-
-- Short flag merging: `-abc` → three separate flags
-- Short option attached value: `-ofile.txt`
-- Choices validation: pass/fail
-- Positional count: too many / too few
-- Hidden args: not shown in help
-- Count action: `-vvv` == 3
-- Mutually exclusive: error on `--json --yaml`
-- Required together: error on `--user` without `--pass`
-- Negation: `--no-color` sets color to False
-- Subcommands: correct dispatch
-- Typo suggestion: Levenshtein output
-
 ## 8. Mojo 0.26.1 Notes
 
-Important Mojo-specific patterns used throughout this project:
+Here are some important Mojo-specific patterns used throughout this project. Mojo is rapidly evolving, so these may need to be updated in the future:
 
 | Pattern                | What & Why                                          |
 | ---------------------- | --------------------------------------------------- |
-| `@fieldwise_init`      | Replaces `@value` in Mojo 0.26.1                    |
+| `"""Tests..."""`       | Docstring convention                                |
+| `@fieldwise_init`      | Replaces `@value`                                   |
 | `var self`             | Used for builder methods instead of `owned self`    |
 | `String()`             | Explicit conversion; `str()` is not available       |
 | `[a, b, c]` for `List` | List literal syntax instead of variadic constructor |

docs/user_manual.md

@@ -45,7 +45,7 @@ myapp "hello" ./src
 #     pattern   path
 ```
 
-Positional arguments are assigned in the order they are registered with `add_arg()`. If fewer values are provided than defined arguments, the remaining ones use their default values (if any). If more are provided, an error is raised (see [Positional Arg Count Validation](#16-positional-arg-count-validation)).
+Positional arguments are assigned in the order they are registered with `add_arg()`. If fewer values are provided than defined arguments, the remaining ones use their default values (if any). If more are provided, an error is raised (see [Positional Arg Count Validation](#17-positional-arg-count-validation)).
 
 **Retrieving:**
 
@@ -388,7 +388,73 @@ Each group is validated independently — using `--json` and `--no-color` togeth
 
 > **Note:** Pass the `List[String]` with `^` (ownership transfer).
 
-## 15. Required-Together Groups
+## 15. Negatable Flags
+
+A **negatable** flag automatically creates a `--no-X` counterpart. When the user passes `--X`, the flag is set to `True`; when they pass `--no-X`, it is explicitly set to `False`.
+
+This replaces the manual pattern of defining two separate flags (`--color` and `--no-color`) and a mutually exclusive group.
+
+### Defining a negatable flag
+
+```mojo
+cmd.add_arg(
+    Arg("color", help="Enable colored output")
+    .long("color").flag().negatable()
+)
+```
+
+### Behaviour
+
+```bash
+myapp --color       # color = True,  has("color") = True
+myapp --no-color    # color = False, has("color") = True
+myapp               # color = False, has("color") = False  (default)
+```
+
+Use `result.has("color")` to distinguish between "user explicitly disabled colour" (`--no-color`) and "user didn't mention colour at all".
+
+### Help output
+
+Negatable flags are displayed as a paired form:
+
+```text
+      --color / --no-color    Enable colored output
+```
+
+### Comparison with manual approach
+
+**Before (two flags + mutually exclusive):**
+
+```mojo
+cmd.add_arg(Arg("color", help="Force colored output").long("color").flag())
+cmd.add_arg(Arg("no-color", help="Disable colored output").long("no-color").flag())
+var group: List[String] = ["color", "no-color"]
+cmd.mutually_exclusive(group^)
+```
+
+**After (single negatable flag):**
+
+```mojo
+cmd.add_arg(
+    Arg("color", help="Enable colored output")
+    .long("color").flag().negatable()
+)
+```
+
+The negatable approach is simpler and uses only one entry in `ParseResult`.
+
+### When to use
+
+| Scenario           | Example                              |
+| ------------------ | ------------------------------------ |
+| Colour control     | `--color` / `--no-color`             |
+| Feature toggle     | `--cache` / `--no-cache`             |
+| Header inclusion   | `--headers` / `--no-headers`         |
+| Interactive prompt | `--interactive` / `--no-interactive` |
+
+> **Note:** Only flags (`.flag()`) can be made negatable. Calling `.negatable()` on a non-flag argument has no effect on parsing.
+
+## 16. Required-Together Groups
 
 **Required together** means "if any one of these arguments is provided, all the others must be provided too". If only some are given, parsing fails.
 
@@ -458,7 +524,7 @@ cmd.mutually_exclusive(excl^)
 
 > **Note:** Pass the `List[String]` with `^` (ownership transfer).
 
-## 16. Positional Arg Count Validation
+## 17. Positional Arg Count Validation
 
 ArgMojo ensures that the user does not provide more positional arguments than defined. Extra positional values trigger an error.
 
@@ -484,7 +550,7 @@ myapp "hello" ./src            # OK — pattern = "hello", path = "./src"
 myapp "hello" ./src /tmp       # Error: Too many positional arguments: expected 2, got 3
 ```
 
-## 17. The `--` Stop Marker
+## 18. The `--` Stop Marker
 
 A bare `--` tells the parser to **stop interpreting options**. Everything after `--` is treated as a positional argument, even if it looks like an option.
 
@@ -508,7 +574,7 @@ myapp --ling -- "-v is not a flag here" ./src
 # path = "./src"
 ```
 
-## 18. Auto-generated Help
+## 19. Auto-generated Help
 
 Every command automatically supports `--help` (or `-h`). The help text is generated from the registered argument definitions.
 
@@ -552,7 +618,7 @@ Options:
 
 After printing help, the program exits cleanly with exit code 0.
 
-## 19. Version Display
+## 20. Version Display
 
 Every command automatically supports `--version` (or `-V`).
 
@@ -575,7 +641,7 @@ var cmd = Command("myapp", "Description", version="1.0.0")
 
 After printing the version, the program exits cleanly with exit code 0.
 
-## 20. Reading Parsed Results
+## 21. Reading Parsed Results
 
 After calling `cmd.parse()` or `cmd.parse_args()`, you get a `ParseResult` with these typed accessors:
 

examples/demo.mojo

@@ -1,8 +1,8 @@
 """Example: a mini CLI to demonstrate argmojo usage.
 
 Showcases: positional args, flags, key-value options, choices,
-count flags, hidden args, mutually exclusive groups, and
-required-together groups.
+count flags, hidden args, negatable flags, mutually exclusive groups,
+and required-together groups.
 """
 
 from argmojo import Arg, Command
@@ -60,20 +60,21 @@ fn main() raises:
         .default("table")
     )
 
-    # ── Mutually exclusive group ─────────────────────────────────────────
-    # Only one of --color / --no-color may be used at a time.
+    # ── Negatable flag ────────────────────────────────────────────────────
+    # --color enables colour, --no-color disables it.
     cmd.add_arg(
-        Arg("color", help="Force colored output")
+        Arg("color", help="Enable colored output")
         .long("color")
         .flag()
+        .negatable()
     )
-    cmd.add_arg(
-        Arg("no-color", help="Disable colored output")
-        .long("no-color")
-        .flag()
-    )
-    var color_group: List[String] = ["color", "no-color"]
-    cmd.mutually_exclusive(color_group^)
+
+    # ── Mutually exclusive group ─────────────────────────────────────────
+    # Only one of --json / --yaml may be used at a time.
+    cmd.add_arg(Arg("json", help="Output as JSON").long("json").flag())
+    cmd.add_arg(Arg("yaml", help="Output as YAML").long("yaml").flag())
+    var format_excl: List[String] = ["json", "yaml"]
+    cmd.mutually_exclusive(format_excl^)
 
     # ── Hidden argument (internal / debug) ───────────────────────────────
     cmd.add_arg(
@@ -102,7 +103,9 @@ fn main() raises:
     print("  --verbose:    ", result.get_count("verbose"))
     print("  --format:     ", result.get_string("format"))
     print("  --color:      ", result.get_flag("color"))
-    print("  --no-color:   ", result.get_flag("no-color"))
+    if result.has("json") or result.has("yaml"):
+        print("  --json:       ", result.get_flag("json"))
+        print("  --yaml:       ", result.get_flag("yaml"))
     if result.has("max-depth"):
         print("  --max-depth:  ", result.get_string("max-depth"))
     else: