karl@sugar.hackercorp.com (Karl Lehenbauer) (03/19/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
NAME
Tcl - overview of tool command language facilities
INTRODUCTION
Tcl stands for ``tool command language'' and is pronounced
``tickle.'' It is actually two things: a language and a
library. First, Tcl is a simple textual language, intended
primarily for issuing commands to interactive programs such
as text editors, debuggers, illustrators, and shells. It
has a simple syntax and is also programmable, so Tcl users
can write command procedures to provide more powerful
commands than those in the built-in set.
Second, Tcl is a library package that can be embedded in
application programs. The Tcl library consists of a parser
for the Tcl language, routines to implement the Tcl built-in
commands, and procedures that allow each application to
extend Tcl with additional commands specific to that
application. The application program generates Tcl commands
and passes them to the Tcl parser for execution. Commands
may be generated by reading characters from an input source,
or by associating command strings with elements of the
application's user interface, such as menu entries, buttons,
or keystrokes. When the Tcl library receives commands it
parses them into component fields and executes built-in
commands directly. For commands implemented by the
application, Tcl calls back to the application to execute
the commands. In many cases commands will invoke recursive
invocations of the Tcl interpreter by passing in additional
strings to execute (procedures, looping commands, and
conditional commands all work in this way).
An application program gains three advantages by using Tcl
for its command language. First, Tcl provides a standard
syntax: once users know Tcl, they will be able to issue
commands easily to any Tcl-based application. Second, Tcl
provides programmability. All a Tcl application needs to do
is to implement a few application-specific low-level
commands. Tcl provides many utility commands plus a general
programming interface for building up complex command
procedures. By using Tcl, applications need not re-
implement these features. Third, Tcl will eventually
provide a mechanism for communicating between applications:
it will be possible to send Tcl commands from one
application to another. The common Tcl language framework
will make it easier for applications to communicate with one
another. The communication features are not implemented in
the current version of Tcl.
This manual page focusses primarily on the Tcl language. It
describes the language syntax and the built-in commands that
Page 1 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
will be available in any application based on Tcl. The
individual library procedures are described in more detail
in separate manual pages, one per procedure.
INTERPRETERS
The central data structure in Tcl is an interpreter (C type
``Tcl_Interp''). An interpreter consists of a set of
command bindings, a set of variable values, and a few other
miscellaneous pieces of state. Each Tcl command is
interpreted in the context of a particular interpreter.
Some Tcl-based applications will maintain multiple
interpreters simultaneously, each associated with a
different widget or portion of the application.
Interpreters are relatively lightweight structures. They
can be created and deleted quickly, so application
programmers should feel free to use multiple interpreters if
that simplifies the application. Eventually Tcl will
provide a mechanism for sending Tcl commands and results
back and forth between interpreters, even if the
interpreters are managed by different processes.
DATA TYPES
Tcl supports only one type of data: strings. All commands,
all arguments to commands, all command results, and all
variable values are strings. Where commands require numeric
arguments or return numeric results, the arguments and
results are passed as strings. Many commands expect their
string arguments to have certain formats, but this
interpretation is up to the individual commands. For
example, arguments often contain Tcl command strings, which
may get executed as part of the commands. The easiest way
to understand the Tcl interpreter is to remember that
everything is just an operation on a string. In many cases
Tcl constructs will look similar to more structured
constructs from other languages. However, the Tcl
constructs are not structured at all; they are just strings
of characters, and this gives them a different behavior than
the structures they may look like.
Although the exact interpretation of a Tcl string depends on
who is doing the interpretation, there are three common
forms that strings take: commands, expressions, and lists.
The major sections below discuss these three forms in more
detail.
BASIC COMMAND SYNTAX
The Tcl language has syntactic similarities to both the Unix
shells and Lisp. However, the interpretation of commands is
different in Tcl than in either of those other two systems.
Page 2 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
A Tcl command string consists of one or more commands
separated by newline characters or semi-colons. Each
command consists of a collection of fields separated by
white space (spaces or tabs). The first field must be the
name of a command, and the additional fields, if any, are
arguments that will be passed to that command. For example,
the command
set a 22
has three fields: the first, set, is the name of a Tcl
command, and the last two, a and 22, will be passed as
arguments to the set command. The command name may refer
either to a built-in Tcl command, an application-specific
command bound in with the library procedure
Tcl_CreateCommand, or a command procedure defined with the
proc built-in command. Arguments are passed literally as
text strings. Individual commands may interpret those
strings in any fashion they wish. The set command, for
example, will treat its first argument as the name of a
variable and its second argument as a string value to assign
to that variable. For other commands arguments may be
interpreted as integers, lists, file names, or Tcl commands.
Command names may be abbreviated as long as the abbreviation
is unique. However, it's probably a bad idea to use
abbreviations in command scripts and other forms that will
be re-used over time: changes to the command set may cause
abbreviations to become ambiguous, resulting in scripts that
no longer work. Abbreviations are intended primarily for
commands that are typed interactively, invoked once, and
discarded.
COMMENTS
If the first non-blank character in a command is #, then
everything from the # up through the next newline character
is treated as a comment and ignored.
GROUPING ARGUMENTS WITH BRACES
Normally each argument field ends at the next white space,
but curly braces (``{'' and ``}'') may be used to group
arguments in different ways. If an argument field begins
with a left brace, then the argument isn't terminated by
white space; instead it ends at the matching right brace.
Tcl will strip off the outermost layer of braces before
passing the argument to the command. This provides a simple
mechanism for including white space in arguments. For
example, the command
set a {This is a single argument}
Page 3 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
will pass two arguments to set: a and This is a single
argument. In the command
set a {xyz a {b c d}}
the set command will receive two arguments: a and xyz a {b c
d}.
When braces are in effect, the matching brace need not be on
the same line as the starting quote or brace; in this case
the newline will be included in the argument field along
with any other characters up to the matching quote or brace.
For example, the eval command takes one argument, which is a
command string; eval invokes the Tcl interpreter to execute
the command string. The command
eval {
set a 22
set b 33
}
will assign the value 22 to a and 33 to b.
When an argument is in braces, then command, variable, and
backslash substitutions do not occur as described below;
all Tcl does is to strip off the outer layer of braces and
pass the contents to the command.
If the first character of a command field isn't a left
brace, then neither left nor right braces in the field will
be treated specially (except as part of variable
substitution; see below).
COMMAND SUBSTITUTION WITH BRACKETS
If an open bracket occurs in any of the fields of a command,
then command substitution occurs. All of the text up to the
matching close bracket is treated as a Tcl command and
executed immediately. Then the result of that command is
substituted for the bracketed text. For example, consider
the command
set a [set b]
When the set command has only a single argument, it is the
name of a variable and set returns the contents of that
variable. In this case, if variable b has the value foo,
then the command above is equivalent to the command
set a foo
Brackets can be used in more complex ways. For example, if
Page 4 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
the variable b has the value foo and the variable c has the
value gorp, then the command
set a xyz[set b].[set c]
is equivalent to the command
set a xyzfoo.gorp
A bracketed command need not be all on one line: newlines
within brackets are treated as argument separators, not
command separators. If a field is enclosed in braces then
the brackets and the characters between them are not
interpreted specially; they are passed through to the
argument verbatim.
VARIABLE SUBSTITUTION WITH $
The dollar sign ($) may be used as a special shorthand form
for substituting variables. If $ appears in an argument
that isn't enclosed in braces then variable substitution
will occur. The characters after the $, up to the first
character that isn't a number, letter, or underscore, are
taken as a variable name and the string value of that
variable is substituted for the name. Or, if the dollar
sign is followed by an open curly brace then the variable
name consists of all the characters up to the next close
curly brace. For example, if variable foo has the value
test, then the command
set a $foo.c
is equivalent to the command
set a test.c
and the command
set a abc${foo}bar
is equivalent to the command
set a abctestbar
Variable substitution does not occur in arguments that are
enclosed in braces: the dollar sign and variable name are
passed through to the argument verbatim.
The dollar sign abbreviation is simply a shorthand form. $a
is completely equivalent to [set a]; it is provided as a
convenience to reduce typing.
Page 5 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
SEPARATING COMMANDS WITH SEMI-COLONS |
Normally, each command occupies one line (the command is |
terminated by a newline character). However, semi-colon |
(``;'') is treated as a command separator character; |
multiple commands may be placed on one line by separating |
them with a semi-colon.
BACKSLASH SUBSTITUTION
Backslashes may be used to insert non-printing characters
into command fields and also to insert special characters
like braces and brackets into fields without them being
interpreted specially as described above. The backslash
sequences understood by the Tcl interpreter are listed
below. In each case, the backslash sequence is replaced by
the given character:
\b Backspace (octal 10).
\e Escape (octal 33).
\n Newline (octal 15).
\t Tab (octal 11).
\{ Left brace (``{'').
\} Right brace (``}'').
\[ Open bracket (``['').
\] Close bracket (``]'').
\<space> Space (`` ''): doesn't terminate
argument.
\; ||
Semi-colon: doesn't terminate command. |
\" ||
Double-quote. |
\<newline> ||
Nothing: this effectively joins two |
lines together into a single line. This |
backslash feature is only provided when |
parsing Tcl commands; it is not |
supported by the Tcl_Backslash |
procedure.
\\ Backslash (``\'').
Page 6 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
\Cx Control-x (x AND octal 037), for any
ASCII x except M (see below).
\Mx Meta-x (x OR octal 200), for any ASCII
x.
\CMx Control-meta-x ((x AND octal 037) OR
octal 0200), for any ASCII x.
\ddd The digits ddd (one, two, or three of
them) give the octal value of the
character.
For example, in the command
set a \{x\[\ yz\141
the second argument to set will be ``{x[ yza''.
If a backslash is followed by something other than one of
the options described above, then the backslash is
transmitted to the argument field without any special
processing, and the Tcl scanner continues normal processing
with the next character. For example, in the command
set \*a \\\{foo
The first argument to set will be \*a and the second
argument will be \{foo.
If an argument is enclosed in braces, then backslash
sequences inside the argument are parsed but no substitution
occurs: the backslash sequence is passed through to the
argument as is, without making any special interpretation of
the characters in the backslash sequence. In particular,
backslashed braces are not counted in locating the matching
right brace that terminates the argument. For example, in
the command
set a {\{abc}
the second argument to set will be \{abc.
This backslash mechanism is not sufficient to generate
absolutely any argument structure; it only covers the most
common cases. To produce particularly complicated arguments
it will probably be easiest to use the format command along
with command substitution.
COMMAND SUMMARY
[1] A command is just a string.
Page 7 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
[2] Within a string commands are separated by newlines or
semi-colons (unless the newline or semi-colon is within
braces or brackets or is backslashed).
[3] A command consists of fields. The first field is the
name of the command, and may be abbreviated. The other
fields are strings that are passed to that command as
arguments.
[4] Fields are normally separated by white space.
[5] Braces defer interpretation of special characters. If
a field begins with a left brace, then it consists of
everything between the left brace and the matching
right brace. The braces themselves are not included in
the argument. No further processing is done on the
information between the braces.
[6] Double-quotes act the same as braces except that they
cannot be nested.
[7] If a field doesn't begin with a left brace or double-
quote, then backslash, variable, and command
substitution are done on the field. Only a single
level of processing is done: the results of one
substitution are not scanned again for further
substitutions or any other special treatment.
Substitution can occur on any field of a command,
including the command name as well as the arguments.
[8] If the first non-blank character of a command is a #,
everything from the # up through the next newline is
treated as a comment and ignored.
EXPRESSIONS
The second major interpretation applied to strings in Tcl is
as expressions. Several commands, such as expr, for, and
if, treat some of their arguments as expressions and call
the Tcl expression processor (Tcl_Expr) to evaluate them. A
Tcl expression has C-like syntax and evaluates to an integer
result. Expressions may contain integer values, variable
names in $ notation (the variables' values must be integer
strings), commands (embedded in brackets) that produce
integer string results, parentheses for grouping, and
operators. Numeric values, whether they are passed directly
or through variable or command substitution, may be
specified either in decimal (the normal case), in octal (if
the first character of the value is 0), or in hexadecimal
(if the first two characters of the value are 0x). The
valid operators are listed below, grouped in decreasing
order of precedence:
Page 8 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
- ~ ! Unary minus, bit-wise NOT, logical NOT.
* / % Multiply, divide, remainder.
+ - Add and subtract.
<< >> Left and right shift.
< > <= >= Boolean less, greater, less than or
equal, and greater than or equal. Each
operator produces 1 if the condition is
true, 0 otherwise.
== != Boolean equal and not equal. Each
operator produces a zero/one result.
& Bit-wise AND.
^ Bit-wise exclusive OR.
| Bit-wise OR.
&& Logical AND. Produces a 1 result if
both operands are non-zero, 0 otherwise.
|| Logical OR. Produces a 0 result if both
operands are zero, 1 otherwise.
See the C manual for more details on the results produced by
each operator. All of the binary operators group left-to-
right within the same precedence level. For example, the
expression
(4*2) < 7
evaluates to 0. Evaluating the expression string
($a + 3) < [set b]
will cause the values of the variables a and b to be
examined; the result will be 1 if b is greater than a by at
least 3; otherwise the result will be 0.
In general it is safest to enclose an expression in braces
when entering it in a command: otherwise, if the expression
contains any white space then the Tcl interpreter will split
it among several arguments. For example, the command
expr $a + $b
results in three arguments being passed to expr: $a, +, and
$b. In addition, if the expression isn't in braces then the
Page 9 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
Tcl interpreter will perform variable and command
substitution immediately (it will happen in the command
parser rather than in the expression parser). In many cases
the expression is being passed to a command that will
evaluate the expression later (or even many times if, for
example, the expression is to be used to decide when to exit
a loop). Usually the desired goal is to re-do the variable
or command substitutions each time the expression is
evaluated, rather than once and for all at the beginning.
For example, the command
for {set i 1} $i<=10 {set i [expr $i+1]} {...}
is probably intended to iterate over all values of i from 1
to 10. After each iteration of the body of the loop, for
will pass its second argument to the expression evaluator to
see whether or not to continue processing. Unfortunately,
in this case the value of i in the second argument will be
substituted once and for all when the for command is parsed.
If i was 0 before the for command was invoked then for's
second argument will be 0<=10 which will always evaluate to
1, even though i's value eventually becomes greater than 10.
In the above case the loop will never terminate. By placing
the expression in braces, the substitution of i's value will
be delayed; it will be re-done each time the expression is
evaluated, which is probably the desired result.
LISTS
The third major way that strings are interpreted in Tcl is
as lists. A list is just a string with a list-like
structure consisting of fields separated by white space.
For example, the string
Al Sue Anne John
is a list with four elements or fields. Lists have the same
basic structure as command strings, except that a newline
character in a list is treated as a field separator just
like space or tab. Conventions for braces and backslashes
are the same for lists as for commands. For example, the
string
a b\ c {d e {f g h}}
is a list with three elements: a, b c, and d e {f g h}.
Whenever an element is extracted from a list, the same rules
about backslashes and braces are applied as for commands.
Thus in the example above when the third element is
extracted from the list, the result is
d e {f g h}
Page 10 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
(when the field was extracted, all that happened was to
strip off the outermost layer of braces). Command
substitution is never made on a list (at least, not by the
list-processing commands; the list can always be passed to
the Tcl interpreter for evaluation).
The Tcl commands concat, foreach, index, length, list, and
range allow you to build lists, extract elements from them,
search them, and perform other list-related functions.
COMMAND RESULTS
Each command produces two results: a code and a string.
The code indicates whether the command completed
successfully or not, and the string gives additional
information. The valid codes are defined in tcl.h, and are:
TCL_OK This is the normal return code, and
indicates that the command
completed succesfully. The string
gives the command's return value.
TCL_ERROR Indicates that an error occurred;
the string gives a message
describing the error. The variable |
errorInfo will contain additional |
information describing which |
commands and procedures were being |
executed when the error occurred.
TCL_RETURN Indicates that the return command
has been invoked, and that the |
current procedure (or top-level |
command or source command) should |
return immediately. The string |
gives the return value for the |
procedure or command.
TCL_BREAK Indicates that the break command
has been invoked, so the innermost
loop should abort immediately. The
string should always be empty.
TCL_CONTINUE Indicates that the continue command
has been invoked, so the innermost
loop should go on to the next
iteration. The string should
always be empty.
Tcl programmers do not normally need to think about return
codes, since TCL_OK is almost always returned. If anything
else is returned by a command, then the Tcl interpreter
immediately stops processing commands and returns to its
Page 11 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
caller. If there are several nested invocations of the Tcl
interpreter in progress, then each nested command will
usually return the error to its caller, until eventually the
error is reported to the top-level application code. The
application will then display the error message for the
user.
In a few cases, some commands will handle certain ``error''
conditions themselves and not return them upwards. For
example, the for command checks for the TCL_BREAK code; if
it occurs, then for stops executing the body of the loop and
returns TCL_OK to its caller. The for command also handles
TCL_CONTINUE codes and the procedure interpreter handles
TCL_RETURN codes. The catch command allows Tcl programs to
catch errors and handle them without aborting command
interpretation any further.
PROCEDURES
Tcl allows you to extend the command interface by defining
procedures. A Tcl procedure can be invoked just like any
other Tcl command (it has a name and it receives one or more
arguments). The only difference is that its body isn't a
piece of C code linked into the program; it is a string
containing one or more other Tcl commands. See the proc
command for information on how to define procedures and what
happens when they are invoked.
VARIABLES
Tcl allows the definition of variables and the use of their
values either through $-style variable substitution, the set
command, or a few other mechanisms. Variables need not be
declared: a new variable will automatically be created each
time a new variable name is used. Variables may be either
global or local. If a variable name is used when a
procedure isn't being executed, then it automatically refers
to a global variable. Variable names used within a
procedure normally refer to local variables associated with
that invocation of the procedure. Local variables are
deleted whenever a procedure exits. The global command may
be used to request that a name refer to a global variable
for the duration of the current procedure (this is somewhat
analogous to extern in C).
BUILT-IN COMMANDS
The Tcl library provides the following built-in commands,
which will be available in any application using Tcl. In
addition to these built-in commands, there may be additional
commands defined by each application, plus commands defined
as Tcl procedures. In the command syntax descriptions
Page 12 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
below, optional arguments are indicated by enclosing their
names in brackets; apologies in advance for the confusion
between this descriptive use of brackets and the use of
brackets to invoke command substitution. Words in boldface
are literals that you type verbatim to Tcl. Words in
italics are meta-symbols; they act as names to refer to a
class of values that you can type.
break
This command may be invoked only inside the body of a
loop command such as for or foreach. It returns a
TCL_BREAK code to signal the innermost containing loop
command to return immediately.
case string [in] patList body patList body ...
Match string against each of the patList arguments in |
order. If one matches, then evaluate the following |
body argument by passing it recursively to the Tcl |
interpreter, and return the result of that evaluation. |
Each patList argument consists of a single pattern or |
list of patterns. Each pattern may contain any of the |
wild-cards described under string match. If a patList |
argument is default, the corresponding body will be |
evaluated if no patList matches string. If no patList |
argument matches string and no default is given, then |
the case command returns an empty string. For example, |
case abc in {a b} {format 1} default {format 2} a* {format 3}|
will return 3, |
case a in {a b} {format 1} default {format 2} a* {format 3}|
will return 1, and |
case xyz {a b} {format 1} default {format 2} a* {format 3}|
will return 2. |
catch command [varName]
The catch command may be used to prevent errors from
aborting command interpretation. Catch calls the Tcl
interpreter recursively to execute command, and always
returns a TCL_OK code, regardless of any errors that
might occur while executing command. The return value
from catch is a decimal string giving the code returned
by the Tcl interpreter after executing command. This
will be 0 (TCL_OK) if there were no errors in command;
otherwise it will have a non-zero value corresponding
to one of the exceptional return codes (see tcl.h for
the definitions of code values). If the varName
argument is given, then it gives the name of a
Page 13 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
variable; catch will set the value of the variable to
the string returned from command (either a result or an
error message).
concat arg arg ...
This command treats each argument as a list and
concatenates them into a single list. It permits any
number of arguments. For example, the command
concat a b {c d e} {f {g h}}
will return
a b c d e f {g h}
as its result.
continue
This command may be invoked only inside the body of a
loop command such as for or foreach. It returns a
TCL_CONTINUE code to signal the innermost containing
loop command to skip the remainder of the loop's body
but continue with the next iteration of the loop.
error message
Returns a TCL_ERROR code, which causes command
interpretation to be unwound. Message is a string that
is returned to the application to indicate what went
wrong. |
eval arg1 arg2 ... ||
Eval takes one or more arguments, which together |
comprise a Tcl command (or collection of Tcl commands |
separated by newlines in the usual way). Eval |
concatenates all its arguments in the same fashion as |
the concat command, passes the concatenated string to |
the Tcl interpreter recursively, and returns the result |
of that evaluation (or any error generated by it).
exec command arg1 arg2 ...[< input]
The exec command treats its command argument as the
name of a program to execute. It searches the
directories in the PATH environment variable to find an
executable file by the name command, then executes the
file, passing it an argument list consisting of command
plus all of the args. If an argument < appears
anywhere among the arguments to exec, then neither it
or the following argument is passed to command.
Instead, the following argument (input) consists of
input to the command; exec will create a pipe and use
it to pass input to command as standard input. Exec
also creates a pipe to receive command's output (both
Page 14 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
standard output and standard error). The information
received over this pipe is returned as the result of
the exec command. The exec command also looks at the
return status returned by command. Normally this
should be zero; if it is then exec returns normally.
If command returns a non-zero status, then exec will
return that code; it should be one of the ones defined
in the section ``COMMAND RESULTS'' above. If an out-of
range code is returned by the command, it will cause
command unwinding just as if TCL_ERROR had been
returned; at the outermost level of command
interpretation, the Tcl interpreter will turn the code
into TCL_ERROR, with an appropriate error message.
expr arg
Calls the expression processor to evaluate arg, and
returns the result as a decimal string.
file name option
Operate on a file or a file name. Name is the name of
a file, and option indicates what to do with the file
name. Any unique abbreviation for option is
acceptable. The valid options are:
file name dirname
Return all of the characters in name up to but not
including the last slash character. If there are
no slashes in name then return ``.''. If the last
slash in name is its first character, then return
``/''.
file name executable
Return 1 if file name is executable by the current
user, 0 otherwise.
file name exists
Return 1 if file name exists and the current user
has search privileges for the directories leading
to it, 0 otherwise.
file name extension
Return all of the characters in name after and
including the last dot in name. If there is no
dot in name then return the empty string.
file name isdirectory
Return 1 if file name is a directory, 0 otherwise.
file name isfile
Return 1 if file name is a regular file, 0
otherwise.
Page 15 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
file name owned
Return 1 if file name is owned by the current
user, 0 otherwise.
file name readable
Return 1 if file name is readable by the current
user, 0 otherwise.
file name rootname
Return all of the characters in name up to but not
including the last ``.'' character in the name.
If name doesn't contain a dot, then return name.
file name tail
Return all of the characters in name after the
last slash. If name contains no slashes then
return name.
file name writable
Return 1 if file name is writable by the current
user, 0 otherwise.
The file commands that return 0/1 results are often
used in conditional or looping commands, for example:
if {![file foo exists]} then {error {bad file name}} else {...}
for start test next body
For is a looping command, similar in structure to the C
for statement. The start, next, and body arguments
must be Tcl command strings, and test is an expression
string. The for command first invokes the Tcl
interpreter to execute first. Then it repeatedly
evaluates test as an expression; if the result is
non-zero it invokes the Tcl interpreter on body, then
invokes the Tcl interpreter on next, then repeats the
loop. The command terminates when test evaluates to 0.
If a continue command is invoked within body then any
remaining commands in the current execution of body are
skipped; processing continues by invoking the Tcl
interpreter on next, then evaluating test, and so on.
If a break command is invoked within body or next, then |
the for command will return immediately. The operation
of break and continue are similar to the corresponding
statements in C. For returns an empty string.
foreach varname list body
In this command, varname is the name of a variable,
list is a list of values to assign to varname, and body
is a collection of Tcl commands. For each field in
list (in order from left to right), foreach assigns the
Page 16 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
contents of the field to varname (as if the index
command had been used to extract the field), then calls
the Tcl interpreter to execute body. The break and
continue statements may be invoked inside body, with
the same effect as in the for command. Foreach an
empty string.
format formatString arg arg ...
This command generates a formatted string in the same
way as the C sprintf procedure (it uses sprintf in its
implementation). FormatString indicates how to format
the result, using % fields as in sprintf, and the
additional arguments, if any, provide values to be
substituted into the result. All of the sprintf
options are valid; see the sprintf man page for
details. Each arg must match the expected type from
the % field in formatString; the format command
converts each argument to the correct type (floating,
integer, etc.) before passing it to sprintf for
formatting. The only unusual conversion is for %c; in
this case the argument must be a decimal string, which
will then be converted to the corresponding ASCII
character value. Format does backslash substitution on
its formatString argument, so backslash sequences in
formatString will be handled correctly even if the
argument is in braces. The return value from format is
the formatted string.
glob filename
This command performs filename globbing, using csh |
rules. The returned value from glob is the list of |
expanded filenames.
global varname varname ...
This command is ignored unless a Tcl procedure is being
interpreted. If so, then it declares the given
varname's to be global variables rather than local
ones. For the duration of the current procedure (and
only while executing in the current procedure), any
reference to any of the varnames will be bound to a
global variable instead of a local one.
if test [then] trueBody [[else] falseBody]
The if command evaluates test as an expression (in the
same way that expr evaluates its argument). If the
result is non-zero then trueBody is called by passing
it to the Tcl interpreter. Otherwise falseBody is
executed by passing it to the Tcl interpreter. The
then and else arguments are optional ``noise words'' to
make the command easier to read. FalseBody is also
optional; if it isn't specified then the command does
nothing if test evaluates to zero. The return value
Page 17 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
from if is the value of the last command executed in
trueBody or falseBody, or the empty string if test
evaluates to zero and falseBody isn't specified.
index value index [chars]
Extract an element from a list or a character from a
string. If the chars keyword isn't specified, then
index treats value as a list and returns the index'th
field from it. In extracting the field, index observes
the same rules concerning braces and backslashes as the
Tcl command interpreter; however, variable
substitution and command substitution do not occur. If
index is greater than or equal to the number of
elements in value, then the empty string is returned.
If the chars keyword is specified (or any abbreviation
of it), then value is treated as a string and the
command returns the index'th character from it (or the
empty string if there aren't at least index+1
characters in the string). Index 0 refers to the first
element or character of value.
info option arg arg ...
Provide information about various internals to the Tcl
interpreter. The legal option's (which may be
abbreviated) are:
info args procname
Returns a list containing the names of the
arguments to procedure procname, in order.
Procname must be the name of a Tcl command
procedure.
info body procname
Returns the body of procedure procname. Procname
must be the name of a Tcl command procedure.
info commands [pattern]
If pattern isn't specified, returns a list of |
names of all the Tcl commands, including both the |
built-in commands written in C and the command |
procedures defined using the proc command. If |
pattern is specified, only those names matching |
pattern are returned. Matching is determined |
using the same rules as for string match.
info cmdcount
Returns a count of the total number of commands
that have been invoked in this interpreter.
info default procname arg varname
Procname must be the name of a Tcl command
procedure and arg must be the name of an argument
Page 18 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
to that procedure. If arg doesn't have a default
value then the command returns 0. Otherwise it
returns 1 and places the default value of arg into
variable varname.
info globals [pattern]
If pattern isn't specified, returns a list of all |
the names of currently-defined global variables. |
If pattern is specified, only those names matching |
pattern are returned. Matching is determined |
using the same rules as for string match. |
info level [number] ||
If number is not specified, this command returns a |
number giving the stack level of the invoking |
procedure, or 0 if the command is invoked at top- |
level. If number is specified, then the result is |
a list consisting of the name and arguments for |
the procedure call at level number on the stack. |
If number is positive then it selects a particular |
stack level (1 refers to the top-most active |
procedure, 2 to the procedure it called, and so |
on); otherwise it gives a level relative to the |
current level (0 refers to the current procedure, |
-1 to its caller, and so on). See the uplevel |
command for more information on what stack levels |
mean. |
info locals [pattern] ||
If pattern isn't specified, returns a list of all |
the names of currently-defined local variables, |
including arguments to the current procedure, if |
any. If pattern is specified, only those names |
matching pattern are returned. Matching is |
determined using the same rules as for string |
match. |
info procs [pattern] ||
If pattern isn't specified, returns a list of all |
the names of Tcl command procedures. If pattern |
is specified, only those names matching pattern |
are returned. Matching is determined using the |
same rules as for string match. |
info tclversion ||
Returns the version number for this version of Tcl |
in the form x.y, where changes to x represent |
major changes with probable incompatibilities and |
changes to y represent small enhancements and bug |
fixes that retain backward compatibility.
info vars
Page 19 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
Returns a list of all the names of currently-
visible variables, including both locals and
currently-visible globals.
length value [chars]
If chars isn't specified, treats value as a list and
returns the number of elements in the list. If chars
is specified (or any abbreviation of it), then length
treats value as a string and returns the number of
characters in it (not including the terminating null
character).
list arg1 arg2 ...
This command returns a list comprised of all the args.
Braces and backslashes get added as necessary, so that
the index command may be used on the result to re-
extract the original arguments, and also so that eval
may be used to execute the resulting list, with arg1
comprising the command's name and the other args
comprising its arguments. List produces slightly
different results than concat: concat removes one
level of grouping before forming the list, while list
works directly from the original arguments. For
example, the command
list a b {c d e} {f {g h}}
will return
a b {c d e} {f {g h}}
while concat with the same arguments will return
a b c d e f {g h}
print string [file [append]]
Print the string argument. If no file is specified |
then string is output to the standard output file. If |
file is specified, then string is output to that file. |
If the append option is given, then string is appended |
to file; otherwise any existing contents of file are |
discarded before string is written to the file.
proc name args body
The proc command creates a new Tcl command procedure,
name, replacing any existing command there may have
been by that name. Whenever the new command is
invoked, the contents of body will be executed by the
Tcl interpreter. Args specifies the formal arguments
to the procedure. It consists of a list, possibly
empty, each of whose elements specifies one argument.
Page 20 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
Each argument specifier is also a list with either one
or two fields. If there is only a single field in the
specifier, then it is the name of the argument; if
there are two fields, then the first is the argument
name and the second is its default value. braces and
backslashes may be used in the usual way to specify
complex default values.
When name is invoked, a local variable will be created
for each of the formal arguments to the procedure; its
value will be the value of corresponding argument in
the invoking command or the argument's default value.
Arguments with default values need not be specified in
a procedure invocation. However, there must be enough
actual arguments for all the formal arguments that
don't have defaults, and there must not be any extra
actual arguments. There is one special case to permit
procedures with variable numbers of arguments. If the
last formal argument has the name args, then a call to
the procedure may contain more actual arguments than
the procedure has formals. In this case, all of the
actual arguments starting at the one that would be
assigned to args are combined into a list (as if the
list command had been used); this combined value is
assigned to the local variable args.
When body is being executed, variable names normally
refer to local variables, which are created
automatically when referenced and deleted when the
procedure returns. One local variable is automatically
created for each of the procedure's arguments. Global
variables can only be accessed by invoking the global
command.
The proc command returns the null string. When a
procedure is invoked, the procedure's return value is
the value specified in a return command. If the
procedure doesn't execute an explicit return, then its
return value is the value of the last command executed
in the procedure's body. If an error occurs while
executing the procedure body, then the procedure-as-a-
whole will return that same error.
range value first last [chars]
Return a range of fields or characters from value. If
the chars keyword isn't specified, then value must be a
list and range will return a new list consisting of
elements first through last, inclusive. The special
keyword end may be specified for last; in this case all
the elements of value starting at first are returned.
If the chars keyword, or any abbreviation of it, is
specified, then range treats value as a character
Page 21 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
string and returns characters first through last of it,
inclusive. Once again, the end keyword may be used for
last. In both cases if a last value is specified
greater than the size of value it is equivalent to
specifying end; if last is less than first then an
empty string is returned. Note: ``range value first
first'' does not always produce the same results as
``index value first'' (although it often does for
simple fields that aren't enclosed in braces); it
does, however, produce exactly the same results as
``list [index value first]''
rename oldName newName
Rename the command that used to be called oldName so |
that it is now called newName. If newName is an empty |
string (e.g. {}) then oldName is deleted. The rename |
command returns an empty string as result.
return [value]
Return immediately from the current procedure (or top- |
level command or source command), with value as the
return value. If value is not specified, an empty
string will be returned as result.
scan string format varname1 varname2 ...
This command parses fields from an input string in the
same fashion as the C sscanf procedure. String gives
the input to be parsed and format indicates how to
parse it, using % fields as in sscanf. All of the
sscanf options are valid; see the sscanf man page for
details. Each varname gives the name of a variable;
when a field is scanned from string, the result is
converted back into a string and assigned to the
corresponding varname. The only unusual conversion is
for %c; in this case, the character value is converted
to a decimal string, which is then assigned to the
corresponding varname. |
set varname [value] ||
If value isn't specified, then return the current value |
of varname. If value is specified, then set the value
of varname to value, creating a new variable if one
doesn't already exist. If no procedure is active, then
varname refers to a global variable. If a procedure is
active, then varname refers to a parameter or local
variable of the procedure, unless the global command
has been invoked to declare varname to be global.
source fileName
Read file fileName and pass the contents to the Tcl
interpreter as a sequence of commands to execute in the
normal fashion. The return value of source is the
Page 22 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
return value of the last command executed from the
file. If an error occurs in executing the contents of
the file, then the source command will return that
error. If a return command is invoked from within the |
file, the remainder of the file will be skipped and the |
source command will return normally with the result |
from the return command.
string option a b
Perform a string operation on the two operands a and b,
based on option. The possible options are:
string compare a b
Perform a character-by-character comparison of
strings a and b, in the same way as the C strcmp
procedure. Return -1, 0, or 1, depending on
whether a is lexicographically less than, equal
to, or greater than b.
string first a b
Search b for a sequence of characters that exactly
match the characters in a. If found, return the
index of the first character in the first such
match within b. If not found, return -1.
string last a b
Search b for a sequence of characters that exactly
match the characters in a. If found, return the
index of the first character in the last such
match within b. If there is no match, then return
-1.
string match pattern string ||
See if pattern matches string; return 1 if it |
does, 0 if it doesn't. Matching is done in a |
fashion similar to that used by the C-shell. For |
the two strings to match, their contents must be |
identical except that the following special |
sequences may appear in pattern: |
* ||
Matches any sequence of characters in |
string, including a null string. |
? ||
Matches any single character in string. |
[chars] ||
Matches any character in the set given |
by chars. If a sequence of the form x-y |
appears in chars, then any character |
between x and y, inclusive, will match. |
Page 23 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
\x ||
Matches the single character x. This |
provides a way of avoiding the special |
interpretation of the characters *?[]\ |
in pattern. |
Unique abbreviations for option are acceptable.
time command [count]
This command will call the Tcl interpreter count times
to execute command (or once if count isn't specified).
It will then return a string of the form
503 microseconds per iteration
which indicates the average amount of time required per
iteration, in microseconds. Time is measured in
elapsed time, not CPU time.
uplevel level command command ...
All of the command arguments are concatenated as if |
they had been passed to concat and the result is |
evaluated in the variable context indicated by level. |
Uplevel returns the result of that evaluation. If |
level is zero, then top-level context is used (all |
variable names refer to global variables). If level is |
a positive number, then it is treated as a stack level: |
1 refers to the topmost active procedure, 2 to the |
procedure it called, and so on. If level is a negative |
number, then it is treated as a level relative to the |
current procedure. For example, a level of -1 refers |
to the procedure that called the one invoking the |
uplevel command (which is top-level if the procedure |
invoking uplevel is at level 1). The uplevel command |
causes the invoking procedure to disappear from the |
procedure calling stack while the command is being |
executed. For example, suppose procedure x is at level |
3 and invokes the command |
uplevel -1 {set a 43; c} |
where c is another Tcl procedure. The set command will |
modify variable a in x's caller, and c will execute at |
level 3, as if called from x's caller. If it in turn |
executes the command |
uplevel -1 {set a 42} |
then the set command will modify the same variable a in |
x's caller: the procedure x does not appear to be on |
the call stack when c is executing. The command ``info |
level'' may be used to obtain the level of the current |
Page 24 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
procedure. Uplevel makes it possible to implement new |
control constructs as Tcl procedures (for example, |
uplevel could be used to implement the while construct |
as a Tcl procedure).
BUILT-IN VARIABLES |
The following global variables are created and managed |
automatically by the Tcl library. These variables should |
normally be treated as read-only by application-specific |
code and by users. |
errorInfo ||
After an error has occurred, this string will contain |
two or more lines identifying the Tcl commands and |
procedures that were being executed when the most |
recent error occurred.
AUTHOR
John Ousterhout, University of California at Berkeley
(ouster@sprite.berkeley.edu)
Page 25 (printed 2/26/90)
Tcl_Backslash(tcl) AMIGA 1.3 Tcl_Backslash(tcl)
NAME
Tcl_Backslash - parse a backslash sequence
SYNOPSIS
#include <tcl.h>
char
Tcl_Backslash(src, countPtr)
ARGUMENTS
char*src(in)
Pointer to a string starting with a backslash.
int*countPtr(out)
If countPtr isn't NULL, *countPtr gets filled in with number
of characters in the backslash sequence, including the
backslash character.
DESCRIPTION
This is a utility procedure used by several of the Tcl
commands. It parses a backslash sequence and returns the
single character corresponding to the sequence.
Tcl_Backslash modifies *countPtr to contain the number of
characters in the backslash sequence. If src doesn't point
to a backslash sequence understood by Tcl, then
Tcl_Backslash returns a backslash as its result and
*countPtr gets set to 1 (in this case the backslash
character should not get any special treatment).
See the Tcl manual entry for information on the valid
backslash sequences. All of the sequences described in the
Tcl manual entry are supported by Tcl_Backslash except |
backslash-newline, which is not understood.
KEYWORDS
backslash, parse
--
-- uunet!sugar!karl "As long as there is a legion of superheros, all else
-- can surely be made right." -- Sensor Girl
-- Usenet access: (713) 438-5018