Tcl/Tk in a Nutshell By Paul Raines & Jeff Tranter 1st Edition March 1999 1-56592-433-9, Order Number: 4339 456 pages, $24.95

Sample Chapter 10:

TclX

Contents:
Special Variables
Group Listing of Commands
Alphabetical Summary of Commands

TclX, also known as Extended Tcl, was developed by Karl Lehenbauer and Mark Diekhans. TclX is not part of the core Tcl/Tk package, but can be obtained for free at http://www.neosoft.com/TclX. This chapter covers TclX Version 8.0.2.

TclX enhances the Tcl language with a number of features designed to make it more suited to general-purpose programming. The TclX software includes a number of new Tcl commands, a new Tcl shell, a standalone help facility, and a library of handy Tcl procedures. Some features of TclX have proven so useful that, over time, they have been integrated into the core Tcl distribution.

This chapter describes only the commands in TclX that are not in standard Tcl. As noted in the text, some commands are not supported or have reduced functionality when running on the Windows 95, Windows 98, and Windows NT platforms. TclX does not support the Macintosh platform.

10.1 Special Variables

The following global variables have special meaning to the Extended Tcl interpreter (the programs tcl and wishx):

argc

Number of command-line arguments, not including the name of the script file

argv

List containing command-line arguments

argv0

Filename being interpreted, or name by which script was invoked

auto_path

Path to search to locate autoload libraries

tcl_interactive

1 if running interactively, 0 otherwise

tcl_prompt1

Primary prompt

tcl_prompt2

Secondary prompt for incomplete commands

tclx_library

Location of Extended Tcl libraries

tkx_library

Location of Extended Tcl Tk libraries

TCLXENV

Array containing information about Tcl procedures

10.2 Group Listing of Commands

This section briefly lists all Extended Tcl commands, grouped logically by function.

10.2.1 General Commands

commandloop	Create an interactive command loop.
dirs	List directories in directory stack.
echo	Write strings to standard output.
for_array_keys	Loop over each key in an array.
for_recursive_glob	Loop recursively over files matching a pattern.
host_info	Return information about a network host.
infox	Return information about Extended Tcl.
loop	Loop over a range of values.
mainloop	Call event loop handler.
popd	Pop top entry from the directory stack.
pushd	Push entry onto directory stack.
recursive_glob	Return list of files recursively matching pattern.
tclx_errorHandler	User-defined procedure to handle errors.
try_eval	Evaluate code and trap errors.

10.2.2 Debugging and Development Commands

cmdtrace	Trace command execution.
edprocs	Edit source code for procedures.
profile	Collect performance data.
profrep	Generate report from performance data.
saveprocs	Save procedure definitions to file.
showproc	List definitions of procedures.

10.2.3 Unix Access Commands

alarm	Send alarm signal.
chroot	Change root directory.
execl	Start a new program.
fork	Create a child process.
id	Set, get, or convert user, group, and process identifiers.
kill	Send signal to a process.
link	Create a hard or symbolic link.
nice	Set or get process priority.
readdir	Return list of directory entries.
signal	Handle Unix signals.
sleep	Delay process execution.
sync	Flush pending buffered output.
system	Execute shell command.
times	Return process and child execution times.
umask	Set or get file creation permission mask.
wait	Wait for command to terminate.

10.2.4 File Commands

bsearch	Search lines of file for a string.
chgrp	Set group ID of files.
chmod	Set file permissions.
chown	Set owner of files.
dup	Duplicate an open file identifier.
fcntl	Set or get attributes of file identifier.
flock	Apply lock on an open file.
for_file	Loop over contents of a file.
fstat	Return status information about an open file identifier.
ftruncate	Truncate a file to a specified length.
funlock	Remove lock from an open file.
lgets	Read Tcl list from a file.
pipe	Create a pipe.
read_file	Read file contents into a string.
select	Check file identifiers for change in status.
write_file	Write strings to a file.

10.2.5 File Scanning Commands

scancontext	Create, delete, or modify file scan contexts.
scanfile	Perform file context scanning.
scanmatch	Specify commands for file context scanning.

