Fish 'n' More 2

home *** CD-ROM | disk | FTP | other *** search

/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / dirs / tcl_447.lzh / TCL / tcl.lzh / tcl / docs / tcl.man < prev

Wrap

Text File | 1990-05-04 | 98.4 KB | 3,231 lines

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