punkshell/goals/G-053-punkargs-multiple-ranges.md

G-053 punk::args range-valued -multiple: occurrence arity with strict duplicate handling

Status: proposed Scope: src/modules/punk/args-999999.0a1.0.tm (spec compiler, parse, arg_error/synopsis renderers), src/tests/modules/punk/args/testsuites/args/ Goal: -multiple accepts a {min max} occurrence range (mirroring -choicemultiple; max -1 unbounded) alongside the legacy booleans - so a definition can declare "at most once, repeat is an error" ({0 1}) or bounded repetition ({2 4}) instead of choosing between silent last-wins (0) and unbounded collection (1) - with boolean semantics preserved exactly, including the prepend-defaults/last-wins override idiom. Acceptance: parse raises a usage-style arity error naming the argument for occurrences outside a declared range; boolean -multiple 0/1 behaviour is unchanged (full existing punk::args suite passes untouched); the -optional/range-min reconciliation rule is documented and enforced at define time; the usage table Multi column and synopsis reflect declared ranges; -multipleunique/-multipleuniqueset compose with max>1 ranges unchanged; characterization tests cover the new forms and the value-shape rule.

Context

Boolean -multiple conflates three axes:

1. occurrence arity - how many times the argument may be supplied
2. overflow policy - what happens beyond the limit: silent replace (legacy -multiple 0 last-wins) or error
3. value shape - scalar vs list-of-occurrences

The motivating incident (2026-07-10): runtests.tcl's -include-paths was a non-multiple list option, so repeated -include-paths flags silently last-won - quietly narrowing a test run while reporting green, and defeating even a recorded memory note about the gotcha. Repeatable accumulating flags are the dominant convention in shell-facing CLIs (gcc -I, curl -H, rsync --exclude), so this misuse recurs. runtests was fixed by making that option -multiple 1, but the general fix for "repeat should be an error" has no expression today.

A separate -duplicates deny|replace policy flag was considered and rejected: with -multiple 1 a duplicates policy is meaningless (duplicates ARE the collected payload), so the flag's validity would depend on another flag's setting, and it would blur into the existing -multipleunique/-multipleuniqueset territory.

punk::args already has the shape precedent in its own vocabulary: -choicemultiple is a {min max} pair, not a boolean.

Approach

-multiple accepts a boolean (legacy, semantics preserved exactly) or a {min max} range (max -1 = unbounded):

• -multiple 0 - legacy: single-valued, repeats silently replace (last wins), scalar shape. Unchanged - this preserves the prepend-defaults override idiom punk::args::parse [list -flag default {*}$userargs].
• -multiple 1 - legacy: unbounded collection, list shape. Unchanged.
• -multiple {0 1} - at most once; a second occurrence is a parse (arity) error. This is the "duplicates deny" case.
• -multiple {2 4}, {1 -1} etc - bounded/lower-bounded repetition, collected.

Design decisions to settle (record here when made):

• Value shape for range forms: lean - max == 1 forms stay scalar (they are strict single-valued variants of legacy 0); max > 1 or -1 yield the occurrence list. Whatever is chosen must be pinned by the characterization tests.
• -optional vs range-min reconciliation: lean - -optional governs presence, the range governs occurrence count when present; contradictory combinations (e.g. range min >= 1 with -optional 1 intended as "required") rejected at define time with a clear message.
• Hot-path canonicalization: -multiple is truth-tested in many parse/render sites; a raw "0 1" value would fail expr boolean coercion. The spec compiler should canonicalize once into internal min/max/policy fields (alongside the existing ARG_INFO/ARG_CHECKS structures) so runtime checks stay cheap.

Display benefits: the usage table's Multi column and the synopsis ?arg...? rendering gain meaningful bounded-repetition forms (e.g. "0-1", "2-4").

Notes

• -multipleunique / -multipleuniqueset remain the uniqueness knobs and only make sense for max > 1; they compose with ranges unchanged.
• Related: G-045 (authoring ergonomics), G-046 (parse-time performance - the canonicalization must not regress the hot path).
• The runtests -include-paths fix (repeatable, accumulate, single-list form still accepted) shipped independently on 2026-07-10 and does not depend on this goal.
• Archived-goal references in this file: G-046 achieved 2026-07-10 (goals/archive/G-046-punkargs-deferred-help-and-fixes.md).