From 55330d28176b0d23901122c243ae7ae165184bf5 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 19 Oct 2026 12:19:30 +0000 Subject: [PATCH] Settle short alias grammar and empty-value correction --- docs/roadmap/aliases.md | 53 +++++++++++++++++++++++++++++++---------- 1 file changed, 40 insertions(+), 13 deletions(-) diff --git a/docs/roadmap/aliases.md b/docs/roadmap/aliases.md index 5c3369b..b2804c2 100644 --- a/docs/roadmap/aliases.md +++ b/docs/roadmap/aliases.md @@ -361,9 +361,40 @@ cycles during installation, identify the participating spellings in diagnostics, and revalidate composition after later registration. Support individual short alias spellings, such as `-c → --color`, alongside -long aliases. Value handling follows the target flag. Short-option clusters -and attached-value syntax must follow CommandKit's deliberately selected grammar; -verify that grammar before settling these forms under OD-6. +long aliases. Canonical short spellings and aliases use the same cluster and +attached-value grammar and may mix freely within a cluster. Resolve each alias +to its final canonical flag before determining whether it consumes a value. + +Process short spellings left to right. Boolean flags use presence as true; +explicit boolean values require `=`. The first value-taking flag consumes the +remaining suffix, removing a separating `=` when present, or consumes the next +argument if there is no suffix. Consumed values are never searched for aliases. +Unknown spellings within a cluster produce a usage error. Preserve occurrence +order for repeatable bindings and singleton last-occurrence behavior. + +With boolean aliases `-v → --verbose` and `-q → --quiet`, and value-taking +`-c → --color`: + +| Input | Interpretation | +| --- | --- | +| `-vq` | `--verbose --quiet` | +| `-c blue`, `-c=blue`, or `-cblue` | `--color=blue` | +| `-vqcblue` or `-vqc blue` | `--verbose --quiet --color=blue` | +| `-cvq` | `--color=vq` | +| `-v=false` | `--verbose=false` | +| `-qv=false` | `--quiet --verbose=false` | + +`-vfalse` is a cluster beginning with `-v`, not an explicit false value. +A spelling such as `-color` follows short-option parsing; long aliases use +the `--` prefix. Options still follow the complete command path, and `--` +ends option parsing. + +Correct explicit empty-value handling for both canonical short spellings and +aliases: `-c=` supplies an empty string, consistently with `--color=` and +`-c ""`. The current backend instead passes the literal string `"="` for `-c=`; +this delivery corrects that behavior. Likewise, `-v=` supplies an empty value +to boolean conversion and fails conversion. This correction preserves the +distinction between an omitted value and an explicitly supplied empty value. ### Flag help and diagnostics @@ -397,7 +428,9 @@ canonical binding. independent of optional-library dependencies and backend-specific exports. 4. Integrate command and flag alias resolution with canonical routing, help, and invocation identity. Use canonical flag metadata and the existing parser to - preserve values and operands, and reuse typed execution machinery. + preserve values and operands, and reuse typed execution machinery. Apply the + selected short-option grammar and correct explicit empty values for canonical + short spellings and aliases together. 5. Add focused behavioral evidence for both example mappings, group aliases, longest matches, chains, group composition, cycles and nonterminating prefix expansion, collisions, missing targets, same-batch @@ -405,7 +438,8 @@ canonical binding. acquisition, and a single execution lifecycle. Cover application-wide and command-scoped flag mappings, attached and separate values, option termination, mixed canonical/alias repetitions, flag chains and scope overrides, short - aliases, flag help and diagnostics, and unchanged typed binding semantics. + aliases, mixed clusters, attached values, explicit empty-value correction, + flag help and diagnostics, and unchanged typed binding semantics. 6. Add maintained consumer examples and update GoDoc, the CLI reference, consumer guidance, and internal documentation when implementation lands. Validate the affected modules under the [developer guide](../development.md). @@ -414,8 +448,7 @@ Completion means consumers can declare alternate command paths and flag spellings with minimal wiring and invoke canonical behavior and help through them while canonical ownership and binding semantics stay intact. Installation rejects conflicts with canonical commands and applicable flags in either -registration order. Remaining public API and short-option grammar details are -listed below. +registration order. Remaining public API details are listed below. ## Open Decisions @@ -429,9 +462,3 @@ interact with application-root alias paths? What exact whitespace parsing and path validation rules accompany the selected string representation? What accessor names and representation expose the selected read-only entered and canonical invocation paths? - -### OD-6: Short-option grammar - -Individual short aliases are selected above. Which short-option clusters and -attached-value forms does CommandKit's selected grammar support, and how should -short aliases participate in those forms?