jn
/
punkshell
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
283 Commits
1 Branch
1 Tag
197 MiB
 
 
 
 
 
 
Tree: ca1d9f422f
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'ca1d9f422f'
${ noResults }
punkshell/src/modules/punk/args/tclcore-999999.0a1.0.tm

747 lines
29 KiB
Raw Blame History

# -*- tcl -*-
# Maintenance Instruction: leave the 999999.xxx.x as is and use punkshell 'dev make' or bin/punkmake to update from <pkg>-buildversion.txt
# module template: punkshell/src/decktemplates/vendor/punk/modules/template_module-0.0.3.tm
#
# Please consider using a BSD or MIT style license for greatest compatibility with the Tcl ecosystem.
# Code using preferred Tcl licenses can be eligible for inclusion in Tcllib, Tklib and the punk package repository.
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
# (C) 2025
#
# @@ Meta Begin
# Application punk::args::tclcore 999999.0a1.0
# Meta platform tcl
# Meta license MIT
# @@ Meta End
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
# doctools header
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
#*** !doctools
#[manpage_begin punkshell_module_punk::args::tclcore 0 999999.0a1.0]
#[copyright "2025"]
#[titledesc {punk::args definitions for tcl core commands}] [comment {-- Name section and table of contents description --}]
#[moddesc {tcl core argument definitions}] [comment {-- Description at end of page heading --}]
#[require punk::args::tclcore]
#[keywords module]
#[description]
#[para] -
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
#*** !doctools
#[section Overview]
#[para] overview of punk::args::tclcore
#[subsection Concepts]
#[para] -
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
## Requirements
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
#*** !doctools
#[subsection dependencies]
#[para] packages used by punk::args::tclcore
#[list_begin itemized]
package require Tcl 8.6-
package require punk::args
#*** !doctools
#[item] [package {Tcl 8.6}]
#[item] [package {punk::args}]
#*** !doctools
#[list_end]
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
#*** !doctools
#[section API]
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
# oo::class namespace
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
#tcl::namespace::eval punk::args::tclcore::class {
#*** !doctools
#[subsection {Namespace punk::args::tclcore::class}]
#[para] class definitions
#if {[tcl::info::commands [tcl::namespace::current]::interface_sample1] eq ""} {
#*** !doctools
#[list_begin enumerated]
# oo::class create interface_sample1 {
# #*** !doctools
# #[enum] CLASS [class interface_sample1]
# #[list_begin definitions]
# method test {arg1} {
# #*** !doctools
# #[call class::interface_sample1 [method test] [arg arg1]]
# #[para] test method
# puts "test: $arg1"
# }
# #*** !doctools
# #[list_end] [comment {-- end definitions interface_sample1}]
# }
#*** !doctools
#[list_end] [comment {--- end class enumeration ---}]
#}
#}
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
# Base namespace
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
tcl::namespace::eval punk::args::tclcore {
tcl::namespace::export {[a-z]*} ;# Convention: export all lowercase
#variable xyz
#for tcllib - we can potentially parse the doctools to get this info.
#for tcl core commands - the data is stored in man pages - which are not so easy to parse.
#todo - link to man pages
#TODO -
#if we want colour in arg definitions -we need to respect nocolor or change colour to off/ on
#If color included in a definition - it will need to be reloaded when colour toggled(?)
#if {[catch {package require punk::ansi}]} {
# set has_punkansi 0
# set A_WARN ""
# set A_RST ""
#} else {
# set has_punkansi 1
# set A_WARN [a+ red]
# set A_RST "\x1b\[0m"
#}
#we can't just strip ansi as there are non colour codes such as hyperlink that should be maintained whether color is on or off.
#for now we can use reverse - (like underline, is a non-colour attribute that remains effective when color off in punk::ansi)
set A_WARN \x1b\[7m
set A_RST \x1b\[0m
variable manbase_tcl
variable manbase_ext
set patch [info patchlevel]
lassign [split $patch .] major
if {$major < 9} {
set manbase_tcl "https://tcl.tk/man/tcl/TclCmd"
set manbase_ext .htm
} else {
set manbase_tcl "https://tcl.tk/man/tcl9.0/TclCmd"
set manbase_ext .html
}
proc manpage_tcl {cmd} {
variable manbase_tcl
variable manbase_ext
return ${manbase_tcl}/${cmd}${manbase_ext}
}
variable PUNKARGS
# -- --- --- --- --- --- --- --- --- --- --- --- --- ---
# library commands loaded via auto_index
# -- --- --- --- --- --- --- --- --- --- --- --- --- ---
lappend PUNKARGS [list {
*id parray
*proc -name "Builtin: parray" -help\
"Prints on standard output the names and values of all the elements in the
array arrayName, or just the names that match pattern (using the matching
rules of string_match) and their values if pattern is given.
ArrayName must be an array accessible to the caller of parray. It may either
be local or global. The result of this command is the empty string.
(loaded via auto_index)"
*values -min 1 -max 2
arrayName -type string -help\
"variable name of an array"
pattern -type string -optional 1 -help\
"Match pattern possibly containing glob characters"
} "*doc -name Manpage: -url [manpage_tcl library]" ]
# -- --- --- --- --- --- --- --- --- --- --- --- --- ---
lappend PUNKARGS [list {
*id time
*proc -name "Builtin: time" -help\
"Calls the Tcl interpreter count times to evaluate script
(or once if count is not specified). It will then return
a string of the form
503.2 microseconds per iteration
which indicates the average amount of time required per
iteration, in microseconds. Time is measured in elapsed
time, not CPU time.
(see also: timerate)"
*values -min 1 -max 2
script -type script
count -type integer -default 1 -optional 1
} "*doc -name Manpage: -url [manpage_tcl time]" ]
lappend PUNKARGS [list {
*id tcl::namespace::path
*proc -name "Builtin: tcl::namespace::path" -help\
"Returns the command resolution path of the current namespace.
If namespaceList is specified as a list of named namespaces, the current
namespace's command resolution path is set to those namespaces and returns
the empty list. The default command resolution path is always empty.
See the section NAME_RESOLUTION in the manpage for an explanation of the
rules regarding name resolution."
*values -min 0 -max 1
namespaceList -type list -optional 1 -help\
"List of existing namespaces"
} "*doc -name Manpage: -url [manpage_tcl namespace]" ]
lappend PUNKARGS [list {
*id tcl::namespace::unknown
*proc -name "Builtin: tcl::namespace::unknown" -help\
"Sets or returns the unknown command handler for the current namespace.
The handler is invoked when a command called from within the namespace cannot
be found in the current namespace, the namespace's path nor in the global
namespace.
When the handler is invoiked, the full invocation line will be appended to
the script and the result evaluated in the context of the namespace.
The default handler for all namespaces is [a+ italic]::unknown[a].
If no argument is given, it returns the handler for the current namespace."
*values -min 0 -max 1
script -type script -optional 1 -help\
"A well formed list representing a command name and optional arguments."
} "*doc -name Manpage: -url [manpage_tcl namespace]" ]
set I [a+ italic]
set NI [a+ noitalic]
lappend PUNKARGS [list {
*id tcl::process::status
*proc -name "Builtin: tcl::process::status" -help\
"Returns a dictionary mapping subprocess PIDs to their respective status.
if ${$I}pids${$NI} is specified as a list of PIDs then the command
only returns the status of the matching subprocesses if they exist, and
raises an error otherwise.
For active processes, the status is an empty value. For terminated
processes, the status is a list with the following format:
{code ?msg errorCode?}
where:
${$I}code${$NI}
is a standard Tcl return code, ie.,
0 for TCL_OK and 1 for TCL_ERROR,
${$I}msg${$NI}
is the human readable error message,
${$I}errorCode${$NI}
uses the same format as the errorCode global variable
Note that msg and errorCode are only present for abnormally
terminated processes (i.e. those where the code is nonzero).
Under the hood this command calls Tcl_WaitPid with the
WNOHANG flag set for non-blocking behaviour, unless the -wait
switch is set (see below).
"
-wait -type none -optional 1 -help\
"By default the command returns immediately (the underlying Tcl_WaitPid
is called with the WNOHANG flag set) unless this switch is set. if pids
is specified as a list of PIDS then the command waits until the status
of the matching subprocesses are avaliable. If pids was not specified,
this command will wait for all known subprocesses."
-- -type none -optional 1 -help\
"Marks the end of switches. The argument following this one will be
treated as the first arg even if it starts with a -."
*values -min 0 -max 1
pids -type list -optional 1 -help\
"A list of PIDs"
} "*doc -name Manpage: -url [manpage_tcl namespace]" ]
lappend PUNKARGS [list {
*id lappend
*proc -name "builtin: lappend" -help\
"Append list elements onto a variable.
"
*values -min 1 -max -1
varName -type string -help\
"variable name"
value -type any -optional 1 -multiple 1
} "*doc -name Manpage: -url [manpage_tcl lappend]"]
punk::args::definition {
*id ledit
*proc -name "builtin: ledit" -help\
"Replace elements of a list stored in variable
"
*values -min 3 -max -1
listVar -type string -help\
"Existing list variable name"
first -type indexexpression
last -type indexexpression
value -type any -optional 1 -multiple 1
} "*doc -name Manpage: -url [manpage_tcl ledit]"
punk::args::definition {
*id lpop
*proc -name "builtin: lpop" -help\
"Get and remove an element in a list
"
*values -min 1 -max -1
varName -type string -help\
"Existing list variable name"
index -type indexexpression -default end -optional 1 -multiple 1 -help\
"When presented with a single index, the lpop command addresses
the index'th element in it, removes it from the list and returns
the element.
If index is negative or greater or equal than the number of
elements in the list in the variable called varName, an error occurs.
If addition index arguments are supplied, then each argument is used
in turn to address an element within a sublist designated by the
previous indexing operation, allowing the script to remove elements
in sublists, similar to lindex and lset."
} "*doc -name Manpage: -url [manpage_tcl lpop]"
punk::args::definition {
*id lrange
*proc -name "builtin: lrange" -help\
"return one or more adjacent elements from a list.
The new list returned consists of elements first through last, inclusive.
The index values first and last are interpreted the same as index values
for the command 'string index', supporting simple index arithmetic and
indices relative to the end of the list.
e.g lrange {a b c} 0 end-1
"
*values -min 3 -max 3
list -type list -help\
"tcl list as a value"
first -help\
"index expression for first element"
last -help\
"index expression for last element"
} "*doc -name Manpage: -url [manpage_tcl lrange]"
punk::args::definition {
*id tcl::string::cat
*proc -name "builtin: tcl::string::cat" -help\
"Concatente the given strings just like placing them directly next to each other and
return the resulting compound string. If no strings are present, the result is an
empty string.
This primitive is occasionally handier than juxtaposition of strings when mixed quoting
is wanted, or when the aim is to return the result of a concatentation without resorting
to return -level 0, and is more efficient than building a list of arguments and using
join with an empty join string."
*values -min 0 -max -1
string -type string -optional 1 -multiple 1
} "*doc -name Manpage: -url [manpage_tcl string]"
punk::args::definition {
*id tcl::string::compare
*proc -name "builtin: tcl::string::compare" -help\
"Perform a character-by-character comparison of strings string1 and string2.
Returns -1, 0, or 1, dpending on whether string1 is lexicographically
lessthan, equal to, or greater than string2"
-nocase -type none -help\
"If -nocase is specified, then the strings are compared in a case insensitive manner."
-length -type integer -help\
"If -length is specified, then only the first length characters are used in the comparison.
If -length is negative, it is ignored."
*values -min 2 -max 2
string1 -type string
string2 -type string
} "*doc -name Manpage: -url [manpage_tcl string]"
punk::args::definition {
*id tcl::string::equal
*proc -name "builtin: tcl::string::equal" -help\
"Perform a character-by-character comparison of strings string1 and string2.
Returns 1 if string1 and string2 are identical, or 0 when not."
-nocase -type none -help\
"If -nocase is specified, then the strings are compared in a case insensitive manner."
-length -type integer -help\
"If -length is specified, then only the first length characters are used in the comparison.
If -length is negative, it is ignored."
*values -min 2 -max 2
string1 -type string
string2 -type string
} "*doc -name Manpage: -url [manpage_tcl string]"
punk::args::definition {
*id tcl::string::first
*proc -name "builtin: tcl::string::first" -help\
"Search haystackString for a sequence of characters that exactly match the characters
in needleString. If found, return the index of the first character in the first such
match within haystackString. If there is no match, then return -1. If startIndex is
specified (in any of the forms described in STRING_INDICES), then the search is
constrained to start with the character in haystackString specified by the index.
"
*values -min 2 -max 3
needleString -type string
haystackString -type string
startIndex -type indexexpression -optional 1 -help\
"integer or simple expression."
} "*doc -name Manpage: -url [manpage_tcl string]"
punk::args::definition {
*id tcl::string::insert
*proc -name "builtin: tcl::string::insert" -help\
"Returns a copy of string with insertString inserted at the index'th character.
If index is start-relative, the first character inserted in the returned string will be
at the specified index.
If index is end-relative, the last character inserted in the returned string will be
at the specified index.
if index is at or before the start of string (e.g., index is 0), insertString is
prepended to the string.
If index is at or after the end of the string (e.g., index is end), insertString is
appended to string."
*values -min 3 -max 3
string -type string
index -type indexexpression -help\
"The index may be specified as described in the STRING_INDICES section"
insertString -type string
} "*doc -name Manpage: -url [manpage_tcl string]"
punk::args::definition {
*id tcl::string::last
*proc -name "builtin: tcl::string::last" -help\
"Search haystackString for a sequence of characters that exactly match the characters
in needleString. If found, return the index of the first character in the last such
match within haystackString. If there is no match, then return -1. If lastIndex is
specified (in any of the forms described in STRING_INDICES), then only the characters
in haystackString at or before the specified lastIndex will be considered by the search
"
*values -min 2 -max 3
needleString -type string
haystackString -type string
lastIndex -type indexexpression -optional 1 -help\
"integer or simple expression."
} "*doc -name Manpage: -url [manpage_tcl string]"
punk::args::definition {
*id tcl::string::repeat
*proc -name "builtin: tcl::string::repeat" -help\
"Returns a string consisting of string concatenated with itself count times."
*values -min 2 -max 2
string -type string
count -type int -help\
"If count is 0, the empty string will be returned."
} "*doc -name Manpage: -url [manpage_tcl string]"
punk::args::definition {
*id tcl::string::replace
*proc -name "builtin: tcl::string::replace" -help\
"Removes a range of consecutive characters from string, starting with the character whose
index is first and ending with the character whose index is last
(Using the forms described in STRING_INDICES). An index of 0 refers to the first
character of the string. First and last may be specified as for the index method.
If first is less than zero then it is treated as if it were zero, and if last is
greater than or equal to the length of the string then it is treated as if it were
end. The initial string is returned untouched, if first is greater than last, or if
first is equal to or greater than the length of the inital string, or last is less
than 0."
*values -min 3 -max 3
string -type string
first -type indexexpression
last -type indexexpression
newstring -type string -optional 1 -help\
"If newstring is specified, then it is placed in the removed character range."
} "*doc -name Manpage: -url [manpage_tcl string]"
punk::args::definition {
*id tcl::string::totitle
*proc -name "builtin: tcl::string::totitle" -help\
"Returns a value equal to string except that the first character in string is converted to
it's Unicode title case variant (or upper case if there is no title case variant) and the
rest of the string is converted to lower case."
*values -min 1 -max 1
string -type string
first -type indexexpression -optional 1 -help\
"If first is specified, it refers to the first char index in the string to start modifying."
last -type indexexpression -optional 1 -help\
"If last is specified, it refers to the char index in the string to stop at (inclusive)."
} "*doc -name Manpage: -url [manpage_tcl string]"
punk::args::definition {
*id tcl::string::wordend
*proc -name "builtin: tcl::string::wordend" -help\
"Returns the index of the character just after the last one in the word containing
character charIndex of string.
A word is considered to be any contiguous range of alphanumeric (Unicode letters or decimal digits)
or underscore (Unicode connector punctuation) characters, or any single character other than these."
*values -min 2 -max 2
string -type string
charIndex -type indexexpression -help\
"integer or simple expresssion.
e.g end
e.g end-1
e.g M+N"
} "*doc -name Manpage: -url [manpage_tcl string]"
punk::args::definition {
*id tcl::string::wordstart
*proc -name "builtin: tcl::string::wordstart" -help\
"Returns the index of the first character in the word containing
character charIndex of string.
A word is considered to be any contiguous range of alphanumeric (Unicode letters or decimal digits)
or underscore (Unicode connector punctuation) characters, or any single character other than these.
"
*values -min 2 -max 2
string -type string
charIndex -type indexexpression -help\
"integer or simple expresssion.
e.g end
e.g end-1
e.g M+N"
} "*doc -name Manpage: -url [manpage_tcl string]"
punk::args::definition [punk::lib::tstr -return string {
*id tcl::string::is
*proc -name "builtin: tcl::string::is" -help\
"Returns 1 if string is a valid member of the specified character class, otherwise returns 0.
"
*leaders -min 1 -max 1
class -type string\
-choices {
alnum
alpha
ascii
boolean
control
dict
digit
double
entier
false
graph
integer
list
lower
print
punct
space
true
upper
wideinteger
wordchar
xdigit
}\
-choicelabels {
alnum\
" Any Unicode alphabet
or digit character"
alpha\
" Any Unicode alphabet
character"
ascii\
" Any character with
a value less than \\u0080
(those that are in the
7-bit ascii range)"
boolean\
" Any of the forms allowed
to Tcl_GetBoolean"
control\
" Any Unicode control char"
dict\
" Any proper dict structure,
with optional surrounding
whitespace. In case of
improper dict structure, 0
is returned and the varname
will contain the index of
the \"element\" where the
dict parsing fails or -1 if
this cannot be determined."
digit\
" Any Unicode digit char.
Note that this includes
chars outside of the \[0-9\]
range."
double\
" Any of the forms allowed
to Tcl_GetDoubleFromObj.
${$A_WARN}With optional surrounding${$A_RST}
${$A_WARN}whitespace.${$A_RST}"
entier\
" Synonym for integer"
false\
" Any of the forms allowed
to Tcl_GetBoolean where the
value is false"
graph\
" Any Unicode printing char
except space."
integer\
" Any of the valid string
formats for an integer value
of arbitrary size in Tcl,
${$A_WARN}with optional surrounding${$A_RST}
${$A_WARN}whitespace${$A_RST}. The formats
accepted are exactly those
accepted by the C routine
Tcl_GetBignumFromObj."
list\
" Any proper list structure,
with optional surrounding
whitespace. In case of
improper list structure, 0
is returned and the varname
will contain the index of
the \"element\" where list
parsing fails, or -1 if
this cannot be determined"
lower\
" Any Unicode lower case
alphabet character"
print\
" Any Unicode printing
character, including space"
punct\
" Any Unicode punctuation
character."
space\
" Any Unicode whitespace
character, mongolian vowel
separator (U+180e),
zero width space (U+200b),
word joiner (U+2060) or
zero width no-break space
(U+feff) (=BOM)"
true\
" Any of the forms allowed
to Tcl_GetBoolean where the
value is true"
upper\
" Any upper case alphabet
character in the Unicode
character set"
wideinteger\
" Any of the valid forms
for a wide integer in Tcl,
${$A_WARN}with optional surrounding${$A_RST}
${$A_WARN}whitespace${$A_RST}. In case of
overflow in the value, 0 is
returned and the varname
will contain -1."
wordchar\
" Any Unicode word char.
That is any alphanumeric
character, and any
Unicode connector
punctuation characters
(e.g. underscore)"
xdigit\
" Any hexadecimal digit
character, and any Unicode
connector punctuation
characters (e.g. underscore)"
}\
-help\
"character class
In the case of boolean, true and false, if the function will return 0, then the
varname will always be set to 0, due to the varied nature of a valid boolean value"
-strict -type none -help\
"If -strictis specified, then an empty string returns 0,
otherwise an empty string will return 1 on any class"
-failindex -type variablename -help\
"If -failindex is specified, then if the function returns 0,
the index in the string where the class was no longer valid will be stored
in the variable named."
*values -min 1 -max 1
string -type string -optional 0
}] "*doc -name Manpage: -url [manpage_tcl string]"
#*** !doctools
#[subsection {Namespace punk::args::tclcore}]
#[para] Core API functions for punk::args::tclcore
#[list_begin definitions]
#proc sample1 {p1 n args} {
# #*** !doctools
# #[call [fun sample1] [arg p1] [arg n] [opt {option value...}]]
# #[para]Description of sample1
# #[para] Arguments:
# # [list_begin arguments]
# # [arg_def tring p1] A description of string argument p1.
# # [arg_def integer n] A description of integer argument n.
# # [list_end]
# return "ok"
#}
#*** !doctools
#[list_end] [comment {--- end definitions namespace punk::args::tclcore ---}]
}
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
# Secondary API namespace
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
tcl::namespace::eval punk::args::tclcore::lib {
tcl::namespace::export {[a-z]*} ;# Convention: export all lowercase
tcl::namespace::path [tcl::namespace::parent]
#*** !doctools
#[subsection {Namespace punk::args::tclcore::lib}]
#[para] Secondary functions that are part of the API
#[list_begin definitions]
#proc utility1 {p1 args} {
# #*** !doctools
# #[call lib::[fun utility1] [arg p1] [opt {?option value...?}]]
# #[para]Description of utility1
# return 1
#}
#*** !doctools
#[list_end] [comment {--- end definitions namespace punk::args::tclcore::lib ---}]
}
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
#*** !doctools
#[section Internal]
#tcl::namespace::eval punk::args::tclcore::system {
#*** !doctools
#[subsection {Namespace punk::args::tclcore::system}]
#[para] Internal functions that are not part of the API
#}
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
if {![info exists ::punk::args::register::NAMESPACES]} {
namespace eval ::punk::args::register {
set ::punk::args::register::NAMESPACES [list] ;#use fully qualified so 8.6 doesn't find existing var in global namespace
}
}
lappend ::punk::args::register::NAMESPACES ::punk::args::tclcore
## Ready
package provide punk::args::tclcore [tcl::namespace::eval punk::args::tclcore {
variable pkg punk::args::tclcore
variable version
set version 999999.0a1.0
}]
return
#*** !doctools
#[manpage_end]