Tool Command Language: 5.2 Commands: Built-in Commands

GEOS SDK TechDocs |

5.1 Notation | Next:

6 Coding

The built-in Tcl commands are as follows:

bc

bc list <proc>
bc disasm <proc>
bc compile <proc>
bc fcompile <file> [<nohelp>]
bc fload <file>
bc fdisasm <file>
bc debug [1|0]

Examples:

"bc compile poof": Compiles the body of the procedure "poof" and replaces the existing procedure with its compiled form.
"bc fcomp bptutils.tcl": Creates the file "bptutils.tlc" that contains a stream of compiled Tcl that will do exactly what sourcing bptutils.tcl does, except the resulting procedures will be compiled Tcl, not interpreted Tcl.
"bc fload bptutils.tlc": Loads a file containing a stream of compiled Tcl code.

The "bc" command allows you to create and examine compiled Tcl code. Compiled Tcl is not nearly as readable or changeable as interpreted Tcl code, but it's 30-50% faster.

The "list" subcommand doesn't work.

See Also: source.

break

break

Examples:

"break": Break out of the current loop.

Breaks out of the current loop or the current nested interpreter.

Only the closest-enclosing loop can be exited via this command.
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.
If you've entered a nested interpreter, e.g. by calling a function in the patient, use this to exit the interpreter and restore the registers to what they were before you made the call.

See Also: continue, for.

case

case <string> [in] [<pat> <body>]+

Examples:

"[case $c in
{[0-9]} {
# do something with digit
}
default {
# do something with non-digit
}
]": Do one of two things depending on whether the character in $c is a digit.

Perform one of a set of actions based on whether a string matches one or more patterns.

Compares each of the <pattern> arguments to the given <string>, executing <body> following the first <pattern> to match. <pattern> uses shell wildcard characters as for the string match command, but may also contain alternatives, which are separated by a vertical bar, thus allowing a <body> to be executed under one of several circumstances. In addition, if one <pattern> (or element thereof) is the string default, the associated <body> will be executed if none of the other patterns matches. For example, the following:

[case $test in
 a|b {return 1}
 {default|[DE]a*} {return 0}
 ?c {return -1}]

will return 1 if variable test contains a or b , -1 if it contains a two-letter string whose second letter is c , and 0 in all other cases, including the ones where test 's first two letters are either Da or Ea .

Each <pat> argument is a list of patterns of the form described for the "string match" command.
Each <pat> argument must be accompanied by a <body> to execute.
If a <pat> contains the special pattern "default," the associated <body> will be executed if no other pattern matches. The difference between "default" and "*" is a pattern of "*" causes the <body> to be executed regardless of the patterns in the remaining <pat> arguments, while "default" postpones the decision until all the remaining patterns have been checked.
You can give the literal "in" argument if you wish to enhance the readability of your code.

See Also: string, if.

catch

catch <command> [<varName>]

Executes a command, retaining control even if the command generates an error (which would otherwise cause execution to unwind completely).

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 zero (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. 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).
This returns an integer that indicates how <command> completed:

0: Completed successfully; $<varName> contains the result of the command.
1: Generated an error; $<varName> contains the error message.
2: Executed "return"; $<varName> contains the argument passed to "return."
3: Executed "break"; $<varName> is empty.
4: Executed "continue"; $<varName> is empty.

See Also: protect.

concat

concat <arg1>+

Examples:

"concat $list1 $list2": Merges the lists in $list1 and $list2 into a single list whose elements are the elements of the two lists.

Concatenates multiple list arguments into a single list.

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.

There is a sometimes-subtle difference between this in the "list" command: Given two lists, "concat" will form a list whose n elements are the combined elements of the two component lists, while "list" will form a list whose 2 elements are the two lists. For example,

 concat a b {c d e} {f {g h}}

yields the list

a b c d e f {g h}

but

list a b {c d e} {f {g h}}

yields

a b {c d e} {f {g h}}

See Also: list.

continue

continue

Examples:

"continue": Return to the top of the enclosing loop.

