@ -341,34 +341,40 @@ tcl::namespace::eval punk::args::tclcore {
#review
#@values -form {*} #note "classify next argument as a value not a leader"
#@values -form {*}
@leaders -form {delay schedule_ms} -min 1 -max 1
ms -form {*} -type int -help\
"milliseconds"
@values -form {delay} -min 1 -max 1
@values -form {schedule_ms} -min 2
@values -form {delay} -min 0 -max 0
@values -form {schedule_ms} -min 1
script -form {schedule_ms} -multiple 1 -optional 0 ref-help common_script_help
@form -form {cancelid} -synopsis "after cancel id"
@values -min 2 -max 2
@leaders -min 1 -max 1
cancel -choices {cancel}
@values -min 1 -max 1
id
@form -form {cancelscript} -synopsis "after cancel script ?script...?"
@values -min 2
@leaders -min 1
cancel -choices {cancel}
@values -min 1
script -multiple 1 -optional 0 ref-help common_script_help
@form -form {schedule_idle} -synopsis "after idle script ?script...?"
@values -min 2
@leaders -min 1 -max 1
idle -choices {idle}
@values -min 1
script -multiple 1 -optional 0 ref-help common_script_help
@form -form {info} -synopsis "after info ?id?"
@values -min 0 -max 2
@leaders -min 1 -max 1
info -choices {info}
@values -min 0 -max 1
id -optional 1
} "@doc -name Manpage: -url [manpage_tcl after]" ]
@ -815,6 +821,64 @@ tcl::namespace::eval punk::args::tclcore {
key -type string -multiple 1 -optional 0
} "@doc -name Manpage: -url [manpage_tcl dict]" ]
# -- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---
# -- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---
lappend PUNKARGS [list {
@id -id ::tcl::dict::for
@cmd -name "Builtin: tcl::dict::for" -help\
"This command takes three arguments, the first a two-element list of
variable names (for the key and value respectively of each mapping in
the dictionary), the second the dictionary value to iterate across, and
the third a script to be evaluated for each mapping with the key and
value variable set appropriately (in the manner of ${$B}foreach${$N}).
The result of the command is an empty string. If any evlauation of the
body generates a ${$B}TCL_BREAK${$N} result, no further pairs from the
dictionary will be iterated over and the ${$B}dict for${$N} command will
terminate successfully immediately. If any evaluation of the body generates
a ${$B}TCL_CONTINUE${$N} result, this shall be treated exactly like a
normal ${$B}TCL_OK${$N} result. The order of iteration is the order in which
the keys were inserted into the dictionary."
@values -min 3 -max 3
"{keyVariable valueVariable}" -type list -minsize 2 -maxsize 2
dictionaryValue -type dict
body -type string -help\
"Tcl script"
} "@doc -name Manpage: -url [manpage_tcl dict]" ]
# -- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---
# -- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---
proc example {str} {
set str [string trimleft $str \n]
set block [punk::ansi::ansiwrap Web-gray [textblock::frame -ansibase [a+ Web-gray bold white] -ansiborder [a+ black White] -boxlimits {hl} -type block -- $str]]
set result [textblock::bookend_lines $block [a] "[a defaultbg] [a]"]
#puts $result
return $result
}
lappend PUNKARGS [list {
@id -id ::tcl::dict::get
@cmd -name "Builtin: tcl::dict::get" -help\
"Given a dictionary value (first argument) and a key (second argument), this
will retrieve the value for that key. Where several keys are supplied, the
behaviour of the command shall be as if the result of ${$B}dict get $dictVal $key${$N}
was passed as the first argument to ${$B}dict get${$N} with the remaining
arguments as second (and possibly subsequent) arguments. This facilitates
lookups in nested dictionaries. For example, the following two commands are
equivalent:
${[punk::args::tclcore::argdoc::example {
dict get $dict foo bar spong
dict get [dict get [dict get $dict foo] bar] spong\
}
]}
If no keys are provided, ${$B}dict get${$N} will return a list containing pairs
of elements in a manner similar to ${$B}array get${$N}. That is, the first
element of each pair would be the key and the second element would be the value
for that key.
It is an error to attempt to retrieve a value for a key that is not present in
the dictionary.
"
@values -min 1 -max -1
dictionaryValue -type dict
key -type string -multiple 1 -optional 1
} "@doc -name Manpage: -url [manpage_tcl dict]" ]
# -- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---
lappend PUNKARGS [list {
@id -id ::tcl::dict::replace
@cmd -name "Builtin: tcl::dict::replace" -help\
@ -1553,6 +1617,41 @@ tcl::namespace::eval punk::args::tclcore {
} "@doc -name Manpage: -url [manpage_tcl llength]"
# -- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---
# -- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---
lappend PUNKARGS [list {
@id -id ::lmap
@cmd -name "Builtin: lmap" -help\
"The ${$B}lmap${$N} command implements a loop where the loop variable(s)
take on values from one or more lists, and the loop returns a list of results
collected from each iteration.
In the simplest case there is one loop variable, ${$I}varname${$NI} and one ${$I}list${$NI},
that is a list of values to assign to ${$I}varName${$NI}. The ${$I}body${$NI}
argument is a Tcl script. For each element of ${$I}list${$NI} (in order from first
to last), ${$B}lmap${$N} assigns the contents of the element to ${$I}varName${$NI}
as if the ${$B}lindex${$NI} command had been used to extract the element, then
calls the Tcl interpreter to execute ${$I}body${$NI}.
If execution of the body completes normally then the result of body is appended
to an accumulator list. ${$B}lmap${$N} returns the accumulator list.
In the general case there can be more than one value list, and each value list
can be associated with a list of loop variables. During each iteration of the
loop the variable of each ${$I}varlist${$NI} are assigned consecutive values from
the corresponding ${$I}list${$NI}. Values in each ${$I}list${$NI} are used in order from
first to last, and each value is used exactly once. The total number of loop
iterations is large enough to use up all the values from all the value lists.
If a value list does not contain enough elements for each of its loop variables
in each iteration, empty values are used for the missing elements.
The ${$B}break${$N} and ${$B}continue${$N} statements may be invoked inside ${$I}body${$NI},
with the same effect as in the ${$B}for${$N} and ${$B}foreach${$N} commands.
In these cases the body does not complete normally and the result is not appended
to the accumulator list."
@values
"varlist list" -type {list list} -multiple 1 -optional 0
body -type string -optional 0 -help\
"Tcl script"
} "@doc -name Manpage: -url [manpage_tcl lmap]" ]
# -- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---
# -- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---
punk::args::define {
@id -id ::lpop
@cmd -name "builtin: lpop" -help\
@ -1669,6 +1768,19 @@ tcl::namespace::eval punk::args::tclcore {
@seealso -commands {list lappend lassign ledit lindex linsert llength lmap lpop lrange lrepeat lreplace lreverse lsearch lseq lset lsort}
} "@doc -name Manpage: -url [manpage_tcl lremove]"
# -- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---
# -- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---
punk::args::define {
@id -id ::lreverse
@cmd -name "builtin: lreverse" -help\
"Reverse the order of a list.
The ${$B}lreverse${$N} command returns a list that has the same elements
as its input list, ${$I}list${$NI}, exept with the elements in reverse
order."
@values -min 1 -max 1
list -type list -help\
"tcl list as a value"
} "@doc -name Manpage: -url [manpage_tcl lreverse]"
# -- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---
# -- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---
punk::args::define {
@ -1737,6 +1849,67 @@ tcl::namespace::eval punk::args::tclcore {
} "@doc -name Manpage: -url [manpage_tcl lset]"
# -- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---
# -- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---
punk::args::define {
@id -id ::lseq
@cmd -name "builtin: lseq" -help\
"Build a numeric sequence returned as a list.
The ${$B}lseq${$N} command creates a sequence of numeric values using the given
parameters ${$I}start${$NI}, ${$I}end${$NI} and ${$I}step${$NI}. The ${$I}operation${$NI}
argument \"..\" or \"${$B}to${$N}\" defines the range. The \"${$B}count${$N}\" option is
used to defina a count of the number of elements in the list. A short form use of the
command, with a single ${$I}count${$NI} value, will creat a range from 0 to ${$I}count-1${$NI}.
The ${$B}lseq${$N} command can produce both increasing and decreasing sequences.
When both ${$I}start${$NI} and ${$I}end${$NI} are provided without a ${$I}step${$NI} value,
then if ${$I}start${$NI} <= ${$I}end${$NI}, the sequence will be increasing and if
${$I}start${$NI} > ${$I}end${$NI} it will be decreasing. If a ${$I}step${$NI} value is
included, it's sign should agree with the direction of the sequence
(descending -> negative and ascending -> positive), otherwise an empty list is returned.
For example:
${[punk::args::tclcore::argdoc::example {
% lseq 1 to 5 ;#increasing
-> 1 2 3 4 5
% lseq 5 to 1 ;#decreasing
-> 5 4 3 2 1
% lseq 6 to 1 by 2 ;#decreasing, step wrong sign, empty list
% lseq 1 5 by 0 ;#all step sizes of 0 produce an empty list
}]}
The numeric arguments ${$I}start${$NI}, ${$I}end${$NI}, ${$I}step${$NI} and ${$I}count${$NI}, may
also be a valid expression. The expression will be evaluated and the numeric result will
be used. An expression that does not evaluate to a number will produce an invalid argument error.
${$I}Start${$NI} defines the initial value and ${$I}end${$NI} defines the limit, not necessarily
the last value. ${$B}lseq${$N} produces a list with ${$B}count${$N} elements and if ${$B}count${$N}
is not supplied, it is computed as:
count = int( (end - start + step) / step)
"
@form -form range
@leaders -min 0 -max 0
@values -min 2 -max 5
start -type number|expr
..|to -type string -choices {.. to} -optional 1
end -type number|expr
"by step" -type {literal number|expr} -optional 1
@form -form start_count
@leaders -min 0 -max 0
@values -min 3 -max 5
start -type number|expr
count -type literal
countelements -type number|expr
"by step" -type {literal number|expr} -optional 1
@form -form count
@leaders -min 0 -max 0
@values -min 1 -max 3
countelements -type number|expr
"by step" -type {literal number|expr} -optional 1
} "@doc -name Manpage: -url [manpage_tcl lreverse]"
# -- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---
}
