6 Jim Tcl v0.77 - reference manual for the Jim Tcl scripting language
15 jimsh [<scriptfile>|-]
16 jimsh -e '<immediate-script>'
22 * <<CommandIndex,Command Reference>>
23 * <<OperatorPrecedence,Operator Precedence>>
24 * <<BuiltinVariables, Builtin Variables>>
25 * <<BackslashSequences, Backslash Sequences>>
29 Jim Tcl is a small footprint reimplementation of the Tcl scripting language.
30 The core language engine is compatible with Tcl 8.5+, while implementing
31 a significant subset of the Tcl 8.6 command set, plus additional features
32 available only in Jim Tcl.
34 Some notable differences with Tcl 8.5/8.6 are:
36 1. Object-based I/O (aio), but with a Tcl-compatibility layer
37 2. I/O: Support for sockets and pipes including udp, unix domain sockets and IPv6
39 4. Support for references (`ref`/`getref`/`setref`) and garbage collection
40 5. Builtin dictionary type (`dict`) with some limitations compared to Tcl 8.6
41 6. `env` command to access environment variables
42 7. Operating system features: `os.fork`, `os.wait`, `os.uptime`, `signal`, `alarm`, `sleep`
43 8. Much better error reporting. `info stacktrace` as a replacement for '$errorInfo', '$errorCode'
44 9. Support for "static" variables in procedures
45 10. Threads and coroutines are not supported
46 11. Command and variable traces are not supported
47 12. Built-in command line editing
48 13. Expression shorthand syntax: +$(...)+
49 14. Modular build allows many features to be omitted or built as dynamic, loadable modules
50 15. Highly suitable for use in an embedded environment
51 16. Support for UDP, IPv6, Unix-Domain sockets in addition to TCP sockets
55 Changes between 0.77 and 0.78
56 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
57 1. Add serial/tty support with `aio tty`
58 2. Add support for 'jimsh -'
59 3. Add hidden '-commands' option to many commands
60 4. Add scriptable autocompletion support in interactive mode with `tcl::autocomplete`
62 6. Add scriptable autocompletion support with `history completion`
63 7. Add support for `tree delete`
64 8. Add support for `defer` and '$jim::defer'
66 Changes between 0.76 and 0.77
67 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
68 1. Add support for `aio sync`
69 2. Add SSL and TLS support in aio
71 4. Added support for boolean constants in `expr`
72 5. `string is` now supports 'boolean' class
73 6. Add support for `aio lock` and `aio unlock`
74 7. Add new `interp` command
76 Changes between 0.75 and 0.76
77 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
78 1. `glob` now supports the +-tails+ option
79 2. Add support for `string cat`
80 3. Allow `info source` to add source info
82 Changes between 0.74 and 0.75
83 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
84 1. `binary`, `pack` and `unpack` now support floating point
85 2. `file copy` +-force+ handles source and target as the same file
86 3. `format` now supports +%b+ for binary conversion
87 4. `lsort` now supports +-unique+ and +-real+
88 5. Add support for half-close with `aio close` +?r|w?+
89 6. Add `socket pair` for a bidirectional pipe
90 7. Add '--random-hash' to randomise hash tables for greater security
91 8. `dict` now supports 'for', 'values', 'incr', 'append', 'lappend', 'update', 'info' and 'replace'
92 9. `file stat` no longer requires the variable name
93 10. Add support for `file link`
95 Changes between 0.73 and 0.74
96 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
97 1. Numbers with leading zeros are treated as decimal, not octal
99 3. Add LFS (64 bit) support for `aio seek`, `aio tell`, `aio copyto`, `file copy`
100 4. `string compare` and `string equal` now support '-length'
101 5. `glob` now supports '-directory'
103 Changes between 0.72 and 0.73
104 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
105 1. Built-in regexp now support non-capturing parentheses: (?:...)
106 2. Add `string replace`
107 3. Add `string totitle`
108 4. Add `info statics`
109 5. Add +build-jim-ext+ for easy separate building of loadable modules (extensions)
110 6. `local` now works with any command, not just procs
111 7. Add `info alias` to access the target of an alias
112 8. UTF-8 encoding past the basic multilingual plane (BMP) is supported
115 11. Most extensions are now enabled by default
116 12. Add support for namespaces and the `namespace` command
119 Changes between 0.71 and 0.72
120 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
121 1. procs now allow 'args' and optional parameters in any position
122 2. Add Tcl-compatible expr functions, `rand()`, `srand()` and `pow()`
123 3. Add support for the '-force' option to `file delete`
124 4. Better diagnostics when `source` fails to load a script with a missing quote or bracket
125 5. New +tcl_platform(pathSeparator)+
126 6. Add support settings the modification time with `file mtime`
127 7. `exec` is now fully supported on win32 (mingw32)
128 8. `file join`, `pwd`, `glob` etc. now work for mingw32
129 9. Line editing is now supported for the win32 console (mingw32)
130 10. Add `aio listen` command
132 Changes between 0.70 and 0.71
133 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
134 1. Allow 'args' to be renamed in procs
135 2. Add +$(...)+ shorthand syntax for expressions
136 3. Add automatic reference variables in procs with +&var+ syntax
137 4. Support +jimsh --version+
138 5. Additional variables in +tcl_platform()+
139 6. `local` procs now push existing commands and `upcall` can call them
140 7. Add `loop` command (TclX compatible)
141 8. Add `aio buffering` command
142 9. `info complete` can now return the missing character
143 10. `binary format` and `binary scan` are now (optionally) supported
144 11. Add `string byterange`
145 12. Built-in regexp now support non-greedy repetition (*?, +?, ??)
149 Tcl stands for 'tool command language' and is pronounced
150 'http://www.oxforddictionaries.com/definition/american_english/tickle[tickle]'.
151 It is actually two things: a language and a library.
153 First, Tcl is a simple textual language, intended primarily for
154 issuing commands to interactive programs such as text editors,
155 debuggers, illustrators, and shells. It has a simple syntax and is also
156 programmable, so Tcl users can write command procedures to provide more
157 powerful commands than those in the built-in set.
159 Second, Tcl is a library package that can be embedded in application
160 programs. The Tcl library consists of a parser for the Tcl language,
161 routines to implement the Tcl built-in commands, and procedures that
162 allow each application to extend Tcl with additional commands specific
163 to that application. The application program generates Tcl commands and
164 passes them to the Tcl parser for execution. Commands may be generated
165 by reading characters from an input source, or by associating command
166 strings with elements of the application's user interface, such as menu
167 entries, buttons, or keystrokes.
169 When the Tcl library receives commands it parses them into component
170 fields and executes built-in commands directly. For commands implemented
171 by the application, Tcl calls back to the application to execute the
172 commands. In many cases commands will invoke recursive invocations of the
173 Tcl interpreter by passing in additional strings to execute (procedures,
174 looping commands, and conditional commands all work in this way).
176 An application program gains three advantages by using Tcl for its command
177 language. First, Tcl provides a standard syntax: once users know Tcl,
178 they will be able to issue commands easily to any Tcl-based application.
179 Second, Tcl provides programmability. All a Tcl application needs
180 to do is to implement a few application-specific low-level commands.
181 Tcl provides many utility commands plus a general programming interface
182 for building up complex command procedures. By using Tcl, applications
183 need not re-implement these features.
185 Third, Tcl can be used as a common language for communicating between
186 applications. Inter-application communication is not built into the
187 Tcl core described here, but various add-on libraries, such as the Tk
188 toolkit, allow applications to issue commands to each other. This makes
189 it possible for applications to work together in much more powerful ways
190 than was previously possible.
192 Fourth, Jim Tcl includes a command processor, +jimsh+, which can be
193 used to run standalone Tcl scripts, or to run Tcl commands interactively.
195 This manual page focuses primarily on the Tcl language. It describes
196 the language syntax and the built-in commands that will be available
197 in any application based on Tcl. The individual library procedures are
198 described in more detail in separate manual pages, one per procedure.
200 JIMSH COMMAND INTERPRETER
201 -------------------------
202 A simple, but powerful command processor, +jimsh+, is part of Jim Tcl.
203 It may be invoked in interactive mode as:
207 or to process the Tcl script in a file with:
211 or to process the Tcl script from standard input:
215 It may also be invoked to execute an immediate script with:
221 Interactive mode reads Tcl commands from standard input, evaluates
222 those commands and prints the results.
225 Welcome to Jim version 0.73, Copyright (c) 2005-8 Salvatore Sanfilippo
228 . lsort [info commands p*]
229 package parray pid popen proc puts pwd
230 . foreach i {a b c} {
237 invalid command name "bad"
241 If +jimsh+ is configured with line editing (it is by default) and a VT-100-compatible
242 terminal is detected, Emacs-style line editing commands are available, including:
243 arrow keys, +\^W+ to erase a word, +\^U+ to erase the line, +^R+ for reverse incremental search
244 in history. Additionally, the +h+ command may be used to display the command history.
246 Command line history is automatically saved and loaded from +~/.jim_history+
248 In interactive mode, +jimsh+ automatically runs the script +~/.jimrc+ at startup
253 The central data structure in Tcl is an interpreter (C type 'Jim_Interp').
254 An interpreter consists of a set of command bindings, a set of variable
255 values, and a few other miscellaneous pieces of state. Each Tcl command
256 is interpreted in the context of a particular interpreter.
258 Some Tcl-based applications will maintain multiple interpreters
259 simultaneously, each associated with a different widget or portion of
260 the application. Interpreters are relatively lightweight structures.
261 They can be created and deleted quickly, so application programmers should
262 feel free to use multiple interpreters if that simplifies the application.
266 Tcl supports only one type of data: strings. All commands, all arguments
267 to commands, all command results, and all variable values are strings.
269 Where commands require numeric arguments or return numeric results,
270 the arguments and results are passed as strings. Many commands expect
271 their string arguments to have certain formats, but this interpretation
272 is up to the individual commands. For example, arguments often contain
273 Tcl command strings, which may get executed as part of the commands.
274 The easiest way to understand the Tcl interpreter is to remember that
275 everything is just an operation on a string. In many cases Tcl constructs
276 will look similar to more structured constructs from other languages.
277 However, the Tcl constructs are not structured at all; they are just
278 strings of characters, and this gives them a different behaviour than
279 the structures they may look like.
281 Although the exact interpretation of a Tcl string depends on who is doing
282 the interpretation, there are three common forms that strings take:
283 commands, expressions, and lists. The major sections below discuss
284 these three forms in more detail.
288 The Tcl language has syntactic similarities to both the Unix shells
289 and Lisp. However, the interpretation of commands is different
290 in Tcl than in either of those other two systems.
291 A Tcl command string consists of one or more commands separated
292 by newline characters or semi-colons.
293 Each command consists of a collection of fields separated by
294 white space (spaces or tabs).
295 The first field must be the name of a command, and the
296 additional fields, if any, are arguments that will be passed to
297 that command. For example, the command:
301 has three fields: the first, `set`, is the name of a Tcl command, and
302 the last two, 'a' and '22', will be passed as arguments to
303 the `set` command. The command name may refer either to a built-in
304 Tcl command, an application-specific command bound in with the library
305 procedure 'Jim_CreateCommand', or a command procedure defined with the
306 `proc` built-in command.
308 Arguments are passed literally as text strings. Individual commands may
309 interpret those strings in any fashion they wish. The `set` command,
310 for example, will treat its first argument as the name of a variable
311 and its second argument as a string value to assign to that variable.
312 For other commands arguments may be interpreted as integers, lists,
313 file names, or Tcl commands.
315 Command names should normally be typed completely (e.g. no abbreviations).
316 However, if the Tcl interpreter cannot locate a command it invokes a
317 special command named `unknown` which attempts to find or create the
320 For example, at many sites `unknown` will search through library
321 directories for the desired command and create it as a Tcl procedure if
322 it is found. The `unknown` command often provides automatic completion
323 of abbreviated commands, but usually only for commands that were typed
326 It's probably a bad idea to use abbreviations in command scripts and
327 other forms that will be re-used over time: changes to the command set
328 may cause abbreviations to become ambiguous, resulting in scripts that
333 If the first non-blank character in a command is +\#+, then everything
334 from the +#+ up through the next newline character is treated as
335 a comment and ignored. When comments are embedded inside nested
336 commands (e.g. fields enclosed in braces) they must have properly-matched
337 braces (this is necessary because when Tcl parses the top-level command
338 it doesn't yet know that the nested field will be used as a command so
339 it cannot process the nested comment character as a comment).
341 GROUPING ARGUMENTS WITH DOUBLE-QUOTES
342 -------------------------------------
343 Normally each argument field ends at the next white space, but
344 double-quotes may be used to create arguments with embedded space.
346 If an argument field begins with a double-quote, then the argument isn't
347 terminated by white space (including newlines) or a semi-colon (see below
348 for information on semi-colons); instead it ends at the next double-quote
349 character. The double-quotes are not included in the resulting argument.
350 For example, the command
352 set a "This is a single argument"
354 will pass two arguments to `set`: 'a' and 'This is a single argument'.
356 Within double-quotes, command substitutions, variable substitutions,
357 and backslash substitutions still occur, as described below. If the
358 first character of a command field is not a quote, then quotes receive
359 no special interpretation in the parsing of that field.
361 GROUPING ARGUMENTS WITH BRACES
362 ------------------------------
363 Curly braces may also be used for grouping arguments. They are similar
364 to quotes except for two differences. First, they nest; this makes them
365 easier to use for complicated arguments like nested Tcl command strings.
366 Second, the substitutions described below for commands, variables, and
367 backslashes do *not* occur in arguments enclosed in braces, so braces
368 can be used to prevent substitutions where they are undesirable.
370 If an argument field begins with a left brace, then the argument ends
371 at the matching right brace. Tcl will strip off the outermost layer
372 of braces and pass the information between the braces to the command
373 without any further modification. For example, in the command
375 set a {xyz a {b c d}}
377 the `set` command will receive two arguments: 'a'
380 When braces or quotes are in effect, the matching brace or quote need
381 not be on the same line as the starting quote or brace; in this case
382 the newline will be included in the argument field along with any other
383 characters up to the matching brace or quote. For example, the `eval`
384 command takes one argument, which is a command string; `eval` invokes
385 the Tcl interpreter to execute the command string. The command
392 will assign the value '22' to 'a' and '33' to 'b'.
394 If the first character of a command field is not a left
395 brace, then neither left nor right
396 braces in the field will be treated specially (except as part of
397 variable substitution; see below).
399 COMMAND SUBSTITUTION WITH BRACKETS
400 ----------------------------------
401 If an open bracket occurs in a field of a command, then command
402 substitution occurs (except for fields enclosed in braces). All of the
403 text up to the matching close bracket is treated as a Tcl command and
404 executed immediately. Then the result of that command is substituted
405 for the bracketed text. For example, consider the command
409 When the `set` command has only a single argument, it is the name of a
410 variable and `set` returns the contents of that variable. In this case,
411 if variable 'b' has the value 'foo', then the command above is equivalent
416 Brackets can be used in more complex ways. For example, if the variable
417 'b' has the value 'foo' and the variable 'c' has the value 'gorp',
420 set a xyz[set b].[set c]
422 is equivalent to the command
427 A bracketed command may contain multiple commands separated by newlines
428 or semi-colons in the usual fashion. In this case the value of the last
429 command is used for substitution. For example, the command
434 is equivalent to the command
439 If a field is enclosed in braces then the brackets and the characters
440 between them are not interpreted specially; they are passed through to
441 the argument verbatim.
443 VARIABLE SUBSTITUTION WITH $
444 ----------------------------
445 The dollar sign (+$+) may be used as a special shorthand form for
446 substituting variable values. If +$+ appears in an argument that isn't
447 enclosed in braces then variable substitution will occur. The characters
448 after the +$+, up to the first character that isn't a number, letter,
449 or underscore, are taken as a variable name and the string value of that
450 variable is substituted for the name.
452 For example, if variable 'foo' has the value 'test', then the command
456 is equivalent to the command
460 There are two special forms for variable substitution. If the next
461 character after the name of the variable is an open parenthesis, then
462 the variable is assumed to be an array name, and all of the characters
463 between the open parenthesis and the next close parenthesis are taken as
464 an index into the array. Command substitutions and variable substitutions
465 are performed on the information between the parentheses before it is
468 For example, if the variable 'x' is an array with one element named
469 'first' and value '87' and another element named '14' and value 'more',
472 set a xyz$x(first)zyx
474 is equivalent to the command
478 If the variable 'index' has the value '14', then the command
480 set a xyz$x($index)zyx
482 is equivalent to the command
486 For more information on arrays, see VARIABLES AND ARRAYS below.
488 The second special form for variables occurs when the dollar sign is
489 followed by an open curly brace. In this case the variable name consists
490 of all the characters up to the next curly brace.
492 Array references are not possible in this form: the name between braces
493 is assumed to refer to a scalar variable. For example, if variable
494 'foo' has the value 'test', then the command
498 is equivalent to the command
503 Variable substitution does not occur in arguments that are enclosed in
504 braces: the dollar sign and variable name are passed through to the
507 The dollar sign abbreviation is simply a shorthand form. +$a+ is
508 completely equivalent to +[set a]+; it is provided as a convenience
511 SEPARATING COMMANDS WITH SEMI-COLONS
512 ------------------------------------
513 Normally, each command occupies one line (the command is terminated by a
514 newline character). However, semi-colon (+;+) is treated as a command
515 separator character; multiple commands may be placed on one line by
516 separating them with a semi-colon. Semi-colons are not treated as
517 command separators if they appear within curly braces or double-quotes.
519 BACKSLASH SUBSTITUTION
520 ----------------------
521 Backslashes may be used to insert non-printing characters into command
522 fields and also to insert special characters like braces and brackets
523 into fields without them being interpreted specially as described above.
525 The backslash sequences understood by the Tcl interpreter are
526 listed below. In each case, the backslash
527 sequence is replaced by the given character:
528 [[BackslashSequences]]
539 Carriage-return (0xd).
562 +{backslash}<space>+::
563 Space ( ): doesn't terminate argument.
566 Semi-colon: doesn't terminate command.
571 +{backslash}<newline>+::
572 Nothing: this joins two lines together
573 into a single line. This backslash feature is unique in that
574 it will be applied even when the sequence occurs within braces.
576 +{backslash}{backslash}+::
577 Backslash ('{backslash}').
580 The digits +'ddd'+ (one, two, or three of them) give the octal value of
581 the character. Note that Jim supports null characters in strings.
584 +{backslash}u\{nnn\}+::
585 +{backslash}Unnnnnnnn+::
586 The UTF-8 encoding of the unicode codepoint represented by the hex digits, +'nnnn'+, is inserted.
587 The 'u' form allows for one to four hex digits.
588 The 'U' form allows for one to eight hex digits.
589 The 'u\{nnn\}' form allows for one to eight hex digits, but makes it easier to insert
590 characters UTF-8 characters which are followed by a hex digit.
592 For example, in the command
596 the second argument to `set` will be +{x[ yza+.
598 If a backslash is followed by something other than one of the options
599 described above, then the backslash is transmitted to the argument
600 field without any special processing, and the Tcl scanner continues
601 normal processing with the next character. For example, in the
606 The first argument to `set` will be +{backslash}*a+ and the second
607 argument will be +{backslash}{foo+.
609 If an argument is enclosed in braces, then backslash sequences inside
610 the argument are parsed but no substitution occurs (except for
611 backslash-newline): the backslash
612 sequence is passed through to the argument as is, without making
613 any special interpretation of the characters in the backslash sequence.
614 In particular, backslashed braces are not counted in locating the
615 matching right brace that terminates the argument.
621 the second argument to `set` will be +{backslash}{abc+.
623 This backslash mechanism is not sufficient to generate absolutely
624 any argument structure; it only covers the
625 most common cases. To produce particularly complicated arguments
626 it is probably easiest to use the `format` command along with
627 command substitution.
629 STRING AND LIST INDEX SPECIFICATIONS
630 ------------------------------------
632 Many string and list commands take one or more 'index' parameters which
633 specify a position in the string relative to the start or end of the string/list.
635 The index may be one of the following forms:
638 A simple integer, where '0' refers to the first element of the string
641 +integer+integer+ or::
643 The sum or difference of the two integers. e.g. +2+3+ refers to the 5th element.
644 This is useful when used with (e.g.) +$i+1+ rather than the more verbose
648 The last element of the string or list.
651 The 'nth-from-last' element of the string or list.
655 1. A command is just a string.
656 2. Within a string commands are separated by newlines or semi-colons
657 (unless the newline or semi-colon is within braces or brackets
659 3. A command consists of fields. The first field is the name of the command.
660 The other fields are strings that are passed to that command as arguments.
661 4. Fields are normally separated by white space.
662 5. Double-quotes allow white space and semi-colons to appear within
664 Command substitution, variable substitution, and backslash substitution
665 still occur inside quotes.
666 6. Braces defer interpretation of special characters.
667 If a field begins with a left brace, then it consists of everything
668 between the left brace and the matching right brace. The
669 braces themselves are not included in the argument.
670 No further processing is done on the information between the braces
671 except that backslash-newline sequences are eliminated.
672 7. If a field doesn't begin with a brace then backslash,
673 variable, and command substitution are done on the field. Only a
674 single level of processing is done: the results of one substitution
675 are not scanned again for further substitutions or any other
676 special treatment. Substitution can
677 occur on any field of a command, including the command name
678 as well as the arguments.
679 8. If the first non-blank character of a command is a +\#+, everything
680 from the +#+ up through the next newline is treated as a comment
685 The second major interpretation applied to strings in Tcl is
686 as expressions. Several commands, such as `expr`, `for`,
687 and `if`, treat one or more of their arguments as expressions
688 and call the Tcl expression processors ('Jim_ExprLong',
689 'Jim_ExprBoolean', etc.) to evaluate them.
691 The operators permitted in Tcl expressions are a subset of
692 the operators permitted in C expressions, and they have the
693 same meaning and precedence as the corresponding C operators.
694 Expressions almost always yield numeric results
695 (integer or floating-point values).
696 For example, the expression
702 Tcl expressions differ from C expressions in the way that
703 operands are specified, and in that Tcl expressions support
704 non-numeric operands and string comparisons.
706 A Tcl expression consists of a combination of operands, operators,
709 White space may be used between the operands and operators and
710 parentheses; it is ignored by the expression processor.
711 Where possible, operands are interpreted as integer values.
713 Integer values may be specified in decimal (the normal case) or in
714 hexadecimal (if the first two characters of the operand are '0x').
715 Note that Jim Tcl does *not* treat numbers with leading zeros as octal.
717 If an operand does not have one of the integer formats given
718 above, then it is treated as a floating-point number if that is
719 possible. Floating-point numbers may be specified in any of the
720 ways accepted by an ANSI-compliant C compiler (except that the
721 'f', 'F', 'l', and 'L' suffixes will not be permitted in
722 most installations). For example, all of the
723 following are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16.
725 If no numeric interpretation is possible, then an operand is left
726 as a string (and only a limited set of operators may be applied to
729 String constants representing boolean constants
730 (+'0'+, +'1'+, +'false'+, +'off'+, +'no'+, +'true'+, +'on'+, +'yes'+)
731 are also recognized and can be used in logical operations.
733 1. Operands may be specified in any of the following ways:
735 2. As a numeric value, either integer or floating-point.
737 3. As one of valid boolean constants
739 4. As a Tcl variable, using standard '$' notation.
740 The variable's value will be used as the operand.
742 5. As a string enclosed in double-quotes.
743 The expression parser will perform backslash, variable, and
744 command substitutions on the information between the quotes,
745 and use the resulting value as the operand
747 6. As a string enclosed in braces.
748 The characters between the open brace and matching close brace
749 will be used as the operand without any substitutions.
751 7. As a Tcl command enclosed in brackets.
752 The command will be executed and its result will be used as
755 Where substitutions occur above (e.g. inside quoted strings), they
756 are performed by the expression processor.
757 However, an additional layer of substitution may already have
758 been performed by the command parser before the expression
759 processor was called.
761 As discussed below, it is usually best to enclose expressions
762 in braces to prevent the command parser from performing substitutions
765 For some examples of simple expressions, suppose the variable 'a' has
766 the value 3 and the variable 'b' has the value 6. Then the expression
767 on the left side of each of the lines below will evaluate to the value
768 on the right side of the line:
773 {word one} < "word $a" 0
775 The valid operators are listed below, grouped in decreasing order
777 [[OperatorPrecedence]]
778 +int() double() round() abs(), rand(), srand()+::
779 Unary functions (except rand() which takes no arguments)
780 * +'int()'+ converts the numeric argument to an integer by truncating down.
781 * +'double()'+ converts the numeric argument to floating point.
782 * +'round()'+ converts the numeric argument to the closest integer value.
783 * +'abs()'+ takes the absolute value of the numeric argument.
784 * +'rand()'+ returns a pseudo-random floating-point value in the range (0,1).
785 * +'srand()'+ takes an integer argument to (re)seed the random number generator. Returns the first random number from that seed.
787 +sin() cos() tan() asin() acos() atan() sinh() cosh() tanh() ceil() floor() exp() log() log10() sqrt()+::
788 Unary math functions.
789 If Jim is compiled with math support, these functions are available.
792 Unary minus, unary plus, bit-wise NOT, logical NOT. None of these operands
793 may be applied to string operands, and bit-wise NOT may be
794 applied only to integers.
797 Power. e.g. 'x^y^'. If Jim is compiled with math support, supports doubles and
798 integers. Otherwise supports integers only. (Note that the math-function form
799 has the same highest precedence)
802 Multiply, divide, remainder. None of these operands may be
803 applied to string operands, and remainder may be applied only
807 Add and subtract. Valid for any numeric operands.
810 Left and right shift, left and right rotate. Valid for integer operands only.
813 Boolean less, greater, less than or equal, and greater than or equal.
814 Each operator produces 1 if the condition is true, 0 otherwise.
815 These operators may be applied to strings as well as numeric operands,
816 in which case string comparison is used.
819 Boolean equal and not equal. Each operator produces a zero/one result.
820 Valid for all operand types. *Note* that values will be converted to integers
821 if possible, then floating point types, and finally strings will be compared.
822 It is recommended that 'eq' and 'ne' should be used for string comparison.
825 String equal and not equal. Uses the string value directly without
826 attempting to convert to a number first.
829 String in list and not in list. For 'in', result is 1 if the left operand (as a string)
830 is contained in the right operand (as a list), or 0 otherwise. The result for
831 +{$a ni $list}+ is equivalent to +{!($a in $list)}+.
834 Bit-wise AND. Valid for integer operands only.
837 Bit-wise OR. Valid for integer operands only.
840 Bit-wise exclusive OR. Valid for integer operands only.
843 Logical AND. Produces a 1 result if both operands are non-zero, 0 otherwise.
844 Valid for numeric operands only (integers or floating-point).
847 Logical OR. Produces a 0 result if both operands are zero, 1 otherwise.
848 Valid for numeric operands only (integers or floating-point).
851 If-then-else, as in C. If +'x'+
852 evaluates to non-zero, then the result is the value of +'y'+.
853 Otherwise the result is the value of +'z'+.
854 The +'x'+ operand must have a numeric value, while +'y'+ and +'z'+ can
857 See the C manual for more details on the results
858 produced by each operator.
859 All of the binary operators group left-to-right within the same
860 precedence level. For example, the expression
866 The +&&+, +||+, and +?:+ operators have 'lazy evaluation', just as
867 in C, which means that operands are not evaluated if they are not
868 needed to determine the outcome. For example, in
872 only one of +[a]+ or +[b]+ will actually be evaluated,
873 depending on the value of +$v+.
875 All internal computations involving integers are done with the C
876 type 'long long' if available, or 'long' otherwise, and all internal
877 computations involving floating-point are done with the C type
880 When converting a string to floating-point, exponent overflow is
881 detected and results in a Tcl error.
882 For conversion to integer from string, detection of overflow depends
883 on the behaviour of some routines in the local C library, so it should
884 be regarded as unreliable.
885 In any case, overflow and underflow are generally not detected
886 reliably for intermediate results.
888 Conversion among internal representations for integer, floating-point,
889 string operands is done automatically as needed.
890 For arithmetic computations, integers are used until some
891 floating-point number is introduced, after which floating-point is used.
896 yields the result 1, while
899 5 / ( [string length "abcd"] + 0.0 )
901 both yield the result 1.25.
903 String values may be used as operands of the comparison operators,
904 although the expression evaluator tries to do comparisons as integer
905 or floating-point when it can.
906 If one of the operands of a comparison is a string and the other
907 has a numeric value, the numeric operand is converted back to
908 a string using the C 'sprintf' format specifier
909 '%d' for integers and '%g' for floating-point values.
910 For example, the expressions
915 both evaluate to 1. The first comparison is done using integer
916 comparison, and the second is done using string comparison after
917 the second operand is converted to the string '18'.
919 In general it is safest to enclose an expression in braces when
920 entering it in a command: otherwise, if the expression contains
921 any white space then the Tcl interpreter will split it
922 among several arguments. For example, the command
926 results in three arguments being passed to `expr`: +$a+,
927 \+, and +$b+. In addition, if the expression isn't in braces
928 then the Tcl interpreter will perform variable and command substitution
929 immediately (it will happen in the command parser rather than in
930 the expression parser). In many cases the expression is being
931 passed to a command that will evaluate the expression later (or
932 even many times if, for example, the expression is to be used to
933 decide when to exit a loop). Usually the desired goal is to re-do
934 the variable or command substitutions each time the expression is
935 evaluated, rather than once and for all at the beginning. For example,
938 for {set i 1} $i<=10 {incr i} {...} ** WRONG **
940 is probably intended to iterate over all values of +i+ from 1 to 10.
941 After each iteration of the body of the loop, `for` will pass
942 its second argument to the expression evaluator to see whether or not
943 to continue processing. Unfortunately, in this case the value of +i+
944 in the second argument will be substituted once and for all when the
945 `for` command is parsed. If +i+ was 0 before the `for`
946 command was invoked then the second argument of `for` will be +0\<=10+
947 which will always evaluate to 1, even though +i+ eventually
948 becomes greater than 10. In the above case the loop will never
949 terminate. Instead, the expression should be placed in braces:
951 for {set i 1} {$i<=10} {incr i} {...} ** RIGHT **
953 This causes the substitution of 'i'
954 to be delayed; it will be re-done each time the expression is
955 evaluated, which is the desired result.
959 The third major way that strings are interpreted in Tcl is as lists.
960 A list is just a string with a list-like structure
961 consisting of fields separated by white space. For example, the
966 is a list with four elements or fields.
967 Lists have the same basic structure as command strings, except
968 that a newline character in a list is treated as a field separator
969 just like space or tab. Conventions for braces and quotes
970 and backslashes are the same for lists as for commands. For example,
975 is a list with three elements: +a+, +b c+, and +d e {f g h}+.
977 Whenever an element is extracted from a list, the same rules about
978 braces and quotes and backslashes are applied as for commands. Thus in
979 the example above when the third element is extracted from the list,
984 (when the field was extracted, all that happened was to strip off
985 the outermost layer of braces). Command substitution and
986 variable substitution are never
987 made on a list (at least, not by the list-processing commands; the
988 list can always be passed to the Tcl interpreter for evaluation).
990 The Tcl commands `concat`, `foreach`, `lappend`, `lindex`, `linsert`,
991 `list`, `llength`, `lrange`, `lreplace`, `lsearch`, and `lsort` allow
992 you to build lists, extract elements from them, search them, and perform
993 other list-related functions.
995 Advanced list commands include `lrepeat`, `lreverse`, `lmap`, `lassign`, `lset`.
1000 A new addition to Tcl 8.5 is the ability to expand a list into separate
1001 arguments. Support for this feature is also available in Jim.
1003 Consider the following attempt to exec a list:
1008 This will attempt to exec a command named "ls -l", which will clearly not
1009 work. Typically eval and concat are required to solve this problem, however
1010 it can be solved much more easily with +\{*\}+.
1014 This will expand the following argument into individual elements and then evaluate
1015 the resulting command.
1017 Note that the official Tcl syntax is +\{*\}+, however +\{expand\}+ is retained
1018 for backward compatibility with experimental versions of this feature.
1022 Tcl provides two commands that support string matching using regular
1023 expressions, `regexp` and `regsub`, as well as `switch -regexp` and
1026 Regular expressions may be implemented one of two ways. Either using the system's C library
1027 POSIX regular expression support, or using the built-in regular expression engine.
1028 The differences between these are described below.
1030 *NOTE* Tcl 7.x and 8.x use perl-style Advanced Regular Expressions (+ARE+).
1032 POSIX Regular Expressions
1033 ~~~~~~~~~~~~~~~~~~~~~~~~~
1034 If the system supports POSIX regular expressions, and UTF-8 support is not enabled,
1035 this support will be used by default. The type of regular expressions supported are
1036 Extended Regular Expressions (+ERE+) rather than Basic Regular Expressions (+BRE+).
1037 See REG_EXTENDED in the documentation.
1039 Using the system-supported POSIX regular expressions will typically
1040 make for the smallest code size, but some features such as UTF-8
1041 and +{backslash}w+, +{backslash}d+, +{backslash}s+ are not supported, and null characters
1042 in strings are not supported.
1044 See regex(3) and regex(7) for full details.
1046 Jim built-in Regular Expressions
1047 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1048 The Jim built-in regular expression engine may be selected with +./configure --with-jim-regexp+
1049 or it will be selected automatically if UTF-8 support is enabled.
1051 This engine supports UTF-8 as well as some +ARE+ features. The differences with both Tcl 7.x/8.x
1052 and POSIX are highlighted below.
1054 1. UTF-8 strings and patterns are both supported
1055 2. All Tcl character classes are supported (e.g. +[:alnum:]+, +[:digit:]+, +[:space:]+), but...
1056 3. Character classes apply to ASCII characters only
1057 4. Supported shorthand character classes: +{backslash}w+ = +[:alnum:]+, +{backslash}W+ = +^[:alnum:]+, +{backslash}d+ = +[:digit:],+ +{backslash}D+ = +^[:digit:],+ +{backslash}s+ = +[:space:]+, + +{backslash}S+ = +^[:space:]+
1058 5. Supported constraint escapes: +{backslash}m+ = +{backslash}<+ = start of word, +{backslash}M+ = +{backslash}>+ = end of word
1059 6. Backslash escapes may be used within regular expressions, such as +{backslash}n+ = newline, +{backslash}uNNNN+ = unicode
1060 7. Partially supported constraint escapes: +{backslash}A+ = start of string, +{backslash}Z+ = end of string
1061 8. Support for the +?+ non-greedy quantifier. e.g. +*?+
1062 9. Support for non-capturing parentheses +(?:...)+
1063 10. Jim Tcl considers that both patterns and strings end at a null character (+\x00+)
1067 Each command produces two results: a code and a string. The
1068 code indicates whether the command completed successfully or not,
1069 and the string gives additional information. The valid codes are
1070 defined in jim.h, and are:
1073 This is the normal return code, and indicates that the command completed
1074 successfully. The string gives the command's return value.
1077 Indicates that an error occurred; the string gives a message describing
1081 Indicates that the `return` command has been invoked, and that the
1082 current procedure (or top-level command or `source` command)
1083 should return immediately. The
1084 string gives the return value for the procedure or command.
1087 Indicates that the `break` command has been invoked, so the
1088 innermost loop should abort immediately. The string should always
1092 Indicates that the `continue` command has been invoked, so the
1093 innermost loop should go on to the next iteration. The string
1094 should always be empty.
1097 Indicates that a signal was caught while executing a commands.
1098 The string contains the name of the signal caught.
1099 See the `signal` and `catch` commands.
1102 Indicates that the command called the `exit` command.
1103 The string contains the exit code.
1105 Tcl programmers do not normally need to think about return codes,
1106 since +JIM_OK+ is almost always returned. If anything else is returned
1107 by a command, then the Tcl interpreter immediately stops processing
1108 commands and returns to its caller. If there are several nested
1109 invocations of the Tcl interpreter in progress, then each nested
1110 command will usually return the error to its caller, until eventually
1111 the error is reported to the top-level application code. The
1112 application will then display the error message for the user.
1114 In a few cases, some commands will handle certain `error` conditions
1115 themselves and not return them upwards. For example, the `for`
1116 command checks for the +JIM_BREAK+ code; if it occurs, then `for`
1117 stops executing the body of the loop and returns +JIM_OK+ to its
1118 caller. The `for` command also handles +JIM_CONTINUE+ codes and the
1119 procedure interpreter handles +JIM_RETURN+ codes. The `catch`
1120 command allows Tcl programs to catch errors and handle them without
1121 aborting command interpretation any further.
1123 The `info returncodes` command may be used to programmatically map between
1124 return codes and names.
1128 Tcl allows you to extend the command interface by defining
1129 procedures. A Tcl procedure can be invoked just like any other Tcl
1130 command (it has a name and it receives one or more arguments).
1131 The only difference is that its body isn't a piece of C code linked
1132 into the program; it is a string containing one or more other
1135 The `proc` command is used to create a new Tcl command procedure:
1137 +*proc* 'name arglist ?statics? body'+
1139 The new command is named +'name'+, and it replaces any existing command
1140 there may have been by that name. Whenever the new command is
1141 invoked, the contents of +'body'+ will be executed by the Tcl
1144 +'arglist'+ specifies the formal arguments to the procedure.
1145 It consists of a list, possibly empty, of the following
1146 argument specifiers:
1149 Required Argument - A simple argument name.
1152 Optional Argument - A two-element list consisting of the
1153 argument name, followed by the default value, which will
1154 be used if the corresponding argument is not supplied.
1157 Reference Argument - The caller is expected to pass the name of
1158 an existing variable. An implicit +`upvar` 1 origname name+ is done
1159 to make the variable available in the proc scope.
1162 Variable Argument - The special name +'args'+, which is
1163 assigned all remaining arguments (including none) as a list. The
1164 variable argument may only be specified once. Note that
1165 the syntax +{args newname}+ may be used to retain the special
1166 behaviour of +'args'+ with a different local name. In this case,
1167 the variable is named +'newname'+ rather than +'args'+.
1169 When the command is invoked, a local variable will be created for each of
1170 the formal arguments to the procedure; its value will be the value
1171 of corresponding argument in the invoking command or the argument's
1174 Arguments with default values need not be specified in a procedure
1175 invocation. However, there must be enough actual arguments for all
1176 required arguments, and there must not be any extra actual arguments
1177 (unless the Variable Argument is specified).
1179 Actual arguments are assigned to formal arguments as in left-to-right
1180 order with the following precedence.
1182 1. Required Arguments (including Reference Arguments)
1183 2. Optional Arguments
1184 3. Variable Argument
1186 The following example illustrates precedence. Assume a procedure declaration:
1188 proc p {{a A} args b {c C} d} {...}
1190 This procedure requires at least two arguments, but can accept an unlimited number.
1191 The following table shows how various numbers of arguments are assigned.
1192 Values marked as +-+ are assigned the default value.
1194 [width="40%",frame="topbot",options="header"]
1196 |Number of arguments|a|args|b|c|d
1204 When +'body'+ is being executed, variable names normally refer to local
1205 variables, which are created automatically when referenced and deleted
1206 when the procedure returns. One local variable is automatically created
1207 for each of the procedure's arguments. Global variables can be
1208 accessed by invoking the `global` command or via the +::+ prefix.
1212 In addition to procedure arguments, Jim procedures may declare static variables.
1213 These variables scoped to the procedure and initialised at procedure definition.
1214 Either from the static variable definition, or from the enclosing scope.
1216 Consider the following example:
1219 jim> proc a {} {a {b 2}} {
1231 The static variable +'a'+ has no initialiser, so it is initialised from
1232 the enclosing scope with the value 1. (Note that it is an error if there
1233 is no variable with the same name in the enclosing scope). However +'b'+
1234 has an initialiser, so it is initialised to 2.
1236 Unlike a local variable, the value of a static variable is retained across
1237 invocations of the procedure.
1239 See the `proc` command for information on how to define procedures
1240 and what happens when they are invoked. See also NAMESPACES.
1242 VARIABLES - SCALARS AND ARRAYS
1243 ------------------------------
1244 Tcl allows the definition of variables and the use of their values
1245 either through '$'-style variable substitution, the `set`
1246 command, or a few other mechanisms.
1248 Variables need not be declared: a new variable will automatically
1249 be created each time a new variable name is used.
1251 Tcl supports two types of variables: scalars and arrays.
1252 A scalar variable has a single value, whereas an array variable
1253 can have any number of elements, each with a name (called
1254 its 'index') and a value.
1256 Array indexes may be arbitrary strings; they need not be numeric.
1257 Parentheses are used refer to array elements in Tcl commands.
1258 For example, the command
1262 will modify the element of 'x' whose index is 'first'
1263 so that its new value is '44'.
1265 Two-dimensional arrays can be simulated in Tcl by using indexes
1266 that contain multiple concatenated values.
1267 For example, the commands
1272 set the elements of 'a' whose indexes are '2,3' and '3,6'.
1274 In general, array elements may be used anywhere in Tcl that scalar
1275 variables may be used.
1277 If an array is defined with a particular name, then there may
1278 not be a scalar variable with the same name.
1280 Similarly, if there is a scalar variable with a particular
1281 name then it is not possible to make array references to the
1284 To convert a scalar variable to an array or vice versa, remove
1285 the existing variable with the `unset` command.
1287 The `array` command provides several features for dealing
1288 with arrays, such as querying the names of all the elements of
1289 the array and converting between an array and a list.
1291 Variables may be either global or local. If a variable
1292 name is used when a procedure isn't being executed, then it
1293 automatically refers to a global variable. Variable names used
1294 within a procedure normally refer to local variables associated with that
1295 invocation of the procedure. Local variables are deleted whenever
1296 a procedure exits. Either `global` command may be used to request
1297 that a name refer to a global variable for the duration of the current
1298 procedure (this is somewhat analogous to 'extern' in C), or the variable
1299 may be explicitly scoped with the +::+ prefix. For example
1315 ARRAYS AS LISTS IN JIM
1316 ----------------------
1317 Unlike Tcl, Jim can automatically convert between a list (with an even
1318 number of elements) and an array value. This is similar to the way Tcl
1319 can convert between a string and a list.
1330 Thus `array set` is equivalent to `set` when the variable does not
1333 The reverse is also true where an array will be converted into
1336 set a(1) one; set a(2) two
1345 Tcl 8.5 introduced the dict command, and Jim Tcl has added a version
1346 of this command. Dictionaries provide efficient access to key-value
1347 pairs, just like arrays, but dictionaries are pure values. This
1348 means that you can pass them to a procedure just as a list or a
1349 string. Tcl dictionaries are therefore much more like Tcl lists,
1350 except that they represent a mapping from keys to values, rather
1351 than an ordered sequence.
1353 You can nest dictionaries, so that the value for a particular key
1354 consists of another dictionary. That way you can elegantly build
1355 complicated data structures, such as hierarchical databases. You
1356 can also combine dictionaries with other Tcl data structures. For
1357 instance, you can build a list of dictionaries that themselves
1360 Dictionaries are values that contain an efficient, order-preserving
1361 mapping from arbitrary keys to arbitrary values. Each key in the
1362 dictionary maps to a single value. They have a textual format that
1363 is exactly that of any list with an even number of elements, with
1364 each mapping in the dictionary being represented as two items in
1365 the list. When a command takes a dictionary and produces a new
1366 dictionary based on it (either returning it or writing it back into
1367 the variable that the starting dictionary was read from) the new
1368 dictionary will have the same order of keys, modulo any deleted
1369 keys and with new keys added on to the end. When a string is
1370 interpreted as a dictionary and it would otherwise have duplicate
1371 keys, only the last value for a particular key is used; the others
1372 are ignored, meaning that, "apple banana" and "apple carrot apple
1373 banana" are equivalent dictionaries (with different string
1376 Note that in Jim, arrays are implemented as dictionaries.
1377 Thus automatic conversion between lists and dictionaries applies
1378 as it does for arrays.
1380 jim> dict set a 1 one
1382 jim> dict set a 2 two
1388 jim> dict set a 3 T three
1389 1 one 2 two 3 {T three}
1391 See the `dict` command for more details.
1395 Tcl added namespaces as a mechanism avoiding name clashes, especially in applications
1396 including a number of 3rd party components. While there is less need for namespaces
1397 in Jim Tcl (which does not strive to support large applications), it is convenient to
1398 provide a subset of the support for namespaces to easy porting code from Tcl.
1400 Jim Tcl currently supports "light-weight" namespaces which should be adequate for most
1401 purposes. This feature is currently experimental. See README.namespaces for more information
1402 and the documentation of the `namespace` command.
1404 GARBAGE COLLECTION, REFERENCES, LAMBDA FUNCTION
1405 -----------------------------------------------
1406 Unlike Tcl, Jim has some sophisticated support for functional programming.
1407 These are described briefly below.
1409 More information may be found at http://wiki.tcl.tk/13847
1413 A reference can be thought of as holding a value with one level of indirection,
1414 where the value may be garbage collected when unreferenced.
1415 Consider the following example:
1417 jim> set r [ref "One String" test]
1418 <reference.<test___>.00000000000000000000>
1422 The operation `ref` creates a references to the value specified by the
1423 first argument. (The second argument is a "type" used for documentation purposes).
1425 The operation `getref` is the dereferencing operation which retrieves the value
1426 stored in the reference.
1428 jim> setref $r "New String"
1433 The operation `setref` replaces the value stored by the reference. If the old value
1434 is no longer accessible by any reference, it will eventually be automatically be garbage
1439 Normally, all values in Tcl are passed by value. As such values are copied and released
1440 automatically as necessary.
1442 With the introduction of references, it is possible to create values whose lifetime
1443 transcend their scope. To support this, case, the Jim system will periodically identify
1444 and discard objects which are no longer accessible by any reference.
1446 The `collect` command may be used to force garbage collection. Consider a reference created
1449 jim> proc f {ref value} { puts "Finaliser called for $ref,$value" }
1450 jim> set r [ref "One String" test f]
1451 <reference.<test___>.00000000000
1456 Finaliser called for <reference.<test___>.00000000000,One String
1459 Note that once the reference, 'r', was modified so that it no longer
1460 contained a reference to the value, the garbage collector discarded
1461 the value (after calling the finalizer).
1463 The finalizer for a reference may be examined or changed with the `finalize` command
1467 jim> finalize $r newf
1472 Jim provides a garbage collected `lambda` function. This is a procedure
1473 which is able to create an anonymous procedure. Consider:
1475 jim> set f [lambda {a} {{x 0}} { incr x $a }]
1482 This create an anonymous procedure (with the name stored in 'f'), with a static variable
1483 which is incremented by the supplied value and the result returned.
1485 Once the procedure name is no longer accessible, it will automatically be deleted
1486 when the garbage collector runs.
1488 The procedure may also be delete immediately by renaming it "". e.g.
1494 If Jim is built with UTF-8 support enabled (configure --enable-utf),
1495 then most string-related commands become UTF-8 aware. These include,
1496 but are not limited to, `string match`, `split`, `glob`, `scan` and
1499 UTF-8 encoding has many advantages, but one of the complications is that
1500 characters can take a variable number of bytes. Thus the addition of
1501 `string bytelength` which returns the number of bytes in a string,
1502 while `string length` returns the number of characters.
1504 If UTF-8 support is not enabled, all commands treat bytes as characters
1505 and `string bytelength` returns the same value as `string length`.
1507 Note that even if UTF-8 support is not enabled, the +{backslash}uNNNN+ and related syntax
1508 is still available to embed UTF-8 sequences.
1510 Jim Tcl supports all currently defined unicode codepoints. That is 21 bits, up to +'U+1FFFFF'.
1514 Commands such as `string match`, `lsearch -glob`, `array names` and others use string
1515 pattern matching rules. These commands support UTF-8. For example:
1517 string match a\[\ua0-\ubf\]b "a\u00a3b"
1521 +format %c+ allows a unicode codepoint to be be encoded. For example, the following will return
1522 a string with two bytes and one character. The same as +{backslash}ub5+
1526 `format` respects widths as character widths, not byte widths. For example, the following will
1527 return a string with three characters, not three bytes.
1529 format %.3s \ub5\ub6\ub7\ub8
1531 Similarly, +scan ... %c+ allows a UTF-8 to be decoded to a unicode codepoint. The following will set
1532 +'a'+ to 181 (0xb5) and +'b'+ to 65 (0x41).
1534 scan \u00b5A %c%c a b
1536 `scan %s` will also accept a character class, including unicode ranges.
1540 `string is` has *not* been extended to classify UTF-8 characters. Therefore, the following
1541 will return 0, even though the string may be considered to be alphabetic.
1543 string is alpha \ub5Test
1545 This does not affect the string classes 'ascii', 'control', 'digit', 'double', 'integer' or 'xdigit'.
1547 Case Mapping and Conversion
1548 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1549 Jim provides a simplified unicode case mapping. This means that case conversion
1550 and comparison will not increase or decrease the number of characters in a string.
1551 (Although it may change the number of bytes).
1553 `string toupper` will convert any lowercase letters to their uppercase equivalent.
1554 Any character which is not a letter or has no uppercase equivalent is left unchanged.
1555 Similarly for `string tolower` and `string totitle`.
1557 Commands which perform case insensitive matches, such as `string compare -nocase`
1558 and `lsearch -nocase` fold both strings to uppercase before comparison.
1560 Invalid UTF-8 Sequences
1561 ~~~~~~~~~~~~~~~~~~~~~~~
1562 Some UTF-8 character sequences are invalid, such as those beginning with '0xff',
1563 those which represent character sequences longer than 3 bytes (greater than U+FFFF),
1564 and those which end prematurely, such as a lone '0xc2'.
1566 In these situations, the offending bytes are treated as single characters. For example,
1567 the following returns 2.
1569 string bytelength \xff\xff
1573 If UTF-8 support is enabled, the built-in regular expression engine will be
1574 selected which supports UTF-8 strings and patterns.
1576 See REGULAR EXPRESSIONS
1580 The Tcl library provides the following built-in commands, which will
1581 be available in any application using Tcl. In addition to these
1582 built-in commands, there may be additional commands defined by each
1583 application, plus commands defined as Tcl procedures.
1585 In the command syntax descriptions below, words in +*boldface*+ are
1586 literals that you type verbatim to Tcl.
1588 Words in +'italics'+ are meta-symbols; they serve as names for any of
1589 a range of values that you can type.
1591 Optional arguments or groups of arguments are indicated by enclosing them
1592 in +?question-marks?+.
1594 Ellipses (+\...+) indicate that any number of additional
1595 arguments or groups of arguments may appear, in the same format
1596 as the preceding argument(s).
1607 Delivers the +SIGALRM+ signal to the process after the given
1608 number of seconds. If the platform supports 'ualarm(3)' then
1609 the argument may be a floating point value. Otherwise it must
1612 Note that unless a signal handler for +SIGALRM+ has been installed
1613 (see `signal`), the process will exit on this signal.
1617 +*alias* 'name args\...'+
1619 Creates a single word alias (command) for one or more words. For example,
1620 the following creates an alias for the command `info exists`.
1627 `alias` returns +'name'+, allowing it to be used with `local`.
1629 See also `proc`, `curry`, `lambda`, `local`, `info alias`, `exists -alias`
1633 +*append* 'varName value ?value value ...?'+
1635 Append all of the +'value'+ arguments to the current value
1636 of variable +'varName'+. If +'varName'+ doesn't exist,
1637 it is given a value equal to the concatenation of all the
1638 +'value'+ arguments.
1640 This command provides an efficient way to build up long
1641 variables incrementally.
1642 For example, "`append a $b`" is much more efficient than
1643 "`set a $a$b`" if +$a+ is long.
1647 +*apply* 'lambdaExpr ?arg1 arg2 \...?'+
1649 The command `apply` provides for anonymous procedure calls,
1650 similar to `lambda`, but without command name being created, even temporarily.
1652 The function +'lambdaExpr'+ is a two element list +{args body}+
1653 or a three element list +{args body namespace}+. The first element
1654 args specifies the formal arguments, in the same form as the `proc` and `lambda` commands.
1658 +*array* 'option arrayName ?arg\...?'+
1660 This command performs one of several operations on the
1661 variable given by +'arrayName'+.
1663 Note that in general, if the named array does not exist, the +'array'+ command behaves
1664 as though the array exists but is empty.
1666 The +'option'+ argument determines what action is carried out by the
1667 command. The legal +'options'+ (which may be abbreviated) are:
1669 +*array exists* 'arrayName'+::
1670 Returns 1 if arrayName is an array variable, 0 if there is
1671 no variable by that name.
1673 +*array get* 'arrayName ?pattern?'+::
1674 Returns a list containing pairs of elements. The first
1675 element in each pair is the name of an element in arrayName
1676 and the second element of each pair is the value of the
1677 array element. The order of the pairs is undefined. If
1678 pattern is not specified, then all of the elements of the
1679 array are included in the result. If pattern is specified,
1680 then only those elements whose names match pattern (using
1681 the matching rules of string match) are included. If arrayName
1682 isn't the name of an array variable, or if the array contains
1683 no elements, then an empty list is returned.
1685 +*array names* 'arrayName ?pattern?'+::
1686 Returns a list containing the names of all of the elements
1687 in the array that match pattern. If pattern is omitted then
1688 the command returns all of the element names in the array.
1689 If pattern is specified, then only those elements whose
1690 names match pattern (using the matching rules of string
1691 match) are included. If there are no (matching) elements
1692 in the array, or if arrayName isn't the name of an array
1693 variable, then an empty string is returned.
1695 +*array set* 'arrayName list'+::
1696 Sets the values of one or more elements in arrayName. list
1697 must have a form like that returned by array get, consisting
1698 of an even number of elements. Each odd-numbered element
1699 in list is treated as an element name within arrayName, and
1700 the following element in list is used as a new value for
1701 that array element. If the variable arrayName does not
1702 already exist and list is empty, arrayName is created with
1703 an empty array value.
1705 +*array size* 'arrayName'+::
1706 Returns the number of elements in the array. If arrayName
1707 isn't the name of an array then 0 is returned.
1709 +*array unset* 'arrayName ?pattern?'+::
1710 Unsets all of the elements in the array that match pattern
1711 (using the matching rules of string match). If arrayName
1712 isn't the name of an array variable or there are no matching
1713 elements in the array, no error will be raised. If pattern
1714 is omitted and arrayName is an array variable, then the
1715 command unsets the entire array. The command always returns
1722 This command may be invoked only inside the body of a loop command
1723 such as `for` or `foreach` or `while`. It returns a +JIM_BREAK+ code
1724 to signal the innermost containing loop command to return immediately.
1728 +*case* 'string' ?in? 'patList body ?patList body ...?'+
1730 +*case* 'string' ?in? {'patList body ?patList body ...?'}+
1732 *Note* that the `switch` command should generally be preferred unless compatibility
1733 with Tcl 6.x is desired.
1735 Match +'string'+ against each of the +'patList'+ arguments
1736 in order. If one matches, then evaluate the following +'body'+ argument
1737 by passing it recursively to the Tcl interpreter, and return the result
1738 of that evaluation. Each +'patList'+ argument consists of a single
1739 pattern or list of patterns. Each pattern may contain any of the wild-cards
1740 described under `string match`.
1742 If a +'patList'+ argument is +default+, the corresponding body will be
1743 evaluated if no +'patList'+ matches +'string'+. If no +'patList'+ argument
1744 matches +'string'+ and no default is given, then the `case` command returns
1747 Two syntaxes are provided.
1749 The first uses a separate argument for each of the patterns and commands;
1750 this form is convenient if substitutions are desired on some of the
1751 patterns or commands.
1753 The second form places all of the patterns and commands together into
1754 a single argument; the argument must have proper list structure, with
1755 the elements of the list being the patterns and commands.
1757 The second form makes it easy to construct multi-line case commands,
1758 since the braces around the whole list make it unnecessary to include a
1759 backslash at the end of each line.
1761 Since the +'patList'+ arguments are in braces in the second form,
1762 no command or variable substitutions are performed on them; this makes
1763 the behaviour of the second form different than the first form in some
1766 Below are some examples of `case` commands:
1768 case abc in {a b} {format 1} default {format 2} a* {format 3}
1778 will return '1', and
1793 +*catch* ?-?no?'code \...'? ?--? 'command ?resultVarName? ?optionsVarName?'+
1795 The `catch` command may be used to prevent errors from aborting
1796 command interpretation. `catch` evaluates +'command'+, and returns a
1797 +JIM_OK+ code, regardless of any errors that might occur while
1798 executing +'command'+ (with the possible exception of +JIM_SIGNAL+ -
1801 The return value from `catch` is a decimal string giving the code
1802 returned by the Tcl interpreter after executing +'command'+. This
1803 will be '0' (+JIM_OK+) if there were no errors in +'command'+; otherwise
1804 it will have a non-zero value corresponding to one of the exceptional
1805 return codes (see jim.h for the definitions of code values, or the
1806 `info returncodes` command).
1808 If the +'resultVarName'+ argument is given, then it gives the name
1809 of a variable; `catch` will set the value of the variable to the
1810 string returned from +'command'+ (either a result or an error message).
1812 If the +'optionsVarName'+ argument is given, then it gives the name
1813 of a variable; `catch` will set the value of the variable to a
1814 dictionary. For any return code other than +JIM_RETURN+, the value
1815 for the key +-code+ will be set to the return code. For +JIM_RETURN+
1816 it will be set to the code given in `return -code`. Additionally,
1817 for the return code +JIM_ERR+, the value of the key +-errorinfo+
1818 will contain the current stack trace (the same result as `info stacktrace`),
1819 the value of the key +-errorcode+ will contain the
1820 same value as the global variable $::errorCode, and the value of
1821 the key +-level+ will be the current return level (see `return -level`).
1822 This can be useful to rethrow an error:
1824 if {[catch {...} msg opts]} {
1825 ...maybe do something with the error...
1827 return {*}$opts $msg
1830 Normally `catch` will +'not'+ catch any of the codes +JIM_EXIT+, +JIM_EVAL+ or +JIM_SIGNAL+.
1831 The set of codes which will be caught may be modified by specifying the one more codes before
1834 e.g. To catch +JIM_EXIT+ but not +JIM_BREAK+ or +JIM_CONTINUE+
1836 catch -exit -nobreak -nocontinue -- { ... }
1838 The use of +--+ is optional. It signifies that no more return code options follow.
1840 Note that if a signal marked as `signal handle` is caught with `catch -signal`, the return value
1841 (stored in +'resultVarName'+) is name of the signal caught.
1847 Change the current working directory to +'dirName'+.
1849 Returns an empty string.
1851 This command can potentially be disruptive to an application, so it may
1852 be removed in some applications.
1857 Returns the current time as seconds since the epoch.
1860 Returns the current time in `clicks'.
1862 +*clock microseconds*+::
1863 Returns the current time in microseconds.
1865 +*clock milliseconds*+::
1866 Returns the current time in milliseconds.
1868 +*clock format* 'seconds' ?*-format* 'format?'+::
1869 Format the given time (seconds since the epoch) according to the given
1870 format. See strftime(3) for supported formats.
1871 If no format is supplied, "%c" is used.
1873 +*clock scan* 'str' *-format* 'format'+::
1874 Scan the given time string using the given format string.
1875 See strptime(3) for supported formats.
1883 Closes the file given by +'fileId'+.
1884 +'fileId'+ must be the return value from a previous invocation
1885 of the `open` command; after this command, it should not be
1892 Normally reference garbage collection is automatically performed periodically.
1893 However it may be run immediately with the `collect` command.
1895 See GARBAGE COLLECTION, REFERENCES, LAMBDA FUNCTION for more detail.
1899 +*concat* 'arg ?arg \...?'+
1901 This command treats each argument as a list and concatenates them
1902 into a single list. It permits any number of arguments. For example,
1905 concat a b {c d e} {f {g h}}
1917 This command may be invoked only inside the body of a loop command such
1918 as `for` or `foreach` or `while`. It returns a +JIM_CONTINUE+ code to
1919 signal the innermost containing loop command to skip the remainder of
1920 the loop's body but continue with the next iteration of the loop.
1924 +*alias* 'args\...'+
1926 Similar to `alias` except it creates an anonymous procedure (lambda) instead of
1929 the following creates a local, unnamed alias for the command `info exists`.
1931 set e [local curry info exists]
1936 `curry` returns the name of the procedure.
1938 See also `proc`, `alias`, `lambda`, `local`.
1942 +*dict* 'option ?arg\...?'+
1944 Performs one of several operations on dictionary values.
1946 The +'option'+ argument determines what action is carried out by the
1947 command. The legal +'options'+ are:
1949 +*dict create* '?key value \...?'+::
1950 Create and return a new dictionary value that contains each of
1951 the key/value mappings listed as arguments (keys and values
1952 alternating, with each key being followed by its associated
1955 +*dict exists* 'dictionary key ?key \...?'+::
1956 Returns a boolean value indicating whether the given key (or path
1957 of keys through a set of nested dictionaries) exists in the given
1958 dictionary value. This returns a true value exactly when `dict get`
1959 on that path will succeed.
1961 +*dict get* 'dictionary ?key \...?'+::
1962 Given a dictionary value (first argument) and a key (second argument),
1963 this will retrieve the value for that key. Where several keys are
1964 supplied, the behaviour of the command shall be as if the result
1965 of "`dict get $dictVal $key`" was passed as the first argument to
1966 dict get with the remaining arguments as second (and possibly
1967 subsequent) arguments. This facilitates lookups in nested dictionaries.
1968 If no keys are provided, dict would return a list containing pairs
1969 of elements in a manner similar to array get. That is, the first
1970 element of each pair would be the key and the second element would
1971 be the value for that key. It is an error to attempt to retrieve
1972 a value for a key that is not present in the dictionary.
1974 +*dict keys* 'dictionary ?pattern?'+::
1975 Returns a list of the keys in the dictionary.
1976 If pattern is specified, then only those keys whose
1977 names match +'pattern'+ (using the matching rules of string
1978 match) are included.
1980 +*dict merge* ?'dictionary \...'?+::
1981 Return a dictionary that contains the contents of each of the
1982 +'dictionary'+ arguments. Where two (or more) dictionaries
1983 contain a mapping for the same key, the resulting dictionary
1984 maps that key to the value according to the last dictionary on
1985 the command line containing a mapping for that key.
1987 +*dict set* 'dictionaryName key ?key \...? value'+::
1988 This operation takes the +'name'+ of a variable containing a dictionary
1989 value and places an updated dictionary value in that variable
1990 containing a mapping from the given key to the given value. When
1991 multiple keys are present, this operation creates or updates a chain
1992 of nested dictionaries.
1994 +*dict size* 'dictionary'+::
1995 Return the number of key/value mappings in the given dictionary value.
1997 +*dict unset* 'dictionaryName key ?key \...? value'+::
1998 This operation (the companion to `dict set`) takes the name of a
1999 variable containing a dictionary value and places an updated
2000 dictionary value in that variable that does not contain a mapping
2001 for the given key. Where multiple keys are present, this describes
2002 a path through nested dictionaries to the mapping to remove. At
2003 least one key must be specified, but the last key on the key-path
2004 need not exist. All other components on the path must exist.
2006 +*dict with* 'dictionaryName key ?key \...? script'+::
2007 Execute the Tcl script in +'script'+ with the value for each
2008 key in +'dictionaryName'+ mapped to a variable with the same
2009 name. Where one or more keys are given, these indicate a chain
2010 of nested dictionaries, with the innermost dictionary being the
2011 one opened out for the execution of body. Making +'dictionaryName'+
2012 unreadable will make the updates to the dictionary be discarded,
2013 and this also happens if the contents of +'dictionaryName'+ are
2014 adjusted so that the chain of dictionaries no longer exists.
2015 The result of `dict with` is (unless some kind of error occurs)
2016 the result of the evaluation of body.
2018 The variables are mapped in the scope enclosing the `dict with`;
2019 it is recommended that this command only be used in a local
2020 scope (procedure). Because of this, the variables set by
2021 `dict with` will continue to exist after the command finishes (unless
2022 explicitly unset). Note that changes to the contents of +'dictionaryName'+
2023 only happen when +'script'+ terminates.
2025 +*dict for, values, incr, append, lappend, update, info, replace*+ to be documented...
2029 +*env* '?name? ?default?'+
2031 If +'name'+ is supplied, returns the value of +'name'+ from the initial
2032 environment (see getenv(3)). An error is returned if +'name'+ does not
2033 exist in the environment, unless +'default'+ is supplied - in which case
2034 that value is returned instead.
2036 If no arguments are supplied, returns a list of all environment variables
2037 and their values as +{name value \...}+
2039 See also the global variable +::env+
2047 Returns 1 if an end-of-file condition has occurred on +'fileId'+,
2050 +'fileId'+ must have been the return value from a previous call to `open`,
2051 or it may be +stdin+, +stdout+, or +stderr+ to refer to one of the
2052 standard I/O channels.
2056 +*error* 'message ?stacktrace?'+
2058 Returns a +JIM_ERR+ code, which causes command interpretation to be
2059 unwound. +'message'+ is a string that is returned to the application
2060 to indicate what went wrong.
2062 If the +'stacktrace'+ argument is provided and is non-empty,
2063 it is used to initialize the stacktrace.
2065 This feature is most useful in conjunction with the `catch` command:
2066 if a caught error cannot be handled successfully, +'stacktrace'+ can be used
2067 to return a stack trace reflecting the original point of occurrence
2072 error $errMsg [info stacktrace]
2074 See also `errorInfo`, `info stacktrace`, `catch` and `return`
2078 +*errorInfo* 'error ?stacktrace?'+
2080 Returns a human-readable representation of the given error message and stack trace.
2083 if {[catch {...} error]} {
2084 puts stderr [errorInfo $error [info stacktrace]]
2092 +*eval* 'arg ?arg\...?'+
2094 `eval` takes one or more arguments, which together comprise a Tcl
2095 command (or collection of Tcl commands separated by newlines in the
2096 usual way). `eval` concatenates all its arguments in the same
2097 fashion as the `concat` command, passes the concatenated string to the
2098 Tcl interpreter recursively, and returns the result of that
2099 evaluation (or any error generated by it).
2103 +*exec* 'arg ?arg\...?'+
2105 This command treats its arguments as the specification
2106 of one or more UNIX commands to execute as subprocesses.
2107 The commands take the form of a standard shell pipeline;
2108 +|+ arguments separate commands in the
2109 pipeline and cause standard output of the preceding command
2110 to be piped into standard input of the next command (or +|&+ for
2111 both standard output and standard error).
2113 Under normal conditions the result of the `exec` command
2114 consists of the standard output produced by the last command
2115 in the pipeline followed by the standard error output.
2117 If any of the commands writes to its standard error file,
2118 then this will be included in the result after the standard output
2119 of the last command.
2121 Note that unlike Tcl, data written to standard error does not cause
2122 `exec` to return an error.
2124 If any of the commands in the pipeline exit abnormally or
2125 are killed or suspended, then `exec` will return an error.
2126 If no standard error output was produced, or is redirected,
2127 the error message will include the normal result, as above,
2128 followed by error messages describing the abnormal terminations.
2130 If any standard error output was produced, these abnormal termination
2131 messages are suppressed.
2133 If the last character of the result or error message
2134 is a newline then that character is deleted from the result
2135 or error message for consistency with normal
2138 An +'arg'+ may have one of the following special forms:
2141 The standard output of the last command in the pipeline
2142 is redirected to the file. In this situation `exec`
2143 will normally return an empty string.
2146 As above, but append to the file.
2149 The standard output of the last command in the pipeline is
2150 redirected to the given (writable) file descriptor (e.g. stdout,
2151 stderr, or the result of `open`). In this situation `exec`
2152 will normally return an empty string.
2155 The standard error of the last command in the pipeline
2156 is redirected to the file.
2159 As above, but append to the file.
2162 The standard error of the last command in the pipeline is
2163 redirected to the given (writable) file descriptor.
2166 The standard error of the last command in the pipeline is
2167 redirected to the same file descriptor as the standard output.
2170 Both the standard output and standard error of the last command
2171 in the pipeline is redirected to the file.
2174 As above, but append to the file.
2177 The standard input of the first command in the pipeline
2178 is taken from the file.
2181 The standard input of the first command is taken as the
2182 given immediate value.
2185 The standard input of the first command in the pipeline
2186 is taken from the given (readable) file descriptor.
2188 If there is no redirection of standard input, standard error
2189 or standard output, these are connected to the corresponding
2190 input or output of the application.
2192 If the last +'arg'+ is +&+ then the command will be
2193 executed in background.
2194 In this case the standard output from the last command
2195 in the pipeline will
2196 go to the application's standard output unless
2197 redirected in the command, and error output from all
2198 the commands in the pipeline will go to the application's
2199 standard error file. The return value of exec in this case
2200 is a list of process ids (pids) in the pipeline.
2202 Each +'arg'+ becomes one word for a command, except for
2203 +|+, +<+, +<<+, +>+, and +&+ arguments, and the
2204 arguments that follow +<+, +<<+, and +>+.
2206 The first word in each command is taken as the command name;
2207 the directories in the PATH environment variable are searched for
2208 an executable by the given name.
2210 No `glob` expansion or other shell-like substitutions
2211 are performed on the arguments to commands.
2213 If the command fails, the global $::errorCode (and the -errorcode
2214 option in `catch`) will be set to a list, as follows:
2216 +*CHILDKILLED* 'pid sigName msg'+::
2217 This format is used when a child process has been killed
2218 because of a signal. The pid element will be the process's
2219 identifier (in decimal). The sigName element will be the
2220 symbolic name of the signal that caused the process to
2221 terminate; it will be one of the names from the include
2222 file signal.h, such as SIGPIPE. The msg element will be a
2223 short human-readable message describing the signal, such
2224 as "write on pipe with no readers" for SIGPIPE.
2226 +*CHILDSUSP* 'pid sigName msg'+::
2227 This format is used when a child process has been suspended
2228 because of a signal. The pid element will be the process's
2229 identifier, in decimal. The sigName element will be the
2230 symbolic name of the signal that caused the process to
2231 suspend; this will be one of the names from the include
2232 file signal.h, such as SIGTTIN. The msg element will be a
2233 short human-readable message describing the signal, such
2234 as "background tty read" for SIGTTIN.
2236 +*CHILDSTATUS* 'pid code'+::
2237 This format is used when a child process has exited with a
2238 non-zero exit status. The pid element will be the process's
2239 identifier (in decimal) and the code element will be the
2240 exit code returned by the process (also in decimal).
2242 The environment for the executed command is set from $::env (unless
2243 this variable is unset, in which case the original environment is used).
2247 +*exists ?-var|-proc|-command|-alias?* 'name'+
2249 Checks the existence of the given variable, procedure, command
2250 or alias respectively and returns 1 if it exists or 0 if not. This command
2251 provides a more simplified/convenient version of `info exists`,
2252 `info procs` and `info commands`.
2254 If the type is omitted, a type of '-var' is used. The type may be abbreviated.
2258 +*exit* '?returnCode?'+
2260 Terminate the process, returning +'returnCode'+ to the
2261 parent as the exit status.
2263 If +'returnCode'+ isn't specified then it defaults
2266 Note that exit can be caught with `catch`.
2272 Calls the expression processor to evaluate +'arg'+, and returns
2273 the result as a string. See the section EXPRESSIONS above.
2275 Note that Jim supports a shorthand syntax for `expr` as +$(\...)+
2276 The following two are identical.
2278 set x [expr {3 * 2 + 1}]
2283 +*file* 'option name ?arg\...?'+
2285 Operate on a file or a file name. +'name'+ is the name of a file.
2287 +'option'+ indicates what to do with the file name. Any unique
2288 abbreviation for +'option'+ is acceptable. The valid options are:
2290 +*file atime* 'name'+::
2291 Return a decimal string giving the time at which file +'name'+
2292 was last accessed. The time is measured in the standard UNIX
2293 fashion as seconds from a fixed starting time (often January 1, 1970).
2294 If the file doesn't exist or its access time cannot be queried then an
2297 +*file copy ?-force?* 'source target'+::
2298 Copies file +'source'+ to file +'target'+. The source file must exist.
2299 The target file must not exist, unless +-force+ is specified.
2301 +*file delete ?-force? ?--?* 'name\...'+::
2302 Deletes file or directory +'name'+. If the file or directory doesn't exist, nothing happens.
2303 If it can't be deleted, an error is generated. Non-empty directories will not be deleted
2304 unless the +-force+ options is given. In this case no errors will be generated, even
2305 if the file/directory can't be deleted. Use +'--'+ if there is any possibility of
2306 the first name being +'-force'+.
2308 +*file dirname* 'name'+::
2309 Return all of the characters in +'name'+ up to but not including
2310 the last slash character. If there are no slashes in +'name'+
2311 then return +.+ (a single dot). If the last slash in +'name'+ is its first
2312 character, then return +/+.
2314 +*file executable* 'name'+::
2315 Return '1' if file +'name'+ is executable by
2316 the current user, '0' otherwise.
2318 +*file exists* 'name'+::
2319 Return '1' if file +'name'+ exists and the current user has
2320 search privileges for the directories leading to it, '0' otherwise.
2322 +*file extension* 'name'+::
2323 Return all of the characters in +'name'+ after and including the
2324 last dot in +'name'+. If there is no dot in +'name'+ then return
2327 +*file isdirectory* 'name'+::
2328 Return '1' if file +'name'+ is a directory,
2331 +*file isfile* 'name'+::
2332 Return '1' if file +'name'+ is a regular file,
2335 +*file join* 'arg\...'+::
2336 Joins multiple path components. Note that if any components is
2337 an absolute path, the preceding components are ignored.
2338 Thus +"`file` join /tmp /root"+ returns +"/root"+.
2340 +*file link* ?*-hard|-symbolic*? 'newname target'+::
2341 Creates a hard link (default) or symbolic link from +'newname'+ to +'target'+.
2342 Note that the sense of this command is the opposite of `file rename` and `file copy`
2343 and also of `ln`, but this is compatible with Tcl.
2344 An error is returned if +'target'+ doesn't exist or +'newname'+ already exists.
2346 +*file lstat* 'name varName'+::
2347 Same as 'stat' option (see below) except uses the +'lstat'+
2348 kernel call instead of +'stat'+. This means that if +'name'+
2349 refers to a symbolic link the information returned in +'varName'+
2350 is for the link rather than the file it refers to. On systems that
2351 don't support symbolic links this option behaves exactly the same
2352 as the 'stat' option.
2354 +*file mkdir* 'dir1 ?dir2\...?'+::
2355 Creates each directory specified. For each pathname +'dir'+ specified,
2356 this command will create all non-existing parent directories
2357 as well as +'dir'+ itself. If an existing directory is specified,
2358 then no action is taken and no error is returned. Trying to
2359 overwrite an existing file with a directory will result in an
2360 error. Arguments are processed in the order specified, halting
2361 at the first error, if any.
2363 +*file mtime* 'name ?time?'+::
2364 Return a decimal string giving the time at which file +'name'+
2365 was last modified. The time is measured in the standard UNIX
2366 fashion as seconds from a fixed starting time (often January 1, 1970).
2367 If the file doesn't exist or its modified time cannot be queried then an
2368 error is generated. If +'time'+ is given, sets the modification time
2369 of the file to the given value.
2371 +*file normalize* 'name'+::
2372 Return the normalized path of +'name'+. See 'realpath(3)'.
2374 +*file owned* 'name'+::
2375 Return '1' if file +'name'+ is owned by the current user,
2378 +*file readable* 'name'+::
2379 Return '1' if file +'name'+ is readable by
2380 the current user, '0' otherwise.
2382 +*file readlink* 'name'+::
2383 Returns the value of the symbolic link given by +'name'+ (i.e. the
2384 name of the file it points to). If
2385 +'name'+ isn't a symbolic link or its value cannot be read, then
2386 an error is returned. On systems that don't support symbolic links
2387 this option is undefined.
2389 +*file rename* ?*-force*? 'oldname' 'newname'+::
2390 Renames the file from the old name to the new name.
2391 If +'newname'+ already exists, an error is returned unless +'-force'+ is
2394 +*file rootname* 'name'+::
2395 Return all of the characters in +'name'+ up to but not including
2396 the last '.' character in the name. If +'name'+ doesn't contain
2397 a dot, then return +'name'+.
2399 +*file size* 'name'+::
2400 Return a decimal string giving the size of file +'name'+ in bytes.
2401 If the file doesn't exist or its size cannot be queried then an
2404 +*file stat* 'name ?varName?'+::
2405 Invoke the 'stat' kernel call on +'name'+, and return the result
2406 as a dictionary with the following keys: 'atime',
2407 'ctime', 'dev', 'gid', 'ino', 'mode', 'mtime',
2408 'nlink', 'size', 'type', 'uid'.
2409 Each element except 'type' is a decimal string with the value of
2410 the corresponding field from the 'stat' return structure; see the
2411 manual entry for 'stat' for details on the meanings of the values.
2412 The 'type' element gives the type of the file in the same form
2413 returned by the command `file type`.
2414 If +'varName'+ is specified, it is taken to be the name of an array
2415 variable and the values are also stored into the array.
2417 +*file tail* 'name'+::
2418 Return all of the characters in +'name'+ after the last slash.
2419 If +'name'+ contains no slashes then return +'name'+.
2421 +*file tempfile* '?template?'+::
2422 Creates and returns the name of a unique temporary file. If +'template'+ is omitted, a
2423 default template will be used to place the file in /tmp. See 'mkstemp(3)' for
2424 the format of the template and security concerns.
2426 +*file type* 'name'+::
2427 Returns a string giving the type of file +'name'+, which will be
2428 one of +file+, +directory+, +characterSpecial+,
2429 +blockSpecial+, +fifo+, +link+, or +socket+.
2431 +*file writable* 'name'+::
2432 Return '1' if file +'name'+ is writable by
2433 the current user, '0' otherwise.
2435 The `file` commands that return 0/1 results are often used in
2436 conditional or looping commands, for example:
2438 if {![file exists foo]} {
2439 error {bad file name}
2446 +*finalize* 'reference ?command?'+
2448 If +'command'+ is omitted, returns the finalizer command for the given reference.
2450 Otherwise, sets a new finalizer command for the given reference. +'command'+ may be
2451 the empty string to remove the current finalizer.
2453 The reference must be a valid reference create with the `ref`
2456 See GARBAGE COLLECTION, REFERENCES, LAMBDA FUNCTION for more detail.
2464 Flushes any output that has been buffered for +'fileId'+. +'fileId'+ must
2465 have been the return value from a previous call to `open`, or it may be
2466 +stdout+ or +stderr+ to access one of the standard I/O streams; it must
2467 refer to a file that was opened for writing. This command returns an
2472 +*for* 'start test next body'+
2474 `for` is a looping command, similar in structure to the C `for` statement.
2475 The +'start'+, +'next'+, and +'body'+ arguments must be Tcl command strings,
2476 and +'test'+ is an expression string.
2478 The `for` command first invokes the Tcl interpreter to execute +'start'+.
2479 Then it repeatedly evaluates +'test'+ as an expression; if the result is
2480 non-zero it invokes the Tcl interpreter on +'body'+, then invokes the Tcl
2481 interpreter on +'next'+, then repeats the loop. The command terminates
2482 when +'test'+ evaluates to 0.
2484 If a `continue` command is invoked within +'body'+ then any remaining
2485 commands in the current execution of +'body'+ are skipped; processing
2486 continues by invoking the Tcl interpreter on +'next'+, then evaluating
2487 +'test'+, and so on.
2489 If a `break` command is invoked within +'body'+ or +'next'+, then the `for`
2490 command will return immediately.
2492 The operation of `break` and `continue` are similar to the corresponding
2495 `for` returns an empty string.
2499 +*foreach* 'varName list body'+
2501 +*foreach* 'varList list ?varList2 list2 \...? body'+
2503 In this command, +'varName'+ is the name of a variable, +'list'+
2504 is a list of values to assign to +'varName'+, and +'body'+ is a
2505 collection of Tcl commands.
2507 For each field in +'list'+ (in order from left to right), `foreach` assigns
2508 the contents of the field to +'varName'+ (as if the `lindex` command
2509 had been used to extract the field), then calls the Tcl interpreter to
2512 If instead of being a simple name, +'varList'+ is used, multiple assignments
2513 are made each time through the loop, one for each element of +'varList'+.
2515 For example, if there are two elements in +'varList'+ and six elements in
2516 the list, the loop will be executed three times.
2518 If the length of the list doesn't evenly divide by the number of elements
2519 in +'varList'+, the value of the remaining variables in the last iteration
2520 of the loop are undefined.
2522 The `break` and `continue` statements may be invoked inside +'body'+,
2523 with the same effect as in the `for` command.
2525 `foreach` returns an empty string.
2529 +*format* 'formatString ?arg \...?'+
2531 This command generates a formatted string in the same way as the
2532 C 'sprintf' procedure (it uses 'sprintf' in its
2533 implementation). +'formatString'+ indicates how to format
2534 the result, using +%+ fields as in 'sprintf', and the additional
2535 arguments, if any, provide values to be substituted into the result.
2537 All of the 'sprintf' options are valid; see the 'sprintf'
2538 man page for details. Each +'arg'+ must match the expected type
2539 from the +%+ field in +'formatString'+; the `format` command
2540 converts each argument to the correct type (floating, integer, etc.)
2541 before passing it to 'sprintf' for formatting.
2543 The only unusual conversion is for +%c+; in this case the argument
2544 must be a decimal string, which will then be converted to the corresponding
2545 ASCII (or UTF-8) character value.
2547 In addition, Jim Tcl provides basic support for conversion to binary with +%b+.
2549 `format` does backslash substitution on its +'formatString'+
2550 argument, so backslash sequences in +'formatString'+ will be handled
2551 correctly even if the argument is in braces.
2553 The return value from `format` is the formatted string.
2557 +*getref* 'reference'+
2559 Returns the string associated with +'reference'+. The reference must
2560 be a valid reference create with the `ref` command.
2562 See GARBAGE COLLECTION, REFERENCES, LAMBDA FUNCTION for more detail.
2566 +*gets* 'fileId ?varName?'+
2568 +'fileId' *gets* '?varName?'+
2570 Reads the next line from the file given by +'fileId'+ and discards
2571 the terminating newline character.
2573 If +'varName'+ is specified, then the line is placed in the variable
2574 by that name and the return value is a count of the number of characters
2575 read (not including the newline).
2577 If the end of the file is reached before reading
2578 any characters then -1 is returned and +'varName'+ is set to an
2581 If +'varName'+ is not specified then the return value will be
2582 the line (minus the newline character) or an empty string if
2583 the end of the file is reached before reading any characters.
2585 An empty string will also be returned if a line contains no characters
2586 except the newline, so `eof` may have to be used to determine
2587 what really happened.
2589 If the last character in the file is not a newline character, then
2590 `gets` behaves as if there were an additional newline character
2591 at the end of the file.
2593 +'fileId'+ must be +stdin+ or the return value from a previous
2594 call to `open`; it must refer to a file that was opened
2599 +*glob* ?*-nocomplain*? ?*-directory* 'dir'? ?*-tails*? ?*--*? 'pattern ?pattern \...?'+
2601 This command performs filename globbing, using csh rules. The returned
2602 value from `glob` is the list of expanded filenames.
2604 If +-nocomplain+ is specified as the first argument then an empty
2605 list may be returned; otherwise an error is returned if the expanded
2606 list is empty. The +-nocomplain+ argument must be provided
2607 exactly: an abbreviation will not be accepted.
2609 If +-directory+ is given, the +'dir'+ is understood to contain a
2610 directory name to search in. This allows globbing inside directories
2611 whose names may contain glob-sensitive characters. The returned names
2612 include the directory name unless +'-tails'+ is specified.
2614 If +'-tails'+ is specified, along with +-directory+, the returned names
2615 are relative to the given directory.
2620 +*global* 'varName ?varName \...?'+
2622 This command is ignored unless a Tcl procedure is being interpreted.
2623 If so, then it declares each given +'varName'+ to be a global variable
2624 rather than a local one. For the duration of the current procedure
2625 (and only while executing in the current procedure), any reference to
2626 +'varName'+ will be bound to a global variable instead
2629 An alternative to using `global` is to use the +::+ prefix
2630 to explicitly name a variable in the global scope.
2634 +*if* 'expr1' ?*then*? 'body1' *elseif* 'expr2' ?*then*? 'body2' *elseif* \... ?*else*? ?'bodyN'?+
2636 The `if` command evaluates +'expr1'+ as an expression (in the same way
2637 that `expr` evaluates its argument). The value of the expression must
2638 be numeric; if it is non-zero then +'body1'+ is executed by passing it to
2639 the Tcl interpreter.
2641 Otherwise +'expr2'+ is evaluated as an expression and if it is non-zero
2642 then +'body2'+ is executed, and so on.
2644 If none of the expressions evaluates to non-zero then +'bodyN'+ is executed.
2646 The +then+ and +else+ arguments are optional "noise words" to make the
2647 command easier to read.
2649 There may be any number of +elseif+ clauses, including zero. +'bodyN'+
2650 may also be omitted as long as +else+ is omitted too.
2652 The return value from the command is the result of the body script that
2653 was executed, or an empty string if none of the expressions was non-zero
2654 and there was no +'bodyN'+.
2658 +*incr* 'varName ?increment?'+
2660 Increment the value stored in the variable whose name is +'varName'+.
2661 The value of the variable must be integral.
2663 If +'increment'+ is supplied then its value (which must be an
2664 integer) is added to the value of variable +'varName'+; otherwise
2665 1 is added to +'varName'+.
2667 The new value is stored as a decimal string in variable +'varName'+
2668 and also returned as result.
2670 If the variable does not exist, the variable is implicitly created
2671 and set to +0+ first.
2676 +*info* 'option ?arg\...?'+::
2678 Provide information about various internals to the Tcl interpreter.
2679 The legal +'option'+'s (which may be abbreviated) are:
2681 +*info args* 'procname'+::
2682 Returns a list containing the names of the arguments to procedure
2683 +'procname'+, in order. +'procname'+ must be the name of a
2684 Tcl command procedure.
2686 +*info alias* 'command'+::
2687 +'command'+ must be an alias created with `alias`. In which case the target
2688 command and arguments, as passed to `alias` are returned. See `exists -alias`
2690 +*info body* 'procname'+::
2691 Returns the body of procedure +'procname'+. +'procname'+ must be
2692 the name of a Tcl command procedure.
2695 Returns a list of all open file handles from `open` or `socket`
2697 +*info commands* ?'pattern'?+::
2698 If +'pattern'+ isn't specified, returns a list of names of all the
2699 Tcl commands, including both the built-in commands written in C and
2700 the command procedures defined using the `proc` command.
2701 If +'pattern'+ is specified, only those names matching +'pattern'+
2702 are returned. Matching is determined using the same rules as for
2705 +*info complete* 'command' ?'missing'?+::
2706 Returns 1 if +'command'+ is a complete Tcl command in the sense of
2707 having no unclosed quotes, braces, brackets or array element names,
2708 If the command doesn't appear to be complete then 0 is returned.
2709 This command is typically used in line-oriented input environments
2710 to allow users to type in commands that span multiple lines; if the
2711 command isn't complete, the script can delay evaluating it until additional
2712 lines have been typed to complete the command. If +'varName'+ is specified, the
2713 missing character is stored in the variable with that name.
2715 +*info exists* 'varName'+::
2716 Returns '1' if the variable named +'varName'+ exists in the
2717 current context (either as a global or local variable), returns '0'
2720 +*info frame* ?'number'?+::
2721 If +'number'+ is not specified, this command returns a number
2722 which is the same result as `info level` - the current stack frame level.
2723 If +'number'+ is specified, then the result is a list consisting of the procedure,
2724 filename and line number for the procedure call at level +'number'+ on the stack.
2725 If +'number'+ is positive then it selects a particular stack level (1 refers
2726 to the top-most active procedure, 2 to the procedure it called, and
2727 so on); otherwise it gives a level relative to the current level
2728 (0 refers to the current procedure, -1 to its caller, and so on).
2729 The level has an identical meaning to `info level`.
2731 +*info globals* ?'pattern'?+::
2732 If +'pattern'+ isn't specified, returns a list of all the names
2733 of currently-defined global variables.
2734 If +'pattern'+ is specified, only those names matching +'pattern'+
2735 are returned. Matching is determined using the same rules as for
2739 An alias for `os.gethostname` for compatibility with Tcl 6.x
2741 +*info level* ?'number'?+::
2742 If +'number'+ is not specified, this command returns a number
2743 giving the stack level of the invoking procedure, or 0 if the
2744 command is invoked at top-level. If +'number'+ is specified,
2745 then the result is a list consisting of the name and arguments for the
2746 procedure call at level +'number'+ on the stack. If +'number'+
2747 is positive then it selects a particular stack level (1 refers
2748 to the top-most active procedure, 2 to the procedure it called, and
2749 so on); otherwise it gives a level relative to the current level
2750 (0 refers to the current procedure, -1 to its caller, and so on).
2751 See the `uplevel` command for more information on what stack
2754 +*info locals* ?'pattern'?+::
2755 If +'pattern'+ isn't specified, returns a list of all the names
2756 of currently-defined local variables, including arguments to the
2757 current procedure, if any. Variables defined with the `global`
2758 and `upvar` commands will not be returned. If +'pattern'+ is
2759 specified, only those names matching +'pattern'+ are returned.
2760 Matching is determined using the same rules as for `string match`.
2762 +*info nameofexecutable*+::
2763 Returns the name of the binary file from which the application
2764 was invoked. A full path will be returned, unless the path
2765 can't be determined, in which case the empty string will be returned.
2767 +*info procs* ?'pattern'?+::
2768 If +'pattern'+ isn't specified, returns a list of all the
2769 names of Tcl command procedures.
2770 If +'pattern'+ is specified, only those names matching +'pattern'+
2771 are returned. Matching is determined using the same rules as for
2774 +*info references*+::
2775 Returns a list of all references which have not yet been garbage
2778 +*info returncodes* ?'code'?+::
2779 Returns a list representing the mapping of standard return codes
2780 to names. e.g. +{0 ok 1 error 2 return \...}+. If a code is given,
2781 instead returns the name for the given code.
2784 If a Tcl script file is currently being evaluated (i.e. there is a
2785 call to 'Jim_EvalFile' active or there is an active invocation
2786 of the `source` command), then this command returns the name
2787 of the innermost file being processed. Otherwise the command returns an
2790 +*info source* 'script ?filename line?'+::
2791 With a single argument, returns the original source location of the given script as a list of
2792 +{filename linenumber}+. If the source location can't be determined, the
2793 list +{{} 0}+ is returned. If +'filename'+ and +'line'+ are given, returns a copy
2794 of +'script'+ with the associate source information. This can be useful to produce
2795 useful messages from `eval`, etc. if the original source information may be lost.
2797 +*info stacktrace*+::
2798 After an error is caught with `catch`, returns the stack trace as a list
2799 of +{procedure filename line \...}+.
2801 +*info statics* 'procname'+::
2802 Returns a dictionary of the static variables of procedure
2803 +'procname'+. +'procname'+ must be the name of a Tcl command
2804 procedure. An empty dictionary is returned if the procedure has
2805 no static variables.
2808 Returns the version number for this version of Jim in the form +*x.yy*+.
2810 +*info vars* ?'pattern'?+::
2811 If +'pattern'+ isn't specified,
2812 returns a list of all the names of currently-visible variables, including
2813 both locals and currently-visible globals.
2814 If +'pattern'+ is specified, only those names matching +'pattern'+
2815 are returned. Matching is determined using the same rules as for
2820 +*join* 'list ?joinString?'+
2822 The +'list'+ argument must be a valid Tcl list. This command returns the
2823 string formed by joining all of the elements of +'list'+ together with
2824 +'joinString'+ separating each adjacent pair of elements.
2826 The +'joinString'+ argument defaults to a space character.
2830 +*kill* ?'SIG'|*-0*? 'pid'+
2832 Sends the given signal to the process identified by +'pid'+.
2834 The signal may be specified by name or number in one of the following forms:
2842 The signal name may be in either upper or lower case.
2844 The special signal name +-0+ simply checks that a signal +'could'+ be sent.
2846 If no signal is specified, SIGTERM is used.
2848 An error is raised if the signal could not be delivered.
2852 +*lambda* 'args ?statics? body'+
2854 The `lambda` command is identical to `proc`, except rather than
2855 creating a named procedure, it creates an anonymous procedure and returns
2856 the name of the procedure.
2858 See `proc` and GARBAGE COLLECTION, REFERENCES, LAMBDA FUNCTION for more detail.
2862 +*lappend* 'varName value ?value value \...?'+
2864 Treat the variable given by +'varName'+ as a list and append each of
2865 the +'value'+ arguments to that list as a separate element, with spaces
2868 If +'varName'+ doesn't exist, it is created as a list with elements given
2869 by the +'value'+ arguments. `lappend` is similar to `append` except that
2870 each +'value'+ is appended as a list element rather than raw text.
2872 This command provides a relatively efficient way to build up large lists.
2877 is much more efficient than
2879 set a [concat $a [list $b]]
2885 +*lassign* 'list varName ?varName \...?'+
2887 This command treats the value +'list'+ as a list and assigns successive elements from that list to
2888 the variables given by the +'varName'+ arguments in order. If there are more variable names than
2889 list elements, the remaining variables are set to the empty string. If there are more list elements
2890 than variables, a list of unassigned elements is returned.
2892 jim> lassign {1 2 3} a b; puts a=$a,b=$b
2898 +*local* 'cmd ?arg\...?'+
2900 First, `local` evaluates +'cmd'+ with the given arguments. The return value must
2901 be the name of an existing command, which is marked as having local scope.
2902 This means that when the current procedure exits, the specified
2903 command is deleted. This can be useful with `lambda`, local procedures or
2904 to automatically close a filehandle.
2906 In addition, if a command already exists with the same name,
2907 the existing command will be kept rather than deleted, and may be called
2908 via `upcall`. The previous command will be restored when the current
2909 procedure exits. See `upcall` for more details.
2911 In this example, a local procedure is created. Note that the procedure
2912 continues to have global scope while it is active.
2915 # proc ... returns "inner" which is marked local
2916 local proc inner {} {
2917 # will be deleted when 'outer' exits
2924 In this example, the lambda is deleted at the end of the procedure rather
2925 than waiting until garbage collection.
2928 set x [lambda inner {args} {
2929 # will be deleted when 'outer' exits
2931 # Use 'function' here which simply returns $x
2940 +*loop* 'var first limit ?incr? body'+
2942 Similar to `for` except simpler and possibly more efficient.
2943 With a positive increment, equivalent to:
2945 for {set var $first} {$var < $limit} {incr var $incr} $body
2947 If +'incr'+ is not specified, 1 is used.
2948 Note that setting the loop variable inside the loop does not
2949 affect the loop count.
2953 +*lindex* 'list ?index ...?'+
2955 Treats +'list'+ as a Tcl list and returns element +'index'+ from it
2956 (0 refers to the first element of the list).
2957 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for +'index'+.
2959 In extracting the element, +'lindex'+ observes the same rules concerning
2960 braces and quotes and backslashes as the Tcl command interpreter; however,
2961 variable substitution and command substitution do not occur.
2963 If no index values are given, simply returns +'list'+
2965 If +'index'+ is negative or greater than or equal to the number of elements
2966 in +'list'+, then an empty string is returned.
2968 If additional index arguments are supplied, then each argument is
2969 used in turn to select an element from the previous indexing
2970 operation, allowing the script to select elements from sublists.
2974 +*linsert* 'list index element ?element element \...?'+
2976 This command produces a new list from +'list'+ by inserting all
2977 of the +'element'+ arguments just before the element +'index'+
2978 of +'list'+. Each +'element'+ argument will become
2979 a separate element of the new list. If +'index'+ is less than
2980 or equal to zero, then the new elements are inserted at the
2981 beginning of the list. If +'index'+ is greater than or equal
2982 to the number of elements in the list, then the new elements are
2983 appended to the list.
2985 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for +'index'+.
2990 +*list* 'arg ?arg \...?'+
2992 This command returns a list comprised of all the arguments, +'arg'+. Braces
2993 and backslashes get added as necessary, so that the `lindex` command
2994 may be used on the result to re-extract the original arguments, and also
2995 so that `eval` may be used to execute the resulting list, with
2996 +'arg1'+ comprising the command's name and the other args comprising
2997 its arguments. `list` produces slightly different results than
2998 `concat`: `concat` removes one level of grouping before forming
2999 the list, while `list` works directly from the original arguments.
3000 For example, the command
3002 list a b {c d e} {f {g h}}
3006 a b {c d e} {f {g h}}
3008 while `concat` with the same arguments will return
3016 Treats +'list'+ as a list and returns a decimal string giving
3017 the number of elements in it.
3021 +*lset* 'varName ?index ..? newValue'+
3023 Sets an element in a list.
3025 The `lset` command accepts a parameter, +'varName'+, which it interprets
3026 as the name of a variable containing a Tcl list. It also accepts
3027 zero or more indices into the list. Finally, it accepts a new value
3028 for an element of varName. If no indices are presented, the command
3031 lset varName newValue
3033 In this case, newValue replaces the old value of the variable
3036 When presented with a single index, the `lset` command
3037 treats the content of the varName variable as a Tcl list. It addresses
3038 the index'th element in it (0 refers to the first element of the
3039 list). When interpreting the list, `lset` observes the same rules
3040 concerning braces and quotes and backslashes as the Tcl command
3041 interpreter; however, variable substitution and command substitution
3042 do not occur. The command constructs a new list in which the
3043 designated element is replaced with newValue. This new list is
3044 stored in the variable varName, and is also the return value from
3047 If index is negative or greater than or equal to the number of
3048 elements in $varName, then an error occurs.
3050 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for +'index'+.
3052 If additional index arguments are supplied, then each argument is
3053 used in turn to address an element within a sublist designated by
3054 the previous indexing operation, allowing the script to alter
3055 elements in sublists. The command,
3059 replaces element 2 of sublist 1 with +'newValue'+.
3061 The integer appearing in each index argument must be greater than
3062 or equal to zero. The integer appearing in each index argument must
3063 be strictly less than the length of the corresponding list. In other
3064 words, the `lset` command cannot change the size of a list. If an
3065 index is outside the permitted range, an error is reported.
3070 +*lmap* 'varName list body'+
3072 +*lmap* 'varList list ?varList2 list2 \...? body'+
3074 `lmap` is a "collecting" `foreach` which returns a list of its results.
3078 jim> lmap i {1 2 3 4 5} {expr $i*$i}
3080 jim> lmap a {1 2 3} b {A B C} {list $a $b}
3083 If the body invokes `continue`, no value is added for this iteration.
3084 If the body invokes `break`, the loop ends and no more values are added.
3090 Loads the dynamic extension, +'filename'+. Generally the filename should have
3091 the extension +.so+. The initialisation function for the module must be based
3092 on the name of the file. For example loading +hwaccess.so+ will invoke
3093 the initialisation function, +Jim_hwaccessInit+. Normally the `load` command
3094 should not be used directly. Instead it is invoked automatically by `package require`.
3098 +*lrange* 'list first last'+
3100 +'list'+ must be a valid Tcl list. This command will return a new
3101 list consisting of elements +'first'+ through +'last'+, inclusive.
3103 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for +'first'+ and +'last'+.
3105 If +'last'+ is greater than or equal to the number of elements
3106 in the list, then it is treated as if it were +end+.
3108 If +'first'+ is greater than +'last'+ then an empty string
3111 Note: +"`lrange` 'list first first'"+ does not always produce the
3112 same result as +"`lindex` 'list first'"+ (although it often does
3113 for simple fields that aren't enclosed in braces); it does, however,
3114 produce exactly the same results as +"`list` [`lindex` 'list first']"+
3119 +*lreplace* 'list first last ?element element \...?'+
3121 Returns a new list formed by replacing one or more elements of
3122 +'list'+ with the +'element'+ arguments.
3124 +'first'+ gives the index in +'list'+ of the first element
3127 If +'first'+ is less than zero then it refers to the first
3128 element of +'list'+; the element indicated by +'first'+
3129 must exist in the list.
3131 +'last'+ gives the index in +'list'+ of the last element
3132 to be replaced; it must be greater than or equal to +'first'+.
3134 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for +'first'+ and +'last'+.
3136 The +'element'+ arguments specify zero or more new arguments to
3137 be added to the list in place of those that were deleted.
3139 Each +'element'+ argument will become a separate element of
3142 If no +'element'+ arguments are specified, then the elements
3143 between +'first'+ and +'last'+ are simply deleted.
3147 +*lrepeat* 'number element1 ?element2 \...?'+
3149 Build a list by repeating elements +'number'+ times (which must be
3150 a positive integer).
3159 Returns the list in reverse order.
3161 jim> lreverse {1 2 3}
3166 +*lsearch* '?options? list pattern'+
3168 This command searches the elements +'list'+ to see if one of them matches +'pattern'+. If so, the
3169 command returns the index of the first matching element (unless the options +-all+, +-inline+ or +-bool+ are
3170 specified.) If not, the command returns -1. The option arguments indicates how the elements of
3171 the list are to be matched against pattern and must have one of the values below:
3173 *Note* that this command is different from Tcl in that default match type is +-exact+ rather than +-glob+.
3176 +'pattern'+ is a literal string that is compared for exact equality against each list element.
3177 This is the default.
3180 +'pattern'+ is a glob-style pattern which is matched against each list element using the same
3181 rules as the string match command.
3184 +'pattern'+ is treated as a regular expression and matched against each list element using
3185 the rules described by `regexp`.
3187 +*-command* 'cmdname'+::
3188 +'cmdname'+ is a command which is used to match the pattern against each element of the
3189 list. It is invoked as +'cmdname' ?*-nocase*? 'pattern listvalue'+ and should return 1
3190 for a match, or 0 for no match.
3193 Changes the result to be the list of all matching indices (or all matching values if
3194 +-inline+ is specified as well). If indices are returned, the indices will be in numeric
3195 order. If values are returned, the order of the values will be the order of those values
3196 within the input list.
3199 The matching value is returned instead of its index (or an empty string if no value
3200 matches). If +-all+ is also specified, then the result of the command is the list of all
3201 values that matched. The +-inline+ and +-bool+ options are mutually exclusive.
3204 Changes the result to '1' if a match was found, or '0' otherwise. If +-all+ is also specified,
3205 the result will be a list of '0' and '1' for each element of the list depending upon whether
3206 the corresponding element matches. The +-inline+ and +-bool+ options are mutually exclusive.
3209 This negates the sense of the match, returning the index (or value
3210 if +-inline+ is specified) of the first non-matching value in the
3211 list. If +-bool+ is also specified, the '0' will be returned if a
3212 match is found, or '1' otherwise. If +-all+ is also specified,
3213 non-matches will be returned rather than matches.
3216 Causes comparisons to be handled in a case-insensitive manner.
3220 +*lsort* ?*-index* 'listindex'? ?*-nocase|-integer|-real|-command* 'cmdname'? ?*-unique*? ?*-decreasing*|*-increasing*? 'list'+
3222 Sort the elements of +'list'+, returning a new list in sorted order.
3223 By default, ASCII (or UTF-8) sorting is used, with the result in increasing order.
3225 If +-nocase+ is specified, comparisons are case-insensitive.
3227 If +-integer+ is specified, numeric sorting is used.
3229 If +-real+ is specified, floating point number sorting is used.
3231 If +-command 'cmdname'+ is specified, +'cmdname'+ is treated as a command
3232 name. For each comparison, +'cmdname $value1 $value2+' is called which
3233 should compare the values and return an integer less than, equal
3234 to, or greater than zero if the +'$value1'+ is to be considered less
3235 than, equal to, or greater than +'$value2'+, respectively.
3237 If +-decreasing+ is specified, the resulting list is in the opposite
3238 order to what it would be otherwise. +-increasing+ is the default.
3240 If +-unique+ is specified, then only the last set of duplicate elements found in the list will be retained.
3241 Note that duplicates are determined relative to the comparison used in the sort. Thus if +-index 0+ is used,
3242 +{1 a}+ and +{1 b}+ would be considered duplicates and only the second element, +{1 b}+, would be retained.
3244 If +-index 'listindex'+ is specified, each element of the list is treated as a list and
3245 the given index is extracted from the list for comparison. The list index may
3246 be any valid list index, such as +1+, +end+ or +end-2+.
3252 This command is a simple helper command to add a script to the '+$jim::defer+' variable
3253 that will run when the current proc or interpreter exits. For example:
3255 jim> proc a {} { defer {puts "Leaving a"}; puts "Exit" }
3260 If the '+$jim::defer+' variable exists, it is treated as a list of scripts to run
3261 when the proc or interpreter exits.
3265 +*open* 'fileName ?access?'+
3267 +*open* '|command-pipeline ?access?'+
3269 Opens a file and returns an identifier
3270 that may be used in future invocations
3271 of commands like `read`, `puts`, and `close`.
3272 +'fileName'+ gives the name of the file to open.
3274 The +'access'+ argument indicates the way in which the file is to be accessed.
3275 It may have any of the following values:
3278 Open the file for reading only; the file must already exist.
3281 Open the file for both reading and writing; the file must
3285 Open the file for writing only. Truncate it if it exists. If it doesn't
3286 exist, create a new file.
3289 Open the file for reading and writing. Truncate it if it exists.
3290 If it doesn't exist, create a new file.
3293 Open the file for writing only. The file must already exist, and the file
3294 is positioned so that new data is appended to the file.
3297 Open the file for reading and writing. If the file doesn't
3298 exist, create a new empty file. Set the initial access position
3299 to the end of the file.
3301 +'access'+ defaults to 'r'.
3303 If a file is opened for both reading and writing, then `seek`
3304 must be invoked between a read and a write, or vice versa.
3306 If the first character of +'fileName'+ is "|" then the remaining
3307 characters of +'fileName'+ are treated as a list of arguments that
3308 describe a command pipeline to invoke, in the same style as the
3309 arguments for exec. In this case, the channel identifier returned
3310 by open may be used to write to the command's input pipe or read
3311 from its output pipe, depending on the value of +'access'+. If write-only
3312 access is used (e.g. +'access'+ is 'w'), then standard output for the
3313 pipeline is directed to the current standard output unless overridden
3314 by the command. If read-only access is used (e.g. +'access'+ is r),
3315 standard input for the pipeline is taken from the current standard
3316 input unless overridden by the command.
3318 The `pid` command may be used to return the process ids of the commands
3319 forming the command pipeline.
3321 See also `socket`, `pid`, `exec`
3325 +*package provide* 'name ?version?'+
3327 Indicates that the current script provides the package named +'name'+.
3328 If no version is specified, '1.0' is used.
3330 Any script which provides a package may include this statement
3331 as the first statement, although it is not required.
3333 +*package require* 'name ?version?'*+
3335 Searches for the package with the given +'name'+ by examining each path
3336 in '$::auto_path' and trying to load '$path/$name.so' as a dynamic extension,
3337 or '$path/$name.tcl' as a script package.
3339 The first such file which is found is considered to provide the package.
3340 (The version number is ignored).
3342 If '$name.so' exists, it is loaded with the `load` command,
3343 otherwise if '$name.tcl' exists it is loaded with the `source` command.
3345 If `load` or `source` fails, `package require` will fail immediately.
3346 No further attempt will be made to locate the file.
3354 The first form returns the process identifier of the current process.
3356 The second form accepts a handle returned by `open` and returns a list
3357 of the process ids forming the pipeline in the same form as `exec ... &`.
3358 If 'fileId' represents a regular file handle rather than a command pipeline,
3359 the empty string is returned instead.
3361 See also `open`, `exec`
3365 +*proc* 'name args ?statics? body'+
3367 The `proc` command creates a new Tcl command procedure, +'name'+.
3368 When the new command is invoked, the contents of +'body'+ will be executed.
3369 Tcl interpreter. +'args'+ specifies the formal arguments to the procedure.
3370 If specified, +'statics'+, declares static variables which are bound to the
3373 See PROCEDURES for detailed information about Tcl procedures.
3375 The `proc` command returns +'name'+ (which is useful with `local`).
3377 When a procedure is invoked, the procedure's return value is the
3378 value specified in a `return` command. If the procedure doesn't
3379 execute an explicit `return`, then its return value is the value
3380 of the last command executed in the procedure's body.
3382 If an error occurs while executing the procedure body, then the
3383 procedure-as-a-whole will return that same error.
3387 +*puts* ?*-nonewline*? '?fileId? string'+
3389 +'fileId' *puts* ?*-nonewline*? 'string'+
3391 Writes the characters given by +'string'+ to the file given
3392 by +'fileId'+. +'fileId'+ must have been the return
3393 value from a previous call to `open`, or it may be
3394 +stdout+ or +stderr+ to refer to one of the standard I/O
3395 channels; it must refer to a file that was opened for
3398 In the first form, if no +'fileId'+ is specified then it defaults to +stdout+.
3399 `puts` normally outputs a newline character after +'string'+,
3400 but this feature may be suppressed by specifying the +-nonewline+
3403 Output to files is buffered internally by Tcl; the `flush`
3404 command may be used to force buffered characters to be output.
3410 Returns the path name of the current working directory.
3414 +*rand* '?min? ?max?'+
3416 Returns a random integer between +'min'+ (defaults to 0) and +'max'+
3417 (defaults to the maximum integer).
3419 If only one argument is given, it is interpreted as +'max'+.
3423 +*range* '?start? end ?step?'+
3425 Returns a list of integers starting at +'start'+ (defaults to 0)
3426 and ranging up to but not including +'end'+ in steps of +'step'+ defaults to 1).
3439 +*read* ?*-nonewline*? 'fileId'+
3441 +'fileId' *read* ?*-nonewline*?+
3443 +*read* 'fileId numBytes'+
3445 +'fileId' *read* 'numBytes'+
3448 In the first form, all of the remaining bytes are read from the file
3449 given by +'fileId'+; they are returned as the result of the command.
3450 If the +-nonewline+ switch is specified then the last
3451 character of the file is discarded if it is a newline.
3453 In the second form, the extra argument specifies how many bytes to read;
3454 exactly this many bytes will be read and returned, unless there are fewer than
3455 +'numBytes'+ bytes left in the file; in this case, all the remaining
3458 +'fileId'+ must be +stdin+ or the return value from a previous call
3459 to `open`; it must refer to a file that was opened for reading.
3463 +*regexp ?-nocase? ?-line? ?-indices? ?-start* 'offset'? *?-all? ?-inline? ?--?* 'exp string ?matchVar? ?subMatchVar subMatchVar \...?'+
3465 Determines whether the regular expression +'exp'+ matches part or
3466 all of +'string'+ and returns 1 if it does, 0 if it doesn't.
3468 See REGULAR EXPRESSIONS above for complete information on the
3469 syntax of +'exp'+ and how it is matched against +'string'+.
3471 If additional arguments are specified after +'string'+ then they
3472 are treated as the names of variables to use to return
3473 information about which part(s) of +'string'+ matched +'exp'+.
3474 +'matchVar'+ will be set to the range of +'string'+ that
3475 matched all of +'exp'+. The first +'subMatchVar'+ will contain
3476 the characters in +'string'+ that matched the leftmost parenthesized
3477 subexpression within +'exp'+, the next +'subMatchVar'+ will
3478 contain the characters that matched the next parenthesized
3479 subexpression to the right in +'exp'+, and so on.
3481 Normally, +'matchVar'+ and the each +'subMatchVar'+ are set to hold the
3482 matching characters from `string`, however see +-indices+ and
3485 If there are more values for +'subMatchVar'+ than parenthesized subexpressions
3486 within +'exp'+, or if a particular subexpression in +'exp'+ doesn't
3487 match the string (e.g. because it was in a portion of the expression
3488 that wasn't matched), then the corresponding +'subMatchVar'+ will be
3489 set to +"-1 -1"+ if +-indices+ has been specified or to an empty
3492 The following switches modify the behaviour of +'regexp'+
3495 Causes upper-case and lower-case characters to be treated as
3496 identical during the matching process.
3499 Use newline-sensitive matching. By default, newline
3500 is a completely ordinary character with no special meaning in
3501 either REs or strings. With this flag, +[^+ bracket expressions
3502 and +.+ never match newline, an +^+ anchor matches the null
3503 string after any newline in the string in addition to its normal
3504 function, and the +$+ anchor matches the null string before any
3505 newline in the string in addition to its normal function.
3508 Changes what is stored in the subMatchVars. Instead of
3509 storing the matching characters from string, each variable
3510 will contain a list of two decimal strings giving the indices
3511 in string of the first and last characters in the matching
3512 range of characters.
3514 +*-start* 'offset'+::
3515 Specifies a character index offset into the string at which to start
3516 matching the regular expression. If +-indices+ is
3517 specified, the indices will be indexed starting from the
3518 absolute beginning of the input string. +'offset'+ will be
3519 constrained to the bounds of the input string.
3522 Causes the regular expression to be matched as many times as possible
3523 in the string, returning the total number of matches found. If this
3524 is specified with match variables, they will contain information
3525 for the last match only.
3528 Causes the command to return, as a list, the data that would otherwise
3529 be placed in match variables. When using +-inline+, match variables
3530 may not be specified. If used with +-all+, the list will be concatenated
3531 at each iteration, such that a flat list is always returned. For
3532 each match iteration, the command will append the overall match
3533 data, plus one element for each subexpression in the regular
3537 Marks the end of switches. The argument following this one will be
3538 treated as +'exp'+ even if it starts with a +-+.
3542 +*regsub ?-nocase? ?-all? ?-line? ?-start* 'offset'? ?*--*? 'exp string subSpec ?varName?'+
3544 This command matches the regular expression +'exp'+ against
3545 +'string'+ using the rules described in REGULAR EXPRESSIONS
3548 If +'varName'+ is specified, the commands stores +'string'+ to +'varName'+
3549 with the substitutions detailed below, and returns the number of
3550 substitutions made (normally 1 unless +-all+ is specified).
3551 This is 0 if there were no matches.
3553 If +'varName'+ is not specified, the substituted string will be returned
3556 When copying +'string'+, the portion of +'string'+ that
3557 matched +'exp'+ is replaced with +'subSpec'+.
3558 If +'subSpec'+ contains a +&+ or +{backslash}0+, then it is replaced
3559 in the substitution with the portion of +'string'+ that
3562 If +'subSpec'+ contains a +{backslash}n+, where +'n'+ is a digit
3563 between 1 and 9, then it is replaced in the substitution with
3564 the portion of +'string'+ that matched the +'n'+\'-th
3565 parenthesized subexpression of +'exp'+.
3566 Additional backslashes may be used in +'subSpec'+ to prevent special
3567 interpretation of +&+ or +{backslash}0+ or +{backslash}n+ or
3570 The use of backslashes in +'subSpec'+ tends to interact badly
3571 with the Tcl parser's use of backslashes, so it's generally
3572 safest to enclose +'subSpec'+ in braces if it includes
3575 The following switches modify the behaviour of +'regsub'+
3578 Upper-case characters in +'string'+ are converted to lower-case
3579 before matching against +'exp'+; however, substitutions
3580 specified by +'subSpec'+ use the original unconverted form
3584 All ranges in +'string'+ that match +'exp'+ are found and substitution
3585 is performed for each of these ranges, rather than only the
3586 first. The +&+ and +{backslash}n+ sequences are handled for
3587 each substitution using the information from the corresponding
3591 Use newline-sensitive matching. By default, newline
3592 is a completely ordinary character with no special meaning in
3593 either REs or strings. With this flag, +[^+ bracket expressions
3594 and +.+ never match newline, an +^+ anchor matches the null
3595 string after any newline in the string in addition to its normal
3596 function, and the +$+ anchor matches the null string before any
3597 newline in the string in addition to its normal function.
3599 +*-start* 'offset'+::
3600 Specifies a character index offset into the string at which to
3601 start matching the regular expression. +'offset'+ will be
3602 constrained to the bounds of the input string.
3605 Marks the end of switches. The argument following this one will be
3606 treated as +'exp'+ even if it starts with a +-+.
3610 +*ref* 'string tag ?finalizer?'+
3612 Create a new reference containing +'string'+ of type +'tag'+.
3613 If +'finalizer'+ is specified, it is a command which will be invoked
3614 when the a garbage collection cycle runs and this reference is
3615 no longer accessible.
3617 The finalizer is invoked as:
3619 finalizer reference string
3621 See GARBAGE COLLECTION, REFERENCES, LAMBDA FUNCTION for more detail.
3625 +*rename* 'oldName newName'+
3627 Rename the command that used to be called +'oldName'+ so that it
3628 is now called +'newName'+. If +'newName'+ is an empty string
3629 (e.g. {}) then +'oldName'+ is deleted. The `rename` command
3630 returns an empty string as result.
3634 +*return* ?*-code* 'code'? ?*-errorinfo* 'stacktrace'? ?*-errorcode* 'errorcode'? ?*-level* 'n'? ?'value'?+
3636 Return immediately from the current procedure (or top-level command
3637 or `source` command), with +'value'+ as the return value. If +'value'+
3638 is not specified, an empty string will be returned as result.
3640 If +-code+ is specified (as either a number or ok, error, break,
3641 continue, signal, return or exit), this code will be used instead
3642 of +JIM_OK+. This is generally useful when implementing flow of control
3645 If +-level+ is specified and greater than 1, it has the effect of delaying
3646 the new return code from +-code+. This is useful when rethrowing an error
3647 from `catch`. See the implementation of try/catch in tclcompat.tcl for
3648 an example of how this is done.
3650 Note: The following options are only used when +-code+ is JIM_ERR.
3652 If +-errorinfo+ is specified (as returned from `info stacktrace`)
3653 it is used to initialize the stacktrace.
3655 If +-errorcode+ is specified, it is used to set the global variable $::errorCode.
3659 +*scan* 'string format varName1 ?varName2 \...?'+
3661 This command parses fields from an input string in the same fashion
3662 as the C 'sscanf' procedure. +'string'+ gives the input to be parsed
3663 and +'format'+ indicates how to parse it, using '%' fields as in
3664 'sscanf'. All of the 'sscanf' options are valid; see the 'sscanf'
3665 man page for details. Each +'varName'+ gives the name of a variable;
3666 when a field is scanned from +'string'+, the result is converted back
3667 into a string and assigned to the corresponding +'varName'+. The
3668 only unusual conversion is for '%c'. For '%c' conversions a single
3669 character value is converted to a decimal string, which is then
3670 assigned to the corresponding +'varName'+; no field width may be
3671 specified for this conversion.
3675 +*seek* 'fileId offset ?origin?'+
3677 +'fileId' *seek* 'offset ?origin?'+
3679 Change the current access position for +'fileId'+.
3680 The +'offset'+ and +'origin'+ arguments specify the position at
3681 which the next read or write will occur for +'fileId'+.
3682 +'offset'+ must be a number (which may be negative) and +'origin'+
3683 must be one of the following:
3686 The new access position will be +'offset'+ bytes from the start
3690 The new access position will be +'offset'+ bytes from the current
3691 access position; a negative +'offset'+ moves the access position
3692 backwards in the file.
3695 The new access position will be +'offset'+ bytes from the end of
3696 the file. A negative +'offset'+ places the access position before
3697 the end-of-file, and a positive +'offset'+ places the access position
3698 after the end-of-file.
3700 The +'origin'+ argument defaults to +start+.
3702 +'fileId'+ must have been the return value from a previous call to
3703 `open`, or it may be +stdin+, +stdout+, or +stderr+ to refer to one
3704 of the standard I/O channels.
3706 This command returns an empty string.
3710 +*set* 'varName ?value?'+
3712 Returns the value of variable +'varName'+.
3714 If +'value'+ is specified, then set the value of +'varName'+ to +'value'+,
3715 creating a new variable if one doesn't already exist, and return
3718 If +'varName'+ contains an open parenthesis and ends with a
3719 close parenthesis, then it refers to an array element: the characters
3720 before the open parenthesis are the name of the array, and the characters
3721 between the parentheses are the index within the array.
3722 Otherwise +'varName'+ refers to a scalar variable.
3724 If no procedure is active, then +'varName'+ refers to a global
3727 If a procedure is active, then +'varName'+ refers to a parameter
3728 or local variable of the procedure, unless the +'global'+ command
3729 has been invoked to declare +'varName'+ to be global.
3731 The +::+ prefix may also be used to explicitly reference a variable
3732 in the global scope.
3736 +*setref* 'reference string'+
3738 Store a new string in +'reference'+, replacing the existing string.
3739 The reference must be a valid reference create with the `ref`
3742 See GARBAGE COLLECTION, REFERENCES, LAMBDA FUNCTION for more detail.
3746 Command for signal handling.
3748 See `kill` for the different forms which may be used to specify signals.
3750 Commands which return a list of signal names do so using the canonical form:
3753 +*signal handle* ?'signals \...'?+::
3754 If no signals are given, returns a list of all signals which are currently
3756 If signals are specified, these are added to the list of signals currently
3759 +*signal ignore* ?'signals \...'?+::
3760 If no signals are given, returns a lists all signals which are currently
3762 If signals are specified, these are added to the list of signals
3763 currently being ignored. These signals are still delivered, but
3764 are not considered by `catch -signal` or `try -signal`. Use
3765 `signal check` to determine which signals have occurred but
3768 +*signal default* ?'signals \...'?+::
3769 If no signals are given, returns a lists all signals which are currently have
3770 the default behaviour.
3771 If signals are specified, these are added to the list of signals which have
3772 the default behaviour.
3774 +*signal check ?-clear?* ?'signals \...'?+::
3775 Returns a list of signals which have been delivered to the process
3776 but are 'ignored'. If signals are specified, only that set of signals will
3777 be checked, otherwise all signals will be checked.
3778 If +-clear+ is specified, any signals returned are removed and will not be
3779 returned by subsequent calls to `signal check` unless delivered again.
3781 +*signal throw* ?'signal'?+::
3782 Raises the given signal, which defaults to +SIGINT+ if not specified.
3783 The behaviour is identical to:
3787 Note that `signal handle` and `signal ignore` represent two forms of signal
3788 handling. `signal handle` is used in conjunction with `catch -signal` or `try -signal`
3789 to immediately abort execution when the signal is delivered. Alternatively, `signal ignore`
3790 is used in conjunction with `signal check` to handle signal synchronously. Consider the
3793 Prevent a processing from taking too long
3795 signal handle SIGALRM
3798 .. possibly long running process ..
3801 puts stderr "Process took too long"
3804 Handle SIGHUP to reconfigure:
3806 signal ignore SIGHUP
3808 ... handle configuration/reconfiguration ...
3809 while {[signal check -clear SIGHUP] eq ""} {
3810 ... do processing ..
3812 # Received SIGHUP, so reconfigure
3815 Note: signal handling is currently not supported in child interpreters.
3816 In these interpreters, the signal command does not exist.
3822 Pauses for the given number of seconds, which may be a floating
3823 point value less than one to sleep for less than a second, or an
3824 integer to sleep for one or more seconds.
3828 +*source* 'fileName'+
3830 Read file +'fileName'+ and pass the contents to the Tcl interpreter
3831 as a sequence of commands to execute in the normal fashion. The return
3832 value of `source` is the return value of the last command executed
3833 from the file. If an error occurs in executing the contents of the
3834 file, then the `source` command will return that error.
3836 If a `return` command is invoked from within the file, the remainder of
3837 the file will be skipped and the `source` command will return
3838 normally with the result from the `return` command.
3842 +*split* 'string ?splitChars?'+
3844 Returns a list created by splitting +'string'+ at each character
3845 that is in the +'splitChars'+ argument.
3847 Each element of the result list will consist of the
3848 characters from +'string'+ between instances of the
3849 characters in +'splitChars'+.
3851 Empty list elements will be generated if +'string'+ contains
3852 adjacent characters in +'splitChars'+, or if the first or last
3853 character of +'string'+ is in +'splitChars'+.
3855 If +'splitChars'+ is an empty string then each character of
3856 +'string'+ becomes a separate element of the result list.
3858 +'splitChars'+ defaults to the standard white-space characters.
3861 split "comp.unix.misc" .
3863 returns +'"comp unix misc"'+ and
3865 split "Hello world" {}
3867 returns +'"H e l l o { } w o r l d"'+.
3872 +*stackdump* 'stacktrace'+
3874 Creates a human readable representation of a stack trace.
3881 Returns a live stack trace as a list of +proc file line proc file line \...+.
3882 Iteratively uses `info frame` to create the stack trace. This stack trace is in the
3883 same form as produced by `catch` and `info stacktrace`
3885 See also `stackdump`.
3890 +*string* 'option arg ?arg \...?'+
3892 Perform one of several string operations, depending on +'option'+.
3893 The legal options (which may be abbreviated) are:
3895 +*string bytelength* 'string'+::
3896 Returns the length of the string in bytes. This will return
3897 the same value as `string length` if UTF-8 support is not enabled,
3898 or if the string is composed entirely of ASCII characters.
3899 See UTF-8 AND UNICODE.
3901 +*string byterange* 'string first last'+::
3902 Like `string range` except works on bytes rather than characters.
3903 These commands are identical if UTF-8 support is not enabled.
3905 +*string cat* '?string1 string2 \...?'+::
3906 Concatenates the given strings into a single string.
3908 +*string compare ?-nocase?* ?*-length* 'len? string1 string2'+::
3909 Perform a character-by-character comparison of strings +'string1'+ and
3910 +'string2'+ in the same way as the C 'strcmp' procedure. Return
3911 -1, 0, or 1, depending on whether +'string1'+ is lexicographically
3912 less than, equal to, or greater than +'string2'+. If +-length+
3913 is specified, then only the first +'len'+ characters are used
3914 in the comparison. If +'len'+ is negative, it is ignored.
3915 Performs a case-insensitive comparison if +-nocase+ is specified.
3917 +*string equal ?-nocase?* '?*-length* len?' 'string1 string2'+::
3918 Returns 1 if the strings are equal, or 0 otherwise. If +-length+
3919 is specified, then only the first +'len'+ characters are used
3920 in the comparison. If +'len'+ is negative, it is ignored.
3921 Performs a case-insensitive comparison if +-nocase+ is specified.
3923 +*string first* 'string1 string2 ?firstIndex?'+::
3924 Search +'string2'+ for a sequence of characters that exactly match
3925 the characters in +'string1'+. If found, return the index of the
3926 first character in the first such match within +'string2'+. If not
3927 found, return -1. If +'firstIndex'+ is specified, matching will start
3928 from +'firstIndex'+ of +'string1'+.
3930 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for +'firstIndex'+.
3932 +*string index* 'string charIndex'+::
3933 Returns the +'charIndex'+'th character of the +'string'+
3934 argument. A +'charIndex'+ of 0 corresponds to the first
3935 character of the string.
3936 If +'charIndex'+ is less than 0 or greater than
3937 or equal to the length of the string then an empty string is
3940 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for +'charIndex'+.
3942 +*string is* 'class' ?*-strict*? 'string'+::
3943 Returns 1 if +'string'+ is a valid member of the specified character
3944 class, otherwise returns 0. If +-strict+ is specified, then an
3945 empty string returns 0, otherwise an empty string will return 1
3946 on any class. The following character classes are recognized
3947 (the class name can be abbreviated):
3949 +alnum+;; Any alphabet or digit character.
3950 +alpha+;; Any alphabet character.
3951 +ascii+;; Any character with a value less than 128 (those that are in the 7-bit ascii range).
3952 +boolean+;; Any of the valid string formats for a boolean value in Tcl (0, false, no, off, 1, true, yes, on)
3953 +control+;; Any control character.
3954 +digit+;; Any digit character.
3955 +double+;; Any of the valid forms for a double in Tcl, with optional surrounding whitespace.
3956 In case of under/overflow in the value, 0 is returned.
3957 +graph+;; Any printing character, except space.
3958 +integer+;; Any of the valid string formats for an integer value in Tcl, with optional surrounding whitespace.
3959 +lower+;; Any lower case alphabet character.
3960 +print+;; Any printing character, including space.
3961 +punct+;; Any punctuation character.
3962 +space+;; Any space character.
3963 +upper+;; Any upper case alphabet character.
3964 +xdigit+;; Any hexadecimal digit character ([0-9A-Fa-f]).
3966 Note that string classification does +'not'+ respect UTF-8. See UTF-8 AND UNICODE
3968 Note that only +'lowercase'+ boolean values are recognized (Tcl accepts any case).
3970 +*string last* 'string1 string2 ?lastIndex?'+::
3971 Search +'string2'+ for a sequence of characters that exactly match
3972 the characters in +'string1'+. If found, return the index of the
3973 first character in the last such match within +'string2'+. If there
3974 is no match, then return -1. If +'lastIndex'+ is specified, only characters
3975 up to +'lastIndex'+ of +'string2'+ will be considered in the match.
3977 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for +'lastIndex'+.
3979 +*string length* 'string'+::
3980 Returns a decimal string giving the number of characters in +'string'+.
3981 If UTF-8 support is enabled, this may be different than the number of bytes.
3982 See UTF-8 AND UNICODE
3984 +*string map ?-nocase?* 'mapping string'+::
3985 Replaces substrings in +'string'+ based on the key-value pairs in
3986 +'mapping'+, which is a list of +key value key value \...+ as in the form
3987 returned by `array get`. Each instance of a key in the string will be
3988 replaced with its corresponding value. If +-nocase+ is specified, then
3989 matching is done without regard to case differences. Both key and value may
3990 be multiple characters. Replacement is done in an ordered manner, so the
3991 key appearing first in the list will be checked first, and so on. +'string'+ is
3992 only iterated over once, so earlier key replacements will have no affect for
3993 later key matches. For example,
3995 string map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc
3998 will return the string +01321221+.
4000 Note that if an earlier key is a prefix of a later one, it will completely mask the later
4001 one. So if the previous example is reordered like this,
4003 string map {1 0 ab 2 a 3 abc 1} 1abcaababcabababc
4006 it will return the string +02c322c222c+.
4008 +*string match ?-nocase?* 'pattern string'+::
4009 See if +'pattern'+ matches +'string'+; return 1 if it does, 0
4010 if it doesn't. Matching is done in a fashion similar to that
4011 used by the C-shell. For the two strings to match, their contents
4012 must be identical except that the following special sequences
4013 may appear in +'pattern'+:
4016 Matches any sequence of characters in +'string'+,
4017 including a null string.
4020 Matches any single character in +'string'+.
4023 Matches any character in the set given by +'chars'+.
4024 If a sequence of the form +'x-y'+ appears in +'chars'+,
4025 then any character between +'x'+ and +'y'+, inclusive,
4029 Matches the single character +'x'+. This provides a way of
4030 avoiding the special interpretation of the characters +{backslash}*?[]+
4033 Performs a case-insensitive comparison if +-nocase+ is specified.
4035 +*string range* 'string first last'+::
4036 Returns a range of consecutive characters from +'string'+, starting
4037 with the character whose index is +'first'+ and ending with the
4038 character whose index is +'last'+. An index of 0 refers to the
4039 first character of the string.
4041 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for +'first'+ and +'last'+.
4043 If +'first'+ is less than zero then it is treated as if it were zero, and
4044 if +'last'+ is greater than or equal to the length of the string then
4045 it is treated as if it were +end+. If +'first'+ is greater than
4046 +'last'+ then an empty string is returned.
4048 +*string repeat* 'string count'+::
4049 Returns a new string consisting of +'string'+ repeated +'count'+ times.
4051 +*string replace* 'string first last ?newstring?'+::
4052 Removes a range of consecutive characters from +'string'+, starting
4053 with the character whose index is +'first'+ and ending with the
4054 character whose index is +'last'+. If +'newstring'+ is specified,
4055 then it is placed in the removed character range. If +'first'+ is
4056 less than zero then it is treated as if it were zero, and if +'last'+
4057 is greater than or equal to the length of the string then it is
4058 treated as if it were +end+. If +'first'+ is greater than +'last'+
4059 or the length of the initial string, or +'last'+ is less than 0,
4060 then the initial string is returned untouched.
4062 +*string reverse* 'string'+::
4063 Returns a string that is the same length as +'string'+ but
4064 with its characters in the reverse order.
4066 +*string tolower* 'string'+::
4067 Returns a value equal to +'string'+ except that all upper case
4068 letters have been converted to lower case.
4070 +*string totitle* 'string'+::
4071 Returns a value equal to +'string'+ except that the first character
4072 is converted to title case (or upper case if there is no UTF-8 titlecase variant)
4073 and all remaining characters have been converted to lower case.
4075 +*string toupper* 'string'+::
4076 Returns a value equal to +'string'+ except that all lower case
4077 letters have been converted to upper case.
4079 +*string trim* 'string ?chars?'+::
4080 Returns a value equal to +'string'+ except that any leading
4081 or trailing characters from the set given by +'chars'+ are
4083 If +'chars'+ is not specified then white space is removed
4084 (spaces, tabs, newlines, and carriage returns).
4086 +*string trimleft* 'string ?chars?'+::
4087 Returns a value equal to +'string'+ except that any
4088 leading characters from the set given by +'chars'+ are
4090 If +'chars'+ is not specified then white space is removed
4091 (spaces, tabs, newlines, and carriage returns).
4093 +*string trimright* 'string ?chars?'+::
4094 Returns a value equal to +'string'+ except that any
4095 trailing characters from the set given by +'chars'+ are
4097 If +'chars'+ is not specified then white space is removed
4098 (spaces, tabs, newlines, and carriage returns).
4099 Null characters are always removed.
4103 +*subst ?-nobackslashes? ?-nocommands? ?-novariables?* 'string'+
4105 This command performs variable substitutions, command substitutions,
4106 and backslash substitutions on its string argument and returns the
4107 fully-substituted result. The substitutions are performed in exactly
4108 the same way as for Tcl commands. As a result, the string argument
4109 is actually substituted twice, once by the Tcl parser in the usual
4110 fashion for Tcl commands, and again by the subst command.
4112 If any of the +-nobackslashes+, +-nocommands+, or +-novariables+ are
4113 specified, then the corresponding substitutions are not performed.
4114 For example, if +-nocommands+ is specified, no command substitution
4115 is performed: open and close brackets are treated as ordinary
4116 characters with no special interpretation.
4118 *Note*: when it performs its substitutions, subst does not give any
4119 special treatment to double quotes or curly braces. For example,
4120 the following script returns +xyz \{44\}+, not +xyz \{$a\}+.
4128 +*switch* '?options? string pattern body ?pattern body \...?'+
4130 +*switch* '?options? string {pattern body ?pattern body \...?}'+
4132 The `switch` command matches its string argument against each of
4133 the pattern arguments in order. As soon as it finds a pattern that
4134 matches string it evaluates the following body and returns the
4135 result of that evaluation. If the last pattern argument is default
4136 then it matches anything. If no pattern argument matches string and
4137 no default is given, then the `switch` command returns an empty string.
4138 If the initial arguments to switch start with - then they are treated
4139 as options. The following options are currently supported:
4142 Use exact matching when comparing string to a
4143 pattern. This is the default.
4146 When matching string to the patterns, use glob-style
4147 matching (i.e. the same as implemented by the string
4151 When matching string to the patterns, use regular
4152 expression matching (i.e. the same as implemented
4153 by the regexp command).
4155 +-command 'commandname'+::
4156 When matching string to the patterns, use the given command, which
4157 must be a single word. The command is invoked as
4158 'commandname pattern string', or 'commandname -nocase pattern string'
4159 and must return 1 if matched, or 0 if not.
4162 Marks the end of options. The argument following
4163 this one will be treated as string even if it starts
4166 Two syntaxes are provided for the pattern and body arguments. The
4167 first uses a separate argument for each of the patterns and commands;
4168 this form is convenient if substitutions are desired on some of the
4169 patterns or commands. The second form places all of the patterns
4170 and commands together into a single argument; the argument must
4171 have proper list structure, with the elements of the list being the
4172 patterns and commands. The second form makes it easy to construct
4173 multi-line `switch` commands, since the braces around the whole list
4174 make it unnecessary to include a backslash at the end of each line.
4175 Since the pattern arguments are in braces in the second form, no
4176 command or variable substitutions are performed on them; this makes
4177 the behaviour of the second form different than the first form in
4180 If a body is specified as +-+ it means that the body for the next
4181 pattern should also be used as the body for this pattern (if the
4182 next pattern also has a body of +-+ then the body after that is
4183 used, and so on). This feature makes it possible to share a single
4184 body among several patterns.
4186 Below are some examples of `switch` commands:
4188 switch abc a - b {format 1} abc {format 2} default {format 3}
4192 switch -regexp aaab {
4212 +*tailcall* 'cmd ?arg\...?'+
4214 The `tailcall` command provides an optimised way of invoking a command whilst replacing
4215 the current call frame. This is similar to 'exec' in Bourne Shell.
4217 The following are identical except the first immediately replaces the current call frame.
4221 return [uplevel 1 [list a b c]]
4223 `tailcall` is useful as a dispatch mechanism:
4226 tailcall sub_$cmd {*}$args
4237 Returns a decimal string giving the current access position in
4240 +'fileId'+ must have been the return value from a previous call to
4241 `open`, or it may be +stdin+, +stdout+, or +stderr+ to refer to one
4242 of the standard I/O channels.
4246 +*throw* 'code ?msg?'+
4248 This command throws an exception (return) code along with an optional message.
4249 This command is mostly for convenient usage with `try`.
4251 The command +throw break+ is equivalent to +break+.
4252 The command +throw 20 message+ can be caught with an +on 20 \...+ clause to `try`.
4256 +*time* 'command ?count?'+
4258 This command will call the Tcl interpreter +'count'+
4259 times to execute +'command'+ (or once if +'count'+ isn't
4260 specified). It will then return a string of the form
4262 503 microseconds per iteration
4264 which indicates the average amount of time required per iteration,
4267 Time is measured in elapsed time, not CPU time.
4271 +*try* '?catchopts? tryscript' ?*on* 'returncodes {?resultvar? ?optsvar?} handlerscript \...'? ?*finally* 'finalscript'?+
4273 The `try` command is provided as a convenience for exception handling.
4275 This interpeter first evaluates +'tryscript'+ under the effect of the catch
4276 options +'catchopts'+ (e.g. +-signal -noexit --+, see `catch`).
4278 It then evaluates the script for the first matching 'on' handler
4279 (there many be zero or more) based on the return code from the `try`
4280 section. For example a normal +JIM_ERR+ error will be matched by
4281 an 'on error' handler.
4283 Finally, any +'finalscript'+ is evaluated.
4285 The result of this command is the result of +'tryscript'+, except in the
4286 case where an exception occurs in a matching 'on' handler script or the 'finally' script,
4287 in which case the result is this new exception.
4289 The specified +'returncodes'+ is a list of return codes either as names ('ok', 'error', 'break', etc.)
4292 If +'resultvar'+ and +'optsvar'+ are specified, they are set as for `catch` before evaluating
4293 the matching handler.
4300 } on {continue break} {} {
4301 error "Unexpected break/continue"
4302 } on error {msg opts} {
4303 puts "Dealing with error"
4304 return {*}$opts $msg
4306 puts "Got signal: $sig"
4311 If break, continue or error are raised, they are dealt with by the matching
4314 In any case, the file will be closed via the 'finally' clause.
4316 See also `throw`, `catch`, `return`, `error`.
4320 +*unknown* 'cmdName ?arg arg ...?'+
4322 This command doesn't actually exist as part of Tcl, but Tcl will
4323 invoke it if it does exist.
4325 If the Tcl interpreter encounters a command name for which there
4326 is not a defined command, then Tcl checks for the existence of
4327 a command named `unknown`.
4329 If there is no such command, then the interpreter returns an
4332 If the `unknown` command exists, then it is invoked with
4333 arguments consisting of the fully-substituted name and arguments
4334 for the original non-existent command.
4336 The `unknown` command typically does things like searching
4337 through library directories for a command procedure with the name
4338 +'cmdName'+, or expanding abbreviated command names to full-length,
4339 or automatically executing unknown commands as UNIX sub-processes.
4341 In some cases (such as expanding abbreviations) `unknown` will
4342 change the original command slightly and then (re-)execute it.
4343 The result of the `unknown` command is used as the result for
4344 the original non-existent command.
4348 +*unset ?-nocomplain? ?--?* '?name name ...?'+
4351 Each +'name'+ is a variable name, specified in any of the
4352 ways acceptable to the `set` command.
4354 If a +'name'+ refers to an element of an array, then that
4355 element is removed without affecting the rest of the array.
4357 If a +'name'+ consists of an array name with no parenthesized
4358 index, then the entire array is deleted.
4360 The `unset` command returns an empty string as result.
4362 An error occurs if any of the variables doesn't exist, unless '-nocomplain'
4363 is specified. The '--' argument may be specified to stop option processing
4364 in case the variable name may be '-nocomplain'.
4368 +*upcall* 'command ?args ...?'+
4370 May be used from within a proc defined as `local` `proc` in order to call
4371 the previous, hidden version of the same command.
4373 If there is no previous definition of the command, an error is returned.
4377 +*uplevel* '?level? command ?command ...?'+
4379 All of the +'command'+ arguments are concatenated as if they had
4380 been passed to `concat`; the result is then evaluated in the
4381 variable context indicated by +'level'+. `uplevel` returns
4382 the result of that evaluation. If +'level'+ is an integer, then
4383 it gives a distance (up the procedure calling stack) to move before
4384 executing the command. If +'level'+ consists of +\#+ followed by
4385 a number then the number gives an absolute level number. If +'level'+
4386 is omitted then it defaults to +1+. +'level'+ cannot be
4387 defaulted if the first +'command'+ argument starts with a digit or +#+.
4389 For example, suppose that procedure 'a' was invoked
4390 from top-level, and that it called 'b', and that 'b' called 'c'.
4391 Suppose that 'c' invokes the `uplevel` command. If +'level'+
4392 is +1+ or +#2+ or omitted, then the command will be executed
4393 in the variable context of 'b'. If +'level'+ is +2+ or +#1+
4394 then the command will be executed in the variable context of 'a'.
4396 If +'level'+ is '3' or +#0+ then the command will be executed
4397 at top-level (only global variables will be visible).
4398 The `uplevel` command causes the invoking procedure to disappear
4399 from the procedure calling stack while the command is being executed.
4400 In the above example, suppose 'c' invokes the command
4402 uplevel 1 {set x 43; d}
4404 where 'd' is another Tcl procedure. The `set` command will
4405 modify the variable 'x' in 'b's context, and 'd' will execute
4406 at level 3, as if called from 'b'. If it in turn executes
4411 then the `set` command will modify the same variable 'x' in 'b's
4412 context: the procedure 'c' does not appear to be on the call stack
4413 when 'd' is executing. The command `info level` may
4414 be used to obtain the level of the current procedure.
4416 `uplevel` makes it possible to implement new control
4417 constructs as Tcl procedures (for example, `uplevel` could
4418 be used to implement the `while` construct as a Tcl procedure).
4422 +*upvar* '?level? otherVar myVar ?otherVar myVar ...?'+
4424 This command arranges for one or more local variables in the current
4425 procedure to refer to variables in an enclosing procedure call or
4426 to global variables.
4428 +'level'+ may have any of the forms permitted for the `uplevel`
4429 command, and may be omitted if the first letter of the first +'otherVar'+
4430 isn't +#+ or a digit (it defaults to '1').
4432 For each +'otherVar'+ argument, `upvar` makes the variable
4433 by that name in the procedure frame given by +'level'+ (or at
4434 global level, if +'level'+ is +#0+) accessible
4435 in the current procedure by the name given in the corresponding
4438 The variable named by +'otherVar'+ need not exist at the time of the
4439 call; it will be created the first time +'myVar'+ is referenced, just like
4440 an ordinary variable.
4442 `upvar` may only be invoked from within procedures.
4444 `upvar` returns an empty string.
4446 The `upvar` command simplifies the implementation of call-by-name
4447 procedure calling and also makes it easier to build new control constructs
4449 For example, consider the following procedure:
4456 'add2' is invoked with an argument giving the name of a variable,
4457 and it adds two to the value of that variable.
4458 Although 'add2' could have been implemented using `uplevel`
4459 instead of `upvar`, `upvar` makes it simpler for 'add2'
4460 to access the variable in the caller's procedure frame.
4464 +*while* 'test body'+
4466 The +'while'+ command evaluates +'test'+ as an expression
4467 (in the same way that `expr` evaluates its argument).
4468 The value of the expression must be numeric; if it is non-zero
4469 then +'body'+ is executed by passing it to the Tcl interpreter.
4471 Once +'body'+ has been executed then +'test'+ is evaluated
4472 again, and the process repeats until eventually +'test'+
4473 evaluates to a zero numeric value. `continue`
4474 commands may be executed inside +'body'+ to terminate the current
4475 iteration of the loop, and `break`
4476 commands may be executed inside +'body'+ to cause immediate
4477 termination of the `while` command.
4479 The `while` command always returns an empty string.
4484 The following extensions may or may not be available depending upon
4485 what options were selected when Jim Tcl was built.
4488 posix: os.fork, os.wait, os.gethostname, os.getids, os.uptime
4489 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4491 Invokes 'fork(2)' and returns the result.
4493 +*os.wait -nohang* 'pid'+::
4494 Invokes waitpid(2), with WNOHANG if +-nohang+ is specified.
4495 Returns a list of 3 elements.
4497 {0 none 0} if -nohang is specified, and the process is still alive.
4499 {-1 error <error-description>} if the process does not exist or has already been waited for.
4501 {<pid> exit <exit-status>} if the process exited normally.
4503 {<pid> signal <signal-number>} if the process terminated on a signal.
4505 {<pid> other 0} otherwise (core dump, stopped, continued, etc.)
4507 +*os.gethostname*+::
4508 Invokes 'gethostname(3)' and returns the result.
4511 Returns the various user/group ids for the current process.
4514 uid 1000 euid 1000 gid 100 egid 100
4517 Returns the number of seconds since system boot. See description of 'uptime' in 'sysinfo(2)'.
4519 ANSI I/O (aio) and EVENTLOOP API
4520 --------------------------------
4521 Jim provides an alternative object-based API for I/O.
4523 See `open` and `socket` for commands which return an I/O handle.
4527 +$handle *accept* ?addrvar?+::
4528 Server socket only: Accept a connection and return stream.
4529 If +'addrvar'+ is specified, the address of the connected client is stored
4530 in the named variable in the form 'addr:port'. See `socket` for details.
4532 +$handle *buffering none|line|full*+::
4533 Sets the buffering mode of the stream.
4535 +$handle *close* ?r(ead)|w(rite)?+::
4537 The two-argument form is a "half-close" on a socket. See the +shutdown(2)+ man page.
4539 +$handle *copyto* 'tofd ?size?'+::
4540 Copy bytes to the file descriptor +'tofd'+. If +'size'+ is specified, at most
4541 that many bytes will be copied. Otherwise copying continues until the end
4542 of the input file. Returns the number of bytes actually copied.
4545 Returns 1 if stream is at eof
4547 +$handle *filename*+::
4548 Returns the original filename associated with the handle.
4549 Handles returned by `socket` give the socket type instead of a filename.
4554 +$handle *gets* '?var?'+::
4555 Read one line and return it or store it in the var
4557 +$handle *isatty*+::
4558 Returns 1 if the stream is a tty device.
4561 Apply a POSIX lock to the open file associated with the handle using
4563 The handle must be open for write access.
4564 Returns 1 if the lock was successfully obtained, 0 otherwise.
4565 An error occurs if the handle is not suitable for locking (e.g.
4566 if it is not open for write)
4568 +$handle *ndelay ?0|1?*+::
4569 Set O_NDELAY (if arg). Returns current/new setting.
4570 Note that in general ANSI I/O interacts badly with non-blocking I/O.
4573 +$handle *puts ?-nonewline?* 'str'+::
4574 Write the string, with newline unless -nonewline
4576 +$handle *read ?-nonewline?* '?len?'+::
4577 Read and return bytes from the stream. To eof if no len.
4579 +$handle *recvfrom* 'maxlen ?addrvar?'+::
4580 Receives a message from the handle via recvfrom(2) and returns it.
4581 At most +'maxlen'+ bytes are read.
4582 If +'addrvar'+ is specified, the sending address of the message is stored in
4583 the named variable in the form 'addr:port'. See `socket` for details.
4585 +$handle *seek* 'offset' *?start|current|end?*+::
4586 Seeks in the stream (default 'current')
4588 +$handle *sendto* 'str ?addr:?port'+::
4589 Sends the string, +'str'+, to the given address via the socket using sendto(2).
4590 This is intended for udp/dgram sockets and may give an error or behave in unintended
4591 ways for other handle types.
4592 Returns the number of bytes written.
4594 +$handle *sockopt* '?name value?'+::
4595 With no arguments, returns a dictionary of socket options currently set for the handle
4596 (will be empty for a non-socket). With +'name'+ and +'value'+, sets the socket option
4597 to the given value. Currently supports the following boolean socket options:
4598 +broadcast, debug, keepalive, nosigpipe, oobinline, tcp_nodelay+, and the following
4599 integer socket options: +sndbuf, rcvbuf+
4602 Flush the stream, then fsync(2) to commit any changes to storage.
4603 Only available on platforms that support fsync(2).
4606 Returns the current seek position
4608 +$handle *tty* ?settings?+::
4609 If no arguments are given, returns a dictionary containing the tty settings for the stream.
4610 If arguments are given, they must either be a dictionary, or +setting value \...+
4611 Abbrevations are supported for both settings and values, so the following is acceptable:
4612 +$f tty parity e input c out raw+.
4613 Only available on platforms that support termios(3). Supported settings are:
4616 Baud rate. e.g. 115200
4624 +*parity even|odd|none*+;;
4627 +*handshake xonxoff|rtscts|none*+;;
4630 +*input raw|cooked*+;;
4631 Input character processing. In raw mode, the usual key sequences such as ^C do
4632 not generate signals.
4634 +*output raw|cooked*+;;
4635 Output character processing. Typically CR -> CRNL is disabled in raw mode.
4637 +*vmin* 'numchars'+;;
4638 Minimum number of characters to read.
4641 Timeout for noncanonical read (units of 0.1 seconds)
4643 +$handle *ssl* *?-server cert priv?*+::
4644 Initiates a SSL/TLS session and returns a new stream
4646 +$handle *unlock*+::
4647 Release a POSIX lock previously acquired by `aio lock`.
4649 +$handle *verify*+::
4650 Verifies the certificate of a SSL/TLS stream peer
4652 +*load_ssl_certs* 'dir'+::
4653 Loads SSL/TLS CA certificates for use during verification
4657 +*fconfigure* 'handle' *?-blocking 0|1? ?-buffering noneline|full? ?-translation* 'mode'?+::
4658 For compatibility with Tcl, a limited form of the `fconfigure`
4659 command is supported.
4660 * `fconfigure ... -blocking` maps to `aio ndelay`
4661 * `fconfigure ... -buffering` maps to `aio buffering`
4662 * `fconfigure ... -translation` is accepted but ignored
4665 eventloop: after, vwait, update
4666 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4668 The following commands allow a script to be invoked when the given condition occurs.
4669 If no script is given, returns the current script. If the given script is the empty, the
4672 +$handle *readable* '?readable-script?'+::
4673 Sets or returns the script for when the socket is readable.
4675 +$handle *writable* '?writable-script?'+::
4676 Sets or returns the script for when the socket is writable.
4678 +$handle *onexception* '?exception-script?'+::
4679 Sets or returns the script for when oob data received.
4681 For compatibility with 'Tcl', these may be prefixed with `fileevent`. e.g.
4684 +fileevent $handle *readable* '\...'+
4686 Time-based execution is also available via the eventloop API.
4689 Sleeps for the given number of milliseconds. No events are
4690 processed during this time.
4692 +*after* 'ms'|*idle* 'script ?script \...?'+::
4693 The scripts are concatenated and executed after the given
4694 number of milliseconds have elapsed. If 'idle' is specified,
4695 the script will run the next time the event loop is processed
4696 with `vwait` or `update`. The script is only run once and
4697 then removed. Returns an event id.
4699 +*after cancel* 'id|command'+::
4700 Cancels an `after` event with the given event id or matching
4701 command (script). Returns the number of milliseconds
4702 remaining until the event would have fired. Returns the
4703 empty string if no matching event is found.
4705 +*after info* '?id?'+::
4706 If +'id'+ is not given, returns a list of current `after`
4707 events. If +'id'+ is given, returns a list containing the
4708 associated script and either 'timer' or 'idle' to indicated
4709 the type of the event. An error occurs if +'id'+ does not
4712 +*vwait* 'variable'+::
4713 A call to `vwait` enters the eventloop. `vwait` processes
4714 events until the named (global) variable changes or all
4715 event handlers are removed. The variable need not exist
4716 beforehand. If there are no event handlers defined, `vwait`
4717 returns immediately.
4719 +*update ?idletasks?*+::
4720 A call to `update` enters the eventloop to process expired events, but
4721 no new events. If 'idletasks' is specified, only expired time events are handled,
4723 Returns once handlers have been run for all expired events.
4725 Scripts are executed at the global scope. If an error occurs during a handler script,
4726 an attempt is made to call (the user-defined command) `bgerror` with the details of the error.
4727 If the `bgerror` command does not exist, the error message details are printed to stderr instead.
4729 If a file event handler script generates an error, the handler is automatically removed
4730 to prevent infinite errors. (A time event handler is always removed after execution).
4733 Called when an event handler script generates an error. Note that the normal command resolution
4734 rules are used for bgerror. First the name is resolved in the current namespace, then in the
4739 Various socket types may be created.
4741 +*socket unix* 'path'+::
4742 A unix domain socket client.
4744 +*socket unix.server* 'path'+::
4745 A unix domain socket server.
4747 +*socket ?-ipv6? stream* 'addr:port'+::
4748 A TCP socket client. (See the forms for +'addr'+ below)
4750 +*socket ?-ipv6? stream.server* '?addr:?port'+::
4751 A TCP socket server (+'addr'+ defaults to +0.0.0.0+ for IPv4 or +[::]+ for IPv6).
4753 +*socket ?-ipv6? dgram* ?'addr:port'?+::
4754 A UDP socket client. If the address is not specified,
4755 the client socket will be unbound and 'sendto' must be used
4756 to indicated the destination.
4758 +*socket ?-ipv6? dgram.server* 'addr:port'+::
4759 A UDP socket server.
4762 A pipe. Note that unlike all other socket types, this command returns
4763 a list of two channels: {read write}
4766 A socketpair (see socketpair(2)). Like `socket pipe`, this command returns
4767 a list of two channels: {s1 s2}. These channels are both readable and writable.
4769 This command creates a socket connected (client) or bound (server) to the given
4772 The returned value is channel and may generally be used with the various file I/O
4773 commands (gets, puts, read, etc.), either as object-based syntax or Tcl-compatible syntax.
4775 . set f [socket stream www.google.com:80]
4777 . $f puts -nonewline "GET / HTTP/1.0\r\n\r\n"
4782 Server sockets, however support only 'accept', which is most useful in conjunction with
4785 set f [socket stream.server 80]
4787 set client [$f accept]
4790 $client puts -nonewline "HTTP/1.1 404 Not found\r\n"
4795 The address, +'addr'+, can be given in one of the following forms:
4797 1. For IPv4 socket types, an IPv4 address such as 192.168.1.1
4798 2. For IPv6 socket types, an IPv6 address such as [fe80::1234] or [::]
4801 Note that on many systems, listening on an IPv6 address such as [::] will
4802 also accept requests via IPv4.
4804 Where a hostname is specified, the +'first'+ returned address is used
4805 which matches the socket type is used.
4807 The special type 'pipe' isn't really a socket.
4809 lassign [socket pipe] r w
4811 # Must close $w after exec
4819 +*syslog* '?options? ?priority? message'+
4821 This command sends message to system syslog facility with given
4822 priority. Valid priorities are:
4824 emerg, alert, crit, err, error, warning, notice, info, debug
4826 If a message is specified, but no priority is specified, then a
4827 priority of info is used.
4829 By default, facility user is used and the value of global tcl variable
4830 argv0 is used as ident string. However, any of the following options
4831 may be specified before priority to control these parameters:
4833 +*-facility* 'value'+::
4834 Use specified facility instead of user. The following
4835 values for facility are recognized:
4837 authpriv, cron, daemon, kernel, lpr, mail, news, syslog, user,
4840 +*-ident* 'string'+::
4841 Use given string instead of argv0 variable for ident string.
4843 +*-options* 'integer'+::
4844 Set syslog options such as +LOG_CONS+, +LOG_NDELAY+. You should
4845 use numeric values of those from your system syslog.h file,
4846 because I haven't got time to implement yet another hash
4851 The optional 'pack' extension provides commands to encode and decode binary strings.
4853 +*pack* 'varName value' *-intle|-intbe|-floatle|-floatbe|-str* 'bitwidth ?bitoffset?'+::
4854 Packs the binary representation of +'value'+ into the variable
4855 +'varName'+. The value is packed according to the given type
4856 (integer/floating point/string, big-endian/little-endian), width and bit offset.
4857 The variable is created if necessary (like `append`).
4858 The variable is expanded if necessary.
4860 +*unpack* 'binvalue' *-intbe|-intle|-uintbe|-uintle|-floatbe|-floatle|-str* 'bitpos bitwidth'+::
4861 Unpacks bits from +'binvalue'+ at bit position +'bitpos'+ and with +'bitwidth'+.
4862 Interprets the value according to the type (integer/floating point/string, big-endian/little-endian
4863 and signed/unsigned) and returns it. For integer types, +'bitwidth'+
4864 may be up to the size of a Jim Tcl integer (typically 64 bits). For floating point types,
4865 +'bitwidth'+ may be 32 bits (for single precision numbers) or 64 bits (for double precision).
4866 For the string type, both the width and the offset must be on a byte boundary (multiple of 8). Attempting to
4867 access outside the length of the value will return 0 for integer types, 0.0 for floating point types
4868 or the empty string for the string type.
4872 The optional 'zlib' extension provides a Tcl-compatible subset of the `zlib` command.
4874 +*crc32* 'data' '?startValue?'+::
4875 Returns the CRC32 checksum of a buffer. Optionally, an initial value may be specified; this is most useful
4876 for calculating the checksum of chunked data read from a stream (for instance, a pipe).
4878 +*deflate* 'string' '?level?'+::
4879 Compresses a buffer and outputs a raw, Deflate-compressed stream. Optionally, a compression level (1-9) may
4880 be specified to choose the desired speed vs. compression rate ratio.
4882 +*inflate* 'data' '?bufferSize?'+::
4883 Decompresses a raw, Deflate-compressed stream. When the uncompressed data size is known and specified, memory
4884 allocation is more efficient. Otherwise, decomperssion is chunked and therefore slower.
4886 +*gzip* 'string' '?-level level?'+::
4887 Compresses a buffer and adds a gzip header.
4889 +*gunzip* 'data' '?-buffersize size?'+::
4890 Decompresses a gzip-compressed buffer. Decompression is chunked, with a default, small buffer size of 64K
4891 which guarantees lower memory footprint at the cost of speed. It is recommended to use a bigger size, on
4892 systems without a severe memory constraint.
4896 The optional, pure-Tcl 'binary' extension provides the Tcl-compatible `binary scan` and `binary format`
4897 commands based on the low-level `pack` and `unpack` commands.
4899 See the Tcl documentation at: http://www.tcl.tk/man/tcl8.5/TclCmd/binary.htm
4901 Note that 'binary format' with f/r/R specifiers (single-precision float) uses the value of Infinity
4902 in case of overflow.
4906 The optional, pure-Tcl 'oo' extension provides object-oriented (OO) support for Jim Tcl.
4908 See the online documentation (http://jim.tcl.tk/index.html/doc/www/www/documentation/oo/) for more details.
4910 +*class* 'classname ?baseclasses? classvars'+::
4911 Create a new class, +'classname'+, with the given dictionary
4912 (+'classvars'+) as class variables. These are the initial variables
4913 which all newly created objects of this class are initialised with.
4914 If a list of baseclasses is given, methods and instance variables
4917 +*super* 'method ?args \...?'+::
4918 From within a method, invokes the given method on the base class.
4919 Note that this will only call the last baseclass given.
4923 The optional, pure-Tcl 'tree' extension implements an OO, general purpose tree structure
4924 similar to that provided by tcllib ::struct::tree (http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/struct/struct_tree.html)
4926 A tree is a collection of nodes, where each node (except the root node) has a single parent
4927 and zero or more child nodes (ordered), as well as zero or more attribute/value pairs.
4930 Creates and returns a new tree object with a single node named "root".
4931 All operations on the tree are invoked through this object.
4934 Destroy the tree and all it's nodes. (Note that the tree will also
4935 be automatically garbage collected once it goes out of scope).
4937 +$tree *set* 'nodename key value'+::
4938 Set the value for the given attribute key.
4940 +$tree *lappend* 'nodename key value \...'+::
4941 Append to the (list) value(s) for the given attribute key, or set if not yet set.
4943 +$tree *keyexists* 'nodename key'+::
4944 Returns 1 if the given attribute key exists.
4946 +$tree *get* 'nodename key'+::
4947 Returns the value associated with the given attribute key.
4949 +$tree *getall* 'nodename'+::
4950 Returns the entire attribute dictionary associated with the given key.
4952 +$tree *depth* 'nodename'+::
4953 Returns the depth of the given node. The depth of "root" is 0.
4955 +$tree *parent* 'nodename'+::
4956 Returns the node name of the parent node, or "" for the root node.
4958 +$tree *numchildren* 'nodename'+::
4959 Returns the number of child nodes.
4961 +$tree *children* 'nodename'+::
4962 Returns a list of the child nodes.
4964 +$tree *next* 'nodename'+::
4965 Returns the next sibling node, or "" if none.
4967 +$tree *insert* 'nodename ?index?'+::
4968 Add a new child node to the given node. The index is a list index
4969 such as +3+ or +end-2+. The default index is +end+.
4970 Returns the name of the newly added node.
4972 +$tree *walk* 'nodename' *dfs|bfs* {'actionvar nodevar'} 'script'+::
4973 Walks the tree starting from the given node, either breadth first (+bfs+)
4974 depth first (+dfs+).
4975 The value +"enter"+ or +"exit"+ is stored in variable +'actionvar'+.
4976 The name of each node is stored in +'nodevar'+.
4977 The script is evaluated twice for each node, on entry and exit.
4980 Dumps the tree contents to stdout
4984 The optional tclprefix extension provides the Tcl8.6-compatible `tcl::prefix` command
4985 (http://www.tcl.tk/man/tcl8.6/TclCmd/prefix.htm) for matching strings against a table
4986 of possible values (typically commands or options).
4988 +*tcl::prefix all* 'table string'+::
4989 Returns a list of all elements in +'table'+ that begin with the prefix +'string'+.
4991 +*tcl::prefix longest* 'table string'+::
4992 Returns the longest common prefix of all elements in +'table'+ that begin with the prefix +'string'+.
4994 +*tcl::prefix match* '?options? table string'+::
4995 If +'string'+ equals one element in +'table'+ or is a prefix to
4996 exactly one element, the matched element is returned. If not, the
4997 result depends on the +-error+ option.
4999 * +*-exact*+ Accept only exact matches.
5000 * +*-message* 'string'+ Use +'string'+ in the error message at a mismatch. Default is "option".
5001 * +*-error* 'options'+ The options are used when no match is found. If +'options'+ is
5002 empty, no error is generated and an empty string is returned.
5003 Otherwise the options are used as return options when
5004 generating the error message. The default corresponds to
5009 Scriptable command line completion is supported in the interactive shell, 'jimsh', through
5010 the `tcl::autocomplete` callback. A simple implementation is provided, however this may
5011 be replaced with a custom command instead if desired.
5013 In the interactive shell, press <TAB> to activate command line completion.
5015 +*tcl::autocomplete* 'commandline'+::
5016 This command is called with the current command line when the user presses <TAB>.
5017 The command should return a list of all possible command lines that match the current command line.
5018 For example if +*pr*+ is the current command line, the list +*{prefix proc}*+ may be returned.
5022 The optional history extension provides script access to the command line editing
5023 and history support available in 'jimsh'. See 'examples/jtclsh.tcl' for an example.
5024 Note: if line editing support is not available, `history getline` acts like `gets` and
5025 the remaining subcommands do nothing.
5027 +*history load* 'filename'+::
5028 Load history from a (text) file. If the file does not exist or is not readable,
5031 +*history getline* 'prompt ?varname?'+::
5032 Displays the given prompt and allows a line to be entered. Similarly to `gets`,
5033 if +'varname'+ is given, it receives the line and the length of the line is returned,
5034 or -1 on EOF. If +'varname'+ is not given, the line is returned directly.
5036 +*history completion* 'command'+::
5037 Sets an autocompletion command (see `tcl::autocomplete`) that is active during `history getline`.
5038 If the command is empty, autocompletion is disabled.
5040 +*history add* 'line'+::
5041 Adds the given line to the history buffer.
5043 +*history save* 'filename'+::
5044 Saves the current history buffer to the given file.
5047 Displays the current history buffer to standard output.
5051 Provides namespace-related functions. See also: http://www.tcl.tk/man/tcl8.6/TclCmd/namespace.htm
5053 +*namespace code* 'script'+::
5054 Captures the current namespace context for later execution of
5055 the script +'script'+. It returns a new script in which script has
5056 been wrapped in a +*namespace inscope*+ command.
5058 +*namespace current*+::
5059 Returns the fully-qualified name for the current namespace.
5061 +*namespace delete* '?namespace ...?'+::
5062 Deletes all commands and variables with the given namespace prefixes.
5064 +*namespace eval* 'namespace arg ?arg...?'+::
5065 Activates a namespace called +'namespace'+ and evaluates some code in that context.
5067 +*namespace origin* 'command'+::
5068 Returns the fully-qualified name of the original command to which the imported command +'command'+ refers.
5070 +*namespace parent* ?namespace?+::
5071 Returns the fully-qualified name of the parent namespace for namespace +'namespace'+, if given, otherwise
5072 for the current namespace.
5074 +*namespace qualifiers* 'string'+::
5075 Returns any leading namespace qualifiers for +'string'+
5077 +*namespace tail* 'string'+::
5078 Returns the simple name at the end of a qualified string.
5080 +*namespace upvar* 'namespace ?arg...?'+::
5081 This command arranges for zero or more local variables in the current procedure to refer to variables in +'namespace'+
5083 +*namespace which* '?-command|-variable? name'+::
5084 Looks up +'name'+ as either a command (the default) or variable and returns its fully-qualified name.
5088 The optional 'interp' command allows sub-interpreters to be created where commands may be run
5089 independently (but synchronously) of the main interpreter.
5092 Creates and returns a new interpreter object (command).
5093 The created interpeter contains any built-in commands along with static extensions,
5094 but does not include any dynamically loaded commands (package require, load).
5095 These must be reloaded in the child interpreter if required.
5097 +*$interp delete*+::
5098 Deletes the interpeter object.
5100 +*$interp eval* 'script' ...+::
5101 Evaluates a script in the context for the child interpreter, in the same way as 'eval'.
5103 +*$interp alias* 'alias childcmd parentcmd ?arg ...?'+::
5104 Similar to 'alias', but creates a command, +'childcmd'+, in the child interpreter that is an
5105 alias for +'parentcmd'+ in the parent interpreter, with the given, fixed arguments.
5106 The alias may be deleted in the child with 'rename'.
5108 [[BuiltinVariables]]
5112 The following global variables are created automatically
5116 This variable is set by Jim as an array
5117 whose elements are the environment variables for the process.
5118 Reading an element will return the value of the corresponding
5119 environment variable.
5120 This array is initialised at startup from the `env` command.
5121 It may be modified and will affect the environment passed to
5122 commands invoked with `exec`.
5125 This variable is set by Jim as an array containing information
5126 about the platform on which Jim was built. Currently this includes
5127 'os' and 'platform'.
5130 This variable contains a list of paths to search for packages.
5131 It defaults to a location based on where jim is installed
5132 (e.g. +/usr/local/lib/jim+), but may be changed by +jimsh+
5133 or the embedding application. Note that +jimsh+ will consider
5134 the environment variable +$JIMLIB+ to be a list of colon-separated
5135 list of paths to add to +*auto_path*+.
5138 This variable holds the value of the -errorcode return
5139 option set by the most recent error that occurred in this
5140 interpreter. This list value represents additional information
5141 about the error in a form that is easy to process with
5142 programs. The first element of the list identifies a general
5143 class of errors, and determines the format of the rest of
5144 the list. The following formats for -errorcode return options
5145 are used by the Tcl core; individual applications may define
5146 additional formats. Currently only `exec` sets this variable.
5147 Otherwise it will be +NONE+.
5149 The following global variables are set by jimsh.
5151 +*tcl_interactive*+::
5152 This variable is set to 1 if jimsh is started in interactive mode
5156 This variable is set by Jim as an array containing information
5157 about the platform upon which Jim was built. The following is an
5158 example of the contents of this array.
5160 tcl_platform(byteOrder) = littleEndian
5161 tcl_platform(engine) = Jim
5162 tcl_platform(os) = Darwin
5163 tcl_platform(platform) = unix
5164 tcl_platform(pointerSize) = 8
5165 tcl_platform(threaded) = 0
5166 tcl_platform(wordSize) = 8
5167 tcl_platform(pathSeparator) = :
5170 If jimsh is invoked to run a script, this variable contains the name
5174 If jimsh is invoked to run a script, this variable contains a list
5175 of any arguments supplied to the script.
5178 If jimsh is invoked to run a script, this variable contains the number
5179 of arguments supplied to the script.
5182 The value of argv[0] when jimsh was invoked.
5184 The following variables have special meaning to Jim Tcl:
5187 If this variable is set, it is considered to be a list of scripts to evaluate
5188 when the current proc exits (local variables), or the interpreter exits (global variable).
5192 CHANGES IN PREVIOUS RELEASES
5193 ----------------------------
5197 1. +platform_tcl()+ settings are now automatically determined
5198 2. Add aio `$handle filename`
5199 3. Add `info channels`
5200 4. The 'bio' extension is gone. Now `aio` supports 'copyto'.
5201 5. Add `exists` command
5202 6. Add the pure-Tcl 'oo' extension
5203 7. The `exec` command now only uses vfork(), not fork()
5204 8. Unit test framework is less verbose and more Tcl-compatible
5205 9. Optional UTF-8 support
5206 10. Optional built-in regexp engine for better Tcl compatibility and UTF-8 support
5207 11. Command line editing in interactive mode, e.g. 'jimsh'
5211 1. `source` now checks that a script is complete (.i.e. not missing a brace)
5212 2. 'info complete' now uses the real parser and so is 100% accurate
5213 3. Better access to live stack frames with 'info frame', `stacktrace` and `stackdump`
5214 4. `tailcall` no longer loses stack trace information
5215 5. Add `alias` and `curry`
5216 6. `lambda`, `alias` and `curry` are implemented via `tailcall` for efficiency
5217 7. `local` allows procedures to be deleted automatically at the end of the current procedure
5218 8. udp sockets are now supported for both clients and servers.
5219 9. vfork-based exec is now working correctly
5220 10. Add 'file tempfile'
5221 11. Add 'socket pipe'
5222 12. Enhance 'try ... on ... finally' to be more Tcl 8.6 compatible
5223 13. It is now possible to `return` from within `try`
5224 14. IPv6 support is now included
5226 16. Event handlers works better if an error occurs. eof handler has been removed.
5227 17. `exec` now sets $::errorCode, and catch sets opts(-errorcode) for exit status
5228 18. Command pipelines via open "|..." are now supported
5229 19. `pid` can now return pids of a command pipeline
5230 20. Add 'info references'
5231 21. Add support for 'after +'ms'+', 'after idle', 'after info', `update`
5232 22. `exec` now sets environment based on $::env
5234 24. Add support for 'lsort -index'
5238 1. Add support to `exec` for '>&', '>>&', '|&', '2>@1'
5239 2. Fix `exec` error messages when special token (e.g. '>') is the last token
5240 3. Fix `subst` handling of backslash escapes.
5241 4. Allow abbreviated options for `subst`
5242 5. Add support for `return`, `break`, `continue` in subst
5243 6. Many `expr` bug fixes
5244 7. Add support for functions in `expr` (e.g. int(), abs()), and also 'in', 'ni' list operations
5245 8. The variable name argument to `regsub` is now optional
5246 9. Add support for 'unset -nocomplain'
5247 10. Add support for list commands: `lassign`, `lrepeat`
5248 11. Fully-functional `lsearch` is now implemented
5249 12. Add 'info nameofexecutable' and 'info returncodes'
5250 13. Allow `catch` to determine what return codes are caught
5251 14. Allow `incr` to increment an unset variable by first setting to 0
5252 15. Allow 'args' and optional arguments to the left or required arguments in `proc`
5254 17. Add 'try ... finally' command
5260 Copyright 2005 Salvatore Sanfilippo <antirez@invece.org>
5261 Copyright 2005 Clemens Hintze <c.hintze@gmx.net>
5262 Copyright 2005 patthoyts - Pat Thoyts <patthoyts@users.sf.net>
5263 Copyright 2008 oharboe - Oyvind Harboe - oyvind.harboe@zylin.com
5264 Copyright 2008 Andrew Lunn <andrew@lunn.ch>
5265 Copyright 2008 Duane Ellis <openocd@duaneellis.com>
5266 Copyright 2008 Uwe Klein <uklein@klein-messgeraete.de>
5267 Copyright 2009 Steve Bennett <steveb@workware.net.au>
5270 Redistribution and use in source and binary forms, with or without
5271 modification, are permitted provided that the following conditions
5273 1. Redistributions of source code must retain the above copyright
5274 notice, this list of conditions and the following disclaimer.
5275 2. Redistributions in binary form must reproduce the above
5276 copyright notice, this list of conditions and the following
5277 disclaimer in the documentation and/or other materials
5278 provided with the distribution.
5280 THIS SOFTWARE IS PROVIDED BY THE JIM TCL PROJECT ``AS IS'' AND ANY
5281 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
5282 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
5283 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
5284 JIM TCL PROJECT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
5285 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
5286 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
5287 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
5288 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
5289 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
5290 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
5291 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
5293 The views and conclusions contained in the software and documentation
5294 are those of the authors and should not be interpreted as representing
5295 official policies, either expressed or implied, of the Jim Tcl Project.