1. Util - Utility Procs
Util is a collection of procs
that are globally available within Mod.
All util procs start with a star * to avoid colliding with
builtins or locally defined procs.
The source for util.tcl can be viewed from
cvs
or at runtime from the console:
<Control-Alt-Shift-Space>
Tk::editproc *fread
1.1 Synopsis
1.2 Commands
Following are the extern definitions for commands in this module.
proc *// args
Comment out a command. Warning: arguments are still evaluated.
proc *array {name {values {}}}
Declare an array variable and assign its initial values.
proc *bexists {lst name}
In pair-list $lst, return 1 if $name exists, or 0 if not found.
Uses dict if available.
proc *bvalue {lst name {default {}}}
In pair-list $lst, return value of $name, or $default if not found.
Uses dict if available.
proc *catch {script {tvar _crv}}
Evaluate script and issue a warning upon an error.
proc *cmdtype cmd
Determine type of a command.
extern *cmdtype cmd {{choice alias builtin ensemble proc proccompiled} .}
proc *dexists {dvar name}
In pair-list dvar, return 1 if $name exists, or 0 if not found.
Like *bexists, but works on a variable.
proc *dvalue {dvar name {default {}}}
In pair-list dvar, return value of $name, or $default if not found.
Like *bvalue, but works on a variable.
proc *existis {var {strict 1} {istype true}}
If ![info exists] return 0, else return [string is].
Most commonly used to check if a boolean var was set to true.
proc *fmt {str {len 78}}
Break str into lines of length <= len.
proc *fnormalize path
A file normalize that works in Tcl 8.3.
proc *fread {fname args}
Read file fname, passing args to fconfigure.
OPTIONS:
{-blocking}
{-buffering}
{-buffersize}
{-encoding}
{-eofchar}
{-translation}
extern *fread {fname args} {. . {opts -blocking -buffering -buffersize -encoding -eofchar -translation}}
proc *fwrite {fname data args}
Write data to file fname, passing args to fconfigure.
OPTIONS:
{-blocking}
{-buffering}
{-buffersize}
{-encoding}
{-eofchar}
{-translation}
extern *fwrite {fname data args} {. . . {opts -blocking -buffering -buffersize -encoding -eofchar -translation}}
proc *incr {var {amt 1}}
Increment var by amount, creating if !exists.
proc *indvar {lst avar}
Return lst with index of each element.
proc *lindex {lst idx}
Compatibility proc with support for nested indexes (circa tcl 8.4).
Note change in 8.4 no accepts "" index and returns lst.
proc *lisearch {ind lst val}
Does the same as [lsearch -exact -index N lst val]
proc *lreverse lst
Return list reversed.
proc *lsearch args
An lsearch compatibility proc with -index, -not, etc.
Tries the builtin [lsearch] first and on error calls [*lsearchtcl].
proc *lsearchtcl args
A Tcl only version of lsearch.
proc *lset {var idx args}
Compatibility proc for lset, with multi-index etc... (circa tcl 8.4)
proc *mset {vars values {body break}}
Assign multiple values to variables, debug-checking their lengths match.
This just uses foreach, but checks for a mismatch between
the length of vars and values.
proc *nrepeat {str last {first 1} {incr 1} {pat %N} {maxloop 1000}}
Repeat string, using [string map] with pat over range of numbers.
proc *nsexists ns
Tcl 8.3 compatible version of namespace exists.
proc *prepend {var args}
Add all elements in $args to begining of list.
proc *relay {command args}
Relay call to command, ignoring trailing args (eg. for var traces).
proc *set {name value}
Set variable $name to $value, creating namespace if required.
proc *setvar {name value args}
Set a variable such that further sets are ignored.
Sets a read-only variable, eg. for overriding module initializers.
Allows setting a variable in a namespace that may not yet exist.
Thus when a module gets loaded and variable initialized, $value
is retained. If variable is already defined, and -chkinit=0, just returns. Note that *setvar
sets up a write trace to reset variable(s) value upon change.
Returns the number of default values successfully setup.
OPTIONS:
{ -once True "Remove reset-trace after first set" }
{ -error False "Generate an error instead of ignoring if set occurs" }
{ -array False "name is an array and value nam/val pairs" }
{ -chkinit False "If already set do nothing" }
extern *setvar {name value args} {. . . {opts -once -error -array -chkinit}}
proc *sqldump {t db table {ids {}}}
Dump a tree to an sql database.
See TreeSql.
proc *sqlsync {op args}
Sync changes to a tree back to an sql database table.
See TreeSqlSync
proc *strfirst {chars str {all True}}
Like [string first] looks for any char in $chars.
If not $all, then return the offset of first.
proc *strhead {char str {max 0}}
Return part of string prior to char, or all and limit the length.
proc *strlast {chars str {all True}}
Like [string last] looks for any char in $chars.
If not $all, then return the offset of first.
proc *strtail {char str}
Return part of string following char, or all and limit the length.
proc *struct {name description args}
Define a struct for use with tree.
OPTIONS:
{ -evals {} "Eval code table in name/value pairs: SIGNAL" }
{ -prefs {} "Command prefix table in name/value pairs: SIGNAL" }
{ -novar False "Do not create struct var in user ns" }
{ -strict False "Do not allow N_* to create new fields" }
{ -typecheck False "Enforce type checking" }
extern *struct {name description args} {. . . {opts -evals -prefs -novar -strict -typecheck}}
See Struct
proc *table {op args}
Manage a table of data (See Tables)
proc *tree {op args}
Manage a tree N levels deep (See Trees)
proc *try {script finally script2}
extern *try {script finally script2} {. code . code}
proc *unset var
Unset var if it exists (ie. unset -nocomplain)
proc *uplevel args
Do uplevel and upon an error issue a debug [.Warn].
proc *value {v {default {}} {doinit False}}
Return $v if defined, else $default, optionally initializing.
If the value was already defined, it's current value is returned.
Otherwise, $default will be returned.
If $doinit is True, and the variable did not exist,
then initialize variable to $default.
proc *vector {op args}
Create a vector of data (See Vectors)
© 2008 Peter MacDonald