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 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. 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. Also, command abbreviations are disallowed if the global variable noAbbrev has the value 1.

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 DOUBLE-QUOTES

Normally each argument field ends at the next white space, but double-quotes may be used to create arguments with embedded space. If an argument field begins with a double-quote, then the argument isn't terminated by white space (including newlines) or a semi-colon (see below for information on semi-colons); instead it ends at the next double-quote character. The double-quotes are not included in the resulting argument. For example, the command set a "This is a single argument" will pass two arguments to set: a and This is a single argument. Within double-quotes, command substitutions, variable substitutions, and backslash substitutions still occur, as described below. If the first character of a command field is not a quote, then quotes receive no special interpretation in the parsing of that field.

GROUPING ARGUMENTS WITH BRACES

Curly braces may also be used for grouping arguments. They are similar to quotes except for two differences. First, they nest; this makes them easier to use for complicated arguments like nested Tcl command strings. Second, the substitutions described below for commands, variables, and backslashes do not occur in arguments enclosed in braces, so braces can be used to prevent substitutions where they are undesirable. If an argument field begins with a left brace, then the argument ends at the matching right brace. Tcl will strip off the outermost layer of braces and pass the information between the braces to the command without any further modification. For example, 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 or quotes are in effect, the matching brace or quote 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 brace or quote. 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.

If the first character of a command field is not 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 a field of a command, then command substitution occurs (except for fields enclosed in braces). 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 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.

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. Semi-colons are not treated as command separators if they appear within curly braces or double-quotes.

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 (0x8).

\e  Escape (0x1b).

\n  Newline (0xa).

\r  Carriage-return (0xd).

\t  Tab (0x9).

\{  Left brace (``{'').

\}  Right brace (``}'').

\[  Open bracket (``['').

\]  Close bracket (``]'').

\$  Dollar sign (``$'').

\<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 (``\'').

\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 is probably easiest to use the format command along with command substitution.

COMMAND SUMMARY

[1] A command is just a string.

[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] Double-quotes allow white space and semi-colons to appear within a single argument. Command substitution, variable substitution, and backslash substitution still occur inside quotes.

[6] 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.

[7] If a field doesn't begin with a brace 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:

-  ~  !
    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.

