Tcl Package for 'tclkit'

These modules will be built:
tclkit: Version 4.8
creates libtclkit4.8.so and libtclkit4.8.tsl

The following indices are available:

File Index

The following files have been documented:
abspath.tcl
clock.tcl
def.tcl
exit.tcl
getopt.tcl
init.tcl
license.c
locate.tcl
lset.tcl
replace.tcl
resource.tcl
sub.tcl
tmpname.tcl
try.tcl
unknown.tcl

Procedure Index

The following procedures have been documented:
proc abspath
return absolute path
proc Clock
date and time routines
proc defglob
conditionally set global variable
proc defproc
conditionally create procedure
proc defset
enhanced set command
proc defvar
conditionally set variable
proc getglob
get global variable
proc ifnset
conditional execution
proc ifset
conditional execution
proc mset
set multiple variables
proc setglob
set global variable
proc atexit
atexit handler
proc exit
exit command handler
proc GetOpt
getopt like functionality
proc Locate
locate files
proc lset
set variables from list
proc Replace
substitution facility
proc LocateFile
find one file
proc LocateFiles
locate some files
proc LocateImage
find an image file
proc sub
install subcommands
proc TmpFile
create temporary file
proc TmpName
create temporary filename
proc aterror
cleanup after an error
proc try
exception handler
proc Unknown
unknown handler
proc unknown
unknown command handler

File abspath.tcl

proc abspath - return absolute path

Synopsis

	proc abspath { {fname "."} } {}

Description

This procedure returns the absolute pathname of a given file or directory, that is it removes all relative or tilde based elements.

Note that cd is used to find the absolute path, so you must pass a legal filename/directory or the routine will fail.

Arguments

fname
a filename, may be absolute, relative or tilde based. If no filename is given, then . is used, so abspath is the same as pwd.

Return Value

Returns the absolute path of the given filename or an error if the filename is illegal or the file does not exist.

File clock.tcl

proc Clock - date and time routines

Synopsis

	proc Clock { {cmd full} args } {}

Description

The Clock subcommands are an encapsulation of some of the subcommands of the original tcl clock command. They return time and/or date values in a format depending on the current language settings.

These routines may be obsolute sometimes in the future, but currently I18N support is bad in tcl (We cannot even use the day/month names in languages other than english)

Subcommands