10.2.6 Math Commands

These commands operate in the same fashion as their counterparts that are built into the expr command. They accept as arguments any expression accepted by the expr command. The trigonometric functions use values expressed in radians.

abs	Absolute value.
acos	Arc cosine.
asin	Arc sine.
atan	Arc tangent.
atan2	Arc tangent (accepts two parameters).
ceil	Round up to the nearest integer.
cos	Cosine.
cosh	Hyperbolic cosine.
double	Convert numeric value to double-precision floating-point value.
exp	e raised to the power of the argument.
floor	Round down to the nearest integer.
fmod	Floating-point remainder (accepts two arguments).
hypot	Hypotenuse function (accepts two arguments).
int	Convert to integer by truncating.
log	Natural logarithm.
log10	Base 10 logarithm.
max	Maximum value (accepts one or more arguments).
min	Minimum value (accepts one or more arguments).
pow	Exponentiation (accepts two parameters).
random	Return random floating-point number.
round	Convert to integer by rounding.
sin	Sine.
sinh	Hyperbolic sine.
sqrt	Square root.
tan	Tangent.
tanh	Hyperbolic tangent.

10.2.7 List Manipulation Commands

intersect	Return list of elements common to two lists.
intersect3	Accept two lists, returning items common to, and unique to, each list.
lassign	Assign list elements to variables.
lcontain	Return 1 if element is contained in a list.
lempty	Return 1 if a list is empty.
lmatch	Search list for elements matching a pattern.
lrmdups	Remove duplicate list elements.
lvarcat	Concatenate lists onto a variable.
lvarpop	Delete or replace list element contained in a variable.
lvarpush	Insert element into list contained in a variable.
union	Return logical union of two lists.

10.2.8 Keyed List Commands

keyldel	Delete entry from keyed list.
keylget	Return value from keyed list.
keylkeys	Return list of keys from keyed list.
keylset	Set value in keyed list.

10.2.9 String and Character Manipulation Commands

ccollate	Return collation ordering of two strings.
cconcat	Concatenate strings.
cequal	Compare strings for equality.
cindex	Return one character from a string.
clength	Return length of a string.
crange	Return range of characters from a string.
csubstr	Return substring of a string.
ctoken	Parse a token out of a string.
ctype	Return type of characters in a string.
replicate	Replicate a string several times.
translit	Transliterate characters in a string.

10.2.10 XPG/3 Message Catalog Commands

catclose	Close a message catalog.
catgets	Retrieve message from a catalog.
catopen	Open a message catalog.

10.2.11 Help Commands

apropos	Locate help information based on a pattern.
help	Online help system for Extended Tcl.
helpcd	Change current location in tree of help subjects.
helppwd	List current help subject location.

10.2.12 Library and Package Commands

auto_commands	List names of loadable commands.
auto_load_file	Source a file using autoload path.
auto_packages	Return names of defined packages.
buildpackageindex	Build index files for package libraries.
convert_lib	Convert Tcl index and source files into a package.
loadlibindex	Load a package library index.
searchpath	Search a path of directories for a file.

10.3 Alphabetical Summary of Commands

This section describes all Extended Tcl commands, listed in alphabetical order.

• abs
• acos
• alarm
• apropos
• asin
• atan
• atan2
• auto_commands
• auto_load_file
• auto_packages
• bsearch
• buildpackageindex
• catclose
• catgets
• catopen
• ccollate
• cconcat
• ceil
• cequal
• chgrp
• chmod
• chown
• chroot
• cindex
• clength
• cmdtrace
• commandloop
• convert_lib
• cos
• cosh
• crange
• csubstr
• ctoken
• ctype
• dirs
• double
• dup
• echo
• edprocs
• execl
• exp
• fcntl
• flock
• floor
• fmod
• for_array_keys
• for_file
• for_recursive_glob
• fork
• fstat
• ftruncate
• funlock
• help
• helpcd
• helppwd
• host_info
• hypot
• id
• infox
• int
• intersect
• intersect3
• keyldel
• keylget
• keylkeys
• keylset
• kill
• lassign
• lcontain
• lempty
• lgets
• link
• lmatch
• loadlibindex
• log
• log10
• loop
• lrmdups
• lvarcat
• lvarpop
• lvarpush
• mainloop
• max
• min
• nice
• pipe
• popd
• pow
• profile
• profrep
• pushd
• random
• read_file
• readdir
• recursive_glob
• replicate
• round
• saveprocs
• scancontext
• scanfile
• scanmatch
• searchpath
• select
• showproc
• signal
• sin
• sinh
• sleep
• sqrt
• sync
• system
• tan
• tanh
• tclx_errorHandler
• times
• translit
• try_eval
• umask
• union
• wait
• write_file

