The -conflicts and -parsekeymode error vocabulary declared at define time
(0.19.0) is now enforced at parse. A new optionconflict failure class joins the
PUNKARGS VALIDATION errorcode vocabulary, mirroring optionmissing's shape:
{optionconflict <arg_a> <arg_b> received <receivednames>} - it names both
offending received arguments, for both per-arg -conflicts violations (any
pair, cross-group) and -parsekeymode error group co-occurrence (distinct
members of a shared-parsekey group).
The check runs in a single post-resolution site in get_dict_form (after the
optionmissing/valuemissing block), so the ordinary option path and the mash
(short-flag bundling) path share it - both raise identically. Checked against
RECEIVED arguments only (defaults never conflict), after prefix/abbreviation
resolution, on optset identity (a new optsets_received tracker for options,
since flagsreceived collapses shared-parsekey members onto one api_opt). Runs
unconditionally - a received conflict is a hard contradiction in any mode, not
end-of-input exhaustion, so parse_status_classify maps optionconflict to invalid
(not incomplete) and the candidacy/viability probe reports it.
Define-time check added: a group marked -parsekeymode error must also declare a
non-empty -parsekey (the strict mode only applies to a shared-parsekey group).
relations.test extended with 7 enforcement pins (raise cases for -conflicts
and -parsekeymode error, defaults-never-conflict, cross-group conflicts,
one-received-ok, override-legacy last-wins, parse_status invalid). buildversion
0.19.0 -> 0.20.0.
Bug found and fixed during the increment: the group-co-occurrence dedup check
initially used `ni` (not-in) where `in` was meant - `ni` returns true on an
empty list, so it skipped every member and the check never fired. Corrected
to `in`.
Legacy untouched by default: -parsekeymode override is the default and absent
-conflicts means no check runs, so the full existing suite (including the
pinned parsekey_repeat_ordering last-wins / prepend-defaults idiom) passes
unchanged.
Verification: full punk/args suite via canonical tclsh90s - 363 total / 360
passed / 3 skipped (punkargsKnownBug) / 0 failed; punk/ns suite 125/125 clean.
goals_lint clean. No punkproject.toml bump (module API addition, not shell-
level user-visible behaviour yet - the lsearch moduledoc adoption that ships
user-visible behaviour lands in increment 3).
Assisted-by: harness=pi; primary-model=huggingface/zai-org/GLM-5.2; api-location=huggingface.co
#(c) a group marked -parsekeymode error must have a non-empty -parsekey -
#the strict mode only has meaning for a shared-parsekey group (distinct
#members collide on the shared result key); an unnamed or keyless group
#has no shared key to conflict on.
dict for {_g83_g _g83_ginfo} [dict get $FDICT OPT_GROUPS] {
if {[punk::args::system::Dict_getdef $_g83_ginfo -parsekeymode override] ne "error"} continue
if {$_g83_g eq ""} continue ;#-parsekeymode required -group at the @opts line already
set _g83_gpk [punk::args::system::Dict_getdef $_g83_ginfo -parsekey ""]
if {$_g83_gpk eq ""} {
error "punk::args::resolve - -parsekeymode error for group '$_g83_g' requires the group to also declare a non-empty -parsekey (the strict mode only applies to a shared-parsekey group). @id:$DEF_definition_id"
set flagsreceived [list] ;#for checking if required flags satisfied
set optsets_received [list] ;#G-083: per-optset received tracker (options only) for -conflicts/-parsekeymode checks - flagsreceived collapses shared-parsekey members onto one api_opt, so the optset is tracked separately here
#G-083 group exclusivity: @opts -parsekeymode error - distinct members of a shared-
#parsekey group received together is an error (iterate groups for deterministic output).
dict for {_g83_g _g83_ginfo} $OPT_GROUPS {
if {[punk::args::system::Dict_getdef $_g83_ginfo -parsekeymode override] ne "error"} continue
set _g83_g_received [list]
foreach _g83_optset $OPT_NAMES {
if {$_g83_optset ni $_g83_received_optsets} continue
set _g83_grp [punk::args::system::Dict_getdef [dict get $ARG_INFO $_g83_optset] -group ""]
if {$_g83_grp ne $_g83_g} continue
if {$_g83_optset in $_g83_g_received} continue
lappend _g83_g_received $_g83_optset
}
if {[llength $_g83_g_received] > 1} {
set _g83_a [lindex $_g83_g_received 0]
set _g83_b [lindex $_g83_g_received 1]
set msg "Arguments '$_g83_a' and '$_g83_b' for %caller% belong to mutually exclusive group '$_g83_g' (-parsekeymode error) and may not be supplied together."
#0.20.0 - G-083 increment 2 (argument-relations parse-time enforcement): the -conflicts and -parsekeymode error vocabulary declared at define time (0.19.0) is now enforced at parse. A new optionconflict failure class joins the PUNKARGS VALIDATION errorcode vocabulary, mirroring optionmissing's shape: {optionconflict <arg_a> <arg_b> received <receivednames>} - it names both offending received arguments, for both per-arg -conflicts violations (any pair, cross-group) and -parsekeymode error group co-occurrence (distinct members of a shared-parsekey group). The check runs in a single post-resolution site in get_dict_form (after the optionmissing/valuemissing block), so the ordinary option path and the mash (short-flag bundling) path share it - both raise identically. Checked against RECEIVED arguments only (defaults never conflict), after prefix/abbreviation resolution, on optset identity (a new optsets_received tracker for options, since flagsreceived collapses shared-parsekey members onto one api_opt). Runs unconditionally - a received conflict is a hard contradiction in any mode, not end-of-input exhaustion, so the candidacy/viability probe reports it as status invalid (parse_status_classify maps optionconflict to invalid, not incomplete). Define-time check added: a group marked -parsekeymode error must also declare a non-empty -parsekey (the strict mode only applies to a shared-parsekey group). Legacy untouched by default: -parsekeymode override is the default and absent -conflicts means no check runs, so the full existing suite (including the pinned parsekey_repeat_ordering last-wins / prepend-defaults idiom) passes unchanged. relations.test extended with 7 parse-time enforcement pins (raise cases, defaults-never-conflict, cross-group, parsekeymode error raise + one-received-ok + override-legacy, parse_status invalid); full punk/args suite green.
#0.19.0 - G-083 increment 1 (argument-relations define-time vocabulary): new per-argument key -conflicts <list> (parsekeys or flag names that must not be RECEIVED together with this argument; checked against received args only at parse time, defaults never conflict - parse-time optionconflict enforcement lands in a later G-083 increment) and new @opts-level -parsekeymode override|error (per named OPT_GROUPS group; error = distinct-member co-occurrence within a shared-parsekey group raises optionconflict at parse; override = legacy last-wins, the default). Both keys are cross-validated at resolve: -conflicts targets must name a defined argname or declared -parsekey; -parsekeymode requires -group and a value of override|error. Define-time integrity hole closed: a -parsekey value colliding with a distinct defined argument's name (one that does not share that -parsekey) is now a resolve error instead of silently forming an implicit shared-key group (parsekey_collides_with_defined_optname_GAP flipped to a define-time error pin in parsekey.test). Legacy behaviour untouched by default (no -conflicts, default -parsekeymode override, no colliding parsekey). New testsuite relations.test pins the define-time vocabulary; full punk/args suite green.
#0.18.0 - G-151 annotated success render: new punk::args::parse_report - landing report for a SUCCESSFUL parse, one row per value-holding argument (received, or filled from -default) in declaration-section order (leaders, opts, values) with columns Argument | Source | Value - the success-side sibling of the arg_error usage table (a flag-like word consumed as a VALUE by position shows attributed to its consuming argument - the make.tcl dry-run 'kitname = punk91 -confirm 0' class). Input: a punk::args::parse result dict (its id key must resolve to a registered definition), or words + 'withid <id>' (the parse is performed first; a rejected line raises the same validation error parse would - only successful parses have a landing report). Source column: received / received xN (-multiple aggregation count) / default - the plain-mode-safe twin of the colour marking (received CLR(check), default CLR(parsekey_hint)); absent optionals with no default-in-effect get no row. Returns: table (arg_error-styled bordered block via textblock; the default), tableobject, string (plain lines 'name (source) = value'; also the degraded no-textblock path), dict (machine form: id/form/rows with class/source/received/positions/multiple/hasvalue/value - never elided). Display elision is type-aware, deterministic and always marked (display-hint honesty): strings single-line-ized (ansistring VIEW -lf 1 -vt 1 -sp 0 - embedded controls/ANSI render visibly so a value cannot disturb the table; real spaces stay spaces) then grapheme-capped via the new ansistring TRUNCATE (punk::ansi 0.2.0) with trailing '...' plus ' (len N)' citing the raw value's string length; -multiple aggregations and -type list values element-capped with '(+N more)' (whole list-quoted elements kept while they fit, first element char-capped if it alone overflows); -type dict values pair-capped with '(+N pairs)'; markers stay intact so cells can exceed very small caps by the marker width; plain-string fallbacks when punk::ansi is unavailable. Width cascade per the G-149 plumbing precedent: caller -valuewidth > new @cmd directive key -reportvaluewidth > built-in 48; 0 means no cap; deliberately never console-derived (deterministic and pipe-safe - the G-007 emit-then-query lesson). Value-in-effect lookup bridges storage-key folds at display level (-parsekey renames, aliased optionsets' last-|-member finalopts fold) so received aliased/parsekey'd arguments keep their row - G-084 owns the storage-key model itself. Failure-side rendering (arg_error/usage) unchanged. make.tcl retiring its interim one-line 'dry-run: line accepted ...' report in favour of this render is consumer follow-through after a bootsupport promotion (not part of this change). New testsuite parsereport.test; define -help documents @cmd -reportvaluewidth beside the other directive-options.
#0.17.0 - G-149 configurable multi-form synopsis hint labels: the per-form hint labels rendered beside a multi-form definition's synopsis lines in the usage/arg_error table (hard-coded ' i -form N ...' previously) are now a template substituted per form - %formindex% replaced with the form's 0-based ordinal, %formname% with its name; an empty template suppresses the labels entirely (the cell keeps just the Synopsis: label, as single-form renders do). Precedence: caller option > definition > built-in default. New arg_error/usage option -formhint <template> (supplied-empty means suppress; usage pulls it from arg_error's definition via resolved_def); new @cmd directive key -formhint <template> for definition-supplied hints (rides the existing arbitrary-key cmd_info merge, so resolved_def round-trips it; not display-deferred). Unconfigured definitions render byte-identical to 0.16.0 (default template reproduces the exact prior bytes, verified by capture diff). Motivation (G-143 origin): script-level (script) ids - e.g make.tcl's - are unreachable from any repl, so the repl-oriented ' i -form N ...' default is not actionable there; consumers can now name their own per-form navigation. The string (non-table) renderer never carried hint labels and is unchanged. make.tcl adoption is consumer follow-through after a bootsupport promotion (not part of this change). New testsuite formhint.test; define -help documents the @cmd key beside the other directive-options.
test conflicts_valid_parsekey_target {per-arg -conflicts naming a declared -parsekey is accepted at define time}\
test conflicts_valid_parsekey_target {per-arg -conflicts naming a declared -parsekey is accepted at define time (parse with only one member received)}\
