base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

Select ordinary BoolFlag registration for shared debug input

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-08 13:55:37 +00:00
parent ec0e58efff
commit f23af30234
1 changed files with 20 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
docs/roadmap/shared-debug-binding.md
View File

@@ -42,10 +42,18 @@ the starting point; applications should not scan or reparse arguments.
### Bind the debug boolean independently ### Bind the debug boolean independently
An application opts into receiving `--debug` in its command input through a OD-1 is resolved: an application declares a normal `BoolFlag` with
`Flag[I]` and the existing typed setter model. Exact construction and metadata `FlagMeta.Name` set to `debug`. CommandKit attaches that binding to the existing
rules are subject to OD-1 and OD-2. Commands without such a binding retain the core flag. The application uses the same `Flag[I]`, `Supplied[bool]`, command
standard core flag and reporting behavior. binding list, and typed setter model as for other boolean flags. No dedicated
`DebugFlag` constructor is planned. Metadata rules remain open in OD-2.
Commands without such a binding retain the standard core flag and reporting
behavior.
This choice keeps the application API familiar and avoids another public
constructor. Core handles shared registration internally; an arbitrary
string-valued or custom-parser flag named `debug` is not equivalent to the
selected boolean binding merely because its name matches.
The ordinary shared binding receives `Supplied[bool]`: omission produces The ordinary shared binding receives `Supplied[bool]`: omission produces
`Value=false, Set=false`; an explicitly supplied false produces `Value=false, Set=false`; an explicitly supplied false produces
@@ -108,9 +116,9 @@ resolved mode. A second accessor on `Reporter` is unnecessary for this scope.
## Implementation work ## Implementation work
1. **Settle binding construction and metadata.** Resolve OD-1 and OD-2 before 1. **Implement ordinary binding attachment and settle metadata.** Use the
making the registration exception. Document which declaration attaches to selected `BoolFlag` form and resolve OD-2 before making the registration
the core flag and how its application metadata is handled. Preserve ordinary exception. Document how its application metadata is handled. Preserve ordinary
validation for unrelated names and bindings; do not broadly disable reserved validation for unrelated names and bindings; do not broadly disable reserved
name or collision checks. name or collision checks.
2. **Connect shared parsing to typed input.** Update declaration validation, 2. **Connect shared parsing to typed input.** Update declaration validation,
@@ -179,27 +187,6 @@ whitespace only. Implementation and the unchecked items above remain future work
## Open Decisions ## Open Decisions
### OD-1: How does an application declare the shared binding?
**Recommendation:** recognize a normal `BoolFlag` with `FlagMeta.Name` set to
`debug` as attachment to the existing core flag. It returns the same `Flag[I]`,
uses `Supplied[bool]`, and occupies the normal command binding list. This most
directly meets the request that using debug should feel like using other flags
and avoids another public constructor. The cost is special handling of a
core-owned name, particularly the metadata rules in OD-2. Do not interpret an
arbitrary string-valued or custom-parser flag named `debug` as equivalent merely
because its name matches.
**Viable alternative:** add a dedicated constructor such as
`DebugFlag[I](set func(*I, Supplied[bool])) Flag[I]`. This still uses the ordinary
typed binding and composition path, but makes attachment explicit and avoids
exposing conflicting declaration options. It adds public API vocabulary and
makes debug construction different from other booleans. Prefer this if ordinary
`BoolFlag` reuse needs substantial metadata reconciliation or confusing exceptions.
The example constructor name is illustrative; choose one binding form rather
than adding both entry points without a demonstrated need.
### OD-2: Which application metadata can accompany a shared flag? ### OD-2: Which application metadata can accompany a shared flag?
**Recommendation:** retain the core boolean grammar and false default. Allow **Recommendation:** retain the core boolean grammar and false default. Allow
@@ -208,9 +195,8 @@ core reporting help, and allow a local short spelling through existing alias
and collision rules. Keep one displayed option. Continue using core boolean and collision rules. Keep one displayed option. Continue using core boolean
completion. Under the ordinary `BoolFlag` approach, report conflicting default, completion. Under the ordinary `BoolFlag` approach, report conflicting default,
requiredness, or completion overrides as declaration errors rather than silently requiredness, or completion overrides as declaration errors rather than silently
ignoring them. A dedicated constructor could instead omit those options. These ignoring them. These are proposed rules for the shared attachment only, not
are proposed rules for the shared attachment only, not accepted new restrictions accepted new restrictions on ordinary application flags.
on ordinary application flags.
This preserves consistent debug input across applications and avoids help that This preserves consistent debug input across applications and avoids help that
claims a default or requirement different from the shared flag. Its tradeoff is claims a default or requirement different from the shared flag. Its tradeoff is
@@ -229,5 +215,6 @@ allow local metadata to change core reporting selection.
**Simpler help alternative:** retain core flag help unchanged and put application **Simpler help alternative:** retain core flag help unchanged and put application
effects in the command description, with short spellings supplied through the effects in the command description, with short spellings supplied through the
existing `FlagAliasFor` mechanism. This avoids help merging, at the cost of less existing `FlagAliasFor` mechanism. This avoids help merging, at the cost of less
convenient flag-local documentation. It combines naturally with the dedicated convenient flag-local documentation. With ordinary `BoolFlag` registration,
constructor in OD-1. There is no need for a general metadata-merging framework. this alternative would also need to explain how supplied usage text and short
spellings are handled. There is no need for a general metadata-merging framework.