abs

abs
arg

Return the absolute value of expression arg. The argument may be in either integer or floating-point format and the result is returned in the same form.

acos

acos arg

Return the arc cosine of expression arg.

alarm

alarm seconds

Instruct the system to send an alarm signal (SIGALRM) to the command interpreter seconds seconds in the future. The time is specified as a floating-point value. A value of 0 cancels any previous alarm request. This command is not supported under Windows.

apropos

apropos pattern

Search the online help system for entries that contain the regular expression pattern in their summaries.

asin

asin arg

Return the arc sine of expression arg.

atan

atan arg

Return the arc tangent of expression arg.

atan2

atan2 x,y

Return the arc tangent of expression x divided by expression y, using the signs of the arguments to determine the quadrant of the result.

auto_commands

auto_commands [-loaders]

List the names of all known loadable procedures. If the -loaders > option is specified, the output also lists the commands that will be executed to load each command.

auto_load_file

auto_load_file file

Load a file, as with the Tcl source > command, but use the search path defined by auto_path > to locate the file.

auto_packages

auto_packages [-location]

Return a list of all defined package names. With the -location > option, return a list of pairs of package name and the .tlib pathname, offset, and length of the package within the library.

bsearch

bsearch fileId
key [retvar]
[compare_proc]

Search file opened with fileId for lines of text matching the string key. Return the line that was found, or an empty string if no match exists. If the variable name is specified with retvar, the matching line is stored in the variable and the command returns 1 if the key matched or 0 if there was no match. Can optionally specify a procedure compare_proc > that will compare the key and each line, returning a value indicating the collation order (see ccollate >).

buildpackageindex

buildpackageindex libfilelist

Build index files for package libraries. Argument libfilelist is a list of package libraries. Each name must end with the suffix .tlib. A corresponding .tndx file will be built.

catclose

