diff options
Diffstat (limited to 'jim_tcl.txt')
| -rw-r--r-- | jim_tcl.txt | 4162 |
1 files changed, 4162 insertions, 0 deletions
diff --git a/jim_tcl.txt b/jim_tcl.txt new file mode 100644 index 0000000..1b719a8 --- /dev/null +++ b/jim_tcl.txt @@ -0,0 +1,4162 @@ +Jim Tcl(n) +========== + +NAME +---- +Jim Tcl v0.63 - overview of the Jim tool command language facilities + +SYNOPSIS +-------- + + cc <source> -ljim + +or + + jimsh <script> + +.Quick Index +* <<CommandIndex,Command Reference>> +* <<OperatorPrecedence,Operator Precedence>> +* <<BuiltinVariables, Builtin Variables>> +* <<BackslashSequences, Backslash Sequences>> + +INTRODUCTION +------------ +Jim is a reimplementation of Tcl, combining some features from +earlier, smaller versions of Tcl (6.x) as well as more modern +features from later versions of Tcl (7.x, 8.x). It also has some some +entirely new features not available in any version of Tcl. + +This version is approximately the same size as "tinytcl" (6.8) but +is faster and has more features. + +Note that most of this man page is the original 6.8 Tcl man page, with +changes made for differences with Jim. + +The major differences are: + +1. Object-based I/O (aio) with backward compatibility wrapper +2. I/O: Support for sockets (client and server) +3. I/O: Support for readable/writable event handlers +4. Integers are 64bit +5. Support for references ('ref'/'getref'/'setref') and garbage collection +6. Builtin dictionary type ('dict') +7. 'file mkdir', 'file rename', 'file tempfile' (Tcl 7.x, 8.x) +8. 'env' command to access environment variables +9. List: 'lmap', 'lset', 'lreverse', 'lassign' (Tcl 8.x) +10. 'os.fork', 'os.wait', 'rand' +11. '\{*\}'/'\{expand\}' +12. 'string map' (Tcl 7.x) +13. 'subst' (Tcl 7.x) +14. 'switch' (Tcl 7.x) (note that 'case' is provided for compatibility) +15. Must better error reporting. 'info stacktrace' as a replacement for 'errorInfo', 'errorCode' +16. Support for "static" variables in procedures +17. Significantly faster for many scripts/operations +18. Support for tail-call optimisation, 'tailcall' +19. Command pipelines via open "|..." are not supported (but see 'exec' and 'socket pipe') +20. Variable traces are not supported +21. The history command is not supported + +CHANGES +------- +Since v0.62: + +1. 'source' now checks that a script is complete (.i.e. not missing a brace) +2. 'info complete' now uses the real parser and so is 100% accurate +3. Better access to live stack frames with 'info frame', 'stacktrace' and 'stackdump' +4. 'tailcall' no longer loses stack trace information +5. Add 'alias' and 'curry' +6. 'lambda', 'alias' and 'curry' are implemented via 'tailcall' for efficiency +7. 'local' allows procedures to be deleted automatically at the end of the current procedure +8. udp sockets are now supported for both clients and servers. +9. vfork-based exec is now working correctly +10. Add 'file tempfile' +11. Add 'socket pipe' +12. Enhance 'try ... on ... finally' to be more Tcl 8.6 compatible +13. It is now possible to 'return' from within 'try' + +Since v0.61: + +1. Add support to 'exec' for '>&', '>>&', '|&', '2>@1' +2. Fix 'exec' error messages when special token (e.g. '>') is the last token +3. Fix 'subst' handling of backslash escapes. +4. Allow abbreviated options for 'subst' +5. Add support for 'return', 'break', 'continue' in subst +6. Many 'expr' bug fixes +7. Add support for functions in 'expr' (e.g. int(), abs()), and also 'in', 'ni' list operations +8. The variable name argument to 'regsub' is now optional +9. Add support for 'unset -nocomplain' +10. Add support for list commands: 'lassign', 'lrepeat' +11. Fully-functional 'lsearch' is now implemented +12. Add 'info nameofexecutable' and 'info returncodes' +13. Allow 'catch' to determine what return codes are caught +14. Allow 'incr' to increment an unset variable by first setting to 0 +15. Allow 'args' and optional arguments to the left or required arguments in 'proc' +16. Add 'file copy' +17. Add 'try ... finally' command + +TCL 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 can be used as a common language for communicating between +applications. Inter-application communication is not built into the +Tcl core described here, but various add-on libraries, such as the Tk +toolkit, allow applications to issue commands to each other. This makes +it possible for applications to work together in much more powerful ways +than was previously possible. + +This manual page focuses primarily on the Tcl language. It describes +the language syntax and the built-in commands that will be available +in any application based on Tcl. The individual library procedures are +described in more detail in separate manual pages, one per procedure. + +INTERPRETERS +------------ +The central data structure in Tcl is an interpreter (C type 'Jim_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. + +DATA TYPES +---------- +Tcl supports only one type of data: strings. All commands, all arguments +to commands, all command results, and all variable values are strings. + +Where commands require numeric arguments or return numeric results, +the arguments and results are passed as strings. Many commands expect +their string arguments to have certain formats, but this interpretation +is up to the individual commands. For example, arguments often contain +Tcl command strings, which may get executed as part of the commands. +The easiest way to understand the Tcl interpreter is to remember that +everything is just an operation on a string. In many cases Tcl constructs +will look similar to more structured constructs from other languages. +However, the Tcl constructs are not structured at all; they are just +strings of characters, and this gives them a different behavior than +the structures they may look like. + +Although the exact interpretation of a Tcl string depends on who is doing +the interpretation, there are three common forms that strings take: +commands, expressions, and lists. The major sections below discuss +these three forms in more detail. + +BASIC COMMAND SYNTAX +-------------------- +The Tcl language has syntactic similarities to both the Unix shells +and Lisp. However, the interpretation of commands is different +in Tcl than in either of those other two systems. +A Tcl command string consists of one or more commands separated +by newline characters or semi-colons. +Each command consists of a collection of fields separated by +white space (spaces or tabs). +The first field must be the name of a command, and the +additional fields, if any, are arguments that will be passed to +that command. For example, the command: + + set a 22 + +has three fields: the first, 'set', is the name of a Tcl command, and +the last two, 'a' and '22', will be passed as arguments to +the 'set' command. The command name may refer either to a built-in +Tcl command, an application-specific command bound in with the library +procedure 'Jim_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 should normally be typed completely (e.g. no abbreviations). +However, if the Tcl interpreter cannot locate a command it invokes a +special command named 'unknown' which attempts to find or create the +command. + +For example, at many sites 'unknown' will search through library +directories for the desired command and create it as a Tcl procedure if +it is found. The 'unknown' command often provides automatic completion +of abbreviated commands, but usually only for commands that were typed +interactively. + +It's probably a bad idea to use abbreviations in command scripts and +other forms that will be re-used over time: changes to the command set +may cause abbreviations to become ambiguous, resulting in scripts that +no longer work. + +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. When comments are embedded inside nested +commands (e.g. fields enclosed in braces) they must have properly-matched +braces (this is necessary because when Tcl parses the top-level command +it doesn't yet know that the nested field will be used as a command so +it cannot process the nested comment character as a comment). + +GROUPING ARGUMENTS WITH DOUBLE-QUOTES +------------------------------------- +Normally each argument field ends at the next white space, but +double-quotes may be used to create arguments with embedded space. + +If an argument field begins with a double-quote, then the argument isn't +terminated by white space (including newlines) or a semi-colon (see below +for information on semi-colons); instead it ends at the next double-quote +character. The double-quotes are not included in the resulting argument. +For example, the command + + set a "This is a single argument" + +will pass two arguments to 'set': 'a' and 'This is a single argument'. + +Within double-quotes, command substitutions, variable substitutions, +and backslash substitutions still occur, as described below. If the +first character of a command field is not a quote, then quotes receive +no special interpretation in the parsing of that field. + +GROUPING ARGUMENTS WITH BRACES +------------------------------ +Curly braces may also be used for grouping arguments. They are similar +to quotes except for two differences. First, they nest; this makes them +easier to use for complicated arguments like nested Tcl command strings. +Second, the substitutions described below for commands, variables, and +backslashes do *not* occur in arguments enclosed in braces, so braces +can be used to prevent substitutions where they are undesirable. + +If an argument field begins with a left brace, then the argument ends +at the matching right brace. Tcl will strip off the outermost layer +of braces and pass the information between the braces to the command +without any further modification. For example, in the command + + set a {xyz a {b c d}} + +the 'set' command will receive two arguments: 'a' +and 'xyz a {b c d}'. + +When braces or quotes are in effect, the matching brace or quote need +not be on the same line as the starting quote or brace; in this case +the newline will be included in the argument field along with any other +characters up to the matching brace or quote. For example, the 'eval' +command takes one argument, which is a command string; 'eval' invokes +the Tcl interpreter to execute the command string. The command + + eval { + set a 22 + set b 33 + } + +will assign the value '22' to 'a' and '33' to 'b'. + +If the first character of a command field is not a left +brace, then neither left nor right +braces in the field will be treated specially (except as part of +variable substitution; see below). + +COMMAND SUBSTITUTION WITH BRACKETS +---------------------------------- +If an open bracket occurs in a field of a command, then command +substitution occurs (except for fields enclosed in braces). All of the +text up to the matching close bracket is treated as a Tcl command and +executed immediately. Then the result of that command is substituted +for the bracketed text. For example, consider the command + + set a [set b] + +When the 'set' command has only a single argument, it is the name of a +variable and 'set' returns the contents of that variable. In this case, +if variable 'b' has the value 'foo', then the command above is equivalent +to the command + + set a foo + +Brackets can be used in more complex ways. For example, if the variable +'b' has the value 'foo' and the variable 'c' has the value 'gorp', +then the command + + set a xyz[set b].[set c] + +is equivalent to the command + + set a xyzfoo.gorp + + +A bracketed command may contain multiple commands separated by newlines +or semi-colons in the usual fashion. In this case the value of the last +command is used for substitution. For example, the command + + set a x[set b 22 + expr $b+2]x + +is equivalent to the command + + set a x24x + + +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 variable values. If '$' appears in an argument that isn't +enclosed in braces then variable substitution will occur. The characters +after the '$', up to the first character that isn't a number, letter, +or underscore, are taken as a variable name and the string value of that +variable is substituted for the name. + +For example, if variable 'foo' has the value 'test', then the command + + set a $foo.c + +is equivalent to the command + + set a test.c + +There are two special forms for variable substitution. If the next +character after the name of the variable is an open parenthesis, then +the variable is assumed to be an array name, and all of the characters +between the open parenthesis and the next close parenthesis are taken as +an index into the array. Command substitutions and variable substitutions +are performed on the information between the parentheses before it is +used as an index. + +For example, if the variable 'x' is an array with one element named +'first' and value '87' and another element named '14' and value 'more', +then the command + + set a xyz$x(first)zyx + +is equivalent to the command + + set a xyz87zyx + +If the variable 'index' has the value '14', then the command + + set a xyz$x($index)zyx + +is equivalent to the command + + set a xyzmorezyx + +For more information on arrays, see VARIABLES AND ARRAYS below. + +The second special form for variables occurs when the dollar sign is +followed by an open curly brace. In this case the variable name consists +of all the characters up to the next curly brace. + +Array references are not possible in this form: the name between braces +is assumed to refer to a scalar variable. For example, if variable +'foo' has the value 'test', then the command + + set a abc${foo}bar + +is equivalent to the command + + set a abctestbar + + +Variable substitution does not occur in arguments that are enclosed in +braces: the dollar sign and variable name are passed through to the +argument verbatim. + +The dollar sign abbreviation is simply a shorthand form. '$a' is +completely equivalent to '[set a]'; it is provided as a convenience +to reduce typing. + +SEPARATING COMMANDS WITH SEMI-COLONS +------------------------------------ +Normally, each command occupies one line (the command is terminated by a +newline character). However, semi-colon (';') is treated as a command +separator character; multiple commands may be placed on one line by +separating them with a semi-colon. Semi-colons are not treated as +command separators if they appear within curly braces or double-quotes. + +BACKSLASH SUBSTITUTION +---------------------- +Backslashes may be used to insert non-printing characters into command +fields and also to insert special characters like braces and brackets +into fields without them being interpreted specially as described above. + +The backslash sequences understood by the Tcl interpreter are +listed below. In each case, the backslash +sequence is replaced by the given character: +[[BackslashSequences]] ++{backslash}b+:: + Backspace (0x8) + ++{backslash}f+:: + Form feed (0xc) + ++{backslash}n+:: + Newline (0xa) + ++{backslash}r+:: + Carriage-return (0xd). + ++{backslash}t+:: + Tab (0x9). + ++{backslash}v+:: + Vertical tab (0xb). + ++{backslash}{+:: + Left brace ({). + ++{backslash}}+:: + Right brace (}). + ++{backslash}[+:: + Open bracket ([). + ++{backslash}]+:: + Close bracket (]). + ++{backslash}$+:: + Dollar sign ($). + ++{backslash}<space>+:: + Space ( ): doesn't terminate argument. + ++{backslash};+:: + Semi-colon: doesn't terminate command. + ++{backslash}"+:: + Double-quote. + ++{backslash}<newline>+:: + Nothing: this joins two lines together + into a single line. This backslash feature is unique in that + it will be applied even when the sequence occurs within braces. + ++{backslash}{backslash}+:: + Backslash ('{backslash}'). + ++{backslash}*ddd*+:: + The digits *ddd* (one, two, or three of them) give the octal value of + the character. Note that Jim supports null characters in strings. + +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 '{backslash}*a' and the second +argument will be '{backslash}{foo'. + +If an argument is enclosed in braces, then backslash sequences inside +the argument are parsed but no substitution occurs (except for +backslash-newline): the backslash +sequence is passed through to the argument as is, without making +any special interpretation of the characters in the backslash sequence. +In particular, backslashed braces are not counted in locating the +matching right brace that terminates the argument. +For example, in the +command + + set a {\{abc} + +the second argument to 'set' will be '{backslash}{abc'. + +This backslash mechanism is not sufficient to generate absolutely +any argument structure; it only covers the +most common cases. To produce particularly complicated arguments +it is probably easiest to use the 'format' command along with +command substitution. + +STRING AND LIST INDEX SPECIFICATIONS +------------------------------------ + +Many string and list commands take one or more 'index' parameters which +specify a position in the string relative to the start or end of the string/list. + +The index may be one of the following forms: + +`integer`:: + A simple integer, where '0' refers to the first element of the string + or list. + +`integer+integer` or:: +`integer-integer`:: + The sum or difference of the two integers. e.g. +2+3+ refers to the 5th element. + This is useful when used with (e.g.) +$i+1+ rather than the more verbose + +[expr {$i+1\}]+ + +`end`:: + The last element of the string or list. + +`end-integer`:: + The 'nth-from-last' element of the string or list. + +COMMAND SUMMARY +--------------- +1. A command is just a string. +2. Within a string commands are separated by newlines or semi-colons + (unless the newline or semi-colon is within braces or brackets + or is backslashed). +3. A command consists of fields. The first field is the name of the command. + The other fields are strings that are passed to that command as arguments. +4. Fields are normally separated by white space. +5. Double-quotes allow white space and semi-colons to appear within + a single argument. + Command substitution, variable substitution, and backslash substitution + still occur inside quotes. +6. Braces defer interpretation of special characters. + If a field begins with a left brace, then it consists of everything + between the left brace and the matching right brace. The + braces themselves are not included in the argument. + No further processing is done on the information between the braces + except that backslash-newline sequences are eliminated. +7. If a field doesn't begin with a brace then backslash, + variable, and command substitution are done on the field. Only a + single level of processing is done: the results of one substitution + are not scanned again for further substitutions or any other + special treatment. Substitution can + occur on any field of a command, including the command name + as well as the arguments. +8. If the first non-blank character of a command is a '\#', everything + from the '\#' up through the next newline is treated as a comment + and ignored. + +EXPRESSIONS +----------- +The second major interpretation applied to strings in Tcl is +as expressions. Several commands, such as 'expr', 'for', +and 'if', treat one or more of their arguments as expressions +and call the Tcl expression processors ('Jim_ExprLong', +'Jim_ExprBoolean', etc.) to evaluate them. + +The operators permitted in Tcl expressions are a subset of +the operators permitted in C expressions, and they have the +same meaning and precedence as the corresponding C operators. +Expressions almost always yield numeric results +(integer or floating-point values). +For example, the expression + + 8.2 + 6 + +evaluates to 14.2. + +Tcl expressions differ from C expressions in the way that +operands are specified, and in that Tcl expressions support +non-numeric operands and string comparisons. + +A Tcl expression consists of a combination of operands, operators, +and parentheses. + +White space may be used between the operands and operators and +parentheses; it is ignored by the expression processor. +Where possible, operands are interpreted as integer values. + +Integer values may be specified in decimal (the normal case), in octal (if the +first character of the operand is '0'), or in hexadecimal (if the first +two characters of the operand are '0x'). + +If an operand does not have one of the integer formats given +above, then it is treated as a floating-point number if that is +possible. Floating-point numbers may be specified in any of the +ways accepted by an ANSI-compliant C compiler (except that the +'f', 'F', 'l', and 'L' suffixes will not be permitted in +most installations). For example, all of the +following are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16. + +If no numeric interpretation is possible, then an operand is left +as a string (and only a limited set of operators may be applied to +it). + +1. Operands may be specified in any of the following ways: + +2. As a numeric value, either integer or floating-point. + +3. As a Tcl variable, using standard '$' notation. +The variable's value will be used as the operand. + +4. As a string enclosed in double-quotes. +The expression parser will perform backslash, variable, and +command substitutions on the information between the quotes, +and use the resulting value as the operand + +5. As a string enclosed in braces. +The characters between the open brace and matching close brace +will be used as the operand without any substitutions. + +6. As a Tcl command enclosed in brackets. +The command will be executed and its result will be used as +the operand. + +Where substitutions occur above (e.g. inside quoted strings), they +are performed by the expression processor. +However, an additional layer of substitution may already have +been performed by the command parser before the expression +processor was called. + +As discussed below, it is usually best to enclose expressions +in braces to prevent the command parser from performing substitutions +on the contents. + +For some examples of simple expressions, suppose the variable 'a' has +the value 3 and the variable 'b' has the value 6. Then the expression +on the left side of each of the lines below will evaluate to the value +on the right side of the line: + + $a + 3.1 6.1 + 2 + "$a.$b" 5.6 + 4*[llength "6 2"] 8 + {word one} < "word $a" 0 + +The valid operators are listed below, grouped in decreasing order +of precedence: +[[OperatorPrecedence]] +`int() double() round() abs()`:: + Unary functions. + int() converts the numeric argument to an integer by truncating down. + double() converts the numeric argument to floating point. + round() converts the numeric argument to the closest integer value. + abs() takes the absolute value of the numeric argument. + +`sin() cos() tan() asin() acos() atan() sinh() cosh() tanh() ceil() floor() exp() log() log10() sqrt()`:: + Unary math functions. + If Jim is compiled with math support, these functions are available. + +`- + ~ !`:: + Unary minus, unary plus, bit-wise NOT, logical NOT. None of these operands + may be applied to string operands, and bit-wise NOT may be + applied only to integers. + +`**`:: + Power. e.g. pow(). If Jim is compiled with math support, supports doubles and + integers. Otherwise supports integers only. + +`* / %`:: + Multiply, divide, remainder. None of these operands may be + applied to string operands, and remainder may be applied only + to integers. + +`+ -`:: + Add and subtract. Valid for any numeric operands. + +`<< >> <<< >>>`:: + Left and right shift, left and right rotate. Valid for integer operands only. + +`< > \<= >=`:: + Boolean less, greater, less than or equal, and greater than or equal. + Each operator produces 1 if the condition is true, 0 otherwise. + These operators may be applied to strings as well as numeric operands, + in which case string comparison is used. + +`== !=`:: + Boolean equal and not equal. Each operator produces a zero/one result. + Valid for all operand types. *Note* that values will be converted to integers + if possible, then floating point types, and finally strings will be compared. + It is recommended that 'eq' and 'ne' should be used for string comparison. + +`eq ne`:: + String equal and not equal. Uses the string value directly without + attempting to convert to a number first. + +`in ni`:: + String in list and not in list. For 'in', result is 1 if the left operand (as a string) + is contained in the right operand (as a list), or 0 otherwise. The result for + '{$a ni $list}' is equivalent to '{!($a in $list)}'. + +`&`:: + Bit-wise AND. Valid for integer operands only. + +`|`:: + Bit-wise OR. Valid for integer operands only. + +`^`:: + Bit-wise exclusive OR. Valid for integer operands only. + +`&&`:: + Logical AND. Produces a 1 result if both operands are non-zero, 0 otherwise. + Valid for numeric operands only (integers or floating-point). + +`||`:: + Logical OR. Produces a 0 result if both operands are zero, 1 otherwise. + Valid for numeric operands only (integers or floating-point). + +`x ? y : z`:: + If-then-else, as in C. If *x* + evaluates to non-zero, then the result is the value of *y*. + Otherwise the result is the value of *z*. + The *x* operand must have a numeric value, while *y* and *z* can + be of any type. + +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. + +The '&&', '||', and '?:' operators have 'lazy +evaluation', just as in C, +which means that operands are not evaluated if they are +not needed to determine the outcome. For example, in + + $v ? [a] : [b] + +only one of '[a]' or '[b]' will actually be evaluated, +depending on the value of '$v'. + +All internal computations involving integers are done with the C +type 'long long' if available, or 'long' otherwise, and all internal +computations involving floating-point are done with the C type +'double'. + +When converting a string to floating-point, exponent overflow is +detected and results in a Tcl error. +For conversion to integer from string, detection of overflow depends +on the behavior of some routines in the local C library, so it should +be regarded as unreliable. +In any case, overflow and underflow are generally not detected +reliably for intermediate results. + +Conversion among internal representations for integer, floating-point, +and string operands is done automatically as needed. +For arithmetic computations, integers are used until some +floating-point number is introduced, after which floating-point is used. +For example, + + 5 / 4 + +yields the result 1, while + + 5 / 4.0 + 5 / ( [string length "abcd"] + 0.0 ) + +both yield the result 1.25. + +String values may be used as operands of the comparison operators, +although the expression evaluator tries to do comparisons as integer +or floating-point when it can. +If one of the operands of a comparison is a string and the other +has a numeric value, the numeric operand is converted back to +a string using the C 'sprintf' format specifier +'%d' for integers and '%g' for floating-point values. +For example, the expressions + + "0x03" > "2" + "0y" < "0x12" + +both evaluate to 1. The first comparison is done using integer +comparison, and the second is done using string comparison after +the second operand is converted to the string '18'. + +In general it is safest to enclose an expression in braces when +entering it in a command: otherwise, if the expression contains +any white space then the Tcl interpreter will split it +among several arguments. For example, the command + + expr $a + $b + +results in three arguments being passed to 'expr': '$a', +'+', and '$b'. In addition, if the expression isn't in braces +then the Tcl interpreter will perform variable and command substitution +immediately (it will happen in the command parser rather than in +the expression parser). In many cases the expression is being +passed to a command that will evaluate the expression later (or +even many times if, for example, the expression is to be used to +decide when to exit a loop). Usually the desired goal is to re-do +the variable or command substitutions each time the expression is +evaluated, rather than once and for all at the beginning. For example, +the command + + for {set i 1} $i<=10 {incr i} {...} *** WRONG *** + +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` eventually +becomes greater than 10. In the above case the loop will never +terminate. Instead, the expression should be placed in braces: + + for {set i 1} {$i<=10} {incr i} {...} *** RIGHT *** + +This causes the substitution of 'i' +to be delayed; it will be re-done each time the expression is +evaluated, which is 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 quotes +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 +braces and quotes and backslashes are applied as for commands. Thus in +the example above when the third element is extracted from the list, +the result is + + d e {f g h} + +(when the field was extracted, all that happened was to strip off +the outermost layer of braces). Command substitution and +variable substitution are 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', 'lappend', 'lindex', 'linsert', +'list', 'llength', 'lrange', 'lreplace', 'lsearch', and 'lsort' allow +you to build lists, extract elements from them, search them, and perform +other list-related functions. + +Advanced list commands include 'lrepeat', 'lreverse', 'lmap', 'lassign', 'lset'. + +LIST EXPANSION +-------------- + +A new addition to Tcl 8.5 is the ability to expand a list into separate +arguments. Support for this feature is also available in Jim. + +Consider the following attempt to exec a list: + + set cmd {ls -l} + exec $cmd + +This will attempt to exec the a command named "ls -l", which will clearly not +work. Typically eval and concat are required to solve this problem, however +it can be solved much more easily with '\{*\}'. + + exec {*}$cmd + +This will expand the following argument into individual elements and then evaluate +the resulting command. + +Note that the official Tcl syntax is '\{*\}', however '\{expand\}' is retained +for backward compatibility with experimental versions of this feature. + +REGULAR EXPRESSIONS +------------------- +Tcl provides two commands that support string matching using +'egrep'-style regular expressions: 'regexp' and 'regsub'. + +Regular expressions are implemented using the system's C library as +Extended Regular Expressions (EREs) rather than Basic Regular Expressions (BREs). + +See regex(3) and regex(7) for full details. + +*NOTE* Tcl 7.x and 8.x use perl-style Advanced Regular Expressions (AREs). + +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 jim.h, and are: + ++JIM_OK(0)+:: + This is the normal return code, and indicates that the command completed + successfully. The string gives the command's return value. + ++JIM_ERR(1)+:: + Indicates that an error occurred; the string gives a message describing + the error. + ++JIM_RETURN(2)+:: + 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. + ++JIM_BREAK(3)+:: + Indicates that the 'break' command has been invoked, so the + innermost loop should abort immediately. The string should always + be empty. + ++JIM_CONTINUE(4)+:: + 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. + ++JIM_SIGNAL(5)+:: + Indicates that a signal was caught while executing a commands. + The string contains the name of the signal caught. + See the 'signal' and 'catch' commands. + ++JIM_EXIT(6)+:: + Indicates that the command called the 'exit' command. + The string contains the exit code. + +Tcl programmers do not normally need to think about return codes, +since +JIM_OK+ is almost always returned. If anything else is returned +by a command, then the Tcl interpreter immediately stops processing +commands and returns to its caller. If there are several nested +invocations of the Tcl interpreter in progress, then each nested +command will usually return the error to its caller, until eventually +the error is reported to the top-level application code. The +application will then display the error message for the user. + +In a few cases, some commands will handle certain 'error' conditions +themselves and not return them upwards. For example, the 'for' +command checks for the +JIM_BREAK+ code; if it occurs, then 'for' +stops executing the body of the loop and returns +JIM_OK+ to its +caller. The 'for' command also handles +JIM_CONTINUE+ codes and the +procedure interpreter handles +JIM_RETURN+ codes. The 'catch' +command allows Tcl programs to catch errors and handle them without +aborting command interpretation any further. + +The 'info returncodes' command may be used to programmatically map between +return codes and names. + +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. + +The 'proc' command is used to create a new Tcl command procedure: + ++*proc* 'name args ?statics? body'+ + +The new command is name *name*, and it replaces 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, of the following +argument specifiers: + ++name+:: + Required Argument - A simple argument name. + ++name default+:: + Optional Argument - A two-element list consisting of the + argument name, followed by the default value, which will + be used if the corresponding argument is not supplied. + ++*args*+:: + Variable Argument - The special name 'args', which is + assigned all remaining arguments (including none). The + variable argument may only be specified once. + +Arguments must be provided in the following order, any of which +may be omitted: + +1. Required Arguments (Left) +2. Optional Arguments +3. Variable Argument +4. Required Arguments (Right) + +When the command 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 +required arguments, and there must not be any extra actual arguments +(unless the Variable Argument is specified). + +Actual arguments are assigned to formal arguments as follows: + +1. Left Required Arguments are assigned from the left +2. Right Required Arguments are assigned from the right +3. Default Arguments are assigned from the left, following the Left Required Arguments. +4. A list is formed from any remaining arguments, which are then + are assigned to the 'args' Variable Argument (if specified). The list will be empty + if there are no remaining arguments. + +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 be +accessed by invoking the 'global' command or via the '::' prefix. + +*New in Jim* + +In addition to procedure arguments, Jim procedures may declare static variables. +These variables scoped to the procedure and initialised at procedure definition. +Either from the static variable definition, or from the enclosing scope. + +Consider the following example: + + jim> set a 1 + jim> proc a {} {a {b 2}} { + set c 1 + puts "$a $b $c" + incr a + incr b + incr c + } + jim> a + 1 2 1 + jim> a + 2 3 1 + +The static variable *a* has no initialiser, so it is initialised from +the enclosing scope with the value 1. (Note that it is an error if there +is no variable with the same name in the enclosing scope). However *b* +has an initialiser, so it is initialised to 2. + +Unlike a local variable, the value of a static variable is retained across +invocations of the procedure. + +See the 'proc' command for information on +how to define procedures and what happens when they are invoked. + +VARIABLES - SCALARS AND ARRAYS +------------------------------ +Tcl allows the definition of variables and the use of their values +either through '$'-style variable substitution, the 'set' +command, or a few other mechanisms. + +Variables need not be declared: a new variable will automatically +be created each time a new variable name is used. + +Tcl supports two types of variables: scalars and arrays. +A scalar variable has a single value, whereas an array variable +can have any number of elements, each with a name (called +its 'index') and a value. + +Array indexes may be arbitrary strings; they need not be numeric. +Parentheses are used refer to array elements in Tcl commands. +For example, the command + + set x(first) 44 + +will modify the element of 'x' whose index is 'first' +so that its new value is '44'. + +Two-dimensional arrays can be simulated in Tcl by using indexes +that contain multiple concatenated values. +For example, the commands + + set a(2,3) 1 + set a(3,6) 2 + +set the elements of 'a' whose indexes are '2,3' and '3,6'. + +In general, array elements may be used anywhere in Tcl that scalar +variables may be used. + +If an array is defined with a particular name, then there may +not be a scalar variable with the same name. + +Similarly, if there is a scalar variable with a particular +name then it is not possible to make array references to the +variable. + +To convert a scalar variable to an array or vice versa, remove +the existing variable with the 'unset' command. + +The 'array' command provides several features for dealing +with arrays, such as querying the names of all the elements of +the array and converting between an array and a list. + +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. Either '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), or the variable +may be explicitly scoped with the '::' prefix. For example + + set a 1 + set b 2 + proc p {} { + set c 3 + global a + + puts "$a $::b $c" + } + p + +will output: + + 1 2 3 + +ARRAYS AS LISTS IN JIM +---------------------- +Unlike Tcl, Jim can automatically convert between a list (with an even +number of elements) and an array value. This is similar to the way Tcl +can convert between a string and a list. + +For example: + + set a {1 one 2 two} + puts $a(2) + +will output: + + two + +Thus 'array set' is equivalent to 'set' when the variable does not +exist or is empty. + +The reverse is also true where an array will be converted into +a list. + + set a(1) one; set a(2) two + puts $a + +will output: + + 1 one 2 two + +DICTIONARY VALUES +----------------- +Tcl 8.5 introduced the dict command, and Jim Tcl has added a version +of this command. Dictionaries provide efficient access to key-value +pairs, just like arrays, but dictionaries are pure values. This +means that you can pass them to a procedure just as a list or a +string. Tcl dictionaries are therefore much more like Tcl lists, +except that they represent a mapping from keys to values, rather +than an ordered sequence. + +You can nest dictionaries, so that the value for a particular key +consists of another dictionary. That way you can elegantly build +complicated data structures, such as hierarchical databases. You +can also combine dictionaries with other Tcl data structures. For +instance, you can build a list of dictionaries that themselves +contain lists. + +Dictionaries are values that contain an efficient, order-preserving +mapping from arbitrary keys to arbitrary values. Each key in the +dictionary maps to a single value. They have a textual format that +is exactly that of any list with an even number of elements, with +each mapping in the dictionary being represented as two items in +the list. When a command takes a dictionary and produces a new +dictionary based on it (either returning it or writing it back into +the variable that the starting dictionary was read from) the new +dictionary will have the same order of keys, modulo any deleted +keys and with new keys added on to the end. When a string is +interpreted as a dictionary and it would otherwise have duplicate +keys, only the last value for a particular key is used; the others +are ignored, meaning that, "apple banana" and "apple carrot apple +banana" are equivalent dictionaries (with different string +representations). + +Note that in Jim, arrays are implemented as dictionaries. +Thus automatic conversion between lists and dictionaries applies +as it does for arrays. + + jim> dict set a 1 one + 1 one + jim> dict set a 2 two + 1 one 2 two + jim> puts $a + 1 one 2 two + jim> puts $a(2) + two + jim> dict set a 3 T three + 1 one 2 two 3 {T three} + +See the 'dict' command for more details. + +GARBAGE COLLECTION, REFERENCES, LAMBDA +-------------------------------------- +Unlike Tcl, Jim has some sophistocated support for functional programming. +These are described briefly below. + +More information may be found at http://wiki.tcl.tk/13847 + +References +~~~~~~~~~~ +A reference can be thought of as holding a value with one level of indirection, +where the value may be garbage collected when unreferenced. +Consider the following example: + + jim> set r [ref "One String" test] + <reference.<test___>.00000000000000000000> + jim> getref $r + One String + +The operation 'ref' creates a references to the value specfied by the +first argument. (The second argument is a "type" used for documentation purposes). + +The operation 'getref' is the dereferencing operation which retrieves the value +stored in the reference. + + jim> setref $r "New String" + New String + jim> getref $r + New String + +The operation 'setref' replaces the value stored by the reference. If the old value +is no longer accessible by any reference, it will eventually be automatically be garbage +collected. + +Garbage Collection +~~~~~~~~~~~~~~~~~~ +Normally, all values in Tcl are passed by value. As such values are copied and released +automatically as necessary. + +With the introduction of references, it is possible to create values whose lifetime +transcend their scope. To support this, case, the Jim system will periodically identify +and discard objects which are no longer accessible by any reference. + +The 'collect' command may be used to force garbage collection. Consider a reference created +with a finalizer: + + jim> proc f {ref value} { puts "Finaliser called for $ref,$value" } + jim> set r [ref "One String" test f] + <reference.<test___>.00000000000 + jim> collect + 0 + jim> set r "" + jim> collect + Finaliser called for <reference.<test___>.00000000000,One String + 1 + +Note that once the reference, 'r', was modified so that it no longer +contained a reference to the value, the garbage collector discarded +the value (after calling the finalizer). + +The finalizer for a reference may be examined or changed with the 'finalize' command + + jim> finalize $r + f + jim> finalize $r newf + newf + +Lambda +~~~~~~ +Jim provides a garbage collected lambda function. This is a procedure +which is able to create an anonymous procedure. Consider: + + jim> set f [lambda {a} {{x 0}} { incr x $a }] + jim> $f 1 + 1 + jim> $f 2 + 3 + jim> set f "" + +This create an anonymous procedure (with the name stored in 'f'), with a static variable +which is incremented by the supplied value and the result returned. + +Once the procedure name is no longer accessible, it will automatically be deleted +when the garbage collector runs. + +The procedure may also be delete immediately by renaming it "". e.g. + + jim> rename $f "" + +BUILT-IN COMMANDS +----------------- +The Tcl library provides the following built-in commands, which will +be available in any application using Tcl. In addition to these +built-in commands, there may be additional commands defined by each +application, plus commands defined as Tcl procedures. + +In the command syntax descriptions below, words in +*boldface*+ are +literals that you type verbatim to Tcl. + +Words in +'italics'+ are meta-symbols; they serve as names for any of +a range of values that you can type. + +Optional arguments or groups of arguments are indicated by enclosing them +in +?question-marks?+. + +Ellipses (+...+) indicate that any number of additional +arguments or groups of arguments may appear, in the same format +as the preceding argument(s). + +[[CommandIndex]] +Command Index +~~~~~~~~~~~~~ +// @INSERTINDEX@ + +alarm +~~~~~ ++*alarm* 'seconds'+ + +Delivers the 'SIGALRM' signal to the process after the given +number of seconds. If the platform supports 'ularm(3)' then +the argument may be a floating point value. Otherwise it must +be an integer. + +Note that unless a signal handler for 'SIGALRM' has been installed +(see 'signal'), the process will exit on this signal. + +alias +~~~~~ ++*alias* 'name args...'+ + +Creates a single word alias (proc) for one or more words. For example, +the following creates an alias for the command 'info exists'. + + alias e info exists + if {[e var]} { + ... + } + +'alias' returns *name*, allowing it to be used with 'local. + +See also 'proc', 'curry', 'lambda', 'local'. + +append +~~~~~~ ++*append* 'varName value ?value value ...?'+ + +Append all of the *value* arguments to the current value +of variable *varName*. If *varName* doesn't exist, +it is given a value equal to the concatenation of all the +*value* arguments. + +This command provides an efficient way to build up long +variables incrementally. +For example, 'append a $b' is much more efficient than +'set a $a$b' if '$a' is long. + +array +~~~~~ ++*array* 'option arrayName ?arg arg ...?'+ + +This command performs one of several operations on the +variable given by *arrayName*. + +Note that in general, if the named array does not exist, the *array* command behaves +as though the array exists but is empty. + +The *option* argument determines what action is carried out by the +command. The legal *options* (which may be abbreviated) are: + ++*array exists* 'arrayName'+:: + Returns 1 if arrayName is an array variable, 0 if there is + no variable by that name. This command is essentially + identical to 'info exists' + ++*array get* 'arrayName ?pattern?'+:: + Returns a list containing pairs of elements. The first + element in each pair is the name of an element in arrayName + and the second element of each pair is the value of the + array element. The order of the pairs is undefined. If + pattern is not specified, then all of the elements of the + array are included in the result. If pattern is specified, + then only those elements whose names match pattern (using + the matching rules of string match) are included. If arrayName + isn't the name of an array variable, or if the array contains + no elements, then an empty list is returned. + ++*array names* 'arrayName ?pattern?'+:: + Returns a list containing the names of all of the elements + in the array that match pattern. If pattern is omitted then + the command returns all of the element names in the array. + If pattern is specified, then only those elements whose + names match pattern (using the matching rules of string + match) are included. If there are no (matching) elements + in the array, or if arrayName isn't the name of an array + variable, then an empty string is returned. + ++*array set* 'arrayName list'+:: + Sets the values of one or more elements in arrayName. list + must have a form like that returned by array get, consisting + of an even number of elements. Each odd-numbered element + in list is treated as an element name within arrayName, and + the following element in list is used as a new value for + that array element. If the variable arrayName does not + already exist and list is empty, arrayName is created with + an empty array value. + ++*array size* 'arrayName'+:: + Returns the number of elements in the array. If arrayName + isn't the name of an array then 0 is returned. + ++*array unset* 'arrayName ?pattern?'+:: + Unsets all of the elements in the array that match pattern + (using the matching rules of string match). If arrayName + isn't the name of an array variable or there are no matching + elements in the array, no error will be raised. If pattern + is omitted and arrayName is an array variable, then the + command unsets the entire array. The command always returns + an empty string. + +break +~~~~~ ++*break*+ + +This command may be invoked only inside the body of a loop command +such as 'for' or 'foreach' or 'while'. It returns a +JIM_BREAK+ code +to signal the innermost containing loop command to return immediately. + +case +~~~~ ++*case* 'string' ?*in*? 'patList body ?patList body ...?'+ + ++*case* 'string' ?*in*? {'patList body ?patList body ...?'}+ + +*Note* that the switch command should generally be preferred unless compatibility +with Tcl 6.x is desired. + +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. + +Two syntaxes are provided. + +The first uses a separate argument for each of the patterns and commands; +this form is convenient if substitutions are desired on some of the +patterns or commands. + +The second form places all of the patterns and commands together into +a single argument; the argument must have proper list structure, with +the elements of the list being the patterns and commands. + +The second form makes it easy to construct multi-line case commands, +since the braces around the whole list make it unnecessary to include a +backslash at the end of each line. + +Since the *patList* arguments are in braces in the second form, +no command or variable substitutions are performed on them; this makes +the behavior of the second form different than the first form in some +cases. + +Below are some examples of 'case' commands: + + case abc in {a b} {format 1} default {format 2} a* {format 3} + +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 +~~~~~ ++*catch* '?-?no?code ...?' *?--?* 'command ?resultVarName? ?optionsVarName?'+ + +The 'catch' command may be used to prevent errors from aborting +command interpretation. 'Catch' evalues *command*, and returns a ++JIM_OK+ code, regardless of any errors that might occur while +executing *command* (with the possible exception of +JIM_SIGNAL+ - +see below). + +The return value from 'catch' is a decimal string giving the code +returned by the Tcl interpreter after executing *command*. This +will be '0' (+JIM_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 jim.h for the definitions of code values, or the +'info returncodes' command). + +If the *resultVarName* 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). + +If the *optionsVarName* argument is given, then it gives the name +of a variable; 'catch' will set the value of the variable to a +dictionary. For any return code other than +JIM_RETURN+, the value +for the key +-code+ will be set to the return code. For +JIM_RETURN+ +it will be set to the code given in 'return -code'. Additionally, +for the return code +JIM_ERR+, the value of the key +-errorinfo+ +will contain the current stack trace (the same result as 'info +stacktrace') and the value of the key +-level+ will be the current +return level (see 'return -level'). This can be useful to rethrow an error: + + if {[catch {...} msg opts]} { + ...maybe do something with the error... + incr opts(-level) + return {*}$opts $msg + } + +Normally 'catch' will *not* catch any of the codes +JIM_EXIT+, +JIM_EVAL+ or +JIM_SIGNAL+. +The set of codes which will be caught may be modified by specifying the one more codes before +*command*. + +e.g. To catch +JIM_EXIT+ but not +JIM_BREAK+ or +JIM_CONTINUE+ + + catch -exit -nobreak -nocontinue -- { ... } + +The use of +--+ is optional. It signifies that no more return code options follow. + +Note that if a signal marked as 'signal handle' is caught with 'catch -signal', the return value +(stored in *resultVarName*) is name of the signal caught. + +cd +~~ ++*cd* 'dirName'+ + +Change the current working directory to *dirName*. + +Returns an empty string. + +This command can potentially be disruptive to an application, so it may +be removed in some applications. + +clock +~~~~~ ++*clock seconds*+:: + Returns the current time as seconds since the epoch. + ++*clock format* 'seconds' ?*-format* 'format?'+:: + Format the given time (seconds since the epoch) according to the given + format. See strftime(3) for supported formats. + If no format is supplied, "%c" is used. + ++*clock scan* 'str' *-format* 'format'+:: + Scan the given time string using the given format string. + See strptime(3) for supported formats. + +close +~~~~~ ++*close* 'fileId'+ + ++'fileId' *close*+ + +Closes the file given by *fileId*. +*fileId* must be the return value from a previous invocation +of the 'open' command; after this command, it should not be +used anymore. + +collect +~~~~~~~ ++*collect*+ + +Normally reference garbage collection is automatically performed periodically. +However it may be run immediately with the 'collect' command. + +See GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail. + +concat +~~~~~~ ++*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 +~~~~~~~~ ++*continue*+ + +This command may be invoked only inside the body of a loop command such +as 'for' or 'foreach' or 'while'. It returns a +JIM_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. + +curry +~~~~~ ++*alias* 'args...'+ + +Similar to 'alias' except it creates an anonymous procedure (lambda) instead of +a named procedure. + +the following creates a local, unnamed alias for the command 'info exists'. + + set e [local curry info exists] + if {[$e var]} { + ... + } + +'curry' returns the name of the procedure. + +See also 'proc', 'alias', 'lambda', 'local'. + +dict +~~~~ ++*dict* 'option ?arg arg ...?'+ + +Performs one of several operations on dictionary values. + +The *option* argument determines what action is carried out by the +command. The legal *options* are: + +*dict create* '?key value ...?'+:: + Create and return a new dictionary value that contains each of + the key/value mappings listed as arguments (keys and values + alternating, with each key being followed by its associated + value.) + +*dict exists* 'dictionary key ?key ...?'+:: + Returns a boolean value indicating whether the given key (or path + of keys through a set of nested dictionaries) exists in the given + dictionary value. This returns a true value exactly when 'dict get' + on that path will succeed. + +*dict get* 'dictionary ?key ...?'+:: + Given a dictionary value (first argument) and a key (second argument), + this will retrieve the value for that key. Where several keys are + supplied, the behaviour of the command shall be as if the result + of 'dict get $dictVal $key' was passed as the first argument to + dict get with the remaining arguments as second (and possibly + subsequent) arguments. This facilitates lookups in nested dictionaries. + If no keys are provided, dict would return a list containing pairs + of elements in a man- ner similar to array get. That is, the first + element of each pair would be the key and the second element would + be the value for that key. It is an error to attempt to retrieve + a value for a key that is not present in the dictionary. + +*dict set* 'dictionaryName key ?key ...? value'+:: + This operation takes the *name* of a variable containing a dictionary + value and places an updated dictionary value in that variable + containing a mapping from the given key to the given value. When + multiple keys are present, this operation creates or updates a chain + of nested dictionaries. + +*dict unset* 'dictionaryName key ?key ...? value'+:: + This operation (the companion to 'dict set') takes the name of a + variable containing a dictionary value and places an updated + dictionary value in that variable that does not contain a mapping + for the given key. Where multiple keys are present, this describes + a path through nested dictionaries to the mapping to remove. At + least one key must be specified, but the last key on the key-path + need not exist. All other components on the path must exist. + +env +~~~ ++*env* '?name? ?default?'+ + +If *name* is supplied, returns the value of *name* from the initial +environment (see getenv(3)). An error is returned if *name* does not +exist in the environment, unless *default* is supplied - in which case +that value is returned instead. + +If no arguments are supplied, returns a list of all environment variables +and their values as +{name value ...}+ + +See also the global variable '::env' + +eof +~~~ ++*eof* 'fileId'+ + ++'fileId' *eof*+ + +Returns 1 if an end-of-file condition has occurred on *fileId*, +0 otherwise. + +*fileId* must have been the return value from a previous call to 'open', +or it may be 'stdin', 'stdout', or 'stderr' to refer to one of the +standard I/O channels. + +error +~~~~~ ++*error* 'message ?stacktrace?'+ + +Returns a +JIM_ERR+ code, which causes command interpretation to be +unwound. *message* is a string that is returned to the application +to indicate what went wrong. + +If the *stacktrace* argument is provided and is non-empty, +it is used to initialize the stacktrace. + +This feature is most useful in conjunction with the 'catch' command: +if a caught error cannot be handled successfully, *stacktrace* can be used +to return a stack trace reflecting the original point of occurrence +of the error: + + catch {...} errMsg + ... + error $errMsg [info stacktrace] + +See also 'errorInfo', 'info stacktrace', 'catch' and 'return' + +errorInfo +~~~~~~~~~ ++*errorInfo* 'error ?stacktrace?'+ + +Returns a human-readable representation of the given error message and stack trace. +Typical usage is: + + if {[catch {...} error]} { + puts stderr [errorInfo $error [info stacktrace]] + exit 1 + } + +See also 'error'. + +eval +~~~~ ++*eval* 'arg ?arg ...?'+ + +'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 +~~~~ ++*exec* 'arg ?arg ...?'+ + +This command treats its arguments as the specification +of one or more UNIX commands to execute as subprocesses. +The commands take the form of a standard shell pipeline; +'|' arguments separate commands in the +pipeline and cause standard output of the preceding command +to be piped into standard input of the next command (or '|&' for +both standard output and standard error). + +Under normal conditions the result of the 'exec' command +consists of the standard output produced by the last command +in the pipeline. + +If any of the commands in the pipeline exit abnormally or +are killed or suspended, then 'exec' will return an error +and the error message will include the pipeline's output followed by +error messages describing the abnormal terminations. + +If any of the commands writes to its standard error file, +then 'exec' will return an error, and the error message +will include the pipeline's output, followed by messages +about abnormal terminations (if any), followed by the standard error +output. + +If the last character of the result or error message +is a newline then that character is deleted from the result +or error message for consistency with normal +Tcl return values. + +An *arg* may have one of the following special forms: + ++>filename+:: + The standard output of the last command in the pipeline + is redirected to the file. In this situation 'exec' + will normally return an empty string. + ++>>filename+:: + As above, but append to the file. + ++>@fileId+:: + The standard output of the last command in the pipeline is + redirected to the given (writable) file descriptor (e.g. stdout, + stderr, or the result of 'open'). In this situation 'exec' + will normally return an empty string. + ++2>filename+:: + The standard error of the last command in the pipeline + is redirected to the file. + ++2>>filename+:: + As above, but append to the file. + ++2>@fileId+:: + The standard error of the last command in the pipeline is + redirected to the given (writable) file descriptor. + ++2>@1+:: + The standard error of the last command in the pipeline is + redirected to the same file descriptor as the standard output. + ++>&filename+:: + Both the standard output and standard error of the last command + in the pipeline is redirected to the file. + ++>>&filename+:: + As above, but append to the file. + ++<filename+:: + The standard input of the first command in the pipeline + is taken from the file. + ++<<string+:: + The standard input of the first command is taken as the + given immediate value. + ++<@fileId+:: + The standard input of the first command in the pipeline + is taken from the given (readable) file descriptor. + +If there is no redirection of standard input, standard error +or standard output, these are connected to the corresponding +input or output of the application. + +If the last *arg* is '&' then the command will be +executed in background. +In this case the standard output from the last command +in the pipeline will +go to the application's standard output unless +redirected in the command, and error output from all +the commands in the pipeline will go to the application's +standard error file. The return value of exec in this case +is a list of process ids (pids) in the pipeline. + +Each *arg* becomes one word for a command, except for +'|', '<', '<<', '>', and '&' arguments, and the +arguments that follow '<', '<<', and '>'. + +The first word in each command is taken as the command name; +the directories in the PATH environment variable are searched for +an executable by the given name. + +No 'glob' expansion or other shell-like substitutions +are performed on the arguments to commands. + +exit +~~~~ ++*exit* '?returnCode?'+ + +Terminate the process, returning *returnCode* to the +parent as the exit status. + +If *returnCode* isn't specified then it defaults +to 0. + +Note that exit can be caught with *catch*. + +expr +~~~~ ++*expr* 'arg'+ + +Calls the expression processor to evaluate *arg*, and returns +the result as a string. See the section EXPRESSIONS above. + +file +~~~~ ++*file* 'option name ?arg arg ...?'+ + +Operate on a file or a file name. *name* is the name of a file. + +*Option* indicates what to do with the file name. Any unique +abbreviation for *option* is acceptable. The valid options are: + ++*file atime* 'name'+:: + Return a decimal string giving the time at which file *name* + was last accessed. The time is measured in the standard UNIX + fashion as seconds from a fixed starting time (often January 1, 1970). + If the file doesn't exist or its access time cannot be queried then an + error is generated. + ++*file copy ?-force?* 'source target'+:: + Copies file *source* to file *target*. The source file must exist. + The target file must not exist, unless *-force* is specified. + ++*file delete* 'name ...'+:: + Deletes file or directory *name*. If the file or directory doesn't exist, nothing happens. + If it can't be deleted, an error is generated. Non-empty directories will not be deleted. + ++*file dirname* 'name'+:: + 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 '.' (a single dot). If the last slash in *name* is its first + character, then return '/'. + ++*file executable* 'name'+:: + Return '1' if file *name* is executable by + the current user, '0' otherwise. + ++*file exists* 'name'+:: + Return '1' if file *name* exists and the current user has + search privileges for the directories leading to it, '0' otherwise. + ++*file extension* 'name'+:: + 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 isdirectory* 'name'+:: + Return '1' if file *name* is a directory, + '0' otherwise. + ++*file isfile* 'name'+:: + Return '1' if file *name* is a regular file, + '0' otherwise. + ++*file join* 'arg arg ...'+:: + Joins multiple path components. Note that if any components is + an absolute path, the preceding components are ignored. + Thus 'file join /tmp /root' returns '/root'. + ++*file lstat* 'name varName'+:: + Same as 'stat' option (see below) except uses the *lstat* + kernel call instead of *stat*. This means that if *name* + refers to a symbolic link the information returned in *varName* + is for the link rather than the file it refers to. On systems that + don't support symbolic links this option behaves exactly the same + as the 'stat' option. + ++*file mkdir* 'dir1 ?dir2? ...'+:: + Creates each directory specified. For each pathname *dir* specified, + this command will create all non-existing parent directories + as well as *dir* itself. If an existing directory is specified, + then no action is taken and no error is returned. Trying to + overwrite an existing file with a directory will result in an + error. Arguments are processed in the order specified, halting + at the first error, if any. + ++*file mtime* 'name'+:: + Return a decimal string giving the time at which file *name* + was last modified. The time is measured in the standard UNIX + fashion as seconds from a fixed starting time (often January 1, 1970). + If the file doesn't exist or its modified time cannot be queried then an + error is generated. + ++*file normalize* 'name'+:: + Return the normalized path of *name*. See realpath(3). + ++*file owned* 'name'+:: + Return '1' if file *name* is owned by the current user, + '0' otherwise. + ++*file readable* 'name'+:: + Return '1' if file *name* is readable by + the current user, '0' otherwise. + ++*file readlink* 'name'+:: + Returns the value of the symbolic link given by *name* (i.e. the + name of the file it points to). If + *name* isn't a symbolic link or its value cannot be read, then + an error is returned. On systems that don't support symbolic links + this option is undefined. + ++*file rename* 'oldname' 'newname'+:: + Renames the file from the old name to the new name. + ++*file rootname* 'name'+:: + 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 size* 'name'+:: + Return a decimal string giving the size of file *name* in bytes. + If the file doesn't exist or its size cannot be queried then an + error is generated. + ++*file stat* 'name varName'+:: + Invoke the 'stat' kernel call on *name*, and use the + variable given by *varName* to hold information returned from + the kernel call. + *VarName* is treated as an array variable, + and the following elements of that variable are set: 'atime', + 'ctime', 'dev', 'gid', 'ino', 'mode', 'mtime', + 'nlink', 'size', 'type', 'uid'. + Each element except 'type' is a decimal string with the value of + the corresponding field from the 'stat' return structure; see the + manual entry for 'stat' for details on the meanings of the values. + The 'type' element gives the type of the file in the same form + returned by the command 'file type'. + This command returns an empty string. + ++*file tail* 'name'+:: + Return all of the characters in *name* after the last slash. + If *name* contains no slashes then return *name*. + ++*file tempfile* '?template?'+:: + Creates and returns the name of a unique temporary file. If *template* is omitted, a + default template will be used to place the file in /tmp. See mkstemp(3) for + the format of the template and security concerns. + ++*file type* 'name'+:: + Returns a string giving the type of file *name*, which will be + one of 'file', 'directory', 'characterSpecial', + 'blockSpecial', 'fifo', 'link', or 'socket'. + ++*file writable* 'name'+:: + 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 exists foo]} then {error {bad file name}} else {...} + +finalize +~~~~~~~~ ++*finalize* 'reference ?command?'+ + +If *command* is omitted, returns the finalizer command for the given reference. + +Otherwise, sets a new finalizer command for the given reference. *command* may be +the empty string to remove the current finalizer. + +The reference must be a valid reference create with the 'ref' +command. + +See GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail. + +flush +~~~~~ ++*flush* 'fileId'+ + ++'fileId' *flush*+ + +Flushes any output that has been buffered for *fileId*. *fileId* must +have been the return value from a previous call to 'open', or it may be +'stdout' or 'stderr' to access one of the standard I/O streams; it must +refer to a file that was opened for writing. This command returns an +empty string. + +for +~~~ ++*for* 'start test next body'+ + +'For' is a looping command, similar in structure to the C 'for' statement. +The *start*, *next*, and *body* arguments must be Tcl command strings, +and *test* is an expression string. + +The 'for' command first invokes the Tcl interpreter to execute *start*. +Then it repeatedly evaluates *test* as an expression; if the result is +non-zero it invokes the Tcl interpreter on *body*, then invokes the Tcl +interpreter on *next*, then repeats the loop. The command terminates +when *test* evaluates to 0. + +If a 'continue' command is invoked within *body* then any remaining +commands in the current execution of *body* are skipped; processing +continues by invoking the Tcl interpreter on *next*, then evaluating +*test*, and so on. + +If a 'break' command is invoked within *body* or *next*, then the 'for' +command will return immediately. + +The operation of 'break' and 'continue' are similar to the corresponding +statements in C. + +'For' returns an empty string. + +foreach +~~~~~~~ ++*foreach* 'varName list body'+ + ++*foreach* 'varList list ?varList2 list2 ...? body'+ + +In this command, *varName* is the name of a variable, *list* +is a list of values to assign to *varName*, and *body* is a +collection of Tcl commands. + +For each field in *list* (in order from left to right),'foreach' assigns +the contents of the field to *varName* (as if the 'lindex' command +had been used to extract the field), then calls the Tcl interpreter to +execute *body*. + +If instead of being a simple name, *varList* is used, multiple assignments +are made each time through the loop, one for each element of *varList*. + +For example, if there are two elements in *varList* and six elements in +the list, the loop will be executed three times. + +If the length of the list doesn't evenly divide by the number of elements +in *varList*, the value of the remaining variables in the last iteration +of the loop are undefined. + +The 'break' and 'continue' statements may be invoked inside *body*, +with the same effect as in the 'for' command. + +'foreach' returns an empty string. + +format +~~~~~~ ++*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. + +getref +~~~~~~ ++*getref* 'reference'+ + +Returns the string associated with *reference*. The reference must +be a valid reference create with the 'ref' command. + +See GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail. + +gets +~~~~ ++*gets* 'fileId ?varName?'+ + ++'fileId' *gets* '?varName?'+ + +Reads the next line from the file given by *fileId* and discards +the terminating newline character. + +If *varName* is specified, then the line is placed in the variable +by that name and the return value is a count of the number of characters +read (not including the newline). + +If the end of the file is reached before reading +any characters then -1 is returned and *varName* is set to an +empty string. + +If *varName* is not specified then the return value will be +the line (minus the newline character) or an empty string if +the end of the file is reached before reading any characters. + +An empty string will also be returned if a line contains no characters +except the newline, so 'eof' may have to be used to determine +what really happened. + +If the last character in the file is not a newline character, then +'gets' behaves as if there were an additional newline character +at the end of the file. + +*fileId* must be 'stdin' or the return value from a previous +call to 'open'; it must refer to a file that was opened +for reading. + +glob +~~~~ ++*glob* ?*-nocomplain*? 'pattern ?pattern ...?'+ + +This command performs filename globbing, using csh rules. The returned +value from 'glob' is the list of expanded filenames. + +If '-nocomplain' is specified as the first argument then an empty +list may be returned; otherwise an error is returned if the expanded +list is empty. The '-nocomplain' argument must be provided +exactly: an abbreviation will not be accepted. + +global +~~~~~~ + ++*global* 'varName ?varName ...?'+ + +This command is ignored unless a Tcl procedure is being interpreted. +If so, then it declares each given *varName* to be a global variable +rather than a local one. For the duration of the current procedure +(and only while executing in the current procedure), any reference to +*varName* will be bound to a global variable instead +of a local one. + +An alternative to using 'global' is to use the '::' prefix +to explicitly name a variable in the global scope. + +if +~~ ++*if* 'expr1' ?*then*? 'body1' *elseif* 'expr2' ?*then*? 'body2' *elseif* ... ?*else*? ?'bodyN'?+ + +The 'if' command evaluates *expr1* as an expression (in the same way +that 'expr' evaluates its argument). The value of the expression must +be numeric; if it is non-zero then *body1* is executed by passing it to +the Tcl interpreter. + +Otherwise *expr2* is evaluated as an expression and if it is non-zero +then *body2* is executed, and so on. + +If none of the expressions evaluates to non-zero then *bodyN* is executed. + +The 'then' and 'else' arguments are optional 'noise words' to make the +command easier to read. + +There may be any number of 'elseif' clauses, including zero. *bodyN* +may also be omitted as long as 'else' is omitted too. + +The return value from the command is the result of the body script that +was executed, or an empty string if none of the expressions was non-zero +and there was no *bodyN*. + +incr +~~~~ ++*incr* 'varName ?increment?'+ + +Increment the value stored in the variable whose name is *varName*. +The value of the variable must be integral. + +If *increment* is supplied then its value (which must be an +integer) is added to the value of variable *varName*; otherwise +1 is added to *varName*. + +The new value is stored as a decimal string in variable *varName* +and also returned as result. + +If the variable does not exist, the variable is implicitly created +and set to +0+ first. + +info +~~~~ + ++*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 complete* 'command'+:: + Returns 1 if *command* is a complete Tcl command in the sense of + having no unclosed quotes, braces, brackets or array element names, + If the command doesn't appear to be complete then 0 is returned. + This command is typically used in line-oriented input environments + to allow users to type in commands that span multiple lines; if the + command isn't complete, the script can delay evaluating it until additional + lines have been typed to complete the command. + ++*info exists* 'varName'+:: + Returns '1' if the variable named *varName* exists in the + current context (either as a global or local variable), returns '0' + otherwise. + ++*info frame* ?'number'?+:: + If *number* is not specified, this command returns a number + which is the same result as 'info level' - the current stack frame level. + If *number* is specified, then the result is a list consisting of the procedure, + filename and line number 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). + The level has an identical meaning to 'info level'. + ++*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 hostname*+:: + An alias for 'os.gethostname' for compatibility with Tcl 6.x + ++*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. Variables defined with the 'global' + and 'upvar' commands will not be returned. If *pattern* is + specified, only those names matching *pattern* are returned. + Matching is determined using the same rules as for 'string match'. + ++*info nameofexecutable*+:: + Returns the name of the binary file from which the application + was invoked, either + as a path relative to the current directory or as a full + path. If the path can't be determined, returns the empty + string. + ++*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 returncodes* ?'code'?+:: + Returns a list representing the mapping of standard return codes + to names. e.g. +{0 ok 1 error 2 return ...}+. If a code is given, + instead returns the name for the given code. + ++*info script*+:: + If a Tcl script file is currently being evaluated (i.e. there is a + call to 'Jim_EvalFile' active or there is an active invocation + of the 'source' command), then this command returns the name + of the innermost file being processed. Otherwise the command returns an + empty string. + ++*info source* 'script'+:: + Returns the original source location of the given script as a list of + +{filename linenumber}+. If the source location can't be determined, the + list +{{} 0}+ is returned. + ++*info stacktrace*+:: + After an error is caught with 'catch', returns the stack trace as a list + of +{procedure filename line ...}+. + ++*info version*+:: + Returns the version number for this version of Jim in the form *x.yy*. + ++*info vars* ?'pattern'?+:: + If *pattern* isn't specified, + returns a list of all the names of currently-visible variables, including + both locals and currently-visible globals. + If *pattern* is specified, only those names matching *pattern* + are returned. Matching is determined using the same rules as for + 'string match'. + +join +~~~~ ++*join* 'list ?joinString?'+ + +The *list* argument must be a valid Tcl list. This command returns the +string formed by joining all of the elements of *list* together with +*joinString* separating each adjacent pair of elements. + +The *joinString* argument defaults to a space character. + +kill +~~~~ ++*kill* ?'SIG'|*-0*? 'pid'+ + +Sends the given signal to the process identified by *pid*. + +The signal may be specified by name or number in one of the following forms: + +* +TERM+ +* +SIGTERM+ +* +-TERM+ +* +15+ +* +-15+ + +The signal name may be in either upper or lower case. + +The special signal name '-0' simply checks that a signal *could* be sent. + +If no signal is specified, SIGTERM is used. + +An error is raised if the signal could not be delivered. + +lambda +~~~~~~ ++*lambda* 'args ?statics? body'+ + +The 'lambda' command is identical to 'proc', except rather than +creating a named procedure, it creates an anonymous procedure and returns +the name of the procedure. + +See 'proc' and GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail. + +lappend +~~~~~~~ ++*lappend* 'varName value ?value value ...?'+ + +Treat the variable given by *varName* as a list and append each of +the *value* arguments to that list as a separate element, with spaces +between elements. + +If *varName* doesn't exist, it is created as a list with elements given +by the *value* arguments. 'lappend' is similar to 'append' except that +each *value* is appended as a list element rather than raw text. + +This command provides a relatively efficient way to build up large lists. +For example, 'lappend a $b' is much more efficient than + + set a [concat $a [list $b]] + +when '$a' is long. + +lassign +~~~~~~~ ++*lassign* 'list varName ?varName? ...'+ + +This command treats the value *list* as a list and assigns successive elements from that list to +the variables given by the *varName* arguments in order. If there are more variable names than +list elements, the remaining variables are set to the empty string. If there are more list ele- +ments than variables, a list of unassigned elements is returned. + + jim> lassign {1 2 3} a b; puts a=$a,b=$b + 3 + a=1,b=2 + +local +~~~~~ ++*local* 'args'+ + +Executes it's arguments as a command (per 'eval') and considers the return +value to be a procedure name, which is marked as having local scope. +This means that when the current procedure exits, the specified +procedure is deleted. This can be useful with 'lambda' or simply +local procedures. + +In this example, a local procedure is created. Note that the procedure +continues to have global scope while it is active. + + proc outer {} { + # proc ... returns "inner" which is marked local + local proc inner {} { + # will be deleted when 'outer' exits + } + + inner + ... + } + +In this example, the lambda is deleted at the end of the procedure rather +than waiting until garbage collection. + + proc outer {} { + set x [lambda inner {args} { + # will be deleted when 'outer' exits + }] + # Use 'function' here which simply returns $x + local function $x + + $x ... + ... + } + +lindex +~~~~~~ ++*lindex* 'list index'+ + +Treats *list* as a Tcl list and returns element *index* from it +(0 refers to the first element of the list). +See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *index*. + +In extracting the element, *lindex* observes the same rules concerning +braces and quotes and backslashes as the Tcl command interpreter; however, +variable substitution and command substitution do not occur. + +If *index* is negative or greater than or equal to the number of elements +in *value*, then an empty string is returned. + +linsert +~~~~~~~ ++*linsert* 'list index element ?element element ...?'+ + +This command produces a new list from *list* by inserting all +of the *element* arguments just before the element *index* +of *list*. Each *element* argument will become +a separate element of the new list. If *index* is less than +or equal to zero, then the new elements are inserted at the +beginning of the list. If *index* is greater than or equal +to the number of elements in the list, then the new elements are +appended to the list. + +See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *index*. + +list +~~~~ + ++*list* 'arg ?arg ...?'+ + +This command returns a list comprised of all the arguments, *arg*. 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} + +llength +~~~~~~~ ++*llength* 'list'+ + +Treats *list* as a list and returns a decimal string giving +the number of elements in it. + +lset +~~~~ ++*lset* 'varName ?index ..? newValue'+ + +Sets an element in a list. + +The 'lset' command accepts a parameter, *varName*, which it interprets +as the name of a variable containing a Tcl list. It also accepts +zero or more indices into the list. Finally, it accepts a new value +for an element of varName. If no indices are presented, the command +takes the form: + + lset varName newValue + +In this case, newValue replaces the old value of the variable +varName. + +When presented with a single index, the 'lset' command +treats the content of the varName variable as a Tcl list. It addresses +the index'th element in it (0 refers to the first element of the +list). When interpreting the list, 'lset' observes the same rules +concerning braces and quotes and backslashes as the Tcl command +interpreter; however, variable substitution and command substitution +do not occur. The command constructs a new list in which the +designated element is replaced with newValue. This new list is +stored in the variable varName, and is also the return value from +the 'lset' command. + +If index is negative or greater than or equal to the number of +elements in $varName, then an error occurs. + +See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *index*. + +If additional index arguments are supplied, then each argument is +used in turn to address an element within a sublist designated by +the previous indexing operation, allowing the script to alter +elements in sublists. The command, + + lset a 1 2 newValue + +replaces element 2 of sublist 1 with *newValue*. + +The integer appearing in each index argument must be greater than +or equal to zero. The integer appearing in each index argument must +be strictly less than the length of the corresponding list. In other +words, the 'lset' command cannot change the size of a list. If an +index is outside the permitted range, an error is reported. + +lmap +~~~~ + ++*lmap* 'varName list body'+ + ++*lmap* 'varList list ?varList2 list2 ...? body'+ + +'lmap' is a "collecting 'foreach'" which returns a list of its results. + +For example: + + jim> lmap i {1 2 3 4 5} {expr $i*$i} + 1 4 9 16 25 + jim> lmap a {1 2 3} b {A B C} {list $a $b} + {1 A} {2 B} {3 C} + +If the body invokes 'continue', no value is added for this iteration. +If the body invokes 'break', the loop ends and no more values are added. + +lrange +~~~~~~ ++*lrange* 'list first last'+ + +*List* must be a valid Tcl list. This command will return a new +list consisting of elements *first* through *last*, inclusive. + +See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *first* and *last*. + +If *last* is greater than or equal to the number of elements +in the list, then it is treated as if it were 'end'. + +If *first* is greater than *last* then an empty string +is returned. + +Note: 'lrange *list first first*' does not always produce the +same result as 'lindex *list first*' (although it often does +for simple fields that aren't enclosed in braces); it does, however, +produce exactly the same results as 'list [lindex *list first*]' + +lreplace +~~~~~~~~ + ++*lreplace* 'list first last ?element element ...?'+ + +Returns a new list formed by replacing one or more elements of +*list* with the *element* arguments. + +*First* gives the index in *list* of the first element +to be replaced. + +If *first* is less than zero then it refers to the first +element of *list*; the element indicated by *first* +must exist in the list. + +*Last* gives the index in *list* of the last element +to be replaced; it must be greater than or equal to *first*. + +See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *first* and *last*. + +The *element* arguments specify zero or more new arguments to +be added to the list in place of those that were deleted. + +Each *element* argument will become a separate element of +the list. + +If no *element* arguments are specified, then the elements +between *first* and *last* are simply deleted. + +lrepeat +~~~~~~~~ ++*lrepeat* 'number element1 ?element2 ...?'+ + +Build a list by repeating elements *number* times (which must be +a positive integer). + + jim> lrepeat 3 a b + a b a b a b + +lreverse +~~~~~~~~ ++*lreverse* 'list'+ + +Returns the list in reverse order. + + jim> lreverse {1 2 3} + 3 2 1 + +lsearch +~~~~~~~ ++*lsearch* '?options? list pattern'+ + +This command searches the elements *list* to see if one of them matches *pattern*. If so, the +command returns the index of the first matching element (unless the options -all, -inline or -bool are +specified.) If not, the command returns -1. The option arguments indicates how the elements of +the list are to be matched against pattern and must have one of the values below: + +*Note* that this command is different from Tcl in that default match type is '-exact' rather than '-glob'. + ++'-exact'+:: + *pattern* is a literal string that is compared for exact equality against each list element. + This is the default. + ++'-glob'+:: + *pattern* is a glob-style pattern which is matched against each list element using the same + rules as the string match command. + ++'-regexp'+:: + *pattern* is treated as a regular expression and matched against each list element using + the rules described by 'regexp'. + ++'-all'+:: + Changes the result to be the list of all matching indices (or all matching values if + '-inline' is specified as well). If indices are returned, the indices will be in numeric + order. If values are returned, the order of the values will be the order of those values + within the input list. + ++'-inline'+:: + The matching value is returned instead of its index (or an empty string if no value + matches). If '-all' is also specified, then the result of the command is the list of all + values that matched. The '-inline' and '-bool' options are mutually exclusive. + ++'-bool'+:: + Changes the result to '1' if a match was found, or '0' otherwise. If '-all' is also specified, + the result will be a list of '0' and '1' for each element of the list depending upon whether + the corresponding element matches. The '-inline' and '-bool' options are mutually exclusive. + ++'-not'+:: + This negates the sense of the match, returning the index (or value + if '-inline' is specified) of the first non-matching value in the + list. If '-bool' is also specified, the '0' will be returned if a + match is found, or '1' otherwise. If '-all' is also specified, + non-matches will be returned rather than matches. + ++'-nocase'+:: + Causes comparisons to be handled in a case-insensitive manner. + +lsort +~~~~~ ++*lsort* ?*-integer*|*-command* 'cmdname'? ?*-decreasing*|*-increasing*? 'list'+ + +Sort the elements of *list*, returning a new list in sorted order. +By default, ASCII sorting is used, with the result in increasing order. + +If *-integer* is specified, numeric sorting is used. + +If *-command cmdname* is specified, *cmdname* is treated as a +command name. For each comparison, *cmdname $value1 $value2* is called +which should return '-1' if *$value1* is less than *$value2*, '0' if +they are equal, or '1' otherwise. + +If *-decreasing* is specified, the resulting list is in the opposite +order to what it would be otherwise. *-increasing* is the default. + +open +~~~~ ++*open* 'fileName ?access?'+ + +Opens a file and returns an identifier +that may be used in future invocations +of commands like 'read', 'puts', and 'close'. +*fileName* gives the name of the file to open. + +The *access* argument indicates the way in which the file is to be accessed. +It may have any of the following values: + ++r+:: + Open the file for reading only; the file must already exist. + ++r++:: + Open the file for both reading and writing; the file must + already exist. + ++w+:: + Open the file for writing only. Truncate it if it exists. If it doesn't + exist, create a new file. + ++w++:: + Open the file for reading and writing. Truncate it if it exists. + If it doesn't exist, create a new file. + ++a+:: + Open the file for writing only. The file must already exist, and the file + is positioned so that new data is appended to the file. + ++a++:: + Open the file for reading and writing. If the file doesn't + exist, create a new empty file. Set the initial access position + to the end of the file. + +*Access* defaults to 'r'. + +If a file is opened for both reading and writing, then 'seek' +must be invoked between a read and a write, or vice versa. + +See also 'socket' + +package +~~~~~~~ ++*package provide* 'name ?version?'+ + +Indicates that the current script provides the package named *name*. +If no version is specified, '1.0' is used. + +Any script which provides a package may include this statement +as the first statement, although it is not required. + ++*package require* 'name ?version?'*+ + +Searches for the package with the given *name* by examining each path +in '$::auto_path' and trying to load '$path/$name.tcl'. + +If either file exists, it is loaded with 'source'. + +Typically '$::auto_path' contains the paths '.' and '/lib/jim'. + +pid +~~~ ++*pid*+ + +Returns the process identifier of the current process. + +proc +~~~~ ++*proc* 'name args ?statics? body'+ + +The 'proc' command creates a new Tcl command procedure, *name*. +When the new command is invoked, the contents of *body* will be executed. +Tcl interpreter. *args* specifies the formal arguments to the procedure. +If specified, *static*, declares static variables which are bound to the +procedure. + +See PROCEDURES for detailed information about Tcl procedures. + +The 'proc' command returns *name* (which is useful with 'local'). + +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. + +puts +~~~~ ++*puts* ?*-nonewline*? '?fileId? string'+ + ++'fileId' *puts* ?*-nonewline*? 'string'+ + +Writes the characters given by *string* to the file given +by *fileId*. *fileId* must have been the return +value from a previous call to 'open', or it may be +'stdout' or 'stderr' to refer to one of the standard I/O +channels; it must refer to a file that was opened for +writing. + +In the first form, if no *fileId* is specified then it defaults to 'stdout'. +'puts' normally outputs a newline character after *string*, +but this feature may be suppressed by specifying the '-nonewline' +switch. + +Output to files is buffered internally by Tcl; the 'flush' +command may be used to force buffered characters to be output. + +pwd +~~~ ++*pwd*+ + +Returns the path name of the current working directory. + +rand +~~~~ ++*rand* '?min? ?max?'+ + +Returns a random integer between *min* (defaults to 0) and *max* +(defaults to the maximum integer). + +If only one argument is given, it is interpreted as *max*. + +range +~~~~ ++*range* '?start? end ?step?'+ + +Returns a list of integers starting at *start* (defaults to 0) +and ranging up to but not including *end* in steps of *step* defaults to 1). + + jim> range 5 + 0 1 2 3 4 + jim> range 2 5 + 2 3 4 + jim> range 2 10 4 + 2 6 + jim> range 7 4 -2 + 7 5 + +read +~~~~ ++*read* ?*-nonewline*? 'fileId'+ + ++'fileId' *read* ?*-nonewline*?+ + ++*read* 'fileId numBytes'+ + ++'fileId' *read* 'numBytes'+ + + +In the first form, all of the remaining bytes are read from the file +given by *fileId*; they are returned as the result of the command. +If the '-nonewline' switch is specified then the last +character of the file is discarded if it is a newline. + +In the second form, the extra argument specifies how many bytes to read; +exactly this many bytes will be read and returned, unless there are fewer than +*numBytes* bytes left in the file; in this case, all the remaining +bytes are returned. + +*fileId* must be 'stdin' or the return value from a previous call +to 'open'; it must refer to a file that was opened for reading. + +regexp +~~~~~~ ++*regexp ?-nocase? ?-line? ?-indices? ?-start* 'offset'? *?-all? ?-inline? ?--?* 'exp string ?matchVar? ?subMatchVar subMatchVar ...?'+ + +Determines whether the regular expression *exp* matches part or +all of *string* and returns 1 if it does, 0 if it doesn't. + +See REGULAR EXPRESSIONS above for complete information on the +syntax of *exp* and how it is matched against *string*. + +If additional arguments are specified after *string* then they +are treated as the names of variables to use to return +information about which part(s) of *string* matched *exp*. +*matchVar* will be set to the range of *string* that +matched all of *exp*. The first *subMatchVar* will contain +the characters in *string* that matched the leftmost parenthesized +subexpression within *exp*, the next *subMatchVar* will +contain the characters that matched the next parenthesized +subexpression to the right in *exp*, and so on. + +Normally, *matchVar* and the each *subMatchVar* are set to hold the +matching characters from 'string', however see '-indices' and +'-inline' below. + +If there are more values for *subMatchVar* than parenthesized subexpressions +within *exp*, or if a particular subexpression in *exp* doesn't +match the string (e.g. because it was in a portion of the expression +that wasn't matched), then the corresponding *subMatchVar* will be +set to '"-1 -1"' if '-indices' has been specified or to an empty +string otherwise. + +The following switches modify the behaviour of *regexp* + ++*-nocase*+:: + Causes upper-case and lower-case characters to be treated as + identical during the matching process. + ++*-line*+:: + Use newline-sensitive matching. By default, newline + is a completely ordinary character with no special meaning in + either REs or strings. With this flag, '[^' bracket expressions + and '.' never match newline, a '^' anchor matches the null + string after any newline in the string in addition to its normal + function, and the '$' anchor matches the null string before any + newline in the string in addition to its normal function. + ++*-indices*+:: + Changes what is stored in the subMatchVars. Instead of + storing the matching characters from string, each variable + will contain a list of two decimal strings giving the indices + in string of the first and last characters in the matching + range of characters. + ++*-start* 'offset'+:: + Specifies a character index offset into the string at which to start + matching the regular expression. If '-indices' is + specified, the indices will be indexed starting from the + absolute beginning of the input string. *offset* will be + constrained to the bounds of the input string. + ++*-all*+:: + Causes the regular expression to be matched as many times as possible + in the string, returning the total number of matches found. If this + is specified with match variables, they will contain information + for the last match only. + ++*-inline*+:: + Causes the command to return, as a list, the data that would otherwise + be placed in match variables. When using '-inline', match variables + may not be specified. If used with '-all', the list will be concatenated + at each iteration, such that a flat list is always returned. For + each match iteration, the command will append the overall match + data, plus one element for each subexpression in the regular + expression. + ++*--*+:: + Marks the end of switches. The argument following this one will be + treated as *exp* even if it starts with a +-+. + +regsub +~~~~~~ ++*regsub ?-nocase? ?-all? ?-line? ?-start* 'offset'? ?*--*? 'exp string subSpec ?varName?'+ + +This command matches the regular expression *exp* against +*string* using the rules described in REGULAR EXPRESSIONS +above. + +If *varName* is specified, the commands stores *string* to *varName* +with the susbstitutions detailed below, and returns the number of +substitutions made (normally 1 unless '-all' is specified). +This is 0 if there were no matches. + +If *varName* is not specified, the substituted string will be returned +instead. + +When copying *string*, the portion of *string* that +matched *exp* is replaced with *subSpec*. +If *subSpec* contains a '&' or '{backslash}0', then it is replaced +in the substitution with the portion of *string* that +matched *exp*. + +If *subSpec* contains a '{backslash}*n*', where *n* is a digit +between 1 and 9, then it is replaced in the substitution with +the portion of *string* that matched the **n**-th +parenthesized subexpression of *exp*. +Additional backslashes may be used in *subSpec* to prevent special +interpretation of '&' or '{backslash}0' or '{backslash}*n*' or +backslash. + +The use of backslashes in *subSpec* tends to interact badly +with the Tcl parser's use of backslashes, so it's generally +safest to enclose *subSpec* in braces if it includes +backslashes. + +The following switches modify the behaviour of *regsub* + ++*-nocase*+:: + Upper-case characters in *string* are converted to lower-case + before matching against *exp*; however, substitutions + specified by *subSpec* use the original unconverted form + of *string*. + ++*-all*+:: + All ranges in *string* that match *exp* are found and substitution + is performed for each of these ranges, rather than only the + first. The '&' and '{backslash}*n*' sequences are handled for + each substitution using the information from the corresponding + match. + ++*-line*+:: + Use newline-sensitive matching. By default, newline + is a completely ordinary character with no special meaning in + either REs or strings. With this flag, '[^' bracket expressions + and '.' never match newline, a '^' anchor matches the null + string after any newline in the string in addition to its normal + function, and the '$' anchor matches the null string before any + newline in the string in addition to its normal function. + ++*-start* 'offset'+:: + Specifies a character index offset into the string at which to + start matching the regular expression. *offset* will be + constrained to the bounds of the input string. + ++*--*+:: + Marks the end of switches. The argument following this one will be + treated as *exp* even if it starts with a +-+. + +ref +~~~ ++*ref* 'string tag ?finalizer?'+ + +Create a new reference containing *string* of type *tag*. +If *finalizer* is specified, it is a command which will be invoked +when the a garbage collection cycle runs and this reference is +no longer accessible. + +The finalizer is invoked as: + + +finalizer 'reference string'+ + +See GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail. + +rename +~~~~~~ ++*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 +~~~~~~ ++*return* ?*-code* 'code'? ?*-errorinfo* 'stacktrace'? ?*-level* 'n'? ?'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. + +If *-code* is specified (as either a number or ok, error, break, +continue, signal, return or exit), this code will be used instead +of +JIM_OK+. This is generally useful when implementing flow of control +commands. + +If *-level* is specified and greater than 1, it has the effect of delaying +the new return code from *-code*. This is useful when rethrowing an error +from 'catch'. See the implementation of try/catch in tclcompat.tcl for +an example of how this is done. + +If *-errorinfo* is specified (as returned from 'info stacktrace') +it is used to initialize the stacktrace. +scan +~~~~ ++*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'. For '%c' conversions a single +character value is converted to a decimal string, which is then +assigned to the corresponding *varName*; no field width may be +specified for this conversion. + +seek +~~~~ ++*seek* 'fileId offset ?origin?'+ + ++'fileId' *seek* 'offset ?origin?'+ + +Change the current access position for *fileId*. +The *offset* and *origin* arguments specify the position at +which the next read or write will occur for *fileId*. +*offset* must be a number (which may be negative) and *origin* +must be one of the following: + ++*start*+:: + The new access position will be *offset* bytes from the start + of the file. + ++*current*+:: + The new access position will be *offset* bytes from the current + access position; a negative *offset* moves the access position + backwards in the file. + ++*end*+:: + The new access position will be *offset* bytes from the end of + the file. A negative *offset* places the access position before + the end-of-file, and a positive *offset* places the access position + after the end-of-file. + +The *origin* argument defaults to 'start'. + +*fileId* must have been the return value from a previous call to +'open', or it may be 'stdin', 'stdout', or 'stderr' to refer to one +of the standard I/O channels. + +This command returns an empty string. + +set +~~~ ++*set* 'varName ?value?'+ + +Returns the value of variable *varName*. + +If *value* is specified, then set the value of *varName* to *value*, +creating a new variable if one doesn't already exist, and return +its value. + +If *varName* contains an open parenthesis and ends with a +close parenthesis, then it refers to an array element: the characters +before the open parenthesis are the name of the array, and the characters +between the parentheses are the index within the array. +Otherwise *varName* refers to a scalar variable. + +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. + +The '::' prefix may also be used to explicitly reference a variable +in the global scope. + +setref +~~~~~~ ++*setref* 'reference string'+ + +Store a new string in *reference*, replacing the existing string. +The reference must be a valid reference create with the 'ref' +command. + +See GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail. + +signal +~~~~~~ +Command for signal handling. + +See 'kill' for the different forms which may be used to specify signals. + +Commands which return a list of signal names do so using the canonical form: +"+SIGINT SIGTERM+". + ++*signal handle* ?'signals ...'?+:: + If no signals are given, returns a list of all signals which are currently + being handled. + If signals are specified, these are added to the list of signals currently + being handled. + ++*signal ignore* ?'signals ...'?+:: + If no signals are given, returns a lists all signals which are currently + being ignored. + If signals are specified, these are added to the list of signals + currently being ignored. These signals are still delivered, but + are not considered by 'catch -signal' or 'try -signal'. Use + 'signal check' to determine which signals have occurred but + been ignored. + ++*signal default* ?'signals ...'?+:: + If no signals are given, returns a lists all signals which are currently have + the default behaviour. + If signals are specified, these are added to the list of signals which have + the default behaviour. + ++*signal check ?-clear?* ?'signals ...'?+:: + Returns a list of signals which have been delivered to the process + but are 'ignored'. If signals are specified, only that set of signals will + be checked, otherwise all signals will be checked. + If '-clear' is specified, any signals returned are removed and will not be + returned by subsequent calls to 'signal check' unless delivered again. + ++*signal throw* ?'signal'?+:: + Raises the given signal, which defaults to +SIGINT+ if not specified. + The behaviour is identical to: + + kill signal [pid] + +Note that 'signal handle' and 'signal ignore' represent two forms of signal +handling. 'signal handle' is used in conjunction with 'catch -signal' or 'try -signal' +to immediately abort execution when the signal is delivered. Alternatively, 'signal ignore' +is used in conjunction with 'signal check' to handle signal synchronously. Consider the +two examples below. + +Prevent a processing from taking too long + + signal handle SIGALRM + alarm 20 + try -signal { + .. possibly long running process .. + alarm 0 + } on signal {sig} { + puts stderr "Process took too long" + } + +Handle SIGHUP to reconfigure: + + signal ignore SIGHUP + while {1} { + ... handle configuration/reconfiguration ... + while {[signal check -clear SIGHUP] eq ""} { + ... do processing .. + } + # Received SIGHUP, so reconfigure + } + +sleep +~~~~~ ++*sleep* 'seconds'+ + +Pauses for the given number of seconds, which may be a floating +point value less than one to sleep for less than a second, or an +integer to sleep for one or more seconds. + +source +~~~~~~ ++*source* 'fileName'+ + +Read file *fileName* and pass the contents to the Tcl interpreter +as a sequence of commands to execute in the normal fashion. The return +value of 'source' is the return value of the last command executed +from the file. If an error occurs in executing the contents of the +file, then the 'source' command will return that error. + +If a 'return' command is invoked from within the file, the remainder of +the file will be skipped and the 'source' command will return +normally with the result from the 'return' command. + +split +~~~~~ ++*split* 'string ?splitChars?'+ + +Returns a list created by splitting *string* at each character +that is in the *splitChars* argument. + +Each element of the result list will consist of the +characters from *string* between instances of the +characters in *splitChars*. + +Empty list elements will be generated if *string* contains +adjacent characters in *splitChars*, or if the first or last +character of *string* is in *splitChars*. + +If *splitChars* is an empty string then each character of +*string* becomes a separate element of the result list. + +*SplitChars* defaults to the standard white-space characters. +For example, + + split "comp.unix.misc" . + +returns +'"comp unix misc"'+ and + + split "Hello world" {} + +returns +'"H e l l o { } w o r l d"'+. + +stackdump +~~~~~~~~~ + ++*stackdump* 'stacktrace'+ + +Creates a human readable representation of a stack trace. + +stacktrace +~~~~~~~~~~ + ++*stacktrace*+ + +Returns a live stack trace as a list of +proc file line proc file line ...+. +Iteratively uses 'info frame' to create the stack trace. This stack trace is in the +same form as produced by 'catch' and 'info stacktrace' + +See also 'stackdump'. + +string +~~~~~~ + ++*string* 'option arg ?arg ...?'+ + +Perform one of several string operations, depending on *option*. +The legal options (which may be abbreviated) are: + ++*string compare ?-nocase?* 'string1 string2'+:: + Perform a character-by-character comparison of strings *string1* and + *string2* in the same way as the C 'strcmp' procedure. Return + -1, 0, or 1, depending on whether *string1* is lexicographically + less than, equal to, or greater than *string2*. + Performs a case-insensitive comparison if '-nocase' is specified. + ++*string equal ?-nocase?* 'string1 string2'+:: + Returns 1 if the strings are equal, or 0 otherwise. + Performs a case-insensitive comparison if '-nocase' is specified. + ++*string first* 'string1 string2 ?firstIndex?'+:: + Search *string2* for a sequence of characters that exactly match + the characters in *string1*. If found, return the index of the + first character in the first such match within *string2*. If not + found, return -1. If *firstIndex* is specified, matching will start + from *firstIndex* of *string1*. + :: + See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *firstIndex*. + ++*string index* 'string charIndex'+:: + Returns the *charIndex*'th character of the *string* + argument. A *charIndex* of 0 corresponds to the first + character of the string. + If *charIndex* is less than 0 or greater than + or equal to the length of the string then an empty string is + returned. + :: + See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *charIndex*. + ++*string last* 'string1 string2 ?lastIndex?'+:: + Search *string2* for a sequence of characters that exactly match + the characters in *string1*. If found, return the index of the + first character in the last such match within *string2*. If there + is no match, then return -1. If *lastIndex* is specified, only characters + up to *lastIndex* of *string2* will be considered in the match. + :: + See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *lastIndex*. + ++*string length* 'string'+:: + Returns a decimal string giving the number of characters in *string*. + ++*string match ?-nocase?* '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. + + +\x+;; + Matches the single character *x*. This provides a way of + avoiding the special interpretation of the characters \`\*?[]\` + in **pattern**. + :: + Performs a case-insensitive comparison if '-nocase' is specified. + ++*string range* 'string first last'+:: + Returns a range of consecutive characters from *string*, starting + with the character whose index is *first* and ending with the + character whose index is *last*. An index of 0 refers to the + first character of the string. + :: + See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *first* and *last*. + :: + If *first* is less than zero then it is treated as if it were zero, and + if *last* is greater than or equal to the length of the string then + it is treated as if it were 'end'. If *first* is greater than + *last* then an empty string is returned. + ++*string repeat* 'string count'+:: + Returns a new string consisting of *string* repeated *count* times. + ++*string reverse* 'string'+:: + Returns a string that is the same length as *string* but + with its characters in the reverse order. + ++*string tolower* 'string'+:: + Returns a value equal to *string* except that all upper case + letters have been converted to lower case. + ++*string toupper* 'string'+:: + Returns a value equal to *string* except that all lower case + letters have been converted to upper case. + ++*string trim* 'string ?chars?'+:: + Returns a value equal to *string* except that any leading + or trailing characters from the set given by *chars* are + removed. + If *chars* is not specified then white space is removed + (spaces, tabs, newlines, and carriage returns). + ++*string trimleft* 'string ?chars?'+:: + Returns a value equal to *string* except that any + leading characters from the set given by *chars* are + removed. + If *chars* is not specified then white space is removed + (spaces, tabs, newlines, and carriage returns). + ++*string trimright* 'string ?chars?'+:: + Returns a value equal to *string* except that any + trailing characters from the set given by *chars* are + removed. + If *chars* is not specified then white space is removed + (spaces, tabs, newlines, and carriage returns). + +subst +~~~~~ ++*subst ?-nobackslashes? ?-nocommands? ?-novariables?* 'string'+ + +This command performs variable substitutions, command substitutions, +and backslash substitutions on its string argument and returns the +fully-substituted result. The substitutions are performed in exactly +the same way as for Tcl commands. As a result, the string argument +is actually substituted twice, once by the Tcl parser in the usual +fashion for Tcl commands, and again by the subst command. + +If any of the *-nobackslashes*, *-nocommands*, or *-novariables* are +specified, then the corresponding substitutions are not performed. +For example, if *-nocommands* is specified, no command substitution +is performed: open and close brackets are treated as ordinary +characters with no special interpretation. + +*Note*: when it performs its substitutions, subst does not give any +special treatment to double quotes or curly braces. For example, +the following script returns 'xyz \{44\}', not 'xyz \{$a\}'. + + set a 44 + subst {xyz {$a}} + + +switch +~~~~~~ ++*switch* '?options? string pattern body ?pattern body ...?'+ + ++*switch* '?options? string {pattern body ?pattern body ...?}'+ + +The 'switch' command matches its string argument against each of +the pattern arguments in order. As soon as it finds a pattern that +matches string it evaluates the following body and returns the +result of that evaluation. If the last pattern argument is default +then it matches anything. If no pattern argument matches string and +no default is given, then the switch command returns an empty string. +If the initial arguments to switch start with - then they are treated +as options. The following options are currently supported: + + +-exact+:: + Use exact matching when comparing string to a + pattern. This is the default. + + +-glob+:: + When matching string to the patterns, use glob-style + matching (i.e. the same as implemented by the string + match command). + + +-regexp+:: + When matching string to the patterns, use regular + expression matching (i.e. the same as implemented + by the regexp command). + + +-command 'commandname'+:: + When matching string to the patterns, use the given command, which + must be a single word. The command is invoked as + 'commandname pattern string', or 'commandname -nocase pattern string' + and must return 1 if matched, or 0 if not. + + +--+:: + Marks the end of options. The argument following + this one will be treated as string even if it starts + with a -. + +Two syntaxes are provided for the pattern and body arguments. The +first uses a separate argument for each of the patterns and commands; +this form is convenient if substitutions are desired on some of the +patterns or commands. The second form places all of the patterns +and commands together into a single argument; the argument must +have proper list structure, with the elements of the list being the +patterns and commands. The second form makes it easy to construct +multi-line switch commands, since the braces around the whole list +make it unnecessary to include a backslash at the end of each line. +Since the pattern arguments are in braces in the second form, no +command or variable substitutions are performed on them; this makes +the behavior of the second form different than the first form in +some cases. + +If a body is specified as '-' it means that the body for the next +pattern should also be used as the body for this pattern (if the +next pattern also has a body of ``-'' then the body after that is +used, and so on). This feature makes it possible to share a single +body among several patterns. + +Below are some examples of switch commands: + + switch abc a - b {format 1} abc {format 2} default {format 3} + +will return 2, + + switch -regexp aaab { + ^a.*b$ - + b {format 1} + a* {format 2} + default {format 3} + } + +will return 1, and + + switch xyz { + a - + b {format 1} + a* {format 2} + default {format 3} + } + +will return 3. + +tailcall +~~~~~~~~ ++*tailcall* 'cmd ?arg...?'+ + +The 'tailcall' command provides an optimised way of invoking a command whilst replacing +the current call frame. This is similar to 'exec' in Bourne Shell. + +The following are identical except the first immediately replaces the current call frame. + + tailcall a b c + + return [uplevel 1 a b c] + +'tailcall' is useful for a dispatch mechanism: + + proc a {cmd args} { + tailcall sub_$cmd {*}$args + } + proc sub_cmd1 ... + proc sub_cmd2 ... + +tell +~~~~ ++*tell* 'fileId'+ + ++'fileId' *tell*+ + +Returns a decimal string giving the current access position in +*fileId*. + +*fileId* must have been the return value from a previous call to +'open', or it may be 'stdin', 'stdout', or 'stderr' to refer to one +of the standard I/O channels. + +throw +~~~~~ ++*throw* 'code ?msg?'+ + +This command throws an exception (return) code along with an optional message. +This command is mostly for convenient usage with 'try'. + +The command +throw break+ is equivalent to +break+. +The command +throw 20 message+ can be caught with an +on 20 ...+ clause to 'try'. + +time +~~~~ ++*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. + +try +~~~ ++*try* '?catchopts? tryscript' ?*on* 'returncodes {?resultvar? ?optsvar?} handlerscript ...'? ?*finally* 'finalscript'?+ + +The 'try' command is provided as a convenience for exception handling. + +This interpeter first evaluates *tryscript* under the effect of the catch +options *catchopts* (e.g. +-signal -noexit --+, see 'catch'). + +It then evaluates the script for the first matching 'on' handler +(there many be zero or more) based on the return code from the 'try' +section. For example a normal +JIM_ERR+ error will be matched by +an 'on error' handler. + +Finally, any *finalscript* is evaluated. + +The result of this command is the result of *tryscript*, except in the +case where an exception occurs in a matching 'on' handler script or the 'finally' script, +in which case the result is this new exception. + +The specified *returncodes* is a list of return codes either as names ('ok', 'error', 'break', etc.) +or as integers. + +If *resultvar* and *optsvar* are specified, they are set as for 'catch' before evaluating +the matching handler. + +For example: + + set f [open input] + try -signal { + process $f + } on {continue break} {} { + error "Unexpected break/continue" + } on error {msg opts} { + puts "Dealing with error" + return {*}$opts $msg + } on signal sig { + puts "Got signal: $sig" + } finally { + $f close + } + +If break, continue or error are raised, they are dealt with by the matching +handler. + +In any case, the file will be closed via the 'finally' clause. + +See also 'throw', 'catch', 'return', 'error'. + +unknown +~~~~~~~ ++*unknown* 'cmdName ?arg arg ...?'+ + +This command doesn't actually exist as part of Tcl, but Tcl will +invoke it if it does exist. + +If the Tcl interpreter encounters a command name for which there +is not a defined command, then Tcl checks for the existence of +a command named 'unknown'. + +If there is no such command, then the interpeter returns an +error. + +If the 'unknown' command exists, then it is invoked with +arguments consisting of the fully-substituted name and arguments +for the original non-existent command. + +The 'unknown' command typically does things like searching +through library directories for a command procedure with the name +*cmdName*, or expanding abbreviated command names to full-length, +or automatically executing unknown commands as UNIX sub-processes. + +In some cases (such as expanding abbreviations) 'unknown' will +change the original command slightly and then (re-)execute it. +The result of the 'unknown' command is used as the result for +the original non-existent command. + +unset +~~~~~ ++*unset ?-nocomplain? ?--?* '?name name ...?'+ + +Remove variables. +Each *name* is a variable name, specified in any of the +ways acceptable to the 'set' command. + +If a *name* refers to an element of an array, then that +element is removed without affecting the rest of the array. + +If a *name* consists of an array name with no parenthesized +index, then the entire array is deleted. + +The 'unset' command returns an empty string as result. + +An error occurs if any of the variables doesn't exist, unless '-nocomplain' +is specified. The '--' argument may be specified to stop option processing +in case the variable name may be '-nocomplain'. + +uplevel +~~~~~~~ ++*uplevel* '?level? command ?command ...?'+ + +All of the *command* arguments are concatenated as if they had +been passed to 'concat'; the result is then evaluated in the +variable context indicated by *level*. 'Uplevel' returns +the result of that evaluation. If *level* is an integer, then +it gives a distance (up the procedure calling stack) to move before +executing the command. If *level* consists of '\#' followed by +a number then the number gives an absolute level number. If *level* +is omitted then it defaults to '1'. *Level* cannot be +defaulted if the first *command* argument starts with a digit or '\#'. + +For example, suppose that procedure 'a' was invoked +from top-level, and that it called 'b', and that 'b' called 'c'. +Suppose that 'c' invokes the 'uplevel' command. If *level* +is '1' or '\#2' or omitted, then the command will be executed +in the variable context of 'b'. If *level* is '2' or '\#1' +then the command will be executed in the variable context of 'a'. + +If *level* is '3' or '\#0' then the command will be executed +at top-level (only global variables will be visible). +The 'uplevel' command causes the invoking procedure to disappear +from the procedure calling stack while the command is being executed. +In the above example, suppose 'c' invokes the command + + uplevel 1 {set x 43; d} + +where 'd' is another Tcl procedure. The 'set' command will +modify the variable 'x' in 'b's context, and 'd' will execute +at level 3, as if called from 'b'. If it in turn executes +the command + + uplevel {set x 42} + +then the 'set' command will modify the same variable 'x' in 'b's +context: the procedure 'c' does not appear to be on the call stack +when 'd' is executing. The command 'info level' may +be used to obtain the level of the current procedure. + +'Uplevel' makes it possible to implement new control +constructs as Tcl procedures (for example, 'uplevel' could +be used to implement the 'while' construct as a Tcl procedure). + +upvar +~~~~~ ++*upvar* '?level? otherVar myVar ?otherVar myVar ...?'+ + +This command arranges for one or more local variables in the current +procedure to refer to variables in an enclosing procedure call or +to global variables. + +*Level* may have any of the forms permitted for the 'uplevel' +command, and may be omitted if the first letter of the first *otherVar* +isn't '\#' or a digit (it defaults to '1'). + +For each *otherVar* argument, 'upvar' makes the variable +by that name in the procedure frame given by *level* (or at +global level, if *level* is '\#0') accessible +in the current procedure by the name given in the corresponding +*myVar* argument. + +The variable named by *otherVar* need not exist at the time of the +call; it will be created the first time *myVar* is referenced, just like +an ordinary variable. + +'Upvar' may only be invoked from within procedures. + +'Upvar' returns an empty string. + +The 'upvar' command simplifies the implementation of call-by-name +procedure calling and also makes it easier to build new control constructs +as Tcl procedures. +For example, consider the following procedure: + + proc add2 name { + upvar $name x + set x [expr $x+2] + } + +'Add2' is invoked with an argument giving the name of a variable, +and it adds two to the value of that variable. +Although 'add2' could have been implemented using 'uplevel' +instead of 'upvar', 'upvar' makes it simpler for 'add2' +to access the variable in the caller's procedure frame. + +while +~~~~~ ++*while* 'test body'+ + +The *while* command evaluates *test* as an expression +(in the same way that 'expr' evaluates its argument). +The value of the expression must be numeric; if it is non-zero +then *body* is executed by passing it to the Tcl interpreter. + +Once *body* has been executed then *test* is evaluated +again, and the process repeats until eventually *test* +evaluates to a zero numeric value. 'Continue' +commands may be executed inside *body* to terminate the current +iteration of the loop, and 'break' +commands may be executed inside *body* to cause immediate +termination of the 'while' command. + +The 'while' command always returns an empty string. + +OPTIONAL-EXTENSIONS +------------------- + +The following extensions may or may not be available depending upon +what options were selected when Jim Tcl was built. + +bio +~~~ +The bio command provides a way to read and write binary files +from within Tcl. Note that since Jim supports binary strings, the +main use of this command is 'bio copy' to easily copy between file +descriptors. + ++*bio read ?-hex?* 'fd var numbytes'+:: + Read bytes from a file descriptor. By default the data is not encoded. + Using *-hex* encodes the data as ascii hex instead. Returns + the number of bytes actually read. + ++*bio write ?-hex?* 'fd buf'+:: + Write a string to a file descriptor. If *-hex* is specified, the + string is expected to be in ascii hexx format. Returns the number + of bytes actually written. + ++*bio copy* 'fromfd tofd ?numbytes?'+:: + Copy binary data from the file descriptor *fromfd* to the + file descriptor *tofd*. If *numbytes* is specified, at most that many + bytes will be copied. Otherwise copying continues until the end + of the input file. Returns the number of bytes actually copied. + +posix: os.fork, os.wait, os.gethostname, os.getids, os.uptime +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ++*os.fork*+:: + Invokes 'fork(2)' and returns the result. + ++*os.wait -nohang* 'pid'+:: + Invokes waitpid(2), with WNOHANG if *-nohang* is specified. + Returns a list of 3 elements. + + {0 none 0} if -nohang is specified, and the process is still alive. + + {-1 error <error-description>} if the process does not exist or has already been waited for. + + {<pid> exit <exit-status>} if the process exited normally. + + {<pid> signal <signal-number>} if the process terminated on a signal. + + {<pid> other 0} otherwise (core dump, stopped, continued, etc.) + ++*os.gethostname*+:: + Invokes 'gethostname(3)' and returns the result. + ++*os.getids*+:: + Returns the various user/group ids for the current process. + + jim> os.getids + uid 1000 euid 1000 gid 100 egid 100 + ++*os.uptime*+:: + Returns the number of seconds since system boot. See description of 'uptime' in 'sysinfo(2)'. + +ANSI I/O (aio) and EVENTLOOP API +-------------------------------- +Jim provides an alternative object-based API for I/O. + +See '<<_open,open>>' and '<<_socket,socket>>' for commands which return an I/O handle. + +aio +~~~ ++$handle *read ?-nonewline?* '?len?'+:: + Read and return bytes from the stream. To eof if no len. + ++$handle *gets* '?var?'+:: + Read one line and return it or store it in the var + ++$handle *puts ?-nonewline?* 'str'+:: + Write the string, with newline unless -nonewline + ++$handle *flush*+:: + Flush the stream + ++$handle *eof*+:: + Returns 1 if stream is at eof + ++$handle *close*+:: + Closes the stream + ++$handle *seek* 'offset' *?start|current|end?*+:: + Seeks in the stream (default 'current') + ++$handle *tell*+:: + Returns the current seek position + ++$handle *ndelay ?0|1?*+:: + Set O_NDELAY (if arg). Returns current/new setting. + Note that in general ANSI I/O interacts badly with non-blocking I/O. + Use with care. + ++$handle *accept*+:: + Server socket only: Accept a connection and return stream + ++$handle *sendto* 'str ?hostname:?port'+:: + Sends the string, *str*, to the given address via the socket using sendto(2). + This is intended for udp sockets and may give an error or behave in unintended + ways for other handle types. + Returns the number of bytes written. + ++$handle *recvfrom* 'maxlen ?addrvar?'+:: + Receives a message from the handle via recvfrom(2) and returns it. + At most *maxlen* bytes are read. + If *addrvar* is specified, the sending address of the message is stored in + the named variable in the form 'hostname:port'. + +eventloop: after, vwait +~~~~~~~~~~~~~~~~~~~~~~~ + +The following commands allow a script to be invoked when the given condition occurs. + ++$handle *readable* '?readable-script ?eof-script??'+:: + Returns script, or invoke readable-script when readable, eof-script on eof, {} to remove + ++$handle *writable* '?writable-script?'+:: + Returns script, or invoke writable-script when writable, {} to remove + ++$handle *onexception* '?exception-script?'+:: + Returns script, or invoke exception-script when oob data, {} to remove + +Time-based execution is also available via the eventloop API. + ++*after* 'time script'+:: + The script is executed after the given number of milliseconds have elapsed. + Returns an event id. + ++*after cancel* 'id'+:: + Cancels an after event with the given event id. + ++*vwait* 'variable'+:: + A call to vwait is required to enter the eventloop. 'vwait' processes events until + the named variabled changes. The variable need not exist beforehand. + +socket +~~~~~~ +Various socket types may be created. + ++*socket unix* 'path'+:: + A unix domain socket client. + ++*socket unix.server* 'path'+:: + A unix domain socket server. + ++*socket stream* 'hostname:port'+:: + A TCP socket client. + ++*socket stream.server* '?hostname:?port'+:: + A TCP socket server (*hostname* defaults to 0.0.0.0). + ++*socket dgram* ?'hostname:port'?+:: + A UDP socket client. If the address is not specified, + the client socket will be unbound and 'sendto' must be used + to indicated the destination. + ++*socket dgram.server* 'hostname:port'+:: + A UDP socket server. + ++*socket pipe*+:: + A pipe. Note that unlike all other socket types, this command returns + a list of two channels: {read write} + +This command creates a socket connected (client) or bound (server) to the given +address. + +The returned value is channel and may generally be used with the various file I/O +commands (gets, puts, read, etc.), either as object-based syntax or Tcl-compatible syntax. + + set f [socket stream www.google.com:80] + aio.sockstream1 + $f puts -nonewline "GET / HTTP/1.0\r\n\r\n" + $f gets + HTTP/1.0 302 Found + $f close + +Server sockets, however support only 'accept', which is most useful in conjunction with +the EVENTLOOP API. + + set f [socket stream.server 80] + $f readable { + set client [$f accept] + $client gets $buf + ... + $client puts -nonewline "HTTP/1.1 404 Not found\r\n" + $client close + } + vwait done + +The special type 'pipe' isn't really a socket. + + lassign [socket pipe] r w + + # Must close $w after exec + exec ps >@$w & + $w close + + $r readable ... + +syslog +~~~~~~ ++*syslog* '?options? ?priority? message'+ + +This command sends message to system syslog facility with given +priority. Valid priorities are: + + emerg, alert, crit, err, error, warning, notice, info, debug + +If a message is specified, but no priority is specified, then a +priority of info is used. + +By default, facility user is used and the value of global tcl variable +argv0 is used as ident string. However, any of the following options +may be specified before priority to control these parameters: + ++*-facility* 'value'+:: + Use specified facility instead of user. The following + values for facility are recognized: + + authpriv, cron, daemon, kernel, lpr, mail, news, syslog, user, + uucp, local0-local7 + ++*-ident* 'string'+:: + Use given string instead of argv0 variable for ident string. + ++*-options* 'integer'+:: + Set syslog options such as LOG_CONS, LOG_NDELAY You should + use numeric values of those from your system syslog.h file, + because I haven't got time to implement yet another hash + table. + +[[BuiltinVariables]] +BUILT-IN VARIABLES +------------------ + +The following global variables are created automatically +by the Tcl library. + ++*env*+:: + This variable is set by Jim as an array + whose elements are the environment variables for the process. + Reading an element will return the value of the corresponding + environment variable. + This array is initialised at startup from the 'env' command. + ++*auto_path*+:: + This variable contains a list of paths to search for packages. + It contains {. /lib/jim} by default. + +The following global variables are set by jimsh. + ++*tcl_interactive*+:: + This variable is set to 1 if jimsh is started in interactive mode + or 0 otherwise. + ++*argv0*+:: + If jimsh is invoked to run a script, this variable contains the name + of the script. + ++*argv*+:: + If jimsh is invoked to run a script, this variable contains a list + of any arguments supplied to the script. + ++*jim_argv0*+:: + The value of argv[0] when jimsh was invoked. + +LICENCE +------- + + Copyright 2005 Salvatore Sanfilippo <antirez@invece.org> + Copyright 2005 Clemens Hintze <c.hintze@gmx.net> + Copyright 2005 patthoyts - Pat Thoyts <patthoyts@users.sf.net> + Copyright 2008 oharboe - Oyvind Harboe - oyvind.harboe@zylin.com + Copyright 2008 Andrew Lunn <andrew@lunn.ch> + Copyright 2008 Duane Ellis <openocd@duaneellis.com> + Copyright 2008 Uwe Klein <uklein@klein-messgeraete.de> + Copyright 2009 Steve Bennett <steveb@workware.net.au> + + The FreeBSD license + +[literal] + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS SOFTWARE IS PROVIDED BY THE JIM TCL PROJECT ``AS IS'' AND ANY + EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, + THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A + PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE + JIM TCL PROJECT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF + ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + The views and conclusions contained in the software and documentation + are those of the authors and should not be interpreted as representing + official policies, either expressed or implied, of the Jim Tcl Project. |