Skips the rest of the commands in the current loop iteration, continuing at the top of the loop.

Only the closest-enclosing loop can be continued via this command.
The <next> clause of the "for" command is not part of the current iteration, i.e. it will be executed even if you execute this command.
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.

See Also: break, for.

defsubr

defsubr <name> <args> <body>

Examples:

"defsubr poof {arg1 args} {return [list $arg1 $args]}": Defines a procedure poof that takes 1 or more arguments and merges them into a list of two elements.

This is the same as the "proc" command, except the new procedure's name may not be abbreviated when it is invoked.

Refer to the documentation for proc for more information.

error

error <message>

Examples:

"error {invalid argument}": Generates an error, giving the not-so-helpful message "invalid argument" to the caller's caller.

Unless one of the procedures in the call stack has executed a "catch" command, all procedures on the stack will be terminated with <message> (and an indication of an error) being the result of the final one so terminated.
Any commands protected by the "protect" command will be executed.

See Also: return, catch.

eval

eval <body>

Examples:

"eval $mangled_command": Evaluate the command contained in $mangled_command and return its result.

Evaluates the passed string as a command and returns the result of that evaluation.

eval takes one argument, which is a Tcl command (or collection of Tcl commands separated by newlines in the usual way). eval evaluates <body> by passing it to the Tcl interpreter recursively, and returns the result of the last command. If an error occurs inside <body> then eval returns that error.
This command is useful when one needs to cobble together a command from arguments or what have you. For example, if one of your arguments is a list of arguments to pass to another command, the only way to accomplish that is to say something like "eval [concat random-command $args]", which will form a list whose first element is the command to be executed, and whose remaining elements are the arguments for the command. "eval" will then execute that list properly.
If the executed command generates an error, "eval" will propagate that error just like any other command.

See Also: concat, list.

expr

expr <expression> [float]

Examples:

"expr 36*25": Multiplies 36 by 25 and returns the result.
"expr $i/6 float": Divides the number in $i by 6 using floating- point arithmetic; the result is a real number.
"expr 7.2*10 float": Multiplies 7.2 by 10. Note that though the answer (72) is an integer, we need to pass the "float" keyword to make sure that the expression is interpreted correctly.

Evaluates an arithmetic expression and returns its value.

Most C operators are supported with the standard operator precedence.
If you use a Tcl variable in the expression, the variable may only contain a number; it may not contain an expression.
The result of any Tcl command, in square brackets ("[ ]") must be a number; it may not be an expression.
All the C and Esp radix specifiers are allowed.
Bitwise and boolean operators (!, &, ^, |, &&, ||, >>, <<, ~) are not permitted when the expression is being evaluated using floating-point arithmetic.

file

file dirname <name>
file exists <name>
file extension <name>
file isdirectory <name>
file isfile <name>
file readable <name>
file rootname <name>
file tail <name>
file writable <name>
file match <pattern>
file newer <name1> <name2>

Examples:

"file match /pcgeos/tcl/*.tcl": Looks for all files/directories in /pcgeos/tcl whose name ends with ".tcl".
"file isdir $path": See if the path stored in $path refers to a directory.
"file tail $path": Return the final component of the path stored in $path

Performs various checks and manipulations of file and directory names.