The following subcommands are available:
date
returns the given date in a format suitable for the currently selected language (depending on the tcl variable $Language, which in turn is set from the environment variable SOFTLANG (or from LANG). The string contains year, month and day.
time
returns the given time in hours, minutes and seconds.
full
returns the given time as year, month, day, hours, minutes and seconds. No argument is the same as full.

Arguments

cmd
is the subcommand that should be invoked. See the description for details.
time
this optional argument is a date/time value in julian notation (eg from clock seconds or a file stat). If it is not present, then the current time is used.

Return Value

returns a time and/or date string that may be used for later output to the user.

File def.tcl

proc defvar - conditionally set variable

Synopsis

	proc defvar { var val } {}

Description

this proc allows the setting of a variable if it is currently unset, that is the new value is only set if the variable did not previously exist.

Arguments

var
name of the variable to conditonally set
val
the value to set into the variable if it currently has no value.

Return Value

returns the actual value of the variable

proc defglob - conditionally set global variable

Synopsis

	proc defglob { var val } {}

Description

this proc allows the setting of a global variable if it is currently unset, that is the new value is only set if the variable did not previously exist.

Arguments

var
name of the global variable to conditonally set
val
the value to set into the variable if it currently has no value.

Return Value

returns the actual value of the variable

proc defset - enhanced set command

Synopsis

	proc defset { name var value } {}

Description

allows using of nonexisting variables on the right hand side of a set expression. That is if you do a set x $y then this will fail if $y is not defined. defset x y 10 will do the trick for you, that is it will set x to the value of y if y does exist and to 10 if not.

Arguments

name
name of variable that should be set
var
name of variable that should be used to retrieve the value (note that this is not $var, it's just var.
value
value to use if var is not set.

Return Value

returns the value that was actually set.

proc defproc - conditionally create procedure

Synopsis

	proc defproc { name argl body } {}

Description

Define a procedure if it is not already defined. This command is used in the same way as the proc command, with the exception that it is ignored if a procedure with this name already exists.

Arguments

name
name of procedure
argl
arguments to procedure

Return Value

returns an empty string (or an error if a failure to define the procedure happens).

proc setglob - set global variable

Synopsis

	proc setglob { var value } {}

Description

This call may be used to create and set a global variable with a single step. It is basically a global command followed by a set.

Arguments

var
name of global variable to create and set
val
value that variable should be set to.

Return Value

returns the value that was set.

proc getglob - get global variable

Synopsis

	proc getglob { var args } {}

Description

This call may be used to get the value of an existing global variable with a single step. It is basically a global command followed by a set var.

This command does not make the variable visible in the current context!.

Arguments

var
name of global variable to get
val
if this optional value is present and the variable is not yet set, then the global variable is created and set to this value before returning this value to the caller.

Return Value

returns the value of the variable

proc ifset - conditional execution

Synopsis

	proc ifset { var body } {}

Description

The body of this statement is executed only if the variable given by var is set.

This is a shorthand for the following tcl code:

   if { [info exists var ] } {
      eval $body
   }

Arguments

var
Name of a local variable which which is checked for existence. It may also be an array index or even a whole array.
body
a block of tcl statements which are executed when the variable does exist.

Return Value

returns either an empty string when the variable does not exist or the result of executing body.

proc ifnset - conditional execution

Synopsis

	proc ifnset { var body } {}

Description

The body of this statement is executed only if the variable given by var is not set.

This is a shorthand for the following tcl code:

   if { ![info exists var ] } {
      eval $body
   }

Arguments

var
Name of a local variable which which is checked for existence. It may also be an array index or even a whole array.
body
a block of tcl statements which are executed when the variable does not exist.

Return Value

returns either an empty string when the variable does exist or the result of executing body.

proc mset - set multiple variables

Synopsis

	proc mset { args } {}

Description

This command is just a simple set command but extendended for multiple variable - value pairs.

Arguments

The arguments are one or more variable - value pairs.

Return Value

returns the value of the last variable that has been set

File exit.tcl

proc atexit - atexit handler

Synopsis

	proc atexit { mode args } {}

Description

this command is the handler for the tcl exit command. It allows addition and deletion of specific handlers without destroying the already existing handlers. All the handlers are called when someone does an exit.

Subcommands

The mode argument states what the handler should do. It may be one of the following subcommands:
add (end may be used instead)
Add a new handler procedure whose name is given as the second arg. The handler is appended to the end of the list of already active handlers, that is it will be executed after all other handlers.
start to add the handler at the start instead of at
the end.
del
removes the given handler again (handler is given by name, may contain wildcards).
info
This returns a list of all currently installed handlers.

If mode is ommitted then add is assumed.

Arguments

mode
The subcommand that should be executed. See the description for details.
args
Name of a procedure that should be invoked when the programm is about to exit. This procedure has the following signature 
	proc exitproc { } {}
It is called with no arguments and should return no result value (values and errors are actually ignored). The handler is executed at global level. You don't have to call exit from inside of the handler.

Return Value

returns an empty string (except you happen to produce an error somehow). The info command returns a list of installed handlers.

Example

Here is an example for the use of atexit 
  proc MyExitHandler { } {
     global file_modified
     if { $file_modified } {
        SaveMyFile 
     }
  }
  atexit add MyExitHandler

proc exit - exit command handler

Synopsis

	proc exit { {code 0} } {}

Description

this is the handler that is called by tcl for the exit command. We call all the installed handlers with this command.

Arguments

code
the exit code of the programm

Return Value

this procedure does not return

File getopt.tcl

proc GetOpt - getopt like functionality

Synopsis

	proc GetOpt { pattern {arglist {}} {optret {}} {argret {}} } {}

Description

An implementation of getopt for tcl. This one does command line parsing together with argument checking for all optional arguments (the -var value things).

Arguments

pattern
This argument is a list that states which arguments should be allowed on the command lines. The list is built up from triples representing the following values: 
	name typ default
name is the name of the option, eg -exact. typ gives the allowed type of this option. This may be itself a list of one or more arguments, depending on the first argument. Here is a description of the typ field:
n
No argument, a boolean option. If this option is specified, then it is set (1), otherwise it is unset (0).
b
Identical to the above, but this time the user must specify an argument to the option (eg. -exact true or -exact 0). Any of the tcl bool representations are valid.
i
User must give an integer value. This may be either a single argument or a list of three subvalues, eg {i 3 20}, where the second argument is the low bound and the third element is the high bound of the argument. If the actual value is out of range then an error is returned.
r
This is the same as the integer subtype, but this time with real values allowed.
s
A string valued option - actually an option where the user may enter anything.
o
A selection from some given things. This is a multivalued list (eg {o C tcl lisp perl java}, which indicates that the user must give on of these options.

default is a default value to use if the user does not specify this option on the command line.

arglist
The argument list to parse, normally comes from the command line arguments, that is the tcl gobal variable argv
optret
This is the name of an array variable indexed by the option names and containing the values that the user specified (or the default if nothing was given in the arglist. This variable is optional
argret
If this value is given it names a list variable which is filled with all the arguments that remain after the -arguments have been removed.

Return Value

GetOpt returns a list with two arguments. The first argument contains the options and is a list of option value pairs (eg. -exact 1) and the second argument contains a list of all remaining values after the -arguments have been removed.

Example

Here is a real example: 
     set ret [GetOpt { \
       -startup s "" \ 
       -script s "" \ 
       -debug {i 0 5} \ 
       -command {o init setup version} \ 
       -noinit n 0 \ 
       -entry s "" \ 
    } $args]

File init.tcl

File license.c

File locate.tcl

proc Locate - locate files

Synopsis

	proc Locate { typ name } {}

Description

This routine locates files according to their use. One or more base directories contain context dependent subdirectories where the specific files will be located.

The current subdirectory layout looks like this:

bin
This directory contains startup scripts for the various programms. It is architecture independent.
cfg
contains configuration files for programms and libraries.
exe
this directory contains subdirectories for each supported platform. All architecture dependent libraries are located in these subdirectories.
hlp
All help files are located in language dependent subdirectories of hlp.
icn
Icons and other small pictures are located in this subdirectory. Currently supported are X-Bitmaps, X-Pixmaps and Gif's.
ins
Files related to the installation of a package reside here.
lib
This directory contains all the tcl libraries (that is architecture independent script files).
msg
The language dependent message catalogues are situtated in subdirectories of this directory.

Locate will try to find a corresponding file for a given file type and a given base name. The filetype gives an indication of the contents of the file and the base name is a formal filename (without any path or extension).

Locate checks all the directories given in the global variable LoadPath for the file structure described above and returns the first matched entry. LoadPath itself is set from the environment variable SOFTWORKS at programm startup (This is true for applications that are linked against the softWorks tclstart.to library, others may need to set LoadPath in their own code).

The following file types are recognized:

config
will find a configuration file.
help
returns the pathname of a (possibly language dependent) help file.
msg
returns the pathname of a (possibly language dependent) message file.
image
returns the pathname of an image file. Image files are located in the icn subdirectory and have an extension of .gif, .xpm or .xbm. They are searched in that order, that is gif's are preferred over xpms.
icon, bitmap
these two types specify either X-Pixmap or X-Bitmap files respectively.

Arguments

typ
one of the file-types described above
name
a formal file name (with no extension or path).

Return Value

Locate returns either a full pathname to the found file or an error indicating why the file could not be found.

Examples

Here are some examples (with possible results following the =>): 
   set helpfile [Locate help "myHelp"] 
   => "/SW/app/hlp/english/myHelp.html" 
   set icon [Locate image "mailbox"] 
   => "/SW/app/icn/mailbox.xpm"

File lset.tcl

proc lset - set variables from list

Synopsis

	proc lset { args } {}

Description

This command takes a list and sets the given variables to subsequent values of the list.

Here is a simple example:

   lset {1 2 3} a b c

The first argument to lset is a list of values. Any additional argument is either the name of a (possibly non-existing) variable or a two element list, where the first element is the name of the variable and the second element is a default value that is used if the list contains no value for this variable (This follows the style of arguments in proc).

If the last formal argument to lset is the name args then all remaining actual arguments are concatenated into a list and assigned to args (again follows the conventions for proc).

If a formal argument is a list of two arguments then the first subelement is the formal variable name and the second is a default value for this variable. This default is taken if no actual argument is present that could be assigned to the variable. Have a look at how this works for proc for further details.

There are some special options available. These options directly follow the lset command, eg lset -create $l a b c.

-create
If the list contains less elements then variables are given then these variables are set to the empty string (Mimicking the behaviour of lindex. Otherwise such variables are undefined.
-exact
This switch indicates that the list must have exactly the number of arguments as there are variables.
-global
Normally local variables are created. If this switch is present then the created variables are global.
--
Does nothing, is just an indication that any argument that may follow is not an option.

Arguments

The lset command takes a variable number of arguments. The generic call syntax is lset ?options? list ?arg? ....

Return Value

lset returns the number of assignments actually made. It may return an error, especially when the -exact option is used.

File replace.tcl

proc Replace - substitution facility

Synopsis

	proc Replace { var lst } {}

Description

This procedure is extensively used in softWorks code to implement such things as configuration or message contexts (you may have a look at the Cfg or Msg command).

Given a string with embedded markers and a list of values, this routine replaces the markers with the corresponding text. This function is most useful in situations like multi-language texts, where you don't know how a specific language text looks like:

Here is a simple example to shed some more light on how to use this function:

    set fname "frodo.txt"
    set err "File not readable"
    set txt "The file '%f' is not readable: %e"
    if { $lang=="german" } {
        set txt "Die Datei '%f' kann nicht gelesen werden:\n%e."
    }   
    puts [Replace $txt "%f=$fname" "%e=$err"]

This would output one of the following strings:

    "The file 'frodo.txt' is not readable: File not readable"
    "Die Datei 'frodo.txt' kann nicht gelesen werden:
         File not readable."

As you can see the marker character is a % followed by a single char. This sign is again found in the replacement list. Note that %% is substituted by % and values not given in the substitution list are left as is. If there are replacements strings that don't occur in the original, then these strings are simply ignored.

Arguments

var
This is the string where replacements should occur. Every %? is considered for replacement if the corresponding code is found in one of the elements of lst
lst
This is a list of replacement values, each of them starting with %?=, where ? is a single character.

Return Value

returns the (possibly) modified argument var. An error may happen if the lst argument is not properly formatted or not present.

File resource.tcl

proc LocateFiles - locate some files

Synopsis

	proc LocateFiles { fname {ThePath ""} } {}

Description

THIS PROCEDURE IS OBSOLETE AND SHOULD NOT BE USED ANY LONGER.

File names are searched within the global list LoadPath (which is normaly a copy of the SOFTWORKS-environment variable.

Arguments

fname
the fname to look for (surprise!)
ThePath
 if given then this is a pathlist to use instead of LoadPath

Return Value

a list of full paths to the fnames or a empty list if nothing found.

proc LocateFile - find one file

Synopsis

	proc LocateFile { fname {path ""} } {}

Description

File names are searched within the directories found in the global list LoadPath (which is normaly a copy of the SOFTWORKS-environment variable).

LoadPath is set at programm startup (This is true for applications that are linked against the softWorks tclstart.to library, others may need to set LoadPath in their own code).

Arguments

fname
Name of a file (possibly without path) to find.
path
This optional argument is a list of directories to use instead of the directories contained in the global variable LoadPath.

Return Value

a full path to the file or an error if the file is not found.

Examples

Here are some examples (with possible results following the =>): 
   set mylib [LocateFile "libtclkit4.1.tsl"] 
   => "/SW/app/lib/libtclkit4.1.tsl" 
   set icon [LocateFile "mailbox.xpm"] 
   => "/SW/app/icn/mailbox.xpm"

proc LocateImage - find an image file

Synopsis

	proc LocateImage { typ img {path ""} } {}

Description

this call returns the name of a loaded image (See the tcl image command for details about images). If the image was not currently loaded then the code tries to find a corresponding file and loads the image from there.

This command is useful to handle images without explicitly writing code that loads the image.

Images are searched with the proc LocateFile call, that is they are found in an icn subdirectory of all the directories given in the global list LoadPath.

LoadPath is set at programm startup (This is true for applications that are linked against the softWorks tclstart.to library, others may need to set LoadPath in their own code).

Note here that a leading underscore is added to the image name as there may be inconveniences when you add an image that is named like a tcl command.

Arguments

typ
may be one of photo, bitmap or pixmap and describes the type of image you want to use.
img
this is the name of the image and corresponds to the base part of the image file name.
path
a list of pathnames to search instead of what is in the global list LoadPath.

Return Value

returns the name of the image if all went well or an error if something failed.

Examples

Here are some examples (with possible results following the =>): 
   button .b -iamge [LocateImage "risc"] 
   set icon [LocateImage "mailbox"] 
   => "_mailbox"

File sub.tcl

proc sub - install subcommands

Synopsis

	proc sub { name args } {}

Description

This procedure is closely related to proc. It generates new tcl commands but unless proc it is usefull to build commands with subcommands (like the string command from tcl, which has subcommands string match, string compare etc).

sub may be used to create completely new commands, but it may also be used to extend already existing commands. It is even possible to extend commands written in C, eg string or file.

sub has two different syntaxes. The first may be used to create a new command with all of it's subcommands in one step. The other is used to add a new subcommand to a (possible already existing) command. The second may be used more than once to extend a command.

The formal argument list of sub follows the same conventions as that of proc, where args catches all remaining arguments and defaulted values may be used too.

Examples

Here are some simple examples (some are really stupid, they are here just to show you the syntax):

First the compact form for the definition:

      sub MyString {
         compare { a b } {
            return [string compare $a $b]
         }
         match { a b } {
            return [string match $a $b]
         }
      }

Now the second form:

      sub YourString compare { a b } {
         return [string compare $a $b]
      }
      sub YourString match { a b } {
         return [string match $a $b]
      }

And finally show how to use the newly created commands:

      set ret [MyString match "hey*" $Hello]
      if { [YourString compare "me" "you"] } {
         puts "oops!"
      }

You may even extend an already existing command (even if it is written in C!)

      sub string add { a b } {
         return "$a $b"
      }

All the basic string commands are available (you could eg use string compare as you did before), but also a new subcommand add is now defined:

      if { [string compare "wow!" $thing] } {
         return [string add $thing "is super."]
      }

Arguments

name
name of the tcl procedure to create (or to extend if it already exists).
args
a variable list of arguments, see the examples for more details.

Return Value

Returns an empty string if the new command could be defined or an error if something went wrong.

File tmpname.tcl

proc TmpName - create temporary filename

Synopsis

	proc TmpName { {stub "" } {}

Description

This call returns a unique filename that is useable for temporary files. This call tries to emulate the tempnam call of C.

Arguments

stub
if this argument is present then it denotes a stub that should be used to create temporary names. Otherwise either the name of the application (from the global variable AppName) or the string tcl is used. See the manual of tempnam for details.

Return Value

returns a temporary filename.

proc TmpFile - create temporary file

Synopsis

	proc TmpFile { args } {}

Description

THIS COMMAND IS CURRENTLY NOT IMPLEMENTED!

This call creates a temporary file that will be automatically removed from the file system when it is closed or the application terminates

Arguments

stub
if this argument is present then it denotes a stub that should be used to create temporary names. Otherwise either the name of the application (from the global variable AppName) or the string tcl is used. See the manual of tempnam for details.

Return Value

returns a tcl file pointer if all is ok (the pointer may be used to write to the file) or an error if something goes wrong.

File try.tcl

proc try - exception handler

Synopsis

	proc try { cmd errcmd } {}

Description

This procedure is a generic exception handler for tcl statements. It executes one or more commands and passes flow of control to another set of commands if an error happens. The second block of statements acts as an error handler for the first block.

Here is an example:

    try {
        set a [expr 3*$c/$d]
        set v [expr 2*$a+10]
        return $v
    } {
        puts "error in expression: $err"
        return 0
    }

The main advantage of try over catch is that you may put a return statement inside the catched block (catch silently ignores it, the code continues after the catched statements).

As you can see in the example the error handler can use a variable named err which contains the error code as it would be returned by a catch command.

Arguments

cmd
This is a list of commands to execute. All commands are executed unless on of them returns an error. If so then the rest of the commands is discarded and the commands in errcmd (see below) are executed.
errcmd
These commands are execute if an error happens. They can reference a variable named err which contains the error of the original cmd.

Return Value

returns what either the legal command or the error catching command returns. return statements are legal and work the way you would expect.

proc aterror - cleanup after an error

Synopsis

	proc aterror { cmd cleanup } {}

Description

Execute a catched command and if an error is encountered, then execute some additional commands. Return the original return value (either a normal return or the error in any case).

Arguments

cmd
The commands to execute.
cleanup
The commands to execute in case of an error.

Return Value

returns what the legal command would return or an error if an error happened there. Errors in the cleanup routines are ignored. return statements are legal inside these blocks.

Example

Here is an example for the use of aterror 
  aterror {
     global MyVar
     set MyVar 10
     # error may happen here
     return [GrumpyFun $MyVar]
  } {
     # MyVar should not be set after an error
     unset MyVar
  }

File unknown.tcl

proc Unknown - unknown handler

Synopsis

	proc Unknown { mode args } {}

Description

this command is the handler for the tcl unkown command. It allows addition and deletion of specific handlers without destroying the already existing handlers.

Arguments

mode
what the handler should do. May be one of the following subcommands:
add or end
to add a new handler procedure whose name is given as the second arg. The handler will be appended to the end of the list of already active handlers.
start
to add the handler at the start instead of at the end.
del
removes the given handler again (handler is given by name, may contain wildcards).
clear
removes all installed handlers.
info
returns a list of all currently installed handlers.

If mode is ommitted then add is assumed.

args
contains the name of a handler, that is a procedure that is called with the original arguments. Your handler should have the following signature: 
	proc handler { origproc args } {}
This handler may returns anything it likes, even an error. The only special return code is continue (eg. return -code 4) to indicate that this handler could not handle the error condition and that we should try other handlers instead. All other codes indicate that the error was handled and no other handler will be invoked.

Return Value

An error is returned if something goes wrong. Normally an empty string is returned.

Example

Here is an example for the use of Unknown 
  proc MyHandler { args } {
     if { [lindex $args 0]=="MyFunc" } {
        source "myfunc.tcl"
        return eval $args"
     }
     # we did not act, maybe an other handler?
     return -code 4
  }
  Unknown add MyHandler
  MyFunc 1 2 3

proc unknown - unknown command handler

Synopsis

	proc unknown { args } {}

Description

this is the handler that is called by tcl for every unknown command. We call all the installed handlers with this command. The handlers themselves should conform to the syntax and return values stated in the tcl manual for the unknown command. The following additional conventions exist: If you return continue then the proc assumes that the handler couldn't handle the command and should continue with other handlers. All other return values (even errors) are returned to the caller.

this command is not normally modified by the user, it is only used to install a generic unknown handler. See Unknown for further details.

Arguments

args
give the call sequence of the original call, but is simply passed through.

Return Value

Returns anything that one of the unknown-handlers may return or returns an error indicating that the original command was not found if none of the handlers handled the error condition.