catclose [-fail|-nofail cathandle

Close a previously opened message catalog.

Options

-fail

Return an error if the catalog cannot be closed.

-nofail

Ignore any errors when closing (default).

catgets

catgets catHandle
setnum msgnum
defaultstr

Retrieve a message from a message catalog. The message catalog handle returned by catopen should be contained in catHandle. The message set number and message number are specified using setnum and msgnum. If the message catalog was not opened or the message set or message number cannot be found, then the default string, defaultstr, is returned.

catopen

catopen
 [-fail|-nofail] catname

Open a message catalog using catname, which can be an absolute or relative pathname. Return a handle that can be used for subsequent catgets > and catclose > commands.

Options

-fail

Return an error if the catalog cannot be opened.

-nofail

Ignore any errors when opening (default).

ccollate

ccollate [-local] string1 string2

Compare two strings and return their collation ordering. Return -1 if string1 is less than string2, 0 if they are equal, and 1 if string1 is greater than string2. With the option -local >, compares according to current locale.

cconcat

cconcat [string...]

Concatenate the strings passed as arguments and return the resulting string.

ceil

ceil arg

Return the value of expression arg, rounded up to the nearest integer.

cequal

cequal string1 string2

Compare two strings, returning 1 if they are identical, 0 if not.

chgrp

chgrp [-fileId] group filelist

Set the group ID of files in the list filelist to group, which can be either a group name or a group ID number.

With option -fileId >, the file list consists of open file identifiers rather than filenames. This command is not supported under Windows.

chmod

chmod [-fileId] mode filelist

Set permissions on the files specified in list filelist to mode, which can be a numeric mode or symbolic permissions as accepted by the Unix chmod > command.

With option -fileId >, the file list consists of open file identifiers rather than filenames. This command is not supported under Windows.

chown

chown [-fileId] owner filelist

chown > [-fileId] {owner group} filelist

Set the ownership of each file in list filelist to owner, which can be a username or numeric user ID. In the second form, a list consisting of the owner and group names can be specified.

With option -fileId >, the file list consists of open file identifiers rather than filenames. This command is not supported under Windows.

chroot

chroot dirname

Set the process root directory to dirname. Can be run only by the superuser.

cindex

cindex string indexExpr

Return the character with index indexExpr in string string. Indices start at 0; the words end and len can be used at the beginning of the expression to indicate the index of the last character and length of the string, respectively.

clength

clength string

Return the length of string in characters.

cmdtrace

cmdtrace level [noeval] [notruncate] [procs]
[fileId]
[command cmd]

Print a trace statement when commands are executed at depth level (1 being the top level) or at all levels if the level is specified as on.

Options

noeval

Cause arguments to be printed before being evaluated.

notruncate

Turn off truncation of output, which normally occurs when a command line is longer than 60 characters.

procs

Enable tracing of procedure calls only.

fileId

Cause output to be written to an open file identifier.

command

Rather than producing normal output, the given command is executed during tracing.

cmdtrace off >

Turn off all tracing.

cmdtrace depth >

Return the current trace depth level, or 0 if tracing is not enabled.

commandloop

commandloop [-async] [-interactive on|off|tty]
[-prompt1 cmd]
[-prompt2 cmd]
[-endcommand cmd]

Enter a command loop, reading from standard input and writing to standard output.

Options

-async

Interpret commands on standard input.

-interactive

Controls interactive command mode (prompting of commands and display of results). If the argument is on, interactive mode is enabled; if off, it is disabled; if tty, it is enabled if standard input is associated with a terminal.

-prompt1

The argument supplies a command that is executed and the result used as the primary command prompt.

-prompt2

The argument supplies a command that is executed and the result used as the secondary command prompt.

-endcommand

The argument supplies a command that is executed when the command loop terminates.

convert_lib

convert_lib tclIndex packagelib
[ignore]

Convert a Tcl index file tclIndex and its associated source files into an Extended Tcl package library packagelib. The list ignore can specify files that should not be included in the library.

cos

cos arg

Return the cosine of expression arg.

cosh

cosh arg

Return the hyperbolic cosine of expression arg.

crange

crange string
firstExpr
lastExpr

Return a range of characters from string string, from index firstExpr through lastExpr.

Indices start at 0, and the words end and len can be used at the beginning of an expression to indicate the index of the last character and length of the string, respectively.

csubstr

csubstr string
firstExpr
lengthExpr

Return a range of characters from string string from index firstExpr for a range of lengthExpr characters.

Indices start at 0, and the words end and len can be used at the beginning of an expression to indicate the index of the last character and length of the string, respectively.

ctoken

ctoken strvar
separators

Parse the next token from the string contained in variable strvar. Tokens are separated by the characters specified in the string separators. Returns the next token and removes it from the string.

ctype

ctype [-failindex var]
class string

Examine the characters in string and determine if they conform to the specified class. Return 1 if they conform, 0 if they do not or the string is empty. The class option takes one of the following forms:

alnum

All characters are alphabetic or numeric.

alpha

All characters are alphabetic.

ascii

All characters are ASCII characters.

char

Converts the string, which must be a number from 0 through 255, to an ASCII character.

cntrl

All characters are control characters

digit

All characters are decimal digits.

graph

All characters are printable and nonspace.

lower

All characters are lowercase.

ord

Converts the first character in the string to its decimal numeric value.

space

All characters are whitespace.

print

All characters are printable (including space).

punct

All characters are punctuation.

upper

All characters are uppercase.

xdigit

All characters are valid hexadecimal digits.

With the option -failindex, the index of the first character in the string that did not conform to the class is placed in the variable named var.

dirs

dirs

List the directories in the directory stack.