 |
 |
Tcl for Embedded Applications |
 |
|||||||
|
|
Tcl for Embedded Applications |
|
|||||||
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 can be used as a common language for communicating between applications. Inter-application communication is not built into the Tcl core described here, but various add-on libraries, such as the Tk toolkit, allow applications to issue commands to each other. This makes it possible for applications to work together in much more powerful ways than was previously possible.
This manual page focuses 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.
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.
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.
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
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.set a 22
Command names should normally be typed completely (e.g. no abbreviations). However, if the Tcl interpreter cannot locate a command it invokes a special command named unknown which attempts to find or create the command. For example, at many sites unknown will search through library directories for the desired command and create it as a Tcl procedure if it is found. The unknown command often provides automatic completion of abbreviated commands, but usually only for commands that were typed interactively. 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.
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. When comments are embedded inside nested commands (e.g. fields enclosed in braces) they must have properly-matched braces (this is necessary because when Tcl parses the top-level command it doesn't yet know that the nested field will be used as a command so it cannot process the nested comment character as a comment).
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
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.set a "This is a single argument"
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}}
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
}
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).
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
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 commandset a [set b]
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 commandset a foo
is equivalent to the commandset a xyz[set b].[set c]
A bracketed command may contain multiple commands separated by newlines or semi-colons in the usual fashion. In this case the value of the last command is used for substitution. For example, the commandset a xyzfoo.gorp
is equivalent to the commandset a x[set b 22 expr $b+2]x
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.set a x24x
The dollar sign ($) may be used as a special shorthand form for substituting variable values. 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. For example, if variable foo has the value test, then the command
is equivalent to the commandset a $foo.c
set a test.c
There are two special forms for variable substitution. If the next character after the name of the variable is an open parenthesis, then the variable is assumed to be an array name, and all of the characters between the open parenthesis and the next close parenthesis are taken as an index into the array. Command substitutions and variable substitutions are performed on the information between the parentheses before it is used as an index. For example, if the variable x is an array with one element named first and value 87 and another element named 14 and value more, then the command
is equivalent to the commandset a xyz$x(first)zyx
If the variable index has the value 14, then the commandset a xyz87zyx
is equivalent to the commandset a xyz$x($index)zyx
For more information on arrays, see VARIABLES AND ARRAYS below.set a xyzmorezyx
The second special form for variables occurs when the dollar sign is followed by an open curly brace. In this case the variable name consists of all the characters up to the next curly brace. Array references are not possible in this form: the name between braces is assumed to refer to a scalar variable. For example, if variable foo has the value test, then the command
set a abc${foo}bar
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.set a abctestbar
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.
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.
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:
For example, in the command
set a \{x\[\ yz\141
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
If an argument is enclosed in braces, then backslash sequences inside the argument are parsed but no substitution occurs (except for backslash-newline): 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}
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.
The second major interpretation applied to strings in Tcl is as expressions. Several commands, such as expr, for, and if, treat one or more of their arguments as expressions and call the Tcl expression processors (Tcl_ExprLong, Tcl_ExprBoolean, etc.) to evaluate them. The operators permitted in Tcl expressions are a subset of the operators permitted in C expressions, and they have the same meaning and precedence as the corresponding C operators. Expressions almost always yield numeric results (integer or floating-point values). For example, the expression
evaluates to 14.2. Tcl expressions differ from C expressions in the way that operands are specified, and in that Tcl expressions support non-numeric operands and string comparisons.8.2 + 6
A Tcl expression consists of a combination of operands, operators, and parentheses. White space may be used between the operands and operators and parentheses; it is ignored by the expression processor. Where possible, operands are interpreted as integer values. Integer values may be specified in decimal (the normal case), in octal (if the first character of the operand is 0), or in hexadecimal (if the first two characters of the operand are 0x). If an operand does not have one of the integer formats given above, then it is treated as a floating-point number if that is possible. Floating-point numbers may be specified in any of the ways accepted by an ANSI-compliant C compiler (except that the ``f'', ``F'', ``l'', and ``L'' suffixes will not be permitted in most installations). For example, all of the following are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16. If no numeric interpretation is possible, then an operand is left as a string (and only a limited set of operators may be applied to it).
Operands may be specified in any of the following ways:
Where substitutions occur above (e.g. inside quoted strings), they are performed by the expression processor. However, an additional layer of substitution may already have been performed by the command parser before the expression processor was called. As discussed below, it is usually best to enclose expressions in braces to prevent the command parser from performing substitutions on the contents.
For some examples of simple expressions, suppose the variable a has the value 3 and the variable b has the value 6. Then the expression on the left side of each of the lines below will evaluate to the value on the right side of the line:
3.1 + $a 6.1
2 + "$a.$b" 5.6
4*[llength "6 2"] 8
{word one} < "word $a" 0
The valid operators are listed below, grouped in decreasing order of precedence:
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
evaluates to 0.4*2 < 7
The &&, ||, and ?: operators have ``lazy evaluation'', just as in C, which means that operands are not evaluated if they are not needed to determine the outcome. For example, in
only one of [a] or [b] will actually be evaluated, depending on the value of $v.$v ? [a] : [b]
All internal computations involving integers are done with the C type long, and all internal computations involving floating-point are done with the C type double. When converting a string to floating-point, exponent overflow is detected and results in a Tcl error. For conversion to integer from string, detection of overflow depends on the behavior of some routines in the local C library, so it should be regarded as unreliable. In any case, overflow and underflow are generally not detected reliably for intermediate results.
Conversion among internal representations for integer, floating-point, and string operands is done automatically as needed. For arithmetic computations, integers are used until some floating-point number is introduced, after which floating-point is used. For example,
yields the result 1, while5 / 4
both yield the result 1.25.5 / 4.0 5 / ( [string length "abcd"] + 0.0 )
String values may be used as operands of the comparison operators, although the expression evaluator tries to do comparisons as integer or floating-point when it can. If one of the operands of a comparison is a string and the other has a numeric value, the numeric operand is converted back to a string using the C sprintf format specifier %d for integers and %g for floating-point values. For example, the expressions
both evaluate to 1. The first comparison is done using integer comparison, and the second is done using string comparison after the second operand is converted to the string ``18''."0x03" > "2" "0y" < "0x12"
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
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 commandexpr $a + $b
for {set i 1} $i<=10 {incr i} {...} *** WRONG ***
for {set i 1} {$i<=10} {incr i} {...} *** RIGHT ***
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
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 quotes and backslashes are the same for lists as for commands. For example, the stringAl Sue Anne John
a b\ c {d e {f g h}}
d e {f g h}
The Tcl commands concat, foreach, lappend, lindex, linsert, list, llength, lrange, lreplace, lsearch, and lsort allow you to build lists, extract elements from them, search them, and perform other list-related functions.
Tcl provides two commands that support string matching using egrep-style regular expressions: regexp and regsub. Regular expressions are implemented using Henry Spencer's package, and the description of regular expressions below is copied verbatim from his manual entry.
A regular expression is zero or more branches, separated by ``|''. It matches anything that matches one of the branches.
A branch is zero or more pieces, concatenated. It matches a match for the first, followed by a match for the second, etc.
A piece is an atom possibly followed by ``*'', ``+'', or ``?''. An atom followed by ``*'' matches a sequence of 0 or more matches of the atom. An atom followed by ``+'' matches a sequence of 1 or more matches of the atom. An atom followed by ``?'' matches a match of the atom, or the null string.
An atom is a regular expression in parentheses (matching a match for the regular expression), a range (see below), ``.'' (matching any single character), ``^'' (matching the null string at the beginning of the input string), ``$'' (matching the null string at the end of the input string), a ``\'' followed by a single character (matching that character), or a single character with no other significance (matching that character).
A range is a sequence of characters enclosed in ``[]''. It normally matches any single character from the sequence. If the sequence begins with ``^'', it matches any single character not from the rest of the sequence. If two characters in the sequence are separated by ``-'', this is shorthand for the full list of ASCII characters between them (e.g. ``[0-9]'' matches any decimal digit). To include a literal ``]'' in the sequence, make it the first character (following a possible ``^''). To include a literal ``-'', make it the first or last character.
If a regular expression could match two different parts of a string, it will match the one which begins earliest. If both begin in the same place but match different lengths, or match the same length in different ways, life gets messier, as follows.
In general, the possibilities in a list of branches are considered in left-to-right order, the possibilities for ``*'', ``+'', and ``?'' are considered longest-first, nested constructs are considered from the outermost in, and concatenated constructs are considered leftmost-first. The match that will be chosen is the one that uses the earliest possibility in the first choice that has to be made. If there is more than one choice, the next will be made in the same manner (earliest possibility) subject to the decision on the first choice. And so forth.
For example, ``(ab|a)b*c'' could match ``abc'' in one of two ways. The first choice is between ``ab'' and ``a''; since ``ab'' is earlier, and does lead to a successful overall match, it is chosen. Since the ``b'' is already spoken for, the ``b*'' must match its last possibilitythe empty stringsince it must respect the earlier choice.
In the particular case where no ``|''s are present and there is only one ``*'', ``+'', or ``?'', the net effect is that the longest possible match will be chosen. So ``ab*'', presented with ``xabbbby'', will match ``abbbb''. Note that if ``ab*'' is tried against ``xabyabbbz'', it will match ``ab'' just after ``x'', due to the begins-earliest rule. (In effect, the decision on where to start the match is the first choice to be made, hence subsequent choices must respect it even if this leads them to less-preferred alternatives.)
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:
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.
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.
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.
Tcl supports two types of variables: scalars and arrays. A scalar variable has a single value, whereas an array variable can have any number of elements, each with a name (called its ``index'') and a value. Array indexes may be arbitrary strings; they need not be numeric. Parentheses are used refer to array elements in Tcl commands. For example, the command
will modify the element of x whose index is first so that its new value is 44. Two-dimensional arrays can be simulated in Tcl by using indexes that contain multiple concatenated values. For example, the commandsset x(first) 44
set the elements of a whose indexes are 2,3 and 3,6.set a(2,3) 1 set a(3,6) 2
In general, array elements may be used anywhere in Tcl that scalar variables may be used. If an array is defined with a particular name, then there may not be a scalar variable with the same name. Similarly, if there is a scalar variable with a particular name then it is not possible to make array references to the variable. To convert a scalar variable to an array or vice versa, remove the existing variable with the unset command.
The array command provides several features for dealing with arrays, such as querying the names of all the elements of the array and searching through the array one element at a time.
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).
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, words in boldface are literals that you type verbatim to Tcl. Words in italics are meta-symbols; they serve as names for any of a range of values that you can type. Optional arguments or groups of arguments are indicated by enclosing them in question-marks. Ellipses (``...'') indicate that any number of additional arguments or groups of arguments may appear, in the same format as the preceding argument(s).
Two syntaxes are provided. The first uses a separate argument for each of the patterns and commands; this form is convenient if substitutions are desired on some of the patterns or commands. The second form places all of the patterns and commands together into a single argument; the argument must have proper list structure, with the elements of the list being the patterns and commands. The second form makes it easy to construct multi-line case commands, since the braces around the whole list make it unnecessary to include a backslash at the end of each line. Since the patList arguments are in braces in the second form, no command or variable substitutions are performed on them; this makes the behavior of the second form different than the first form in some cases.
Below are some examples of case commands:
case abc in {a b} {format 1} default {format 2} a* {format 3}
case a in {
{a b} {format 1}
default {format 2}
a* {format 3}
}
case xyz {
{a b}
{format 1}
default
{format 2}
a*
{format 3}
}
concat a b {c d e} {f {g h}}
a b c d e f {g h}
If the info argument is provided and is non-empty, 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 errorInfo 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 errorInfo; 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
If the code argument is present, then its value is stored in the errorCode global variable. This variable is intended to hold a machine-readable description of the error in cases where such information is available; see the section BUILT-IN VARIABLES below for information on the proper format for the variable. If the code argument is not present, then errorCode is automatically reset to ``NONE'' by the Tcl interpreter as part of processing the error generated by the command.
Under normal conditions the result of the exec command consists of the standard output produced by the last command in the pipeline. If any of the commands in the pipeline exit abnormally or are killed or suspended, then exec will return an error and the error message will include the pipeline's output followed by error messages describing the abnormal terminations; the errorCode variable will contain additional information about the last abnormal termination encountered. If any of the commands writes to its standard error file, then exec will return an error, and the error message will include the pipeline's output, followed by messages about abnormal terminations (if any), followed by the standard error output.
If the last character of the result or error message is a newline then that character is deleted from the result or error message for consistency with normal Tcl return values.
If an arg has the value ``>'' then the following argument is taken as the name of a file and the standard output of the last command in the pipeline is redirected to the file. In this situation exec will normally return an empty string.
If an arg has the value ``<'' then the following argument is taken as the name of a file to use for standard input to the first command in the pipeline. If an argument has the value ``<<'' then the following argument is taken as an immediate value to be passed to the first command as standard input. If there is no ``<'' or ``<<'' argument then the standard input for the first command in the pipeline is taken from the application's current standard input.
If the last arg is ``&'' then the command will be executed in background. In this case the standard output from the last command in the pipeline will go to the application's standard output unless redirected in the command, and error output from all the commands in the pipeline will go to the application's standard error file.
Each arg becomes one word for a command, except for ``|'', ``<'', ``<<'', ``>'', and ``&'' arguments, and the arguments that follow ``<'', ``<<'', and ``>''. The first word in each command is taken as the command name; tilde-substitution is performed on it, and the directories in the PATH environment variable are searched for an executable by the given name. No ``glob'' expansion or other shell-like substitutions are performed on the arguments to commands.
Conversion of the manual page failed. We are looking into it. In the meantime, check out the printable PDF version elsewhere on the site.