feat: Add Stackable Boolean Flags

examples/example.py

@@ -75,7 +75,8 @@ class NestedCommand:
 class SubCommand(FlattenedNested):
     # Options / flags
     option: str = cb.option("-o", "--option", help="A simple option")
-    flag: bool = cb.flag("-f", "--flag", help="A boolean flag")
+    flag: bool = cb.flag("-f", "--flag", help="A boolean flag", stackable=True)
+    flag2: bool = cb.flag("-F", "--flag2", help="Another boolean flag", stackable=True)
 
     # File / directory inputs
     file: str = cb.file(

src/cranberry/fields.py

@@ -47,6 +47,7 @@ class annotation when ``None``.
     long: str | None = None
     help: str = ""
     default: Any = field(default_factory=lambda: None)
+    stackable: bool = False  # for flags only
     type: Any = None  # filled in by registry from the class annotation
     required: bool = (
         False  # for args, this is just a convenience property based on default
@@ -120,6 +121,7 @@ def flag(
     *,
     help: str = "",
     default: bool = False,
+    stackable: bool = False,
 ) -> Any:
     """Declare a boolean flag that stores *True* when present (``-f`` / ``--flag``)."""
     return FieldSpec(
@@ -128,6 +130,7 @@ def flag(
         long=long,
         help=help,
         default=default,
+        stackable=stackable,
         type=bool,
     )
 

src/cranberry/parser.py

@@ -211,6 +211,31 @@ def _parse_leaf_command(
             i += 2
             continue
 
+        # Combined short flags allowed for stackable boolean flags (e.g. -fs -> -f and -s) - only if all are valid flags.
+        if token.startswith("-") and not token.startswith("--") and len(token) > 2:
+            # Attempt to decompose into multiple short flags
+            j = 1
+            short_flags: list[str] = []
+            ok = True
+            while j < len(token):
+                short = "-" + token[j]
+                entry = flag_map.get(short)
+                if (
+                    entry is None
+                    or entry[1].kind != "flag"
+                    or entry[1].stackable is False
+                ):
+                    ok = False
+                    break
+                short_flags.append(short)
+                j += 1
+            if ok and short_flags:
+                for short in short_flags:
+                    attr, spec = flag_map[short]
+                    values[attr] = True
+                i += 1
+                continue
+
         if token.startswith("-"):
             raise CranberryParseError(f"Unknown flag: {token!r}")
 
@@ -298,9 +323,30 @@ def parse_args(argv: list[str] | None = None) -> ParseContext:
             else:
                 global_values[attr] = _coerce(argv[i + 1], spec, attr)
                 i += 2
-        else:
-            stripped.append(t)
-            i += 1
+            continue
+
+        # Combined short flags for globals (e.g., -fF -> -f and -F) - only allowed for boolean flags
+        if t.startswith("-") and not t.startswith("--") and len(t) > 2:
+            j = 1
+            short_flags = []
+            ok = True
+            while j < len(t):
+                short = "-" + t[j]
+                entry = global_map.get(short)
+                if entry is None or entry[1].kind != "flag":
+                    ok = False
+                    break
+                short_flags.append(short)
+                j += 1
+            if ok and short_flags:
+                for short in short_flags:
+                    attr, spec = global_map[short]
+                    global_values[attr] = True
+                i += 1
+                continue
+
+        stripped.append(t)
+        i += 1
 
     for n, s in global_fields.items():
         global_values.setdefault(n, s.default)

tests/test_parser.py

@@ -449,6 +449,43 @@ def test_version_short_flag(self, capsys):
             cb.parse_args(["-V"])
 
 
+# ---------------------------------------------------------------------------
+# Combined short flags
+# ---------------------------------------------------------------------------
+class TestParseStackableFlags:
+    def test_combined_short_flags_fs(self, capsys):
+        @cb.command("c")
+        class C:
+            first: bool = cb.flag("-f", "--flag", stackable=True)
+            second: bool = cb.flag("-s", "--second", stackable=True)
+
+        make_app(C)
+        ctx = cb.parse_args(["c", "-fs"])
+        assert ctx.command.first is True
+        assert ctx.command.second is True
+
+    def test_combined_short_flags_sf(self, capsys):
+        @cb.command("c2")
+        class C2:
+            first: bool = cb.flag("-f", "--flag", stackable=True)
+            second: bool = cb.flag("-s", "--second", stackable=True)
+
+        make_app(C2)
+        ctx = cb.parse_args(["c2", "-sf"])
+        assert ctx.command.first is True
+        assert ctx.command.second is True
+
+    def test_non_stackable_flag_combined_raises(self, capsys):
+        @cb.command("c3")
+        class C3:
+            first: bool = cb.flag("-f", "--flag", stackable=False)
+            second: bool = cb.flag("-s", "--second", stackable=True)
+
+        make_app(C3)
+        with pytest.raises(CranberryParseError, match="Unknown flag: '-fs'"):
+            cb.parse_args(["c3", "-fs"])
+
+
 # ---------------------------------------------------------------------------
 # ParseContext repr and globals
 # ---------------------------------------------------------------------------