The forward slash is the path separator for this command.
The predicate subcommands (executable, exists, isdirectory, isfile, owned, readable, and writable) all return 1 if the path meets the requirements, or 0 if it doesn't.
"file match" takes a pattern made from the same components as are described for "string match". It is not the same as the standard DOS wildcarding, where `.' serves to separate the root pattern from the extension pattern. For this command "*.*" would match only files that actually have an extension.
"file dirname" returns the directory portion of name . If name has no directory portion, this returns "."
"file rootname" returns all leading directory components of name , plus the text before its extension, without the "." that separates the name from the extension.
"file tail" returns all of the characters in name after the final forward slash, or name if it contains no forward slashes.
"file newer" returns 1 if name1 was modified after name2 . It returns 0 otherwise.

See Also: string.

for

for <start> <test> <next> <body>

Examples:

"for {var i 0} {$i < 10} {var i [expr $i+1]} {echo $i}": Prints the numbers from 0 to 9.

This is Tcl's main looping construct. It functions similarly to the "for" in C.

<start> is a Tcl command string (which may involve multiple commands over multiple lines, if desired) that is executed once at the very start of the loop. It is always executed. If it returns an error, or contains a "break" command, no part of the loop will execute.
<test> is an arithmetic expression that is passed to the "expr" command. If the result is non-zero, the <body> is executed.
<next> is a Tcl command string (which may involve multiple commands over multiple lines, if desired) that is executed at the end of each iteration before <test> is evaluated again. If it returns an error, or contains a "break" command, no part of the loop will execute.
You can exit the loop prematurely by executing the "break" command in any of the three Tcl command strings (<start>, <next>, or <body>).
So long as there's no error, "for" always returns the empty string as its result.
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>, then the for command will return immediately. The operation of break and continue are similar to the corresponding statements in C.

See Also: foreach, break, continue.

foreach

foreach <varname> <list> <body>

Examples:

"foreach el $list {echo poof = $el}": Prints each element of the list $list preceded by the profound words "poof = "

This is a looping construct to easily iterate over all the elements of a list.

<body> is evaluated once for each element in <list>. Before each evaluation, the next element is placed in the variable <varName>.
You can exit the loop prematurely by executing the "break" command.
As long as there's no error, "foreach" always returns the empty string.
The break and continue statements may be invoked inside <body>, with the same effect as in the for command.

format

format <formatString> [<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 procedure in a C manual for more 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.

global

global <varname>+

Examples:

"global attached": When next the "attached" variable is fetched or set, get it from the global scope, not the local one.

Declares the given variables to be from the global scope.

For the duration of the procedure in which this command is executed (but not in any procedure it invokes), the global variable of the given name will be used when the variable is fetched or set.
If no global variable of the given name exists, the setting of that variable will define it in the global scope.
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 <varname> values will be bound to a global variable instead of a local one.

See Also: var.

if

if <test> [then] <trueBody> 

             (elif <test> [(then)] <trueBody>)* 

             [[else] <falseBody>]

Examples:

"if {$v > 3} {echo yes} {echo no}": Prints "yes" if $v is greater than 3, else it prints "no".
"if {$v > 3} then {echo yes} else {echo no}": Ditto.
"if {$v > 3} then {echo yes} elif {$v == 3} {echo maybe} else {echo no}"

This is Tcl's conditional, as you'd expect from its name.

The "then" and "else" keywords are optional, intended to delineate the different sections of the command and make the whole easier to read.
The "elif" keyword is mandatory if you want to perform additional tests.
The <expr> arguments are normal Tcl expressions. If the result is non-zero, the appropriate <truebody> is executed. If none of the <expr> arguments evaluates non-zero, <falsebody> is executed.
If a <truebody> is empty and the test evaluated non-zero, "if" will return the result of the test. Otherwise "if" returns the result from last command executed in whichever <truebody> or <falsebody> argument was finally executed. It returns an empty string if no <expr> evaluated non-zero and no <falsebody> was given.
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. <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. Alternative test conditions can be added by adding <elif> arguments.

See Also: expr.

index

index <value> <index> [chars]

Examples:

"index {a b c} 1": Extracts "b" from the list.
"index {hi mom} 3 char": Extracts "m" from the string.

"index" is used to retrieve a single element or character from a list or string.

Elements and characters are numbered from 0.
If you request an element or character from beyond the end of the <list> or <string>, you'll receive an empty list or string as a result.
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 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).

info

info args <procname> [<pattern>]
info arglist <procname>
info body <procname>
info cmdcount
info commands [<pattern>]
info default <procname> <arg> <varname>
info globals [<pattern>]
info locals [<pattern>]
info procs [<pattern>]
info vars [<pattern>]

Examples:

"info args fmtval": Retrieves the names of the arguments for the "fmtval" command so you know in what order to pass things.
"info body print-frame": Retrieves the string that is the body of the "print-frame" Tcl procedure.
"info commands reg ": Retrieves a list of commands whose names contain the string "reg".

This command provides information about a number of data structures maintained by the Tcl interpreter.

All the <pattern> arguments are standard wildcard patterns as are used for the "string match" and "case" commands. See "string" for a description of these patterns.
"info args" returns the complete list of arguments for a Tcl procedure, or only those matching the <pattern>, if one is given. The arguments are returned in the order in which they must be passed to the procedure.
"info arglist" returns the complete list of arguments, and their default values, for a Tcl procedure.
"info body" returns the command string that is the body of the given Tcl procedure.
"info cmdcount" returns the total number of commands the Tcl interpreter has executed in its lifetime.
"info commands" returns the list of all known commands, either built-in or as Tcl procedures, known to the interpreter. You may also specify a pattern to restrict the commands to those whose names match the pattern.
"info default" returns non-zero if the argument named <arg> for the given Tcl procedure has a default value. If it does, that default value is stored in the variable whose name is <varname>.
"info globals" returns the list of all global variables accessible within the current variable scope (i.e. only those that have been declared global with the "global" command, unless you issue this command from the command-line, which is at the global scope), or those that match the given pattern.
"info locals" returns the list of all local variables, or those that match the given pattern.
"info procs" returns the list of all known Tcl procedures, or those that match the given pattern.
"info vars" returns the list of all known Tcl variables in the current scope, either local or global. You may also give a pattern to restrict the list to only those that match.

See Also: proc, defcmd, defcommand, defsubr.

length

length <value> [<chars>]

Examples:

"length $args": Returns the number of elements in the list $args
"length $str char": Returns the number of characters in the string $str

Determines the number of characters in a string, or elements in a list.

If (chars) isn't specified, length 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).

See Also: index, range.

list

list <arg>+

Examples:

"list a b {c d e} {f {g h}}": Returns the list "a b {c d e} {f {g h}}"

Joins any number of arguments into a single list, applying quoting braces and backslashes as necessary to form a valid Tcl list.

If you use the "index" command on the result, the 0th element will be the first argument that was passed, the 1st element will be the second argument that was passed, etc.
The difference between "list" and "concat" is subtle. Given the above arguments, "concat" would return "a b c d e f {g h}".
This command returns a list comprised of all the <args>. It also adds braces and backslashes 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.

See Also: concat, index, range.

proc

proc <name> <args> <body>

Examples:

"proc poof {{arg1 one} args} {return [list $arg1 $args]}": Defines a procedure poof that takes 0 or more arguments and merges them into a list of two elements. If no argument is given, the result will be the list {one {}}

Defines a new Tcl procedure that can be invoked by typing a unique abbreviation of the procedure name.

Any existing procedure or built-in command with the same name is overridden.
<name> is the name of the new procedure and can consist of pretty much any character (even a space or tab, if you enclose the argument in braces).
<args> is the (possibly empty) list of formal parameters the procedure accepts. Each element of the list can be either the name of local variable, to which the corresponding actual parameter is assigned before the first command of the procedure is executed, or a two-element list, the first element of which is the local variable name, as above, and the second element of which is the value to assign the variable if no actual parameter is given.
If the final formal parameter is named "args", the remaining actual parameters from that position on are cobbled into a list and assigned to the local variable $args. This allows a procedure to receive a variable number of arguments (even 0, in which case $args will be the empty list).
If the only formal parameter is "noeval", all the actual parameters are merged into a list and assigned to $noeval. Moreover, neither command- nor variable-substitution is performed on the actual parameters.
The return value for the procedure is specified by executing the "return" command within the procedure. If no "return" command is executed, the return value for the procedure is the empty string.
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. Braces and backslashes may be used in the usual way to specify complex default values.
When <name> (or a unique abbreviation of same) 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 (unless the "args" keyword was used).
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 itself returns the null string.

See Also: defsubr, return.

protect

protect <body> <cleanup>

Examples:

"protect {
var s [stream open $file w] # do stuff with the stream } { catch {stream close $s} }": Perform some random operations on a file making sure the stream gets closed, even if the user types control-C.

Allows one to ensure that clean-up for a sequence of commands will always happen, even if the user types control-C to interrupt the command.

Since the interrupt can come at any time during the <body>, the <cleanup> command string should not rely on any particular variables being set. Hence the "catch" command used in the <cleanup> clause of the example.
The <cleanup> clause will also be executed if any command in the <body> generates an error.

See Also: catch.

range

range <value> <first> <last> [chars]

Examples:

"range {a b c} 1 end": Returns {b c} (element 1 to the end)
"range {hi mom} 3 end chars": Returns "mom"

Extracts a range of characters from a string, or elements from a list.

If you give an ending index that is greater than the number of elements in the list (characters in the string), it will be adjusted to be the index of the last element (character).
If you give a starting index that is greater than the number of elements in the list (characters in the string), the result will be the empty list (string).
You can give <end> as "end" (without the quotation marks, of course) to indicate the extraction should go to the end of the list (string).
The range is inclusive, so "range {a b c} 0 0" returns "a".
Neither index may be less than 0 or "range" will generate an error.
Return a range of fields or characters from value. 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. If <last> is less than <first> then an empty string is returned. Note: range value first first does not always produce the same results asindex value first (although it often does for simple fields that are not enclosed in braces); it does, however, produce exactly the same results as list [index value first] .

See Also: index.

return

return [<value>]

Examples:

"return $val": Returns the string in $val as the value for the current Tcl procedure.

Causes an immediate return from the current Tcl procedure, with or without a value.

Every Tcl procedure returns a string for a value. If the procedure was called via command substitution (having been placed between square brackets as the argument to another command), the return value takes the place of the command invocation.
Execution of the current procedure terminates immediately, though any <cleanup> clause for a containing "protect" command will still be executed.
If no "return" command is invoked within a Tcl procedure, the procedure returns the empty string by default.
This command may be invoked only when a procedure call is in progress. It causes the current procedure to return immediately. If <value> is specified, it will be the return value from the procedure. Otherwise the current procedure will return the empty string.

See Also: error, proc, defsubr, defcommand, defcmd.

scan

scan <string> <format> [<varname1> ]*

Examples:

"scan $input {my name is %s} name": Trims the leading string "my name is " from the string in $input and stores the rest of the string within the variable $name

"scan" parses fields from an input string, given the string and a format string that defines the various types of fields. The fields are assigned to variables within the caller's scope.

The <format> string consists of literal text, which must be matched explicitly, and field definitions. The <varName> arguments are names of variables to which each successive field value is assigned.
A single whitespace character (space or tab) will match any number of whitespace characters in the input string. Fields are specified as for the standard C library routine "sscanf":

%c: A single character. The field value stored is the decimal number of the ASCII code for the character scanned. So if the character were a space, the variable would receive the string "32".
%d: A signed decimal integer is parsed and stored.
%o: An octal integer is parsed and stored, as a decimal number.
%x: A hexadecimal integer is parsed and stored, as a decimal number.
%i: A signed integer, following the standard C radix-specification standard, is parsed and stored as a decimal number.
%f: A floating-point number is parsed as a "float" and stored without exponent, unless the exponent is less than -4.
%s: A whitespace-terminated string is parsed and stored.
%[<char-class>]: A string consisting only of the characters in the given character class (see "string match" for details on character classes) is parsed and stored. The normal leading-whitespace skipping is suppressed.
%%: Matches a single percent sign in the input.

If the % of a field specifier is followed by an *, the field is parsed as usual, consuming characters from the string, but the result is not stored anywhere and you should not specify a variable to receive the value.
The maximum length of a field may be specified by giving a decimal number between the % and the field-type character. So "%10s" will extract out a string of at most 10 characters.
There is a limit of 5 fields.

See Also: format.

source

source <fileName>

Examples:

"source coolness": Evaluates all commands within the file "coolness.tcl" in the current directory.

Reads and evaluates commands from a file.

If <file> has no extension and doesn't exist, "source" will append ".tcl" to the end and try and read that file.
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.

string

string compare<string1> <string2> [no_case]
string first<substring> <string> [no_case]
string last<substring> <string> [no_case]
string match<string> <pattern>
string subst <string> <search> <replace> [global]

Examples:

"if {[string c [index $args 1] all] == 0}": Do something if the 2nd element of the list in $args is the string "all".
"while {[string m [index $args 0] -*]}": Loop while the first element of the list in $args begins with a hyphen.

Examine strings in various ways.

"string subst" searches <string> for occurrences of <search> and replaces them with <replace>. If 5th argument is given as "global" (it may be abbreviated), then all (non-overlapping) occurrences of <search> will be replaced. If 5th argument is absent, only the first occurrence will be replaced.
"string compare" compares the two strings character-by-character. It returns -1, 0, or 1 depending on whether <string1> is lexicographically less than, equal to, or greater than <string2>. If the no_case parameter is passed than it does a case insensitive compare.
"string first" searches <string> for the given <substring>. If it finds it, it returns the index of the first character in the first such match. If <substring> isn't part of <string>, it returns -1. If the no_case parameter is passed it does the search ignoring case.
"string last" is much like "string first", except it returns the index of the first character of the last match for the <substring> within <string>. If there is no match, it returns -1.
"string match" compares <string> against <pattern> and returns 1 if the two match, or 0 if they do not. For the strings to match, their contents must be identical, except that the following special sequences may appear in <pattern> with the following results:

*: Matches any sequence of characters, including none.
?: Matches any single character
[<char-class>]: Matches a single character within the given set. The elements of the set are specified as single characters, or as ranges of the form <start>-<end>. Thus [0-9x] matches a single character that is a numeric digit or the letter x.
[^<char-class>]: Matches a single character not within the given set.
\*: Matches an asterisk.
\?: Matches a question mark.
\[: Matches an open-bracket.

See Also: case.

uplevel

uplevel <level> <body>

uplevel <function> <body>

Examples:

"uplevel print-frame {var found1}": Sets $found to 1 within the variables belonging to the nearest invocation of print-frame on the call stack.
"uplevel 0 {var foo-table}": Retrieves the value of the global variable foo-table.
"uplevel 1 {var found 1}": Sets $found to 1 within the scope of the procedure that called the one executing the "uplevel" command.

Provides access to the variables of another procedure for fairly specialized purposes.

<level> is a signed integer with the following meaning:

> 0: Indicates the number of scopes to go up. For example, if you say "uplevel 1 {var foo 36}", you would modify (or create) the variable "foo" in your caller's scope.
<= 0: Indicates the number of scopes to go down from the global one. "uplevel 0 <body>" will execute <body> in the top-most scope, which means that no local variables are involved, and any variables created by the commands in <body> persist as global variables.

<function> is the name of a function known to be somewhere on the call stack. If the named function isn't on the call stack anywhere, "uplevel" generates an error.
<body> may be spread over multiple arguments, allowing the command to be executed to use variables local to the current procedure as arguments without having to use the "list" command to form the <body>.

See Also: global.

var

var <varname>
var (<name> <value>)+

Examples:

"echo [var poof]": Prints the value stored in the variable "poof"
"var a b c d": Assigns the string "b" to the variable "a", and the string "d" to the variable "c".
"var yes $no no $yes": Exchanges the values of the "yes" and "no" variables

This is the means by which variables are defined in Tcl. Less often, it is also used to retrieve the value of a variable (usually that's done via variable substitution).

If you give only one argument, the value of that variable will be returned. If the variable has never been given a value, the variable will be created and assigned the empty string, then the empty string will be returned.
You can set the value of a variable by giving the value as the second argument, after the variable name. No value is returned by the "var" command in this case.
You can assign values to multiple variables "in parallel" by giving successive name/value pairs.
If invoked in a procedure on a variable that has not been declared global (using the "global" command), this applies to the local variable of the given name, even if it has no value yet.

See Also: global.

GEOS SDK TechDocs |

5.1 Notation | Next:

6 Coding