rename_command accepts a new leading option '-punkargs
<list-of-definitionlists>' attaching punk::args doc blocks to the
rename's stack record - e.g documenting a subcommand the override adds,
with space-form ids such as {::package epoch}. Each element is one
definitionlist exactly as given to punk::args::define (the same shape as
a PUNKARGS variable element).
Lifecycle: docs attach only when the rename lands (aborted renames
return early) and are LIVE while the record is on the stack. The detach
hook sits at remove_rename's doomed-record site - pop_rename,
remove_renamer and restore_original all funnel through it - so every
removal path removes the docs with the record.
Works whether or not punk::args is loaded at rename time: deflists are
mirrored in a new ::commandstack::stackdocs namespace registered inert
into ::punk::args::register::NAMESPACES at module load (punk::args need
not be present - the early-boot renames precede it), so a later-loading
punk::args picks them up lazily; when punk::args is already present they
are ALSO defined immediately (a namespace already consumed into
loaded_packages never lazy-loads later appends; redefinition is
idempotent). Detach removes one mirror occurrence per deflist and
undefines via punk::args::undefine_deflist (deflist-keyed - commandstack
never parses ids; never-defined deflists skip silently). Supported
shape: one live record per doc id (same-id declarations in two records
shadow; removing either removes the doc).
The record carries the deflists under a trailing 'punkargs' key - the
append-only key-order contract is preserved (token idx 0-1, renamer idx
2-3). The leading-option parse is generalised: -renamer/-punkargs in
either order, both leading-only, non-dash word ends option scanning so
misplaced options raise the pointed error. stackdocs state follows the
0.7.1 reload contract (info-exists guarded; registration idempotent
across re-source). commandstack::help and the rename_command argdoc
document the mechanism; the In-tree users line gains punk::libunknown
(the increment-2 migration).
commandstack.test: 5 new pins (docs live with the record incl key-order
assertions, all four removal paths detach, the pre-punk::args pending
path in a bare child that loads punk::args afterwards and lazily
consumes the registered mirror, reload contract on mirror + single
registration, option positions in either order + pointed misplacement) +
2 existing G-160 message pins updated to the generalised
usage/misplacement wording (behaviour contracts unchanged). Suite 46/46.
src/tests/modules/AGENTS.md commandstack bullet updated; goal Progress
entry added. Project 0.63.0 -> 0.64.0 + CHANGELOG.
Suites: commandstack 46/46; full modules tree 1351 total / 1340 pass /
11 constraint-skipped / 0 fail (zig-built tclsh90s 9.0.5);
testbody_lint 1704 clean; goals_lint clean (80 active-index / 96
archived); make.tcl projectversion consistency OK.
Claude-Session: https://claude.ai/code/session_01QgaxV27VZkmEec7oNbEVFc
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
#todo: consider -forcebase 1 or similar to allow this rename to point to bottom of stack (original command) bypassing existing renames
# - need to consider that upon removing, that any remaining rename that was higher on the stack should not also be diverted to the base - but rather to the next lower in the stack
#
if {[lindex $args 0] eq "-renamer"} {
set renamer [lindex $args 1]
set arglist [lrange $args 2 end]
} else {
set renamer ""
set arglist $args
set renamer ""
set punkargs_defs [list]
set arglist $args
while {[llength $arglist] > 3 && [string match -* [lindex $arglist 0]]} {
error "commandstack::rename_command -renamer is recognised only as the leading argument. usage: rename_command ?-renamer <string>? command procargs procbody"
foreach opt {-renamer -punkargs} {
if {$opt in $arglist} {
error "commandstack::rename_command $opt is recognised only in the leading option positions. usage: rename_command ?-renamer <string>? ?-punkargs <list-of-definitionlists>? command procargs procbody"
#0.8.0 - G-176 increment 3: rename_command accepts a new leading option '-punkargs <list-of-definitionlists>' attaching punk::args doc blocks to the rename's stack record (e.g documenting a subcommand the override adds, space-form ids like {::package epoch} supported). The docs are LIVE while the record is on the stack and are removed with it by ANY removal path - the detach hook sits in remove_rename, which pop_rename/remove_renamer/restore_original all funnel through. Works whether or not punk::args is loaded at rename time: deflists are mirrored in a new registered ::commandstack::stackdocs namespace (inert ::punk::args::register::NAMESPACES registration at module load - punk::args need not be present) so a later-loading punk::args picks them up lazily; when punk::args is already present they are ALSO defined immediately (a namespace already consumed into loaded_packages never lazy-loads later appends; redefinition is idempotent). Detach removes one mirror occurrence per deflist and undefines via punk::args::undefine_deflist (deflist-keyed - commandstack never parses ids; silently skips never-defined deflists). Record carries the deflists under a trailing 'punkargs' key (append-only key-order contract preserved: token idx 0-1, renamer idx 2-3). Supported shape: one live record per doc id (same-id declarations in two records shadow; removing either removes the doc). Leading-option parse generalised (-renamer/-punkargs in either order, both leading-only). stackdocs state follows the reload contract (info-exists guarded). help + rename_command argdoc document the how-to; In-tree users line gains punk::libunknown (the increment-2 migration). Pins: commandstack.test -punkargs lifecycle (docs live with record + removed by all four removal paths + pre-punk::args pending path in a bare child that loads punk::args afterwards + key-order/reload guards).
#0.7.1 - G-160 follow-on: reload contract - known_renamers and debug are now
# info-exists guarded like the rest of the module state (all_stacks,
# renamer_command_tokens, token_implementations): a module re-source no
#'rename_command -punkargs' attaches punk::args definitionlists to the record.
#Children needing punk::args derive the source-modules dir from
#::COMMANDSTACK_SRC and require it prefer-latest (999999 dev copy).
#docs live with the record: -punkargs defines immediately when punk::args is
#present, the record carries a TRAILING punkargs key (leading key-order
#contract intact - token/renamer lsearch indices unchanged), and
#remove_rename removes the doc and its stackdocs mirror entry with the record.
test commandstack_punkargs_docs_live_with_record {-punkargs docs defined at rename (punk::args loaded), trailing record key, removed with the record by remove_rename}\
-constraints commandstacksrc -body {
cs_probe {
tcl::tm::add [file dirname $::COMMANDSTACK_SRC]
package prefer latest
package require punk::args
proc ::tgt {args} {return [list base $args]}
set rec [commandstack::rename_command -renamer ::csA -punkargs {{{@id -id {::tgt extra}
lappend r [punk::args::id_exists {::tgt extra}] [llength $::commandstack::stackdocs::PUNKARGS]
}
set r
}
} -result {1 0 0 1 0 0 1 0 0}
#the early-boot shape: the rename happens BEFORE punk::args exists - the
#deflists sit in the registered stackdocs mirror, punk::args picks them up
#lazily (update_definitions on the registered namespace), and a pop still
#removes the by-then-defined doc.
test commandstack_punkargs_pending_before_punkargs_loads {-punkargs before punk::args loads: mirrored, lazily defined when punk::args arrives, removed on pop}\