x?y:z
    If-then-else, as in C. If x evaluates to non-zero, then the result is the value of y. Otherwise the result is the value of z.

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 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} (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 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 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 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 [info]
    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. If the info argument is provided, it is used to initialize the global variable errorInfo. ErrorInfo is used to accumulate a stack trace of what was in progress when an error occurred; as nested commands unwind, the Tcl interpreter adds information to errorInfo. If the info argument is present, it is used to initialize the errorInfo variable, and the first increment of unwind information will not be added by the Tcl interpreter. In other words, the command containing the error command will not appear in the errorInfo variable; in its place will be info. This feature is most useful in conjunction with the catch command: if a caught error cannot be handled successfully, info can be used to return a stack trace reflecting the original point of occurrence of the error:
    catch {...} errMsg set savedInfo $errorInfo ... error $errMsg $savedInfo

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. Exec performs tilde-substitution on command, if appropriate, then 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 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; if it starts with a tilde, then tilde substitution is done before executing the command (see the manual entry for Tcl_TildeSubst for details). 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.

    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 start. 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 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 [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.

history [option [arg arg ...]
    Note: this command may not be available in all Tcl-based applications. Typically, only those that receive command input in a typescript form will support history. The history command performs one of several operations related to recently-executed commands recorded in a history list. Each of these recorded commands is referred to as an ``event''. When specifying an event to the history command, the following forms may be used:

    [1] A number: if positive, it refers to the event with that number (all events are numbered starting at 1). If the number is negative, it selects an event relative to the current event (-1 refers to the previous event, -2 to the one before that, and so on).

    [2] A string: selects the most recent event that matches the string. An event is considered to match the string either if the string is the same as the first characters of the event, or if the string matches the event in the sense of the string match command.

    The history command can take any of the following forms:

    history
        Re-execute the most recent command in the history list and return its result. This command has the same effect as history redo -1.

    history add command [exec]
        Add the command argument to the history list as a new event. If exec is specified (or abbreviated) then the command is also executed and its result is returned. If exec isn't specified then an empty string is returned as result.

    history change newValue [event]
        Replace the value recorded for an event with newValue. Event specifies the event to replace, and defaults to the current event (not event -1). This command is intended for use in commands that implement new forms of history substitution and wish to replace the current event (which invokes the substitution) with the command created through substitution. The return value is an empty string.

    history event [event]
        Returns the value of the event given by event. Event defaults to -1. This command causes history revision to occur: see below for details.

    history info [count]
        Returns a formatted string (intended for humans to read) giving the event number and contents for each of the events in the history list except the current event. If count is specified then only the most recent count events are returned.

    history keep count
        This command may be used to change the size of the history list to count events. Initially, 20 events are retained in the history list. This command returns an empty string.

    history nextid
        Returns the number of the next event to be recorded in the history list. It is useful for things like printing the event number in command-line prompts.

    history redo [event]
        Re-execute the command indicated by event and return its result. Event defaults to -1. This command results in history revision: see below for details.

    history substitute old new [event]
        Retrieve the command given by event (-1 by default), replace any occurences of old by new in the command (only simple character equality is supported; no wild cards), execute the resulting command, and return the result of that execution. This command results in history revision: see below for details.

    history words selector [event]
        Retrieve from the command given by event (-1 by default) the words given by selector, and return those words in a string separated by spaces. The selector argument has three forms. If it is a single number then it selects the word given by that number (0 for the command name, 1 for its first argument, and so on). If it consists of two numbers separated by a dash, then it selects all the arguments between those two. Otherwise seletor is treated as a pattern; all words matching that pattern (in the sense of string match) are returned. In the numeric forms $ may be used to select the last word of a command. For example, suppose the most recent command in the history list is
        format {%s is %d years old} Alice [expr $ageInMonths/12] Below are some history commands and the results they would produce:
        history words $	[expr $ageInMonths*12]
        history words 1-2	{%s is %d years  old} Alice
        history words *a*o*	{%s is %d years old} [expr $ageInMonths*12]
        History words results in history revision:  see below for details.
    The history options redo, substitute, and words result
    in ``history revision''.  If a history command with one of these options
    can be traced directly to the current history event (e.g. the current
    event invoked the history command directly or through command
    substitution), then the current event is modified to eliminate the
    history command and replace it with the result of the history
    substitution.  For example, suppose that the most recent command in
    the history list is
    set a [expr $b+2]
    and suppose that the next command invoked is one of the ones on
    the left side of the table below.  The command actually recorded in
    the history event will be the corresponding one on the right side
    of the table.
    history	set a [expr $b+2]
    history s a b	set b [expr $b+2]
    set c [history w 2]	set c [expr $b+2]
    History revision only occurs for history commands that can be directly
    traced to the current event.  For example, the command
    eval history will not result in history revision, because
    the history command is invoked indirectly by eval.  If history
    revision is desired in cases like this, it can be achieved by
    requesting it explicitly with history change.

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 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 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 exists varName
        Returns 1 if the variable named varName exists in the
        current context (either as a global or local variable), returns 0
        otherwise.

    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
        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.  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
    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 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.
    If fileName starts with a tilde, then it is tilde-substituted
    as described in the Tcl_TildeSubst manual entry.

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.
            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;  the result is then evaluated in the
    variable context indicated by level.  Uplevel returns
    the result of that evaluation.  If level is an integer, then
    it gives a distance (up the procedure calling stack) to move before
    executing the command.  If level consists of # followed by
    a number then the number gives an absolute level number.  If level
    is omitted then it defaults to 1.  Level cannot be
    defaulted if the first command argument starts with a digit or #.
    For example, suppose that procedure a was invoked
    from top-level, and that it called b, and that b called c.
    Suppose that c invokes the uplevel command.  If level
    is 1 or #2  or omitted, then the command will be executed
    in the variable context of b.  If level is 2 or #1
    then the command will be executed in the variable context of a.
    If level is 3 or #0 then the command will be executed
    at top-level (only global variables will be visible).
    The uplevel command causes the invoking procedure to disappear
    from the procedure calling stack while the command is being executed.
    In the above example, suppose c invokes the command
    uplevel 1 {set x 43; d}
    where c is another Tcl procedure.  The set command will
    modify the variable x in b's context, and d will execute
    at level 3, as if called from b.  If it in turn executes
    the command
    uplevel {set x 42}
    then the set command will modify the same variable x in b's
    context:  the procedure c does not appear to be on the call stack
    when d is executing.  The command ``info level'' may
    be used to obtain the level of the current 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.

noAbbrev
    If this variable has the value 1 then abbreviations are disallowed for command names. If the variable doesn't exist or has a value other than 1 then abbreviations are permitted.

AUTHOR
John Ousterhout, University of California at Berkeley (ouster@sprite.berkeley.edu)