punk::args 0.5.0 + punk::ns 0.2.0: G-049 parse-status data model + machine-parsable cmdhelp returns
- new punk::args::parse_status: documented status structure from a parse attempt (overall ok / status valid|invalid|incomplete / scheme / message / errorcode minus -argspecs / failureclass / badarg / form / receivednames + per-argument argstatus with class, status ok|bad|unparsed, received count/positions, value-in-effect incl -default fill); validation failures reported in the structure, not raised
- arg_error -parsestatus: both renderers derive goodarg/badarg row marking and choice value-in-effect highlighting from the structure (transient goodargs/badarg locals replaced; built internally from -badarg/-parsedargs when not supplied)
- per-render scheme colour resolution: documented -scheme choice value 'nocolour' now takes effect and scheme renders no longer mutate the shared arg_error_CLR array (strike-only goodarg leak fixed)
- parse: new -caller option overriding the %caller% frame-walk substitution (included in parse cache key); get_dict missingrequiredvalue/missingrequiredleader now carry -badarg (type/allocation failures get badarg marking, not just choice violations)
- punk::ns::cmdhelp: -return dict {origin docid cmdtype args_remaining parsestatus}; advisory parse via parse_status on both alias and main paths; explicit -scheme honoured on the parse-failure render; failure messages name the queried command instead of leaking the internal parse source line at top call depth
- tests: parsestatus.test new (12); usagemarking.test G-049 GAP pins flipped + -parsestatus parity/badarg render tests (17); cmdhelp.test G-049 GAP pins flipped + cmdhelp_return_dict_* (25); punk/args + punk/ns trees green on Tcl 9.0.3 and 8.7; full source-tree suite baseline unchanged (exec-14.3 only)
- punkshell 0.5.0: CHANGELOG entry; src/tests/modules/AGENTS.md test-index blurbs updated
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
@ -5,6 +5,11 @@ The latest `## [X.Y.Z]` header must match the `version` field in `punkproject.to
Entries are newest-first; one bullet per notable change. See the root `AGENTS.md`
"Project Versioning" section for the bump policy.
## [0.5.0] - 2026-07-10
- punk::args 0.5.0 (G-049): new `punk::args::parse_status` - runs a parse attempt and returns a documented parse-status structure instead of raising on validation failure: overall `ok`/`status` (valid|invalid|incomplete)/`scheme`/`message`/`errorcode`/`failureclass`/`badarg`/`form`/`receivednames` plus per-argument `argstatus` entries (class, status ok|bad|unparsed, received count/positions, value-in-effect including `-default` fill). `arg_error` accepts the structure via `-parsestatus` and both its renderers derive goodarg/badarg row marking and choice value-in-effect highlighting from it. Scheme colours now resolve per-render: the documented `-scheme` value `nocolour` takes effect (previously it fell through to whatever colours the last scheme render left behind) and scheme renders no longer mutate the shared colour array (the strike-only goodarg style no longer leaks into later renders). `missingrequiredvalue`/`missingrequiredleader` failures now carry `-badarg`, and `punk::args::parse` gained `-caller` to control the `%caller%` attribution in failure messages.
- punk::ns 0.2.0 (G-049): `i <cmd> <args...>` (cmdhelp) gains `-return dict` - a machine-parsable dict of resolution info (origin/docid/cmdtype/args_remaining) plus the parse-status structure of the supplied argument words. Display fixes: a value failing its `-type` check now badarg-marks the unfillable argument's row (previously only choice violations marked anything), an explicit `-scheme` is honoured on the parse-failure path, and parse-failure messages name the queried command instead of leaking cmdhelp's internal parse source line at top call depth.
## [0.4.15] - 2026-07-10
- punk::args 0.4.2 (G-046): argument resolution no longer expands display-only `${...}` content (`-help` on `@cmd`/`@examples`/argument records, `@formdisplay` bodies) - expansion is deferred to help-display time with its own cache. First use of heavily documented commands is dramatically faster (`punk::ansi::mark_columns` first call ~4.3s → ~12ms; tclcore `::lseq` resolve ~184ms → ~2ms) and `-help` content that calls punk::args-parsing commands (including against its own definition id) resolves cleanly instead of stalling or looping. Also fixed: `@dynamic` multiline `-help` substitutions now align at their insertion column; prefix/alias-normalized choice values keep the same plain-string shape as exact input (`\Deleted`-style values); the `-return string` renderer aligns cmd-help continuation lines under the `Description:` label and its `Example:` line shows the example reference instead of the doc url.
#map each member of an -alias1|-alias2|-realname optionset to the optionset (the ARG_INFO key)
set lookup_optset [dict create]
foreach optionset [dict get $form_dict OPT_NAMES] {
foreach o [split $optionset |] {
dict set lookup_optset $o $optionset
}
}
#received argument names normalized to definition argument names.
#received is dict-like but may repeat keys for -multiple arguments; values are clause ordinals.
set receivednames [list]
set positions [dict create] ;#argname -> list of clause ordinals
foreach {r rpos} [Dict_getdef $parsedargs received {}] {
if {[string match -* $r] && [dict exists $lookup_optset $r]} {
set r [dict get $lookup_optset $r]
}
if {$r ni $receivednames} {
lappend receivednames $r
}
dict lappend positions $r $rpos
}
if {$badarg ne "" && [string match -* $badarg] && [dict exists $lookup_optset $badarg]} {
set badarg [dict get $lookup_optset $badarg]
}
set parsed_leaders [Dict_getdef $parsedargs leaders {}]
set parsed_opts [Dict_getdef $parsedargs opts {}]
set parsed_values [Dict_getdef $parsedargs values {}]
set argstatus [dict create]
foreach {names class parsedvalues} [list {*}{
} [dict get $form_dict LEADER_NAMES] leader {*}{
} $parsed_leaders {*}{
} [dict get $form_dict OPT_NAMES] option {*}{
} $parsed_opts {*}{
} [dict get $form_dict VAL_NAMES] value {*}{
} $parsed_values {*}{
}] {
foreach arg $names {
set argpositions [Dict_getdef $positions $arg {}]
set received [llength $argpositions]
if {$arg eq $badarg} {
set status bad
set argfailclass [dict get $opts -failureclass]
} elseif {$received > 0} {
set status ok
set argfailclass ""
} else {
set status unparsed
set argfailclass ""
}
#value-in-effect (includes values the parse filled from -default).
#Direct lookup by definition argument name, matching the display renderers:
#aliased optionsets store under their canonical name and are not resolved here.
if {[dict exists $parsedvalues $arg]} {
set hasvalue 1
set value [dict get $parsedvalues $arg]
} else {
set hasvalue 0
set value ""
}
dict set argstatus $arg [dict create class $class status $status received $received positions $argpositions hasvalue $hasvalue value $value failureclass $argfailclass]
}
}
return [dict create {*}{
} ok [dict get $opts -ok] {*}{
} status [dict get $opts -status] {*}{
} scheme [dict get $opts -scheme] {*}{
} message [dict get $opts -message] {*}{
} errorcode [dict get $opts -errorcode] {*}{
} failureclass [dict get $opts -failureclass] {*}{
} badarg $badarg {*}{
} id [Dict_getdef $spec_dict id ""] {*}{
} form $fid {*}{
} receivednames $receivednames {*}{
} argstatus $argstatus {*}{
}]
}
#resolve the form name whose argument set parse-status per-argument entries cover
#(first form matching the -form selection - mirrors arg_error's display-form resolution)
#0.5.0 - G-049 parse-status data model: new punk::args::parse_status - runs a parse attempt (withid/withdef) and returns a documented status structure instead of raising on validation failure (overall ok/status valid|invalid|incomplete/scheme/message/errorcode-minus-argspecs/failureclass/badarg/id/form/receivednames + per-argument argstatus with class/status ok|bad|unparsed/received/positions/hasvalue/value-in-effect incl -default fill). arg_error: new -parsestatus option - both renderers (table and string) now derive goodarg/badarg row marking and choice value-in-effect highlighting from the structure (built internally from -badarg/-parsedargs when not supplied), replacing the transient goodargs/badarg locals; scheme colours resolve per-render into a local array (scheme renders no longer mutate the shared arg_error_CLR array - the -nocolour leak) and the DOCUMENTED -scheme choice value 'nocolour' (and 'nocolor') now takes effect instead of falling through to leftover colours. parse: new -caller option overriding the %caller% frame-walk substitution in validation failure messages (parse_status defaults it to the definition's @cmd -name). get_dict: missingrequiredvalue/missingrequiredleader allocation failures now carry -badarg (type-failed words get badarg marking, not just choice violations). Tests: parsestatus.test (new), usagemarking.test nocolour/leak GAP pins flipped + -parsestatus render parity
#0.4.2 - G-046: display-field deferral - resolve no longer tstr-expands display-only content during argument resolution: ${...} in -help (@cmd/@examples/argument records) and @formdisplay -header/-body is masked with inert tokens (spec key DISPLAY_DEFERRED) and expanded on demand at display time (arg_error/eg/resolved_def/@default-copyfrom hooks; separate argdefcache_display cache for non-dynamic defs; @dynamic display content re-expands per render preserving provider refresh). First parse of heavily documented commands drops accordingly (punk::ansi::mark_columns ~4.3s -> ~12ms; tclcore ::lseq resolve ~184ms -> ~2ms) and -help content that calls punk::args-parsing commands (including against its own id) no longer stalls or loops - plus a display-time reentrancy guard (raw ${...} source substituted on nested expansion of the same id). Record splitter factored to private::split_definition_records. Also: @dynamic second-round multiline substitutions into deferred fields now get the 'line' paramindents alignment (rendering_atdynamic_multiline_help_insertion GAP flipped); prefix/alias choice normalization writeback no longer list-quotes single-element-clause values ({\Deleted} shape bug, choicegroups_imap_prefix_shape GAP flipped); -return string renderer aligns cmd-help continuations under the Description label and its Example line shows the example instead of the doc url. Tests: deferredhelp.test (new), rendering.test/choicegroups.test updated per G-046 acceptance
#0.4.1 - fixed ensemble_subcommands_definition building the definition against unloaded argdocs: subhelp/doctype-punkargs choiceinfo entries and synopsis choicelabels were omitted for documented subcommands whose registered namespace (::punk::args::register::NAMESPACES) had not yet been lazily loaded - e.g first 'i ansistring' in a fresh shell rendered the autogenerated ensemble help without subcommand-help markers until something else loaded ::punk::ansi::ansistring. The generator now runs update_definitions for the namespaces its id_exists checks could resolve in before testing them (tests: punk/args ensembledef.test, punk/ns cmdhelp.test cmdhelp_ensemble_lazy_registered_argdocs)
#0.4.0 - tidy-up (pre G-046): removed dead developer-test procs define2 and parseXXX and the unused ::punk::args::TEST definition; renamed the interactive Get_caller diagnostics test_get_dict/test_get_by_id/test_callers (+ test1 id) and lib::tstr_test_one with leading double underscores and excluded them from exports (punk::args::lib now exports {[a-z]*} instead of *). new punk::args::private namespace (namespace path to punk::args/lib/system) for internal helpers - _get_dict_can_assign_value, _split_type_expression, _check_clausecolumn, _synopsis_form_arg_display, _argerror_load_colours and lib::_parse_tstr_parts moved there with underscore prefixes dropped. documentation: PUNKARGS definitions added for every remaining exported command (errorstyle, undefine, undefine_deflist, raw_def, resolved_def_values, get_spec, is_dynamic, rawdef_id, rawdef_is_dynamic, id_exists, idaliases, set_idalias, unset_idalias, get_idalias, id_query, real_id, status, choiceword_match, get_dict; lib: string_is_dict, flatzip, zero_based_posns, choiceinfo_marks, indent, undent, undentleader, longestCommonPrefix, lunique; helpers and argdocbase B/N/I/NI); resolve's empty @cmd -help filled in; punk::args::argdocbase added to the registered definition namespaces
#0.2.0 - G-049: cmdhelp -return dict - machine-parsable return carrying resolution info (origin/docid/cmdtype/args_remaining) plus the parse-status structure of the supplied argument words (punk::args::parse_status shape; empty for undocumented commands); the scheme field reflects an explicit -scheme and the G-046-item-5 no-supplied-words suppression. cmdhelp's advisory parse now runs via punk::args::parse_status on both the alias path and the main path: an explicit -scheme is honoured on the parse-failure render (previously only on success/tableobject - failures returned parse's internally rendered error with the default error scheme), failure renders consume the structure via arg_error -parsestatus (badarg marking now covers type/allocation failures via the structure), and the failure message names the queried command (parse -caller: querycommand + consumed subcommand words) instead of whatever the %caller% frame walk found - at top call depth that was cmdhelp's own raw 'punk::args::parse $args_remaining ...' source text. Tests: cmdhelp.test G-049 GAP pins flipped + cmdhelp_return_dict_* added
#0.1.4 - G-046 item 5: cmdhelp's advisory goodargs parse failing with NO supplied argument words (e.g 'i string is' where the definition requires leaders) now shows plain info-scheme usage instead of the internal-looking "Bad number of leading values for punk::args::parse ..." error output (both the alias path and the main path; error display for supplied-but-invalid words unchanged). The no-supplied-words advisory parse runs with -errorstyle minimal so its failure doesn't render the full usage table inside the discarded error - large argdocs (e.g 'i punk::args::define') render the table once, not twice (verified parity with pre-G-046 timings: ~5.3s first/~4.1s repeat on punk91 src, table construction dominant). Test: cmdhelp.test cmdhelp_leader_required_no_args_plain_usage
#0.1.3 - documentation-only: cmdhelp 'subcommand' argument help rewritten to match actual behaviour (was described as ensemble-subcommands-only; also covers tcl::oo methods and argument words, whose validity drives the info/error scheme and received-argument marking of the usage display)
#0.1.2 - cmd_traverse subcommand walk resolves choice words via the shared punk::args::choiceword_match resolver (G-040 parity): -choiceprefixdenylist and -choiceprefixreservelist are now honoured in doc lookup (previously ignored - 'i <cmd> <word>' could accept words parsing rejects), -choicealiases normalize to their canonical before choiceinfo lookup, and -nocase is honoured in the walk
- `punk/ansi/` — punk::ansi tests (`testsuites/ansi/`): ansistrip/ansimerge, plus characterization of the ANSI-at-position mechanisms (`ansistring.test`: INDEX/INDEXCODE/INDEXCHAR/RANGE/INSERT grapheme indexing with SGR-prefix merging, INDEXCOLUMNS/COLUMNINDEX double-wide column mapping, trim/VIEW), code splitting invariants (`ta.test`: detect/detectcode distinction, split_codes/split_codes_single/split_at_codes shapes and round-trip) and single-code/effective-state semantics (`codetype.test`: is_sgr_reset/has_sgr_leadingreset, has_any/all_effective, sgr_merge, sequence_type classify). ANSI codes in these tests are literal escape strings so results are colour-state independent
- `punk/args/` — punk::args tests (`testsuites/args/`): parsing, choices/choicegroups, forms, rendering/indentation characterization, and usage-marking characterization (`usagemarking.test`: -parsedargs/-badarg/-scheme marking primitives plus goodchoice highlighting of selected/default-in-effect choice words, asserted by SGR-parameter subset against the live colour arrays; GAP pins for the nocolour-scheme fallthrough and shared colour-array leakage that G-049 will flip)
- `punk/ns/` — punk::ns tests (`testsuites/ns/`): cmdwhich/cmdinfo/cmd_traverse doc-lookup flow (`cmdflow.test`, G-040 parity) and cmdhelp usage-rendering integration (`cmdhelp.test`: scheme selection, goodarg/badarg marking, goodchoice highlighting of supplied/default choice words, alias path, cmdinfo result shape; GAP pins for badarg coverage/scheme-on-failure/caller attribution (G-049), pseudo-command cmdtype + space-form docid prefixes (G-051, real `string is` pins behind the have_tclcoredocs constraint), TclOO undocumented-method fallback (G-052), and synopsis marking absence (G-050))
- `punk/args/` — punk::args tests (`testsuites/args/`): parsing, choices/choicegroups, forms, rendering/indentation characterization, usage-marking characterization (`usagemarking.test`: -parsedargs/-badarg/-parsestatus/-scheme marking primitives plus goodchoice highlighting of selected/default-in-effect choice words, asserted by SGR-parameter subset against the live colour arrays; the G-049 nocolour/colour-leak GAP pins flipped 2026-07-10 to scheme-statelessness assertions), and the G-049 parse-status structure (`parsestatus.test`: punk::args::parse_status overall/per-argument statuses, badarg for type/allocation failures, -caller attribution, errorcode -argspecs stripping)
- `punk/ns/` — punk::ns tests (`testsuites/ns/`): cmdwhich/cmdinfo/cmd_traverse doc-lookup flow (`cmdflow.test`, G-040 parity) and cmdhelp usage-rendering integration (`cmdhelp.test`: scheme selection, goodarg/badarg marking incl type/allocation failures, goodchoice highlighting of supplied/default choice words, alias path, cmdinfo result shape, queried-command failure attribution, and `-return dict` parse-status returns (G-049 - its GAP pins flipped 2026-07-10); remaining GAP pins for pseudo-command cmdtype + space-form docid prefixes (G-051, real `string is` pins behind the have_tclcoredocs constraint), TclOO undocumented-method fallback (G-052), and synopsis marking absence (G-050))
test parsestatus_typed_value_allocation_failure {a supplied word failing its -type check surfaces as an allocation shortfall WITH the unfillable argument as badarg}\
-setup $common -body {
set ps [punk::args::parse_status {v1 x x} withid ::testspace::psfix]
lappend result [dict get $ps ok] [dict get $ps failureclass] [dict get $ps badarg]
lappend result [dict get $ps argstatus firstval status]
lappend result [dict get $ps argstatus lastval status]
}\
-cleanup {
}\
-result [list 0 missingrequiredvalue firstval bad unparsed]
test parsestatus_count_shortfall_incomplete {too few values reports incomplete with no offending argument}\
-setup $common -body {
set ps [punk::args::parse_status {v1} withid ::testspace::psfix]
lappend result [dict get $ps ok] [dict get $ps status] [dict get $ps failureclass] [dict get $ps badarg]
}\
-cleanup {
}\
-result [list 0 incomplete trailingvaluecount {}]
test parsestatus_count_excess_invalid {too many values reports invalid (the count classes only classify as incomplete below the minimum)}\
-setup $common -body {
set ps [punk::args::parse_status {v1 0 1 2} withid ::testspace::psfix]
lappend result [dict get $ps ok] [dict get $ps status]
}\
-cleanup {
}\
-result [list 0 invalid]
test parsestatus_errorcode_argspecs_stripped {the reported errorcode keeps classification and custom keys but not the bulky -argspecs payload}\
-setup $common -body {
set ps [punk::args::parse_status {horse 5} withid ::testspace::pschoosy]
#trigger the initial colour-array load, then capture the pristine styles the tests
#assert against (the shared arg_error_CLR array is mutated in place by scheme renders -
#see the leakage GAP pins at the end of this file - so capture before anything else)
#trigger the initial colour-array load, then capture the styles the tests assert
#against (since G-049 scheme renders resolve colours per-render and no longer mutate
#the shared arrays - the statelessness tests at the end of this file pin that)
render_markfix
variable GOOD [sgr_params $::punk::args::arg_error_CLR(goodarg)]
variable BAD [sgr_params $::punk::args::arg_error_CLR(badarg)]
@ -369,63 +369,94 @@ namespace eval ::testspace {
}\
-result [list 1 0 0]
#--- GAP pins: the nocolour scheme and shared colour-array statefulness ------------------
#arg_error normalizes its -scheme value with a switch whose nocolour arm matches "",
#"-nocolor" and "-nocolour" (leading dash) - so the DOCUMENTED choice value "nocolour"
#falls through to the catch-all "na" scheme: no override array is merged and the render
#uses whatever colours the most recent info/error render left in the shared
#arg_error_CLR array. The dash spelling "-nocolour" does merge the nocolour overrides -
#and because the merge writes the shared array in place, its strike-only goodarg/badarg
#styles then LEAK into all subsequent renders (nothing restores them until a colour
#on/off state flip forces an array reload).
#Pinned 2026-07-10 as characterization - a fix (accept the documented choice value +
#per-render colour resolution, G-049 candidates) should flip these pins.
test usagemarking_GAP_scheme_nocolour_renders_with_leftover_colours {the documented choice value 'nocolour' is treated as an unknown scheme and renders with the previous scheme's colours}\
#Flipped from GAP pins 2026-07-10 by G-049: arg_error's scheme switch previously only
#matched dash spellings for the nocolour arm (the DOCUMENTED choice value 'nocolour'
#fell through to the catch-all "na" scheme and rendered with whatever colours the most
#recent scheme render left behind), and scheme overrides were merged into the SHARED
#arg_error_CLR array in place - leaking into all subsequent renders until a colour
#on/off state flip forced a reload. Colours are now resolved per-render into a local
#array and the documented choice value takes effect.
test usagemarking_scheme_nocolour_documented_choice {the documented choice value 'nocolour' takes effect regardless of which scheme rendered previously}\
-setup $common -body {
variable INFOBORDER
#prime the shared array with the info scheme, then render 'nocolour'
#prime with the info scheme, then render 'nocolour' - no info border may remain
render_markfix -scheme info
set out [render_markfix -scheme nocolour]
lappend result [has_sgr_with $out $INFOBORDER]
#prime with the error scheme instead - the same call now renders differently
#prime with the error scheme instead - the same call renders identically
render_markfix -scheme error
set out [render_markfix -scheme nocolour]
lappend result [has_sgr_with $out $INFOBORDER]
}\
-cleanup {
punk::args::private::argerror_load_colours 1
}\
-result [list 1 0]
-result [list 0 0]
test usagemarking_GAP_dash_nocolour_leaks_into_shared_array {a -scheme -nocolour (dash spelling) render overwrites goodarg in the shared colour array}\
test usagemarking_scheme_render_shared_array_not_mutated {a -scheme -nocolour (dash spelling) render leaves the shared colour array pristine}\
-setup $common -body {
variable GOOD
variable NCGOOD
render_markfix -scheme -nocolour
set leaked [sgr_params $::punk::args::arg_error_CLR(goodarg)]
#the shared array now holds the strike-only nocolour style, not the pristine one
lappend result [expr {$leaked eq $NCGOOD}]
lappend result [expr {$leaked eq $GOOD}]
set goodnow [sgr_params $::punk::args::arg_error_CLR(goodarg)]
#the shared array keeps the pristine goodarg style, not the strike-only nocolour override
lappend result [expr {$goodnow eq $NCGOOD}]
lappend result [expr {$goodnow eq $GOOD}]
}\
-cleanup {
punk::args::private::argerror_load_colours 1
}\
-result [list 1 0]
-result [list 0 1]
test usagemarking_GAP_dash_nocolour_leak_affects_later_info_render {after a -scheme -nocolour render, an info-scheme render marks goodargs with the leaked strike-only style}\
test usagemarking_scheme_render_isolation_later_info_render {after a -scheme -nocolour render, an info-scheme render still marks goodargs with the pristine goodarg style}\
-setup $common -body {
variable GOOD
variable NCGOOD
render_markfix -scheme -nocolour
set argd [punk::args::parse {v1 0 1} withid ::testspace::markfix]
set out [render_markfix -scheme info -parsedargs $argd]
#marking present as strike (9) without the green (32) of the pristine goodarg style
lappend result [any_line_has_sgr $out lvarname $NCGOOD [lremove_params $GOOD $NCGOOD]]
lappend result [any_line_has_sgr $out lvarname $GOOD]
}\
-cleanup {
punk::args::private::argerror_load_colours 1
}\
-result [list 1]
test usagemarking_scheme_repeat_renders_identical {repeated renders of the same call are byte-identical regardless of prior scheme renders}\
-setup $common -body {
set argd [punk::args::parse {v1 0 1} withid ::testspace::markfix]
set first [render_markfix -scheme info -parsedargs $argd]
render_markfix -scheme error
render_markfix -scheme -nocolour
render_markfix -scheme nocolour
set again [render_markfix -scheme info -parsedargs $argd]
#Flipped from GAP pins 2026-07-10 by G-049: badarg marking now covers type/allocation
#failures (missingrequiredvalue/missingrequiredleader carry -badarg), an explicit
#-scheme reaches the parse-failure render (cmdhelp renders failures itself from the
#parse-status structure instead of returning parse's internally rendered error), and
#the failure message names the queried command via parse -caller instead of whatever
#the call-frame walk found.
test cmdhelp_GAP_no_badarg_marking_for_failed_typed_value {a value failing its -type check reports 'missingrequiredvalue' with NO badarg marking - only choice violations mark the bad argument}\
test cmdhelp_badarg_marking_failed_typed_value {a value failing its -type check (surfacing as an allocation shortfall) badarg-marks the unfillable argument's row}\
-setup $common -body {
variable BAD
set out [punk::ns::cmdhelp ::testspace::helpfix v1 x x]
#the message names the failing argument but no row is badarg-marked
#the message names the failing argument and its row is badarg-marked
lappend result [string match "*fail on firstval*" [punk::ansi::ansistrip [lindex [split $out \n] 0]]]
lappend result [any_line_has_sgr $out firstval $BAD]
lappend result [any_line_has_sgr $out lastval $BAD]
}\
-cleanup {
}\
-result [list 1 0 0]
-result [list 1 1 0]
test cmdhelp_GAP_explicit_scheme_ignored_on_failure {an explicit -scheme is honoured on the success path but IGNORED on the parse-failure path (the rendered error keeps the error scheme)}\
test cmdhelp_explicit_scheme_honoured_on_failure {an explicit -scheme is honoured on the parse-failure path as well as the success path}\
-setup $common -body {
variable INFOBORDER
set out [punk::ns::cmdhelp -scheme info ::testspace::helpfix v1]
@ -352,25 +360,79 @@ namespace eval ::testspace {
}\
-cleanup {
}\
-result [list 0]
-result [list 1]
test cmdhelp_GAP_errormsg_leaks_internal_source {called at the global level (as from a repl), the parse-failure message shows cmdhelp's own unsubstituted source line as the caller instead of the queried command}\
test cmdhelp_errormsg_names_queried_command {the parse-failure message names the queried command at any invocation depth - never cmdhelp's internal parse source}\
-setup $common -body {
#caller attribution depends on the invocation depth: from a nested context the
#message names the user's cmdhelp invocation (correct), but a top-level call -
#the interactive 'i <cmd>' case - walks to cmdhelp's internal parse call and
#shows its raw source text
#top-level call - the interactive 'i <cmd>' case
set out [uplevel #0 [list punk::ns::cmdhelp ::testspace::helpfix v1]]
set line1 [punk::ansi::ansistrip [lindex [split $out \n] 0]]
lappend result [string match {*punk::args::parse $args_remaining*} $line1]
#from a nested context the same call attributes correctly
lappend result [string match {*punk::args::parse*} $line1]
lappend result [string match {*::testspace::helpfix*} $line1]
#nested context attributes identically
set out [punk::ns::cmdhelp ::testspace::helpfix v1]
set line1 [punk::ansi::ansistrip [lindex [split $out \n] 0]]
lappend result [string match {*punk::ns::cmdhelp*} $line1]
lappend result [string match {*::testspace::helpfix*} $line1]
test cmdhelp_return_dict_valid {a fully-valid argument set returns ok/valid/info with received arguments status ok}\
-setup $common -body {
set d [punk::ns::cmdhelp -return dict ::testspace::helpfix v1 0 1]
lappend result [dict keys $d]
lappend result [dict get $d docid] [dict get $d cmdtype]
set ps [dict get $d parsestatus]
lappend result [dict get $ps ok] [dict get $ps status] [dict get $ps scheme]
lappend result [dict get $ps argstatus lvarname status]
lappend result [dict get $ps argstatus firstval status] [dict get $ps argstatus firstval value]
#-flag was not supplied
lappend result [dict get $ps argstatus -flag status]
}\
-cleanup {
}\
-result [list {origin docid cmdtype args_remaining parsestatus} ::testspace::helpfix proc 1 valid info ok ok 0 unparsed]
test cmdhelp_return_dict_invalid {an invalid argument set (choice violation) returns ok 0/invalid/error with the offending argument status bad}\
-setup $common -body {
set d [punk::ns::cmdhelp -return dict ::testspace::choosy horse 5]
set ps [dict get $d parsestatus]
lappend result [dict get $ps ok] [dict get $ps status] [dict get $ps scheme]
lappend result [dict get $ps badarg] [dict get $ps failureclass]
lappend result [dict get $ps argstatus animal status]
lappend result [dict get $ps argstatus volume status]
lappend result [expr {[dict get $ps message] ne ""}]
}\
-cleanup {
}\
-result [list 0 invalid error animal choiceviolation bad unparsed 1]
test cmdhelp_return_dict_incomplete {an incomplete argument set returns ok 0/incomplete with no offending argument}\
-setup $common -body {
set d [punk::ns::cmdhelp -return dict ::testspace::helpfix v1]
set ps [dict get $d parsestatus]
lappend result [dict get $ps ok] [dict get $ps status] [dict get $ps scheme] [dict get $ps badarg]
}\
-cleanup {
}\
-result [list 0 incomplete error {}]
test cmdhelp_return_dict_scheme {the dict scheme field reflects an explicit -scheme, and the no-supplied-words suppression (G-046 item 5) reports info}\
-setup $common -body {
set d [punk::ns::cmdhelp -return dict -scheme error ::testspace::helpfix v1 0 1]
lappend result [dict get [dict get $d parsestatus] scheme]
#leader-requiring definition with no argument words - failure reflects only the
#absent input, reported with the info scheme the display path would use
set d [punk::ns::cmdhelp -return dict ::testspace::helpstr]
set ps [dict get $d parsestatus]
lappend result [dict get $ps ok] [dict get $ps scheme]
