6 Jim Tcl v0.76+ - reference manual for the Jim Tcl scripting language
16 jimsh -e '<immediate-script>'
21 * <<CommandIndex,Command Reference>>
22 * <<OperatorPrecedence,Operator Precedence>>
23 * <<BuiltinVariables, Builtin Variables>>
24 * <<BackslashSequences, Backslash Sequences>>
28 Jim Tcl is a small footprint reimplementation of the Tcl scripting language.
29 The core language engine is compatible with Tcl 8.5+, while implementing
30 a significant subset of the Tcl 8.6 command set, plus additional features
31 available only in Jim Tcl.
33 Some notable differences with Tcl 8.5/8.6 are:
35 1. Object-based I/O (aio), but with a Tcl-compatibility layer
36 2. I/O: Support for sockets and pipes including udp, unix domain sockets and IPv6
38 4. Support for references (`ref`/`getref`/`setref`) and garbage collection
39 5. Builtin dictionary type (`dict`) with some limitations compared to Tcl 8.6
40 6. `env` command to access environment variables
41 7. Operating system features: `os.fork`, `os.wait`, `os.uptime`, `signal`, `alarm`, `sleep`
42 8. Much better error reporting. `info stacktrace` as a replacement for '$errorInfo', '$errorCode'
43 9. Support for "static" variables in procedures
44 10. Threads and coroutines are not supported
45 11. Command and variable traces are not supported
46 12. Built-in command line editing
47 13. Expression shorthand syntax: +$(...)+
48 14. Modular build allows many features to be omitted or built as dynamic, loadable modules
49 15. Highly suitable for use in an embedded environment
50 16. Support for UDP, IPv6, Unix-Domain sockets in addition to TCP sockets
54 Changes between 0.76 and 0.77
55 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
56 1. Add support for `aio sync`
57 2. Add SSL and TLS support in aio
59 4. Added support for boolean constants in `expr`
60 5. `string is` now supports 'boolean' class
61 6. Add support for `aio lock` and `aio unlock`
63 Changes between 0.75 and 0.76
64 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
65 1. Add support for `file link`
66 2. `glob` now supports the '--tails' option
67 3. Add support for `string cat`
68 4. Allow `info source` to add source info
70 Changes between 0.74 and 0.75
71 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
72 1. `binary`, `pack` and `unpack` now support floating point
73 2. `file copy` '-force' handles source and target as the same file
74 3. `format` now supports +%b+ for binary conversion
75 4. `lsort` now supports '-unique' and '-real'
76 5. Add support for half-close with `aio close` ?r|w?
77 6. Add `socket pair` for a bidirectional pipe
78 7. Add '--random-hash' to randomise hash tables for greater security
79 8. `dict` now supports 'for', 'values', 'incr', 'append', 'lappend', 'update', 'info' and 'replace'
80 9. `file stat` no longer requires the variable name
82 Changes between 0.73 and 0.74
83 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
84 1. Numbers with leading zeros are treated as decimal, not octal
86 3. Add LFS (64 bit) support for `aio seek`, `aio tell`, `aio copyto`, `file copy`
87 4. `string compare` and `string equal` now support '-length'
88 5. `glob` now supports '-directory'
90 Changes between 0.72 and 0.73
91 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
92 1. Built-in regexp now support non-capturing parentheses: (?:...)
93 2. Add `string replace`
94 3. Add `string totitle`
96 5. Add +build-jim-ext+ for easy separate building of loadable modules (extensions)
97 6. `local` now works with any command, not just procs
98 7. Add `info alias` to access the target of an alias
99 8. UTF-8 encoding past the basic multilingual plane (BMP) is supported
102 11. Most extensions are now enabled by default
103 12. Add support for namespaces and the `namespace` command
106 Changes between 0.71 and 0.72
107 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
108 1. procs now allow 'args' and optional parameters in any position
109 2. Add Tcl-compatible expr functions, `rand()`, `srand()` and `pow()`
110 3. Add support for the '-force' option to `file delete`
111 4. Better diagnostics when `source` fails to load a script with a missing quote or bracket
112 5. New +tcl_platform(pathSeparator)+
113 6. Add support settings the modification time with `file mtime`
114 7. `exec` is now fully supported on win32 (mingw32)
115 8. `file join`, `pwd`, `glob` etc. now work for mingw32
116 9. Line editing is now supported for the win32 console (mingw32)
117 10. Add `aio listen` command
119 Changes between 0.70 and 0.71
120 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
121 1. Allow 'args' to be renamed in procs
122 2. Add +$(...)+ shorthand syntax for expressions
123 3. Add automatic reference variables in procs with +&var+ syntax
124 4. Support +jimsh --version+
125 5. Additional variables in +tcl_platform()+
126 6. `local` procs now push existing commands and `upcall` can call them
127 7. Add `loop` command (TclX compatible)
128 8. Add `aio buffering` command
129 9. `info complete` can now return the missing character
130 10. `binary format` and `binary scan` are now (optionally) supported
131 11. Add `string byterange`
132 12. Built-in regexp now support non-greedy repetition (*?, +?, ??)
136 Tcl stands for 'tool command language' and is pronounced
137 'http://www.oxforddictionaries.com/definition/american_english/tickle[tickle]'.
138 It is actually two things: a language and a library.
140 First, Tcl is a simple textual language, intended primarily for
141 issuing commands to interactive programs such as text editors,
142 debuggers, illustrators, and shells. It has a simple syntax and is also
143 programmable, so Tcl users can write command procedures to provide more
144 powerful commands than those in the built-in set.
146 Second, Tcl is a library package that can be embedded in application
147 programs. The Tcl library consists of a parser for the Tcl language,
148 routines to implement the Tcl built-in commands, and procedures that
149 allow each application to extend Tcl with additional commands specific
150 to that application. The application program generates Tcl commands and
151 passes them to the Tcl parser for execution. Commands may be generated
152 by reading characters from an input source, or by associating command
153 strings with elements of the application's user interface, such as menu
154 entries, buttons, or keystrokes.
156 When the Tcl library receives commands it parses them into component
157 fields and executes built-in commands directly. For commands implemented
158 by the application, Tcl calls back to the application to execute the
159 commands. In many cases commands will invoke recursive invocations of the
160 Tcl interpreter by passing in additional strings to execute (procedures,
161 looping commands, and conditional commands all work in this way).
163 An application program gains three advantages by using Tcl for its command
164 language. First, Tcl provides a standard syntax: once users know Tcl,
165 they will be able to issue commands easily to any Tcl-based application.
166 Second, Tcl provides programmability. All a Tcl application needs
167 to do is to implement a few application-specific low-level commands.
168 Tcl provides many utility commands plus a general programming interface
169 for building up complex command procedures. By using Tcl, applications
170 need not re-implement these features.
172 Third, Tcl can be used as a common language for communicating between
173 applications. Inter-application communication is not built into the
174 Tcl core described here, but various add-on libraries, such as the Tk
175 toolkit, allow applications to issue commands to each other. This makes
176 it possible for applications to work together in much more powerful ways
177 than was previously possible.
179 Fourth, Jim Tcl includes a command processor, +jimsh+, which can be
180 used to run standalone Tcl scripts, or to run Tcl commands interactively.
182 This manual page focuses primarily on the Tcl language. It describes
183 the language syntax and the built-in commands that will be available
184 in any application based on Tcl. The individual library procedures are
185 described in more detail in separate manual pages, one per procedure.
187 JIMSH COMMAND INTERPRETER
188 -------------------------
189 A simple, but powerful command processor, +jimsh+, is part of Jim Tcl.
190 It may be invoked in interactive mode as:
194 or to process the Tcl script in a file with:
198 It may also be invoked to execute an immediate script with:
204 Interactive mode reads Tcl commands from standard input, evaluates
205 those commands and prints the results.
208 Welcome to Jim version 0.73, Copyright (c) 2005-8 Salvatore Sanfilippo
211 . lsort [info commands p*]
212 package parray pid popen proc puts pwd
213 . foreach i {a b c} {
220 invalid command name "bad"
224 If +jimsh+ is configured with line editing (it is by default) and a VT-100-compatible
225 terminal is detected, Emacs-style line editing commands are available, including:
226 arrow keys, +\^W+ to erase a word, +\^U+ to erase the line, +^R+ for reverse incremental search
227 in history. Additionally, the +h+ command may be used to display the command history.
229 Command line history is automatically saved and loaded from +~/.jim_history+
231 In interactive mode, +jimsh+ automatically runs the script +~/.jimrc+ at startup
236 The central data structure in Tcl is an interpreter (C type 'Jim_Interp').
237 An interpreter consists of a set of command bindings, a set of variable
238 values, and a few other miscellaneous pieces of state. Each Tcl command
239 is interpreted in the context of a particular interpreter.
241 Some Tcl-based applications will maintain multiple interpreters
242 simultaneously, each associated with a different widget or portion of
243 the application. Interpreters are relatively lightweight structures.
244 They can be created and deleted quickly, so application programmers should
245 feel free to use multiple interpreters if that simplifies the application.
249 Tcl supports only one type of data: strings. All commands, all arguments
250 to commands, all command results, and all variable values are strings.
252 Where commands require numeric arguments or return numeric results,
253 the arguments and results are passed as strings. Many commands expect
254 their string arguments to have certain formats, but this interpretation
255 is up to the individual commands. For example, arguments often contain
256 Tcl command strings, which may get executed as part of the commands.
257 The easiest way to understand the Tcl interpreter is to remember that
258 everything is just an operation on a string. In many cases Tcl constructs
259 will look similar to more structured constructs from other languages.
260 However, the Tcl constructs are not structured at all; they are just
261 strings of characters, and this gives them a different behaviour than
262 the structures they may look like.
264 Although the exact interpretation of a Tcl string depends on who is doing
265 the interpretation, there are three common forms that strings take:
266 commands, expressions, and lists. The major sections below discuss
267 these three forms in more detail.
271 The Tcl language has syntactic similarities to both the Unix shells
272 and Lisp. However, the interpretation of commands is different
273 in Tcl than in either of those other two systems.
274 A Tcl command string consists of one or more commands separated
275 by newline characters or semi-colons.
276 Each command consists of a collection of fields separated by
277 white space (spaces or tabs).
278 The first field must be the name of a command, and the
279 additional fields, if any, are arguments that will be passed to
280 that command. For example, the command:
284 has three fields: the first, `set`, is the name of a Tcl command, and
285 the last two, 'a' and '22', will be passed as arguments to
286 the `set` command. The command name may refer either to a built-in
287 Tcl command, an application-specific command bound in with the library
288 procedure 'Jim_CreateCommand', or a command procedure defined with the
289 `proc` built-in command.
291 Arguments are passed literally as text strings. Individual commands may
292 interpret those strings in any fashion they wish. The `set` command,
293 for example, will treat its first argument as the name of a variable
294 and its second argument as a string value to assign to that variable.
295 For other commands arguments may be interpreted as integers, lists,
296 file names, or Tcl commands.
298 Command names should normally be typed completely (e.g. no abbreviations).
299 However, if the Tcl interpreter cannot locate a command it invokes a
300 special command named `unknown` which attempts to find or create the
303 For example, at many sites `unknown` will search through library
304 directories for the desired command and create it as a Tcl procedure if
305 it is found. The `unknown` command often provides automatic completion
306 of abbreviated commands, but usually only for commands that were typed
309 It's probably a bad idea to use abbreviations in command scripts and
310 other forms that will be re-used over time: changes to the command set
311 may cause abbreviations to become ambiguous, resulting in scripts that
316 If the first non-blank character in a command is +\#+, then everything
317 from the +#+ up through the next newline character is treated as
318 a comment and ignored. When comments are embedded inside nested
319 commands (e.g. fields enclosed in braces) they must have properly-matched
320 braces (this is necessary because when Tcl parses the top-level command
321 it doesn't yet know that the nested field will be used as a command so
322 it cannot process the nested comment character as a comment).
324 GROUPING ARGUMENTS WITH DOUBLE-QUOTES
325 -------------------------------------
326 Normally each argument field ends at the next white space, but
327 double-quotes may be used to create arguments with embedded space.
329 If an argument field begins with a double-quote, then the argument isn't
330 terminated by white space (including newlines) or a semi-colon (see below
331 for information on semi-colons); instead it ends at the next double-quote
332 character. The double-quotes are not included in the resulting argument.
333 For example, the command
335 set a "This is a single argument"
337 will pass two arguments to `set`: 'a' and 'This is a single argument'.
339 Within double-quotes, command substitutions, variable substitutions,
340 and backslash substitutions still occur, as described below. If the
341 first character of a command field is not a quote, then quotes receive
342 no special interpretation in the parsing of that field.
344 GROUPING ARGUMENTS WITH BRACES
345 ------------------------------
346 Curly braces may also be used for grouping arguments. They are similar
347 to quotes except for two differences. First, they nest; this makes them
348 easier to use for complicated arguments like nested Tcl command strings.
349 Second, the substitutions described below for commands, variables, and
350 backslashes do *not* occur in arguments enclosed in braces, so braces
351 can be used to prevent substitutions where they are undesirable.
353 If an argument field begins with a left brace, then the argument ends
354 at the matching right brace. Tcl will strip off the outermost layer
355 of braces and pass the information between the braces to the command
356 without any further modification. For example, in the command
358 set a {xyz a {b c d}}
360 the `set` command will receive two arguments: 'a'
363 When braces or quotes are in effect, the matching brace or quote need
364 not be on the same line as the starting quote or brace; in this case
365 the newline will be included in the argument field along with any other
366 characters up to the matching brace or quote. For example, the `eval`
367 command takes one argument, which is a command string; `eval` invokes
368 the Tcl interpreter to execute the command string. The command
375 will assign the value '22' to 'a' and '33' to 'b'.
377 If the first character of a command field is not a left
378 brace, then neither left nor right
379 braces in the field will be treated specially (except as part of
380 variable substitution; see below).
382 COMMAND SUBSTITUTION WITH BRACKETS
383 ----------------------------------
384 If an open bracket occurs in a field of a command, then command
385 substitution occurs (except for fields enclosed in braces). All of the
386 text up to the matching close bracket is treated as a Tcl command and
387 executed immediately. Then the result of that command is substituted
388 for the bracketed text. For example, consider the command
392 When the `set` command has only a single argument, it is the name of a
393 variable and `set` returns the contents of that variable. In this case,
394 if variable 'b' has the value 'foo', then the command above is equivalent
399 Brackets can be used in more complex ways. For example, if the variable
400 'b' has the value 'foo' and the variable 'c' has the value 'gorp',
403 set a xyz[set b].[set c]
405 is equivalent to the command
410 A bracketed command may contain multiple commands separated by newlines
411 or semi-colons in the usual fashion. In this case the value of the last
412 command is used for substitution. For example, the command
417 is equivalent to the command
422 If a field is enclosed in braces then the brackets and the characters
423 between them are not interpreted specially; they are passed through to
424 the argument verbatim.
426 VARIABLE SUBSTITUTION WITH $
427 ----------------------------
428 The dollar sign (+$+) may be used as a special shorthand form for
429 substituting variable values. If +$+ appears in an argument that isn't
430 enclosed in braces then variable substitution will occur. The characters
431 after the +$+, up to the first character that isn't a number, letter,
432 or underscore, are taken as a variable name and the string value of that
433 variable is substituted for the name.
435 For example, if variable 'foo' has the value 'test', then the command
439 is equivalent to the command
443 There are two special forms for variable substitution. If the next
444 character after the name of the variable is an open parenthesis, then
445 the variable is assumed to be an array name, and all of the characters
446 between the open parenthesis and the next close parenthesis are taken as
447 an index into the array. Command substitutions and variable substitutions
448 are performed on the information between the parentheses before it is
451 For example, if the variable 'x' is an array with one element named
452 'first' and value '87' and another element named '14' and value 'more',
455 set a xyz$x(first)zyx
457 is equivalent to the command
461 If the variable 'index' has the value '14', then the command
463 set a xyz$x($index)zyx
465 is equivalent to the command
469 For more information on arrays, see VARIABLES AND ARRAYS below.
471 The second special form for variables occurs when the dollar sign is
472 followed by an open curly brace. In this case the variable name consists
473 of all the characters up to the next curly brace.
475 Array references are not possible in this form: the name between braces
476 is assumed to refer to a scalar variable. For example, if variable
477 'foo' has the value 'test', then the command
481 is equivalent to the command
486 Variable substitution does not occur in arguments that are enclosed in
487 braces: the dollar sign and variable name are passed through to the
490 The dollar sign abbreviation is simply a shorthand form. +$a+ is
491 completely equivalent to +[set a]+; it is provided as a convenience
494 SEPARATING COMMANDS WITH SEMI-COLONS
495 ------------------------------------
496 Normally, each command occupies one line (the command is terminated by a
497 newline character). However, semi-colon (+;+) is treated as a command
498 separator character; multiple commands may be placed on one line by
499 separating them with a semi-colon. Semi-colons are not treated as
500 command separators if they appear within curly braces or double-quotes.
502 BACKSLASH SUBSTITUTION
503 ----------------------
504 Backslashes may be used to insert non-printing characters into command
505 fields and also to insert special characters like braces and brackets
506 into fields without them being interpreted specially as described above.
508 The backslash sequences understood by the Tcl interpreter are
509 listed below. In each case, the backslash
510 sequence is replaced by the given character:
511 [[BackslashSequences]]
522 Carriage-return (0xd).
545 +{backslash}<space>+::
546 Space ( ): doesn't terminate argument.
549 Semi-colon: doesn't terminate command.
554 +{backslash}<newline>+::
555 Nothing: this joins two lines together
556 into a single line. This backslash feature is unique in that
557 it will be applied even when the sequence occurs within braces.
559 +{backslash}{backslash}+::
560 Backslash ('{backslash}').
563 The digits +'ddd'+ (one, two, or three of them) give the octal value of
564 the character. Note that Jim supports null characters in strings.
567 +{backslash}u\{nnn\}+::
568 +{backslash}Unnnnnnnn+::
569 The UTF-8 encoding of the unicode codepoint represented by the hex digits, +'nnnn'+, is inserted.
570 The 'u' form allows for one to four hex digits.
571 The 'U' form allows for one to eight hex digits.
572 The 'u\{nnn\}' form allows for one to eight hex digits, but makes it easier to insert
573 characters UTF-8 characters which are followed by a hex digit.
575 For example, in the command
579 the second argument to `set` will be +{x[ yza+.
581 If a backslash is followed by something other than one of the options
582 described above, then the backslash is transmitted to the argument
583 field without any special processing, and the Tcl scanner continues
584 normal processing with the next character. For example, in the
589 The first argument to `set` will be +{backslash}*a+ and the second
590 argument will be +{backslash}{foo+.
592 If an argument is enclosed in braces, then backslash sequences inside
593 the argument are parsed but no substitution occurs (except for
594 backslash-newline): the backslash
595 sequence is passed through to the argument as is, without making
596 any special interpretation of the characters in the backslash sequence.
597 In particular, backslashed braces are not counted in locating the
598 matching right brace that terminates the argument.
604 the second argument to `set` will be +{backslash}{abc+.
606 This backslash mechanism is not sufficient to generate absolutely
607 any argument structure; it only covers the
608 most common cases. To produce particularly complicated arguments
609 it is probably easiest to use the `format` command along with
610 command substitution.
612 STRING AND LIST INDEX SPECIFICATIONS
613 ------------------------------------
615 Many string and list commands take one or more 'index' parameters which
616 specify a position in the string relative to the start or end of the string/list.
618 The index may be one of the following forms:
621 A simple integer, where '0' refers to the first element of the string
624 +integer+integer+ or::
626 The sum or difference of the two integers. e.g. +2+3+ refers to the 5th element.
627 This is useful when used with (e.g.) +$i+1+ rather than the more verbose
631 The last element of the string or list.
634 The 'nth-from-last' element of the string or list.
638 1. A command is just a string.
639 2. Within a string commands are separated by newlines or semi-colons
640 (unless the newline or semi-colon is within braces or brackets
642 3. A command consists of fields. The first field is the name of the command.
643 The other fields are strings that are passed to that command as arguments.
644 4. Fields are normally separated by white space.
645 5. Double-quotes allow white space and semi-colons to appear within
647 Command substitution, variable substitution, and backslash substitution
648 still occur inside quotes.
649 6. Braces defer interpretation of special characters.
650 If a field begins with a left brace, then it consists of everything
651 between the left brace and the matching right brace. The
652 braces themselves are not included in the argument.
653 No further processing is done on the information between the braces
654 except that backslash-newline sequences are eliminated.
655 7. If a field doesn't begin with a brace then backslash,
656 variable, and command substitution are done on the field. Only a
657 single level of processing is done: the results of one substitution
658 are not scanned again for further substitutions or any other
659 special treatment. Substitution can
660 occur on any field of a command, including the command name
661 as well as the arguments.
662 8. If the first non-blank character of a command is a +\#+, everything
663 from the +#+ up through the next newline is treated as a comment
668 The second major interpretation applied to strings in Tcl is
669 as expressions. Several commands, such as `expr`, `for`,
670 and `if`, treat one or more of their arguments as expressions
671 and call the Tcl expression processors ('Jim_ExprLong',
672 'Jim_ExprBoolean', etc.) to evaluate them.
674 The operators permitted in Tcl expressions are a subset of
675 the operators permitted in C expressions, and they have the
676 same meaning and precedence as the corresponding C operators.
677 Expressions almost always yield numeric results
678 (integer or floating-point values).
679 For example, the expression
685 Tcl expressions differ from C expressions in the way that
686 operands are specified, and in that Tcl expressions support
687 non-numeric operands and string comparisons.
689 A Tcl expression consists of a combination of operands, operators,
692 White space may be used between the operands and operators and
693 parentheses; it is ignored by the expression processor.
694 Where possible, operands are interpreted as integer values.
696 Integer values may be specified in decimal (the normal case) or in
697 hexadecimal (if the first two characters of the operand are '0x').
698 Note that Jim Tcl does *not* treat numbers with leading zeros as octal.
700 If an operand does not have one of the integer formats given
701 above, then it is treated as a floating-point number if that is
702 possible. Floating-point numbers may be specified in any of the
703 ways accepted by an ANSI-compliant C compiler (except that the
704 'f', 'F', 'l', and 'L' suffixes will not be permitted in
705 most installations). For example, all of the
706 following are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16.
708 If no numeric interpretation is possible, then an operand is left
709 as a string (and only a limited set of operators may be applied to
712 String constants representing boolean constants
713 (+'0'+, +'1'+, +'false'+, +'off'+, +'no'+, +'true'+, +'on'+, +'yes'+)
714 are also recognized and can be used in logical operations.
716 1. Operands may be specified in any of the following ways:
718 2. As a numeric value, either integer or floating-point.
720 3. As one of valid boolean constants
722 4. As a Tcl variable, using standard '$' notation.
723 The variable's value will be used as the operand.
725 5. As a string enclosed in double-quotes.
726 The expression parser will perform backslash, variable, and
727 command substitutions on the information between the quotes,
728 and use the resulting value as the operand
730 6. As a string enclosed in braces.
731 The characters between the open brace and matching close brace
732 will be used as the operand without any substitutions.
734 7. As a Tcl command enclosed in brackets.
735 The command will be executed and its result will be used as
738 Where substitutions occur above (e.g. inside quoted strings), they
739 are performed by the expression processor.
740 However, an additional layer of substitution may already have
741 been performed by the command parser before the expression
742 processor was called.
744 As discussed below, it is usually best to enclose expressions
745 in braces to prevent the command parser from performing substitutions
748 For some examples of simple expressions, suppose the variable 'a' has
749 the value 3 and the variable 'b' has the value 6. Then the expression
750 on the left side of each of the lines below will evaluate to the value
751 on the right side of the line:
756 {word one} < "word $a" 0
758 The valid operators are listed below, grouped in decreasing order
760 [[OperatorPrecedence]]
761 +int() double() round() abs(), rand(), srand()+::
762 Unary functions (except rand() which takes no arguments)
763 * +'int()'+ converts the numeric argument to an integer by truncating down.
764 * +'double()'+ converts the numeric argument to floating point.
765 * +'round()'+ converts the numeric argument to the closest integer value.
766 * +'abs()'+ takes the absolute value of the numeric argument.
767 * +'rand()'+ returns a pseudo-random floating-point value in the range (0,1).
768 * +'srand()'+ takes an integer argument to (re)seed the random number generator. Returns the first random number from that seed.
770 +sin() cos() tan() asin() acos() atan() sinh() cosh() tanh() ceil() floor() exp() log() log10() sqrt()+::
771 Unary math functions.
772 If Jim is compiled with math support, these functions are available.
775 Unary minus, unary plus, bit-wise NOT, logical NOT. None of these operands
776 may be applied to string operands, and bit-wise NOT may be
777 applied only to integers.
780 Power. e.g. 'x^y^'. If Jim is compiled with math support, supports doubles and
781 integers. Otherwise supports integers only. (Note that the math-function form
782 has the same highest precedence)
785 Multiply, divide, remainder. None of these operands may be
786 applied to string operands, and remainder may be applied only
790 Add and subtract. Valid for any numeric operands.
793 Left and right shift, left and right rotate. Valid for integer operands only.
796 Boolean less, greater, less than or equal, and greater than or equal.
797 Each operator produces 1 if the condition is true, 0 otherwise.
798 These operators may be applied to strings as well as numeric operands,
799 in which case string comparison is used.
802 Boolean equal and not equal. Each operator produces a zero/one result.
803 Valid for all operand types. *Note* that values will be converted to integers
804 if possible, then floating point types, and finally strings will be compared.
805 It is recommended that 'eq' and 'ne' should be used for string comparison.
808 String equal and not equal. Uses the string value directly without
809 attempting to convert to a number first.
812 String in list and not in list. For 'in', result is 1 if the left operand (as a string)
813 is contained in the right operand (as a list), or 0 otherwise. The result for
814 +{$a ni $list}+ is equivalent to +{!($a in $list)}+.
817 Bit-wise AND. Valid for integer operands only.
820 Bit-wise OR. Valid for integer operands only.
823 Bit-wise exclusive OR. Valid for integer operands only.
826 Logical AND. Produces a 1 result if both operands are non-zero, 0 otherwise.
827 Valid for numeric operands only (integers or floating-point).
830 Logical OR. Produces a 0 result if both operands are zero, 1 otherwise.
831 Valid for numeric operands only (integers or floating-point).
834 If-then-else, as in C. If +'x'+
835 evaluates to non-zero, then the result is the value of +'y'+.
836 Otherwise the result is the value of +'z'+.
837 The +'x'+ operand must have a numeric value, while +'y'+ and +'z'+ can
840 See the C manual for more details on the results
841 produced by each operator.
842 All of the binary operators group left-to-right within the same
843 precedence level. For example, the expression
849 The +&&+, +||+, and +?:+ operators have 'lazy evaluation', just as
850 in C, which means that operands are not evaluated if they are not
851 needed to determine the outcome. For example, in
855 only one of +[a]+ or +[b]+ will actually be evaluated,
856 depending on the value of +$v+.
858 All internal computations involving integers are done with the C
859 type 'long long' if available, or 'long' otherwise, and all internal
860 computations involving floating-point are done with the C type
863 When converting a string to floating-point, exponent overflow is
864 detected and results in a Tcl error.
865 For conversion to integer from string, detection of overflow depends
866 on the behaviour of some routines in the local C library, so it should
867 be regarded as unreliable.
868 In any case, overflow and underflow are generally not detected
869 reliably for intermediate results.
871 Conversion among internal representations for integer, floating-point,
872 string operands is done automatically as needed.
873 For arithmetic computations, integers are used until some
874 floating-point number is introduced, after which floating-point is used.
879 yields the result 1, while
882 5 / ( [string length "abcd"] + 0.0 )
884 both yield the result 1.25.
886 String values may be used as operands of the comparison operators,
887 although the expression evaluator tries to do comparisons as integer
888 or floating-point when it can.
889 If one of the operands of a comparison is a string and the other
890 has a numeric value, the numeric operand is converted back to
891 a string using the C 'sprintf' format specifier
892 '%d' for integers and '%g' for floating-point values.
893 For example, the expressions
898 both evaluate to 1. The first comparison is done using integer
899 comparison, and the second is done using string comparison after
900 the second operand is converted to the string '18'.
902 In general it is safest to enclose an expression in braces when
903 entering it in a command: otherwise, if the expression contains
904 any white space then the Tcl interpreter will split it
905 among several arguments. For example, the command
909 results in three arguments being passed to `expr`: +$a+,
910 \+, and +$b+. In addition, if the expression isn't in braces
911 then the Tcl interpreter will perform variable and command substitution
912 immediately (it will happen in the command parser rather than in
913 the expression parser). In many cases the expression is being
914 passed to a command that will evaluate the expression later (or
915 even many times if, for example, the expression is to be used to
916 decide when to exit a loop). Usually the desired goal is to re-do
917 the variable or command substitutions each time the expression is
918 evaluated, rather than once and for all at the beginning. For example,
921 for {set i 1} $i<=10 {incr i} {...} ** WRONG **
923 is probably intended to iterate over all values of +i+ from 1 to 10.
924 After each iteration of the body of the loop, `for` will pass
925 its second argument to the expression evaluator to see whether or not
926 to continue processing. Unfortunately, in this case the value of +i+
927 in the second argument will be substituted once and for all when the
928 `for` command is parsed. If +i+ was 0 before the `for`
929 command was invoked then the second argument of `for` will be +0\<=10+
930 which will always evaluate to 1, even though +i+ eventually
931 becomes greater than 10. In the above case the loop will never
932 terminate. Instead, the expression should be placed in braces:
934 for {set i 1} {$i<=10} {incr i} {...} ** RIGHT **
936 This causes the substitution of 'i'
937 to be delayed; it will be re-done each time the expression is
938 evaluated, which is the desired result.
942 The third major way that strings are interpreted in Tcl is as lists.
943 A list is just a string with a list-like structure
944 consisting of fields separated by white space. For example, the
949 is a list with four elements or fields.
950 Lists have the same basic structure as command strings, except
951 that a newline character in a list is treated as a field separator
952 just like space or tab. Conventions for braces and quotes
953 and backslashes are the same for lists as for commands. For example,
958 is a list with three elements: +a+, +b c+, and +d e {f g h}+.
960 Whenever an element is extracted from a list, the same rules about
961 braces and quotes and backslashes are applied as for commands. Thus in
962 the example above when the third element is extracted from the list,
967 (when the field was extracted, all that happened was to strip off
968 the outermost layer of braces). Command substitution and
969 variable substitution are never
970 made on a list (at least, not by the list-processing commands; the
971 list can always be passed to the Tcl interpreter for evaluation).
973 The Tcl commands `concat`, `foreach`, `lappend`, `lindex`, `linsert`,
974 `list`, `llength`, `lrange`, `lreplace`, `lsearch`, and `lsort` allow
975 you to build lists, extract elements from them, search them, and perform
976 other list-related functions.
978 Advanced list commands include `lrepeat`, `lreverse`, `lmap`, `lassign`, `lset`.
983 A new addition to Tcl 8.5 is the ability to expand a list into separate
984 arguments. Support for this feature is also available in Jim.
986 Consider the following attempt to exec a list:
991 This will attempt to exec a command named "ls -l", which will clearly not
992 work. Typically eval and concat are required to solve this problem, however
993 it can be solved much more easily with +\{*\}+.
997 This will expand the following argument into individual elements and then evaluate
998 the resulting command.
1000 Note that the official Tcl syntax is +\{*\}+, however +\{expand\}+ is retained
1001 for backward compatibility with experimental versions of this feature.
1005 Tcl provides two commands that support string matching using regular
1006 expressions, `regexp` and `regsub`, as well as `switch -regexp` and
1009 Regular expressions may be implemented one of two ways. Either using the system's C library
1010 POSIX regular expression support, or using the built-in regular expression engine.
1011 The differences between these are described below.
1013 *NOTE* Tcl 7.x and 8.x use perl-style Advanced Regular Expressions (+ARE+).
1015 POSIX Regular Expressions
1016 ~~~~~~~~~~~~~~~~~~~~~~~~~
1017 If the system supports POSIX regular expressions, and UTF-8 support is not enabled,
1018 this support will be used by default. The type of regular expressions supported are
1019 Extended Regular Expressions (+ERE+) rather than Basic Regular Expressions (+BRE+).
1020 See REG_EXTENDED in the documentation.
1022 Using the system-supported POSIX regular expressions will typically
1023 make for the smallest code size, but some features such as UTF-8
1024 and +{backslash}w+, +{backslash}d+, +{backslash}s+ are not supported, and null characters
1025 in strings are not supported.
1027 See regex(3) and regex(7) for full details.
1029 Jim built-in Regular Expressions
1030 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1031 The Jim built-in regular expression engine may be selected with +./configure --with-jim-regexp+
1032 or it will be selected automatically if UTF-8 support is enabled.
1034 This engine supports UTF-8 as well as some +ARE+ features. The differences with both Tcl 7.x/8.x
1035 and POSIX are highlighted below.
1037 1. UTF-8 strings and patterns are both supported
1038 2. All Tcl character classes are supported (e.g. +[:alnum:]+, +[:digit:]+, +[:space:]+), but...
1039 3. Character classes apply to ASCII characters only
1040 4. Supported shorthand character classes: +{backslash}w+ = +[:alnum:]+, +{backslash}W+ = +^[:alnum:]+, +{backslash}d+ = +[:digit:],+ +{backslash}D+ = +^[:digit:],+ +{backslash}s+ = +[:space:]+, + +{backslash}S+ = +^[:space:]+
1041 5. Supported constraint escapes: +{backslash}m+ = +{backslash}<+ = start of word, +{backslash}M+ = +{backslash}>+ = end of word
1042 6. Backslash escapes may be used within regular expressions, such as +{backslash}n+ = newline, +{backslash}uNNNN+ = unicode
1043 7. Partially supported constraint escapes: +{backslash}A+ = start of string, +{backslash}Z+ = end of string
1044 8. Support for the +?+ non-greedy quantifier. e.g. +*?+
1045 9. Support for non-capturing parentheses +(?:...)+
1046 10. Jim Tcl considers that both patterns and strings end at a null character (+\x00+)
1050 Each command produces two results: a code and a string. The
1051 code indicates whether the command completed successfully or not,
1052 and the string gives additional information. The valid codes are
1053 defined in jim.h, and are:
1056 This is the normal return code, and indicates that the command completed
1057 successfully. The string gives the command's return value.
1060 Indicates that an error occurred; the string gives a message describing
1064 Indicates that the `return` command has been invoked, and that the
1065 current procedure (or top-level command or `source` command)
1066 should return immediately. The
1067 string gives the return value for the procedure or command.
1070 Indicates that the `break` command has been invoked, so the
1071 innermost loop should abort immediately. The string should always
1075 Indicates that the `continue` command has been invoked, so the
1076 innermost loop should go on to the next iteration. The string
1077 should always be empty.
1080 Indicates that a signal was caught while executing a commands.
1081 The string contains the name of the signal caught.
1082 See the `signal` and `catch` commands.
1085 Indicates that the command called the `exit` command.
1086 The string contains the exit code.
1088 Tcl programmers do not normally need to think about return codes,
1089 since +JIM_OK+ is almost always returned. If anything else is returned
1090 by a command, then the Tcl interpreter immediately stops processing
1091 commands and returns to its caller. If there are several nested
1092 invocations of the Tcl interpreter in progress, then each nested
1093 command will usually return the error to its caller, until eventually
1094 the error is reported to the top-level application code. The
1095 application will then display the error message for the user.
1097 In a few cases, some commands will handle certain `error` conditions
1098 themselves and not return them upwards. For example, the `for`
1099 command checks for the +JIM_BREAK+ code; if it occurs, then `for`
1100 stops executing the body of the loop and returns +JIM_OK+ to its
1101 caller. The `for` command also handles +JIM_CONTINUE+ codes and the
1102 procedure interpreter handles +JIM_RETURN+ codes. The `catch`
1103 command allows Tcl programs to catch errors and handle them without
1104 aborting command interpretation any further.
1106 The `info returncodes` command may be used to programmatically map between
1107 return codes and names.
1111 Tcl allows you to extend the command interface by defining
1112 procedures. A Tcl procedure can be invoked just like any other Tcl
1113 command (it has a name and it receives one or more arguments).
1114 The only difference is that its body isn't a piece of C code linked
1115 into the program; it is a string containing one or more other
1118 The `proc` command is used to create a new Tcl command procedure:
1120 +*proc* 'name arglist ?statics? body'+
1122 The new command is named +'name'+, and it replaces any existing command
1123 there may have been by that name. Whenever the new command is
1124 invoked, the contents of +'body'+ will be executed by the Tcl
1127 +'arglist'+ specifies the formal arguments to the procedure.
1128 It consists of a list, possibly empty, of the following
1129 argument specifiers:
1132 Required Argument - A simple argument name.
1135 Optional Argument - A two-element list consisting of the
1136 argument name, followed by the default value, which will
1137 be used if the corresponding argument is not supplied.
1140 Reference Argument - The caller is expected to pass the name of
1141 an existing variable. An implicit `upvar 1 'origname' 'name'` is done
1142 to make the variable available in the proc scope.
1145 Variable Argument - The special name +'args'+, which is
1146 assigned all remaining arguments (including none) as a list. The
1147 variable argument may only be specified once. Note that
1148 the syntax +args newname+ may be used to retain the special
1149 behaviour of +'args'+ with a different local name. In this case,
1150 the variable is named +'newname'+ rather than +'args'+.
1152 When the command is invoked, a local variable will be created for each of
1153 the formal arguments to the procedure; its value will be the value
1154 of corresponding argument in the invoking command or the argument's
1157 Arguments with default values need not be specified in a procedure
1158 invocation. However, there must be enough actual arguments for all
1159 required arguments, and there must not be any extra actual arguments
1160 (unless the Variable Argument is specified).
1162 Actual arguments are assigned to formal arguments as in left-to-right
1163 order with the following precedence.
1165 1. Required Arguments (including Reference Arguments)
1166 2. Optional Arguments
1167 3. Variable Argument
1169 The following example illustrates precedence. Assume a procedure declaration:
1171 proc p {{a A} args b {c C} d} {...}
1173 This procedure requires at least two arguments, but can accept an unlimited number.
1174 The following table shows how various numbers of arguments are assigned.
1175 Values marked as +-+ are assigned the default value.
1177 [width="40%",frame="topbot",options="header"]
1179 |Number of arguments|a|args|b|c|d
1187 When +'body'+ is being executed, variable names normally refer to local
1188 variables, which are created automatically when referenced and deleted
1189 when the procedure returns. One local variable is automatically created
1190 for each of the procedure's arguments. Global variables can be
1191 accessed by invoking the `global` command or via the +::+ prefix.
1195 In addition to procedure arguments, Jim procedures may declare static variables.
1196 These variables scoped to the procedure and initialised at procedure definition.
1197 Either from the static variable definition, or from the enclosing scope.
1199 Consider the following example:
1202 jim> proc a {} {a {b 2}} {
1214 The static variable +'a'+ has no initialiser, so it is initialised from
1215 the enclosing scope with the value 1. (Note that it is an error if there
1216 is no variable with the same name in the enclosing scope). However +'b'+
1217 has an initialiser, so it is initialised to 2.
1219 Unlike a local variable, the value of a static variable is retained across
1220 invocations of the procedure.
1222 See the `proc` command for information on how to define procedures
1223 and what happens when they are invoked. See also NAMESPACES.
1225 VARIABLES - SCALARS AND ARRAYS
1226 ------------------------------
1227 Tcl allows the definition of variables and the use of their values
1228 either through '$'-style variable substitution, the `set`
1229 command, or a few other mechanisms.
1231 Variables need not be declared: a new variable will automatically
1232 be created each time a new variable name is used.
1234 Tcl supports two types of variables: scalars and arrays.
1235 A scalar variable has a single value, whereas an array variable
1236 can have any number of elements, each with a name (called
1237 its 'index') and a value.
1239 Array indexes may be arbitrary strings; they need not be numeric.
1240 Parentheses are used refer to array elements in Tcl commands.
1241 For example, the command
1245 will modify the element of 'x' whose index is 'first'
1246 so that its new value is '44'.
1248 Two-dimensional arrays can be simulated in Tcl by using indexes
1249 that contain multiple concatenated values.
1250 For example, the commands
1255 set the elements of 'a' whose indexes are '2,3' and '3,6'.
1257 In general, array elements may be used anywhere in Tcl that scalar
1258 variables may be used.
1260 If an array is defined with a particular name, then there may
1261 not be a scalar variable with the same name.
1263 Similarly, if there is a scalar variable with a particular
1264 name then it is not possible to make array references to the
1267 To convert a scalar variable to an array or vice versa, remove
1268 the existing variable with the `unset` command.
1270 The `array` command provides several features for dealing
1271 with arrays, such as querying the names of all the elements of
1272 the array and converting between an array and a list.
1274 Variables may be either global or local. If a variable
1275 name is used when a procedure isn't being executed, then it
1276 automatically refers to a global variable. Variable names used
1277 within a procedure normally refer to local variables associated with that
1278 invocation of the procedure. Local variables are deleted whenever
1279 a procedure exits. Either `global` command may be used to request
1280 that a name refer to a global variable for the duration of the current
1281 procedure (this is somewhat analogous to 'extern' in C), or the variable
1282 may be explicitly scoped with the +::+ prefix. For example
1298 ARRAYS AS LISTS IN JIM
1299 ----------------------
1300 Unlike Tcl, Jim can automatically convert between a list (with an even
1301 number of elements) and an array value. This is similar to the way Tcl
1302 can convert between a string and a list.
1313 Thus `array set` is equivalent to `set` when the variable does not
1316 The reverse is also true where an array will be converted into
1319 set a(1) one; set a(2) two
1328 Tcl 8.5 introduced the dict command, and Jim Tcl has added a version
1329 of this command. Dictionaries provide efficient access to key-value
1330 pairs, just like arrays, but dictionaries are pure values. This
1331 means that you can pass them to a procedure just as a list or a
1332 string. Tcl dictionaries are therefore much more like Tcl lists,
1333 except that they represent a mapping from keys to values, rather
1334 than an ordered sequence.
1336 You can nest dictionaries, so that the value for a particular key
1337 consists of another dictionary. That way you can elegantly build
1338 complicated data structures, such as hierarchical databases. You
1339 can also combine dictionaries with other Tcl data structures. For
1340 instance, you can build a list of dictionaries that themselves
1343 Dictionaries are values that contain an efficient, order-preserving
1344 mapping from arbitrary keys to arbitrary values. Each key in the
1345 dictionary maps to a single value. They have a textual format that
1346 is exactly that of any list with an even number of elements, with
1347 each mapping in the dictionary being represented as two items in
1348 the list. When a command takes a dictionary and produces a new
1349 dictionary based on it (either returning it or writing it back into
1350 the variable that the starting dictionary was read from) the new
1351 dictionary will have the same order of keys, modulo any deleted
1352 keys and with new keys added on to the end. When a string is
1353 interpreted as a dictionary and it would otherwise have duplicate
1354 keys, only the last value for a particular key is used; the others
1355 are ignored, meaning that, "apple banana" and "apple carrot apple
1356 banana" are equivalent dictionaries (with different string
1359 Note that in Jim, arrays are implemented as dictionaries.
1360 Thus automatic conversion between lists and dictionaries applies
1361 as it does for arrays.
1363 jim> dict set a 1 one
1365 jim> dict set a 2 two
1371 jim> dict set a 3 T three
1372 1 one 2 two 3 {T three}
1374 See the `dict` command for more details.
1378 Tcl added namespaces as a mechanism avoiding name clashes, especially in applications
1379 including a number of 3rd party components. While there is less need for namespaces
1380 in Jim Tcl (which does not strive to support large applications), it is convenient to
1381 provide a subset of the support for namespaces to easy porting code from Tcl.
1383 Jim Tcl currently supports "light-weight" namespaces which should be adequate for most
1384 purposes. This feature is currently experimental. See README.namespaces for more information
1385 and the documentation of the `namespace` command.
1387 GARBAGE COLLECTION, REFERENCES, LAMBDA FUNCTION
1388 -----------------------------------------------
1389 Unlike Tcl, Jim has some sophisticated support for functional programming.
1390 These are described briefly below.
1392 More information may be found at http://wiki.tcl.tk/13847
1396 A reference can be thought of as holding a value with one level of indirection,
1397 where the value may be garbage collected when unreferenced.
1398 Consider the following example:
1400 jim> set r [ref "One String" test]
1401 <reference.<test___>.00000000000000000000>
1405 The operation `ref` creates a references to the value specified by the
1406 first argument. (The second argument is a "type" used for documentation purposes).
1408 The operation `getref` is the dereferencing operation which retrieves the value
1409 stored in the reference.
1411 jim> setref $r "New String"
1416 The operation `setref` replaces the value stored by the reference. If the old value
1417 is no longer accessible by any reference, it will eventually be automatically be garbage
1422 Normally, all values in Tcl are passed by value. As such values are copied and released
1423 automatically as necessary.
1425 With the introduction of references, it is possible to create values whose lifetime
1426 transcend their scope. To support this, case, the Jim system will periodically identify
1427 and discard objects which are no longer accessible by any reference.
1429 The `collect` command may be used to force garbage collection. Consider a reference created
1432 jim> proc f {ref value} { puts "Finaliser called for $ref,$value" }
1433 jim> set r [ref "One String" test f]
1434 <reference.<test___>.00000000000
1439 Finaliser called for <reference.<test___>.00000000000,One String
1442 Note that once the reference, 'r', was modified so that it no longer
1443 contained a reference to the value, the garbage collector discarded
1444 the value (after calling the finalizer).
1446 The finalizer for a reference may be examined or changed with the `finalize` command
1450 jim> finalize $r newf
1455 Jim provides a garbage collected `lambda` function. This is a procedure
1456 which is able to create an anonymous procedure. Consider:
1458 jim> set f [lambda {a} {{x 0}} { incr x $a }]
1465 This create an anonymous procedure (with the name stored in 'f'), with a static variable
1466 which is incremented by the supplied value and the result returned.
1468 Once the procedure name is no longer accessible, it will automatically be deleted
1469 when the garbage collector runs.
1471 The procedure may also be delete immediately by renaming it "". e.g.
1477 If Jim is built with UTF-8 support enabled (configure --enable-utf),
1478 then most string-related commands become UTF-8 aware. These include,
1479 but are not limited to, `string match`, `split`, `glob`, `scan` and
1482 UTF-8 encoding has many advantages, but one of the complications is that
1483 characters can take a variable number of bytes. Thus the addition of
1484 `string bytelength` which returns the number of bytes in a string,
1485 while `string length` returns the number of characters.
1487 If UTF-8 support is not enabled, all commands treat bytes as characters
1488 and `string bytelength` returns the same value as `string length`.
1490 Note that even if UTF-8 support is not enabled, the +{backslash}uNNNN+ and related syntax
1491 is still available to embed UTF-8 sequences.
1493 Jim Tcl supports all currently defined unicode codepoints. That is 21 bits, up to +'U+1FFFFF'.
1497 Commands such as `string match`, `lsearch -glob`, `array names` and others use string
1498 pattern matching rules. These commands support UTF-8. For example:
1500 string match a\[\ua0-\ubf\]b "a\u00a3b"
1504 +format %c+ allows a unicode codepoint to be be encoded. For example, the following will return
1505 a string with two bytes and one character. The same as +{backslash}ub5+
1509 `format` respects widths as character widths, not byte widths. For example, the following will
1510 return a string with three characters, not three bytes.
1512 format %.3s \ub5\ub6\ub7\ub8
1514 Similarly, +scan ... %c+ allows a UTF-8 to be decoded to a unicode codepoint. The following will set
1515 +'a'+ to 181 (0xb5) and +'b'+ to 65 (0x41).
1517 scan \u00b5A %c%c a b
1519 `scan %s` will also accept a character class, including unicode ranges.
1523 `string is` has *not* been extended to classify UTF-8 characters. Therefore, the following
1524 will return 0, even though the string may be considered to be alphabetic.
1526 string is alpha \ub5Test
1528 This does not affect the string classes 'ascii', 'control', 'digit', 'double', 'integer' or 'xdigit'.
1530 Case Mapping and Conversion
1531 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1532 Jim provides a simplified unicode case mapping. This means that case conversion
1533 and comparison will not increase or decrease the number of characters in a string.
1534 (Although it may change the number of bytes).
1536 `string toupper` will convert any lowercase letters to their uppercase equivalent.
1537 Any character which is not a letter or has no uppercase equivalent is left unchanged.
1538 Similarly for `string tolower` and `string totitle`.
1540 Commands which perform case insensitive matches, such as `string compare -nocase`
1541 and `lsearch -nocase` fold both strings to uppercase before comparison.
1543 Invalid UTF-8 Sequences
1544 ~~~~~~~~~~~~~~~~~~~~~~~
1545 Some UTF-8 character sequences are invalid, such as those beginning with '0xff',
1546 those which represent character sequences longer than 3 bytes (greater than U+FFFF),
1547 and those which end prematurely, such as a lone '0xc2'.
1549 In these situations, the offending bytes are treated as single characters. For example,
1550 the following returns 2.
1552 string bytelength \xff\xff
1556 If UTF-8 support is enabled, the built-in regular expression engine will be
1557 selected which supports UTF-8 strings and patterns.
1559 See REGULAR EXPRESSIONS
1563 The Tcl library provides the following built-in commands, which will
1564 be available in any application using Tcl. In addition to these
1565 built-in commands, there may be additional commands defined by each
1566 application, plus commands defined as Tcl procedures.
1568 In the command syntax descriptions below, words in +*boldface*+ are
1569 literals that you type verbatim to Tcl.
1571 Words in +'italics'+ are meta-symbols; they serve as names for any of
1572 a range of values that you can type.
1574 Optional arguments or groups of arguments are indicated by enclosing them
1575 in +?question-marks?+.
1577 Ellipses (+\...+) indicate that any number of additional
1578 arguments or groups of arguments may appear, in the same format
1579 as the preceding argument(s).
1590 Delivers the +SIGALRM+ signal to the process after the given
1591 number of seconds. If the platform supports 'ualarm(3)' then
1592 the argument may be a floating point value. Otherwise it must
1595 Note that unless a signal handler for +SIGALRM+ has been installed
1596 (see `signal`), the process will exit on this signal.
1600 +*alias* 'name args\...'+
1602 Creates a single word alias (command) for one or more words. For example,
1603 the following creates an alias for the command `info exists`.
1610 `alias` returns +'name'+, allowing it to be used with `local`.
1612 See also `proc`, `curry`, `lambda`, `local`, `info alias`, `exists -alias`
1616 +*append* 'varName value ?value value ...?'+
1618 Append all of the +'value'+ arguments to the current value
1619 of variable +'varName'+. If +'varName'+ doesn't exist,
1620 it is given a value equal to the concatenation of all the
1621 +'value'+ arguments.
1623 This command provides an efficient way to build up long
1624 variables incrementally.
1625 For example, "`append a $b`" is much more efficient than
1626 "`set a $a$b`" if +$a+ is long.
1630 +*apply* 'lambdaExpr ?arg1 arg2 \...?'+
1632 The command `apply` provides for anonymous procedure calls,
1633 similar to `lambda`, but without command name being created, even temporarily.
1635 The function +'lambdaExpr'+ is a two element list +{args body}+
1636 or a three element list +{args body namespace}+. The first element
1637 args specifies the formal arguments, in the same form as the `proc` and `lambda` commands.
1641 +*array* 'option arrayName ?arg\...?'+
1643 This command performs one of several operations on the
1644 variable given by +'arrayName'+.
1646 Note that in general, if the named array does not exist, the +'array'+ command behaves
1647 as though the array exists but is empty.
1649 The +'option'+ argument determines what action is carried out by the
1650 command. The legal +'options'+ (which may be abbreviated) are:
1652 +*array exists* 'arrayName'+::
1653 Returns 1 if arrayName is an array variable, 0 if there is
1654 no variable by that name. This command is essentially
1655 identical to `info exists`
1657 +*array get* 'arrayName ?pattern?'+::
1658 Returns a list containing pairs of elements. The first
1659 element in each pair is the name of an element in arrayName
1660 and the second element of each pair is the value of the
1661 array element. The order of the pairs is undefined. If
1662 pattern is not specified, then all of the elements of the
1663 array are included in the result. If pattern is specified,
1664 then only those elements whose names match pattern (using
1665 the matching rules of string match) are included. If arrayName
1666 isn't the name of an array variable, or if the array contains
1667 no elements, then an empty list is returned.
1669 +*array names* 'arrayName ?pattern?'+::
1670 Returns a list containing the names of all of the elements
1671 in the array that match pattern. If pattern is omitted then
1672 the command returns all of the element names in the array.
1673 If pattern is specified, then only those elements whose
1674 names match pattern (using the matching rules of string
1675 match) are included. If there are no (matching) elements
1676 in the array, or if arrayName isn't the name of an array
1677 variable, then an empty string is returned.
1679 +*array set* 'arrayName list'+::
1680 Sets the values of one or more elements in arrayName. list
1681 must have a form like that returned by array get, consisting
1682 of an even number of elements. Each odd-numbered element
1683 in list is treated as an element name within arrayName, and
1684 the following element in list is used as a new value for
1685 that array element. If the variable arrayName does not
1686 already exist and list is empty, arrayName is created with
1687 an empty array value.
1689 +*array size* 'arrayName'+::
1690 Returns the number of elements in the array. If arrayName
1691 isn't the name of an array then 0 is returned.
1693 +*array unset* 'arrayName ?pattern?'+::
1694 Unsets all of the elements in the array that match pattern
1695 (using the matching rules of string match). If arrayName
1696 isn't the name of an array variable or there are no matching
1697 elements in the array, no error will be raised. If pattern
1698 is omitted and arrayName is an array variable, then the
1699 command unsets the entire array. The command always returns
1706 This command may be invoked only inside the body of a loop command
1707 such as `for` or `foreach` or `while`. It returns a +JIM_BREAK+ code
1708 to signal the innermost containing loop command to return immediately.
1712 +*case* 'string' ?in? 'patList body ?patList body ...?'+
1714 +*case* 'string' ?in? {'patList body ?patList body ...?'}+
1716 *Note* that the `switch` command should generally be preferred unless compatibility
1717 with Tcl 6.x is desired.
1719 Match +'string'+ against each of the +'patList'+ arguments
1720 in order. If one matches, then evaluate the following +'body'+ argument
1721 by passing it recursively to the Tcl interpreter, and return the result
1722 of that evaluation. Each +'patList'+ argument consists of a single
1723 pattern or list of patterns. Each pattern may contain any of the wild-cards
1724 described under `string match`.
1726 If a +'patList'+ argument is +default+, the corresponding body will be
1727 evaluated if no +'patList'+ matches +'string'+. If no +'patList'+ argument
1728 matches +'string'+ and no default is given, then the `case` command returns
1731 Two syntaxes are provided.
1733 The first uses a separate argument for each of the patterns and commands;
1734 this form is convenient if substitutions are desired on some of the
1735 patterns or commands.
1737 The second form places all of the patterns and commands together into
1738 a single argument; the argument must have proper list structure, with
1739 the elements of the list being the patterns and commands.
1741 The second form makes it easy to construct multi-line case commands,
1742 since the braces around the whole list make it unnecessary to include a
1743 backslash at the end of each line.
1745 Since the +'patList'+ arguments are in braces in the second form,
1746 no command or variable substitutions are performed on them; this makes
1747 the behaviour of the second form different than the first form in some
1750 Below are some examples of `case` commands:
1752 case abc in {a b} {format 1} default {format 2} a* {format 3}
1762 will return '1', and
1777 +*catch* ?-?no?'code \...'? ?--? 'command ?resultVarName? ?optionsVarName?'+
1779 The `catch` command may be used to prevent errors from aborting
1780 command interpretation. `catch` evaluates +'command'+, and returns a
1781 +JIM_OK+ code, regardless of any errors that might occur while
1782 executing +'command'+ (with the possible exception of +JIM_SIGNAL+ -
1785 The return value from `catch` is a decimal string giving the code
1786 returned by the Tcl interpreter after executing +'command'+. This
1787 will be '0' (+JIM_OK+) if there were no errors in +'command'+; otherwise
1788 it will have a non-zero value corresponding to one of the exceptional
1789 return codes (see jim.h for the definitions of code values, or the
1790 `info returncodes` command).
1792 If the +'resultVarName'+ argument is given, then it gives the name
1793 of a variable; `catch` will set the value of the variable to the
1794 string returned from +'command'+ (either a result or an error message).
1796 If the +'optionsVarName'+ argument is given, then it gives the name
1797 of a variable; `catch` will set the value of the variable to a
1798 dictionary. For any return code other than +JIM_RETURN+, the value
1799 for the key +-code+ will be set to the return code. For +JIM_RETURN+
1800 it will be set to the code given in `return -code`. Additionally,
1801 for the return code +JIM_ERR+, the value of the key +-errorinfo+
1802 will contain the current stack trace (the same result as `info stacktrace`),
1803 the value of the key +-errorcode+ will contain the
1804 same value as the global variable $::errorCode, and the value of
1805 the key +-level+ will be the current return level (see `return -level`).
1806 This can be useful to rethrow an error:
1808 if {[catch {...} msg opts]} {
1809 ...maybe do something with the error...
1811 return {*}$opts $msg
1814 Normally `catch` will +'not'+ catch any of the codes +JIM_EXIT+, +JIM_EVAL+ or +JIM_SIGNAL+.
1815 The set of codes which will be caught may be modified by specifying the one more codes before
1818 e.g. To catch +JIM_EXIT+ but not +JIM_BREAK+ or +JIM_CONTINUE+
1820 catch -exit -nobreak -nocontinue -- { ... }
1822 The use of +--+ is optional. It signifies that no more return code options follow.
1824 Note that if a signal marked as `signal handle` is caught with `catch -signal`, the return value
1825 (stored in +'resultVarName'+) is name of the signal caught.
1831 Change the current working directory to +'dirName'+.
1833 Returns an empty string.
1835 This command can potentially be disruptive to an application, so it may
1836 be removed in some applications.
1841 Returns the current time as seconds since the epoch.
1844 Returns the current time in `clicks'.
1846 +*clock microseconds*+::
1847 Returns the current time in microseconds.
1849 +*clock milliseconds*+::
1850 Returns the current time in milliseconds.
1852 +*clock format* 'seconds' ?*-format* 'format?'+::
1853 Format the given time (seconds since the epoch) according to the given
1854 format. See strftime(3) for supported formats.
1855 If no format is supplied, "%c" is used.
1857 +*clock scan* 'str' *-format* 'format'+::
1858 Scan the given time string using the given format string.
1859 See strptime(3) for supported formats.
1867 Closes the file given by +'fileId'+.
1868 +'fileId'+ must be the return value from a previous invocation
1869 of the `open` command; after this command, it should not be
1876 Normally reference garbage collection is automatically performed periodically.
1877 However it may be run immediately with the `collect` command.
1879 See GARBAGE COLLECTION, REFERENCES, LAMBDA FUNCTION for more detail.
1883 +*concat* 'arg ?arg \...?'+
1885 This command treats each argument as a list and concatenates them
1886 into a single list. It permits any number of arguments. For example,
1889 concat a b {c d e} {f {g h}}
1901 This command may be invoked only inside the body of a loop command such
1902 as `for` or `foreach` or `while`. It returns a +JIM_CONTINUE+ code to
1903 signal the innermost containing loop command to skip the remainder of
1904 the loop's body but continue with the next iteration of the loop.
1908 +*alias* 'args\...'+
1910 Similar to `alias` except it creates an anonymous procedure (lambda) instead of
1913 the following creates a local, unnamed alias for the command `info exists`.
1915 set e [local curry info exists]
1920 `curry` returns the name of the procedure.
1922 See also `proc`, `alias`, `lambda`, `local`.
1926 +*dict* 'option ?arg\...?'+
1928 Performs one of several operations on dictionary values.
1930 The +'option'+ argument determines what action is carried out by the
1931 command. The legal +'options'+ are:
1933 +*dict create* '?key value \...?'+::
1934 Create and return a new dictionary value that contains each of
1935 the key/value mappings listed as arguments (keys and values
1936 alternating, with each key being followed by its associated
1939 +*dict exists* 'dictionary key ?key \...?'+::
1940 Returns a boolean value indicating whether the given key (or path
1941 of keys through a set of nested dictionaries) exists in the given
1942 dictionary value. This returns a true value exactly when `dict get`
1943 on that path will succeed.
1945 +*dict get* 'dictionary ?key \...?'+::
1946 Given a dictionary value (first argument) and a key (second argument),
1947 this will retrieve the value for that key. Where several keys are
1948 supplied, the behaviour of the command shall be as if the result
1949 of "`dict get $dictVal $key`" was passed as the first argument to
1950 dict get with the remaining arguments as second (and possibly
1951 subsequent) arguments. This facilitates lookups in nested dictionaries.
1952 If no keys are provided, dict would return a list containing pairs
1953 of elements in a manner similar to array get. That is, the first
1954 element of each pair would be the key and the second element would
1955 be the value for that key. It is an error to attempt to retrieve
1956 a value for a key that is not present in the dictionary.
1958 +*dict keys* 'dictionary ?pattern?'+::
1959 Returns a list of the keys in the dictionary.
1960 If pattern is specified, then only those keys whose
1961 names match +'pattern'+ (using the matching rules of string
1962 match) are included.
1964 +*dict merge* ?'dictionary \...'?+::
1965 Return a dictionary that contains the contents of each of the
1966 +'dictionary'+ arguments. Where two (or more) dictionaries
1967 contain a mapping for the same key, the resulting dictionary
1968 maps that key to the value according to the last dictionary on
1969 the command line containing a mapping for that key.
1971 +*dict set* 'dictionaryName key ?key \...? value'+::
1972 This operation takes the +'name'+ of a variable containing a dictionary
1973 value and places an updated dictionary value in that variable
1974 containing a mapping from the given key to the given value. When
1975 multiple keys are present, this operation creates or updates a chain
1976 of nested dictionaries.
1978 +*dict size* 'dictionary'+::
1979 Return the number of key/value mappings in the given dictionary value.
1981 +*dict unset* 'dictionaryName key ?key \...? value'+::
1982 This operation (the companion to `dict set`) takes the name of a
1983 variable containing a dictionary value and places an updated
1984 dictionary value in that variable that does not contain a mapping
1985 for the given key. Where multiple keys are present, this describes
1986 a path through nested dictionaries to the mapping to remove. At
1987 least one key must be specified, but the last key on the key-path
1988 need not exist. All other components on the path must exist.
1990 +*dict with* 'dictionaryName key ?key \...? script'+::
1991 Execute the Tcl script in +'script'+ with the value for each
1992 key in +'dictionaryName'+ mapped to a variable with the same
1993 name. Where one or more keys are given, these indicate a chain
1994 of nested dictionaries, with the innermost dictionary being the
1995 one opened out for the execution of body. Making +'dictionaryName'+
1996 unreadable will make the updates to the dictionary be discarded,
1997 and this also happens if the contents of +'dictionaryName'+ are
1998 adjusted so that the chain of dictionaries no longer exists.
1999 The result of `dict with` is (unless some kind of error occurs)
2000 the result of the evaluation of body.
2002 The variables are mapped in the scope enclosing the `dict with`;
2003 it is recommended that this command only be used in a local
2004 scope (procedure). Because of this, the variables set by
2005 `dict with` will continue to exist after the command finishes (unless
2006 explicitly unset). Note that changes to the contents of +'dictionaryName'+
2007 only happen when +'script'+ terminates.
2009 +*dict for, values, incr, append, lappend, update, info, replace*+ to be documented...
2013 +*env* '?name? ?default?'+
2015 If +'name'+ is supplied, returns the value of +'name'+ from the initial
2016 environment (see getenv(3)). An error is returned if +'name'+ does not
2017 exist in the environment, unless +'default'+ is supplied - in which case
2018 that value is returned instead.
2020 If no arguments are supplied, returns a list of all environment variables
2021 and their values as +{name value \...}+
2023 See also the global variable +::env+
2031 Returns 1 if an end-of-file condition has occurred on +'fileId'+,
2034 +'fileId'+ must have been the return value from a previous call to `open`,
2035 or it may be +stdin+, +stdout+, or +stderr+ to refer to one of the
2036 standard I/O channels.
2040 +*error* 'message ?stacktrace?'+
2042 Returns a +JIM_ERR+ code, which causes command interpretation to be
2043 unwound. +'message'+ is a string that is returned to the application
2044 to indicate what went wrong.
2046 If the +'stacktrace'+ argument is provided and is non-empty,
2047 it is used to initialize the stacktrace.
2049 This feature is most useful in conjunction with the `catch` command:
2050 if a caught error cannot be handled successfully, +'stacktrace'+ can be used
2051 to return a stack trace reflecting the original point of occurrence
2056 error $errMsg [info stacktrace]
2058 See also `errorInfo`, `info stacktrace`, `catch` and `return`
2062 +*errorInfo* 'error ?stacktrace?'+
2064 Returns a human-readable representation of the given error message and stack trace.
2067 if {[catch {...} error]} {
2068 puts stderr [errorInfo $error [info stacktrace]]
2076 +*eval* 'arg ?arg\...?'+
2078 `eval` takes one or more arguments, which together comprise a Tcl
2079 command (or collection of Tcl commands separated by newlines in the
2080 usual way). `eval` concatenates all its arguments in the same
2081 fashion as the `concat` command, passes the concatenated string to the
2082 Tcl interpreter recursively, and returns the result of that
2083 evaluation (or any error generated by it).
2087 +*exec* 'arg ?arg\...?'+
2089 This command treats its arguments as the specification
2090 of one or more UNIX commands to execute as subprocesses.
2091 The commands take the form of a standard shell pipeline;
2092 +|+ arguments separate commands in the
2093 pipeline and cause standard output of the preceding command
2094 to be piped into standard input of the next command (or +|&+ for
2095 both standard output and standard error).
2097 Under normal conditions the result of the `exec` command
2098 consists of the standard output produced by the last command
2099 in the pipeline followed by the standard error output.
2101 If any of the commands writes to its standard error file,
2102 then this will be included in the result after the standard output
2103 of the last command.
2105 Note that unlike Tcl, data written to standard error does not cause
2106 `exec` to return an error.
2108 If any of the commands in the pipeline exit abnormally or
2109 are killed or suspended, then `exec` will return an error.
2110 If no standard error output was produced, or is redirected,
2111 the error message will include the normal result, as above,
2112 followed by error messages describing the abnormal terminations.
2114 If any standard error output was produced, these abnormal termination
2115 messages are suppressed.
2117 If the last character of the result or error message
2118 is a newline then that character is deleted from the result
2119 or error message for consistency with normal
2122 An +'arg'+ may have one of the following special forms:
2125 The standard output of the last command in the pipeline
2126 is redirected to the file. In this situation `exec`
2127 will normally return an empty string.
2130 As above, but append to the file.
2133 The standard output of the last command in the pipeline is
2134 redirected to the given (writable) file descriptor (e.g. stdout,
2135 stderr, or the result of `open`). In this situation `exec`
2136 will normally return an empty string.
2139 The standard error of the last command in the pipeline
2140 is redirected to the file.
2143 As above, but append to the file.
2146 The standard error of the last command in the pipeline is
2147 redirected to the given (writable) file descriptor.
2150 The standard error of the last command in the pipeline is
2151 redirected to the same file descriptor as the standard output.
2154 Both the standard output and standard error of the last command
2155 in the pipeline is redirected to the file.
2158 As above, but append to the file.
2161 The standard input of the first command in the pipeline
2162 is taken from the file.
2165 The standard input of the first command is taken as the
2166 given immediate value.
2169 The standard input of the first command in the pipeline
2170 is taken from the given (readable) file descriptor.
2172 If there is no redirection of standard input, standard error
2173 or standard output, these are connected to the corresponding
2174 input or output of the application.
2176 If the last +'arg'+ is +&+ then the command will be
2177 executed in background.
2178 In this case the standard output from the last command
2179 in the pipeline will
2180 go to the application's standard output unless
2181 redirected in the command, and error output from all
2182 the commands in the pipeline will go to the application's
2183 standard error file. The return value of exec in this case
2184 is a list of process ids (pids) in the pipeline.
2186 Each +'arg'+ becomes one word for a command, except for
2187 +|+, +<+, +<<+, +>+, and +&+ arguments, and the
2188 arguments that follow +<+, +<<+, and +>+.
2190 The first word in each command is taken as the command name;
2191 the directories in the PATH environment variable are searched for
2192 an executable by the given name.
2194 No `glob` expansion or other shell-like substitutions
2195 are performed on the arguments to commands.
2197 If the command fails, the global $::errorCode (and the -errorcode
2198 option in `catch`) will be set to a list, as follows:
2200 +*CHILDKILLED* 'pid sigName msg'+::
2201 This format is used when a child process has been killed
2202 because of a signal. The pid element will be the process's
2203 identifier (in decimal). The sigName element will be the
2204 symbolic name of the signal that caused the process to
2205 terminate; it will be one of the names from the include
2206 file signal.h, such as SIGPIPE. The msg element will be a
2207 short human-readable message describing the signal, such
2208 as "write on pipe with no readers" for SIGPIPE.
2210 +*CHILDSUSP* 'pid sigName msg'+::
2211 This format is used when a child process has been suspended
2212 because of a signal. The pid element will be the process's
2213 identifier, in decimal. The sigName element will be the
2214 symbolic name of the signal that caused the process to
2215 suspend; this will be one of the names from the include
2216 file signal.h, such as SIGTTIN. The msg element will be a
2217 short human-readable message describing the signal, such
2218 as "background tty read" for SIGTTIN.
2220 +*CHILDSTATUS* 'pid code'+::
2221 This format is used when a child process has exited with a
2222 non-zero exit status. The pid element will be the process's
2223 identifier (in decimal) and the code element will be the
2224 exit code returned by the process (also in decimal).
2226 The environment for the executed command is set from $::env (unless
2227 this variable is unset, in which case the original environment is used).
2231 +*exists ?-var|-proc|-command|-alias?* 'name'+
2233 Checks the existence of the given variable, procedure, command
2234 or alias respectively and returns 1 if it exists or 0 if not. This command
2235 provides a more simplified/convenient version of `info exists`,
2236 `info procs` and `info commands`.
2238 If the type is omitted, a type of '-var' is used. The type may be abbreviated.
2242 +*exit* '?returnCode?'+
2244 Terminate the process, returning +'returnCode'+ to the
2245 parent as the exit status.
2247 If +'returnCode'+ isn't specified then it defaults
2250 Note that exit can be caught with `catch`.
2256 Calls the expression processor to evaluate +'arg'+, and returns
2257 the result as a string. See the section EXPRESSIONS above.
2259 Note that Jim supports a shorthand syntax for `expr` as +$(\...)+
2260 The following two are identical.
2262 set x [expr {3 * 2 + 1}]
2267 +*file* 'option name ?arg\...?'+
2269 Operate on a file or a file name. +'name'+ is the name of a file.
2271 +'option'+ indicates what to do with the file name. Any unique
2272 abbreviation for +'option'+ is acceptable. The valid options are:
2274 +*file atime* 'name'+::
2275 Return a decimal string giving the time at which file +'name'+
2276 was last accessed. The time is measured in the standard UNIX
2277 fashion as seconds from a fixed starting time (often January 1, 1970).
2278 If the file doesn't exist or its access time cannot be queried then an
2281 +*file copy ?-force?* 'source target'+::
2282 Copies file +'source'+ to file +'target'+. The source file must exist.
2283 The target file must not exist, unless +-force+ is specified.
2285 +*file delete ?-force? ?--?* 'name\...'+::
2286 Deletes file or directory +'name'+. If the file or directory doesn't exist, nothing happens.
2287 If it can't be deleted, an error is generated. Non-empty directories will not be deleted
2288 unless the +-force+ options is given. In this case no errors will be generated, even
2289 if the file/directory can't be deleted. Use +'--'+ if there is any possibility of
2290 the first name being +'-force'+.
2292 +*file dirname* 'name'+::
2293 Return all of the characters in +'name'+ up to but not including
2294 the last slash character. If there are no slashes in +'name'+
2295 then return +.+ (a single dot). If the last slash in +'name'+ is its first
2296 character, then return +/+.
2298 +*file executable* 'name'+::
2299 Return '1' if file +'name'+ is executable by
2300 the current user, '0' otherwise.
2302 +*file exists* 'name'+::
2303 Return '1' if file +'name'+ exists and the current user has
2304 search privileges for the directories leading to it, '0' otherwise.
2306 +*file extension* 'name'+::
2307 Return all of the characters in +'name'+ after and including the
2308 last dot in +'name'+. If there is no dot in +'name'+ then return
2311 +*file isdirectory* 'name'+::
2312 Return '1' if file +'name'+ is a directory,
2315 +*file isfile* 'name'+::
2316 Return '1' if file +'name'+ is a regular file,
2319 +*file join* 'arg\...'+::
2320 Joins multiple path components. Note that if any components is
2321 an absolute path, the preceding components are ignored.
2322 Thus +"`file` join /tmp /root"+ returns +"/root"+.
2324 +*file link* ?*-hard|-symbolic*? 'newname target'+::
2325 Creates a hard link (default) or symbolic link from +'newname'+ to +'target'+.
2326 Note that the sense of this command is the opposite of `file rename` and `file copy`
2327 and also of `ln`, but this is compatible with Tcl.
2328 An error is returned if +'target'+ doesn't exist or +'newname'+ already exists.
2330 +*file lstat* 'name varName'+::
2331 Same as 'stat' option (see below) except uses the +'lstat'+
2332 kernel call instead of +'stat'+. This means that if +'name'+
2333 refers to a symbolic link the information returned in +'varName'+
2334 is for the link rather than the file it refers to. On systems that
2335 don't support symbolic links this option behaves exactly the same
2336 as the 'stat' option.
2338 +*file mkdir* 'dir1 ?dir2\...?'+::
2339 Creates each directory specified. For each pathname +'dir'+ specified,
2340 this command will create all non-existing parent directories
2341 as well as +'dir'+ itself. If an existing directory is specified,
2342 then no action is taken and no error is returned. Trying to
2343 overwrite an existing file with a directory will result in an
2344 error. Arguments are processed in the order specified, halting
2345 at the first error, if any.
2347 +*file mtime* 'name ?time?'+::
2348 Return a decimal string giving the time at which file +'name'+
2349 was last modified. The time is measured in the standard UNIX
2350 fashion as seconds from a fixed starting time (often January 1, 1970).
2351 If the file doesn't exist or its modified time cannot be queried then an
2352 error is generated. If +'time'+ is given, sets the modification time
2353 of the file to the given value.
2355 +*file normalize* 'name'+::
2356 Return the normalized path of +'name'+. See 'realpath(3)'.
2358 +*file owned* 'name'+::
2359 Return '1' if file +'name'+ is owned by the current user,
2362 +*file readable* 'name'+::
2363 Return '1' if file +'name'+ is readable by
2364 the current user, '0' otherwise.
2366 +*file readlink* 'name'+::
2367 Returns the value of the symbolic link given by +'name'+ (i.e. the
2368 name of the file it points to). If
2369 +'name'+ isn't a symbolic link or its value cannot be read, then
2370 an error is returned. On systems that don't support symbolic links
2371 this option is undefined.
2373 +*file rename* ?*-force*? 'oldname' 'newname'+::
2374 Renames the file from the old name to the new name.
2375 If +'newname'+ already exists, an error is returned unless +'-force'+ is
2378 +*file rootname* 'name'+::
2379 Return all of the characters in +'name'+ up to but not including
2380 the last '.' character in the name. If +'name'+ doesn't contain
2381 a dot, then return +'name'+.
2383 +*file size* 'name'+::
2384 Return a decimal string giving the size of file +'name'+ in bytes.
2385 If the file doesn't exist or its size cannot be queried then an
2388 +*file stat* 'name ?varName?'+::
2389 Invoke the 'stat' kernel call on +'name'+, and return the result
2390 as a dictionary with the following keys: 'atime',
2391 'ctime', 'dev', 'gid', 'ino', 'mode', 'mtime',
2392 'nlink', 'size', 'type', 'uid'.
2393 Each element except 'type' is a decimal string with the value of
2394 the corresponding field from the 'stat' return structure; see the
2395 manual entry for 'stat' for details on the meanings of the values.
2396 The 'type' element gives the type of the file in the same form
2397 returned by the command `file type`.
2398 If +'varName'+ is specified, it is taken to be the name of an array
2399 variable and the values are also stored into the array.
2401 +*file tail* 'name'+::
2402 Return all of the characters in +'name'+ after the last slash.
2403 If +'name'+ contains no slashes then return +'name'+.
2405 +*file tempfile* '?template?'+::
2406 Creates and returns the name of a unique temporary file. If +'template'+ is omitted, a
2407 default template will be used to place the file in /tmp. See 'mkstemp(3)' for
2408 the format of the template and security concerns.
2410 +*file type* 'name'+::
2411 Returns a string giving the type of file +'name'+, which will be
2412 one of +file+, +directory+, +characterSpecial+,
2413 +blockSpecial+, +fifo+, +link+, or +socket+.
2415 +*file writable* 'name'+::
2416 Return '1' if file +'name'+ is writable by
2417 the current user, '0' otherwise.
2419 The `file` commands that return 0/1 results are often used in
2420 conditional or looping commands, for example:
2422 if {![file exists foo]} {
2423 error {bad file name}
2430 +*finalize* 'reference ?command?'+
2432 If +'command'+ is omitted, returns the finalizer command for the given reference.
2434 Otherwise, sets a new finalizer command for the given reference. +'command'+ may be
2435 the empty string to remove the current finalizer.
2437 The reference must be a valid reference create with the `ref`
2440 See GARBAGE COLLECTION, REFERENCES, LAMBDA FUNCTION for more detail.
2448 Flushes any output that has been buffered for +'fileId'+. +'fileId'+ must
2449 have been the return value from a previous call to `open`, or it may be
2450 +stdout+ or +stderr+ to access one of the standard I/O streams; it must
2451 refer to a file that was opened for writing. This command returns an
2456 +*for* 'start test next body'+
2458 `for` is a looping command, similar in structure to the C `for` statement.
2459 The +'start'+, +'next'+, and +'body'+ arguments must be Tcl command strings,
2460 and +'test'+ is an expression string.
2462 The `for` command first invokes the Tcl interpreter to execute +'start'+.
2463 Then it repeatedly evaluates +'test'+ as an expression; if the result is
2464 non-zero it invokes the Tcl interpreter on +'body'+, then invokes the Tcl
2465 interpreter on +'next'+, then repeats the loop. The command terminates
2466 when +'test'+ evaluates to 0.
2468 If a `continue` command is invoked within +'body'+ then any remaining
2469 commands in the current execution of +'body'+ are skipped; processing
2470 continues by invoking the Tcl interpreter on +'next'+, then evaluating
2471 +'test'+, and so on.
2473 If a `break` command is invoked within +'body'+ or +'next'+, then the `for`
2474 command will return immediately.
2476 The operation of `break` and `continue` are similar to the corresponding
2479 `for` returns an empty string.
2483 +*foreach* 'varName list body'+
2485 +*foreach* 'varList list ?varList2 list2 \...? body'+
2487 In this command, +'varName'+ is the name of a variable, +'list'+
2488 is a list of values to assign to +'varName'+, and +'body'+ is a
2489 collection of Tcl commands.
2491 For each field in +'list'+ (in order from left to right), `foreach` assigns
2492 the contents of the field to +'varName'+ (as if the `lindex` command
2493 had been used to extract the field), then calls the Tcl interpreter to
2496 If instead of being a simple name, +'varList'+ is used, multiple assignments
2497 are made each time through the loop, one for each element of +'varList'+.
2499 For example, if there are two elements in +'varList'+ and six elements in
2500 the list, the loop will be executed three times.
2502 If the length of the list doesn't evenly divide by the number of elements
2503 in +'varList'+, the value of the remaining variables in the last iteration
2504 of the loop are undefined.
2506 The `break` and `continue` statements may be invoked inside +'body'+,
2507 with the same effect as in the `for` command.
2509 `foreach` returns an empty string.
2513 +*format* 'formatString ?arg \...?'+
2515 This command generates a formatted string in the same way as the
2516 C 'sprintf' procedure (it uses 'sprintf' in its
2517 implementation). +'formatString'+ indicates how to format
2518 the result, using +%+ fields as in 'sprintf', and the additional
2519 arguments, if any, provide values to be substituted into the result.
2521 All of the 'sprintf' options are valid; see the 'sprintf'
2522 man page for details. Each +'arg'+ must match the expected type
2523 from the +%+ field in +'formatString'+; the `format` command
2524 converts each argument to the correct type (floating, integer, etc.)
2525 before passing it to 'sprintf' for formatting.
2527 The only unusual conversion is for +%c+; in this case the argument
2528 must be a decimal string, which will then be converted to the corresponding
2529 ASCII (or UTF-8) character value.
2531 In addition, Jim Tcl provides basic support for conversion to binary with +%b+.
2533 `format` does backslash substitution on its +'formatString'+
2534 argument, so backslash sequences in +'formatString'+ will be handled
2535 correctly even if the argument is in braces.
2537 The return value from `format` is the formatted string.
2541 +*getref* 'reference'+
2543 Returns the string associated with +'reference'+. The reference must
2544 be a valid reference create with the `ref` command.
2546 See GARBAGE COLLECTION, REFERENCES, LAMBDA FUNCTION for more detail.
2550 +*gets* 'fileId ?varName?'+
2552 +'fileId' *gets* '?varName?'+
2554 Reads the next line from the file given by +'fileId'+ and discards
2555 the terminating newline character.
2557 If +'varName'+ is specified, then the line is placed in the variable
2558 by that name and the return value is a count of the number of characters
2559 read (not including the newline).
2561 If the end of the file is reached before reading
2562 any characters then -1 is returned and +'varName'+ is set to an
2565 If +'varName'+ is not specified then the return value will be
2566 the line (minus the newline character) or an empty string if
2567 the end of the file is reached before reading any characters.
2569 An empty string will also be returned if a line contains no characters
2570 except the newline, so `eof` may have to be used to determine
2571 what really happened.
2573 If the last character in the file is not a newline character, then
2574 `gets` behaves as if there were an additional newline character
2575 at the end of the file.
2577 +'fileId'+ must be +stdin+ or the return value from a previous
2578 call to `open`; it must refer to a file that was opened
2583 +*glob* ?*-nocomplain*? ?*-directory* 'dir'? ?*-tails*? ?*--*? 'pattern ?pattern \...?'+
2585 This command performs filename globbing, using csh rules. The returned
2586 value from `glob` is the list of expanded filenames.
2588 If +-nocomplain+ is specified as the first argument then an empty
2589 list may be returned; otherwise an error is returned if the expanded
2590 list is empty. The +-nocomplain+ argument must be provided
2591 exactly: an abbreviation will not be accepted.
2593 If +-directory+ is given, the +'dir'+ is understood to contain a
2594 directory name to search in. This allows globbing inside directories
2595 whose names may contain glob-sensitive characters. The returned names
2596 include the directory name unless +'-tails'+ is specified.
2598 If +'-tails'+ is specified, along with +-directory+, the returned names
2599 are relative to the given directory.
2604 +*global* 'varName ?varName \...?'+
2606 This command is ignored unless a Tcl procedure is being interpreted.
2607 If so, then it declares each given +'varName'+ to be a global variable
2608 rather than a local one. For the duration of the current procedure
2609 (and only while executing in the current procedure), any reference to
2610 +'varName'+ will be bound to a global variable instead
2613 An alternative to using `global` is to use the +::+ prefix
2614 to explicitly name a variable in the global scope.
2618 +*if* 'expr1' ?*then*? 'body1' *elseif* 'expr2' ?*then*? 'body2' *elseif* \... ?*else*? ?'bodyN'?+
2620 The `if` command evaluates +'expr1'+ as an expression (in the same way
2621 that `expr` evaluates its argument). The value of the expression must
2622 be numeric; if it is non-zero then +'body1'+ is executed by passing it to
2623 the Tcl interpreter.
2625 Otherwise +'expr2'+ is evaluated as an expression and if it is non-zero
2626 then +'body2'+ is executed, and so on.
2628 If none of the expressions evaluates to non-zero then +'bodyN'+ is executed.
2630 The +then+ and +else+ arguments are optional "noise words" to make the
2631 command easier to read.
2633 There may be any number of +elseif+ clauses, including zero. +'bodyN'+
2634 may also be omitted as long as +else+ is omitted too.
2636 The return value from the command is the result of the body script that
2637 was executed, or an empty string if none of the expressions was non-zero
2638 and there was no +'bodyN'+.
2642 +*incr* 'varName ?increment?'+
2644 Increment the value stored in the variable whose name is +'varName'+.
2645 The value of the variable must be integral.
2647 If +'increment'+ is supplied then its value (which must be an
2648 integer) is added to the value of variable +'varName'+; otherwise
2649 1 is added to +'varName'+.
2651 The new value is stored as a decimal string in variable +'varName'+
2652 and also returned as result.
2654 If the variable does not exist, the variable is implicitly created
2655 and set to +0+ first.
2660 +*info* 'option ?arg\...?'+::
2662 Provide information about various internals to the Tcl interpreter.
2663 The legal +'option'+'s (which may be abbreviated) are:
2665 +*info args* 'procname'+::
2666 Returns a list containing the names of the arguments to procedure
2667 +'procname'+, in order. +'procname'+ must be the name of a
2668 Tcl command procedure.
2670 +*info alias* 'command'+::
2671 +'command'+ must be an alias created with `alias`. In which case the target
2672 command and arguments, as passed to `alias` are returned. See `exists -alias`
2674 +*info body* 'procname'+::
2675 Returns the body of procedure +'procname'+. +'procname'+ must be
2676 the name of a Tcl command procedure.
2679 Returns a list of all open file handles from `open` or `socket`
2681 +*info commands* ?'pattern'?+::
2682 If +'pattern'+ isn't specified, returns a list of names of all the
2683 Tcl commands, including both the built-in commands written in C and
2684 the command procedures defined using the `proc` command.
2685 If +'pattern'+ is specified, only those names matching +'pattern'+
2686 are returned. Matching is determined using the same rules as for
2689 +*info complete* 'command' ?'missing'?+::
2690 Returns 1 if +'command'+ is a complete Tcl command in the sense of
2691 having no unclosed quotes, braces, brackets or array element names,
2692 If the command doesn't appear to be complete then 0 is returned.
2693 This command is typically used in line-oriented input environments
2694 to allow users to type in commands that span multiple lines; if the
2695 command isn't complete, the script can delay evaluating it until additional
2696 lines have been typed to complete the command. If +'varName'+ is specified, the
2697 missing character is stored in the variable with that name.
2699 +*info exists* 'varName'+::
2700 Returns '1' if the variable named +'varName'+ exists in the
2701 current context (either as a global or local variable), returns '0'
2704 +*info frame* ?'number'?+::
2705 If +'number'+ is not specified, this command returns a number
2706 which is the same result as `info level` - the current stack frame level.
2707 If +'number'+ is specified, then the result is a list consisting of the procedure,
2708 filename and line number for the procedure call at level +'number'+ on the stack.
2709 If +'number'+ is positive then it selects a particular stack level (1 refers
2710 to the top-most active procedure, 2 to the procedure it called, and
2711 so on); otherwise it gives a level relative to the current level
2712 (0 refers to the current procedure, -1 to its caller, and so on).
2713 The level has an identical meaning to `info level`.
2715 +*info globals* ?'pattern'?+::
2716 If +'pattern'+ isn't specified, returns a list of all the names
2717 of currently-defined global variables.
2718 If +'pattern'+ is specified, only those names matching +'pattern'+
2719 are returned. Matching is determined using the same rules as for
2723 An alias for `os.gethostname` for compatibility with Tcl 6.x
2725 +*info level* ?'number'?+::
2726 If +'number'+ is not specified, this command returns a number
2727 giving the stack level of the invoking procedure, or 0 if the
2728 command is invoked at top-level. If +'number'+ is specified,
2729 then the result is a list consisting of the name and arguments for the
2730 procedure call at level +'number'+ on the stack. If +'number'+
2731 is positive then it selects a particular stack level (1 refers
2732 to the top-most active procedure, 2 to the procedure it called, and
2733 so on); otherwise it gives a level relative to the current level
2734 (0 refers to the current procedure, -1 to its caller, and so on).
2735 See the `uplevel` command for more information on what stack
2738 +*info locals* ?'pattern'?+::
2739 If +'pattern'+ isn't specified, returns a list of all the names
2740 of currently-defined local variables, including arguments to the
2741 current procedure, if any. Variables defined with the `global`
2742 and `upvar` commands will not be returned. If +'pattern'+ is
2743 specified, only those names matching +'pattern'+ are returned.
2744 Matching is determined using the same rules as for `string match`.
2746 +*info nameofexecutable*+::
2747 Returns the name of the binary file from which the application
2748 was invoked. A full path will be returned, unless the path
2749 can't be determined, in which case the empty string will be returned.
2751 +*info procs* ?'pattern'?+::
2752 If +'pattern'+ isn't specified, returns a list of all the
2753 names of Tcl command procedures.
2754 If +'pattern'+ is specified, only those names matching +'pattern'+
2755 are returned. Matching is determined using the same rules as for
2758 +*info references*+::
2759 Returns a list of all references which have not yet been garbage
2762 +*info returncodes* ?'code'?+::
2763 Returns a list representing the mapping of standard return codes
2764 to names. e.g. +{0 ok 1 error 2 return \...}+. If a code is given,
2765 instead returns the name for the given code.
2768 If a Tcl script file is currently being evaluated (i.e. there is a
2769 call to 'Jim_EvalFile' active or there is an active invocation
2770 of the `source` command), then this command returns the name
2771 of the innermost file being processed. Otherwise the command returns an
2774 +*info source* 'script ?filename line?'+::
2775 With a single argument, returns the original source location of the given script as a list of
2776 +{filename linenumber}+. If the source location can't be determined, the
2777 list +{{} 0}+ is returned. If +'filename'+ and +'line'+ are given, returns a copy
2778 of +'script'+ with the associate source information. This can be useful to produce
2779 useful messages from `eval`, etc. if the original source information may be lost.
2781 +*info stacktrace*+::
2782 After an error is caught with `catch`, returns the stack trace as a list
2783 of +{procedure filename line \...}+.
2785 +*info statics* 'procname'+::
2786 Returns a dictionary of the static variables of procedure
2787 +'procname'+. +'procname'+ must be the name of a Tcl command
2788 procedure. An empty dictionary is returned if the procedure has
2789 no static variables.
2792 Returns the version number for this version of Jim in the form +*x.yy*+.
2794 +*info vars* ?'pattern'?+::
2795 If +'pattern'+ isn't specified,
2796 returns a list of all the names of currently-visible variables, including
2797 both locals and currently-visible globals.
2798 If +'pattern'+ is specified, only those names matching +'pattern'+
2799 are returned. Matching is determined using the same rules as for
2804 +*join* 'list ?joinString?'+
2806 The +'list'+ argument must be a valid Tcl list. This command returns the
2807 string formed by joining all of the elements of +'list'+ together with
2808 +'joinString'+ separating each adjacent pair of elements.
2810 The +'joinString'+ argument defaults to a space character.
2814 +*kill* ?'SIG'|*-0*? 'pid'+
2816 Sends the given signal to the process identified by +'pid'+.
2818 The signal may be specified by name or number in one of the following forms:
2826 The signal name may be in either upper or lower case.
2828 The special signal name +-0+ simply checks that a signal +'could'+ be sent.
2830 If no signal is specified, SIGTERM is used.
2832 An error is raised if the signal could not be delivered.
2836 +*lambda* 'args ?statics? body'+
2838 The `lambda` command is identical to `proc`, except rather than
2839 creating a named procedure, it creates an anonymous procedure and returns
2840 the name of the procedure.
2842 See `proc` and GARBAGE COLLECTION, REFERENCES, LAMBDA FUNCTION for more detail.
2846 +*lappend* 'varName value ?value value \...?'+
2848 Treat the variable given by +'varName'+ as a list and append each of
2849 the +'value'+ arguments to that list as a separate element, with spaces
2852 If +'varName'+ doesn't exist, it is created as a list with elements given
2853 by the +'value'+ arguments. `lappend` is similar to `append` except that
2854 each +'value'+ is appended as a list element rather than raw text.
2856 This command provides a relatively efficient way to build up large lists.
2861 is much more efficient than
2863 set a [concat $a [list $b]]
2869 +*lassign* 'list varName ?varName \...?'+
2871 This command treats the value +'list'+ as a list and assigns successive elements from that list to
2872 the variables given by the +'varName'+ arguments in order. If there are more variable names than
2873 list elements, the remaining variables are set to the empty string. If there are more list elements
2874 than variables, a list of unassigned elements is returned.
2876 jim> lassign {1 2 3} a b; puts a=$a,b=$b
2882 +*local* 'cmd ?arg\...?'+
2884 First, `local` evaluates +'cmd'+ with the given arguments. The return value must
2885 be the name of an existing command, which is marked as having local scope.
2886 This means that when the current procedure exits, the specified
2887 command is deleted. This can be useful with `lambda`, local procedures or
2888 to automatically close a filehandle.
2890 In addition, if a command already exists with the same name,
2891 the existing command will be kept rather than deleted, and may be called
2892 via `upcall`. The previous command will be restored when the current
2893 procedure exits. See `upcall` for more details.
2895 In this example, a local procedure is created. Note that the procedure
2896 continues to have global scope while it is active.
2899 # proc ... returns "inner" which is marked local
2900 local proc inner {} {
2901 # will be deleted when 'outer' exits
2908 In this example, the lambda is deleted at the end of the procedure rather
2909 than waiting until garbage collection.
2912 set x [lambda inner {args} {
2913 # will be deleted when 'outer' exits
2915 # Use 'function' here which simply returns $x
2924 +*loop* 'var first limit ?incr? body'+
2926 Similar to `for` except simpler and possibly more efficient.
2927 With a positive increment, equivalent to:
2929 for {set var $first} {$var < $limit} {incr var $incr} $body
2931 If +'incr'+ is not specified, 1 is used.
2932 Note that setting the loop variable inside the loop does not
2933 affect the loop count.
2937 +*lindex* 'list ?index ...?'+
2939 Treats +'list'+ as a Tcl list and returns element +'index'+ from it
2940 (0 refers to the first element of the list).
2941 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for +'index'+.
2943 In extracting the element, +'lindex'+ observes the same rules concerning
2944 braces and quotes and backslashes as the Tcl command interpreter; however,
2945 variable substitution and command substitution do not occur.
2947 If no index values are given, simply returns +'list'+
2949 If +'index'+ is negative or greater than or equal to the number of elements
2950 in +'list'+, then an empty string is returned.
2952 If additional index arguments are supplied, then each argument is
2953 used in turn to select an element from the previous indexing
2954 operation, allowing the script to select elements from sublists.
2958 +*linsert* 'list index element ?element element \...?'+
2960 This command produces a new list from +'list'+ by inserting all
2961 of the +'element'+ arguments just before the element +'index'+
2962 of +'list'+. Each +'element'+ argument will become
2963 a separate element of the new list. If +'index'+ is less than
2964 or equal to zero, then the new elements are inserted at the
2965 beginning of the list. If +'index'+ is greater than or equal
2966 to the number of elements in the list, then the new elements are
2967 appended to the list.
2969 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for +'index'+.
2974 +*list* 'arg ?arg \...?'+
2976 This command returns a list comprised of all the arguments, +'arg'+. Braces
2977 and backslashes get added as necessary, so that the `lindex` command
2978 may be used on the result to re-extract the original arguments, and also
2979 so that `eval` may be used to execute the resulting list, with
2980 +'arg1'+ comprising the command's name and the other args comprising
2981 its arguments. `list` produces slightly different results than
2982 `concat`: `concat` removes one level of grouping before forming
2983 the list, while `list` works directly from the original arguments.
2984 For example, the command
2986 list a b {c d e} {f {g h}}
2990 a b {c d e} {f {g h}}
2992 while `concat` with the same arguments will return
3000 Treats +'list'+ as a list and returns a decimal string giving
3001 the number of elements in it.
3005 +*lset* 'varName ?index ..? newValue'+
3007 Sets an element in a list.
3009 The `lset` command accepts a parameter, +'varName'+, which it interprets
3010 as the name of a variable containing a Tcl list. It also accepts
3011 zero or more indices into the list. Finally, it accepts a new value
3012 for an element of varName. If no indices are presented, the command
3015 lset varName newValue
3017 In this case, newValue replaces the old value of the variable
3020 When presented with a single index, the `lset` command
3021 treats the content of the varName variable as a Tcl list. It addresses
3022 the index'th element in it (0 refers to the first element of the
3023 list). When interpreting the list, `lset` observes the same rules
3024 concerning braces and quotes and backslashes as the Tcl command
3025 interpreter; however, variable substitution and command substitution
3026 do not occur. The command constructs a new list in which the
3027 designated element is replaced with newValue. This new list is
3028 stored in the variable varName, and is also the return value from
3031 If index is negative or greater than or equal to the number of
3032 elements in $varName, then an error occurs.
3034 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for +'index'+.
3036 If additional index arguments are supplied, then each argument is
3037 used in turn to address an element within a sublist designated by
3038 the previous indexing operation, allowing the script to alter
3039 elements in sublists. The command,
3043 replaces element 2 of sublist 1 with +'newValue'+.
3045 The integer appearing in each index argument must be greater than
3046 or equal to zero. The integer appearing in each index argument must
3047 be strictly less than the length of the corresponding list. In other
3048 words, the `lset` command cannot change the size of a list. If an
3049 index is outside the permitted range, an error is reported.
3054 +*lmap* 'varName list body'+
3056 +*lmap* 'varList list ?varList2 list2 \...? body'+
3058 `lmap` is a "collecting" `foreach` which returns a list of its results.
3062 jim> lmap i {1 2 3 4 5} {expr $i*$i}
3064 jim> lmap a {1 2 3} b {A B C} {list $a $b}
3067 If the body invokes `continue`, no value is added for this iteration.
3068 If the body invokes `break`, the loop ends and no more values are added.
3074 Loads the dynamic extension, +'filename'+. Generally the filename should have
3075 the extension +.so+. The initialisation function for the module must be based
3076 on the name of the file. For example loading +hwaccess.so+ will invoke
3077 the initialisation function, +Jim_hwaccessInit+. Normally the `load` command
3078 should not be used directly. Instead it is invoked automatically by `package require`.
3082 +*lrange* 'list first last'+
3084 +'list'+ must be a valid Tcl list. This command will return a new
3085 list consisting of elements +'first'+ through +'last'+, inclusive.
3087 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for +'first'+ and +'last'+.
3089 If +'last'+ is greater than or equal to the number of elements
3090 in the list, then it is treated as if it were +end+.
3092 If +'first'+ is greater than +'last'+ then an empty string
3095 Note: +"`lrange` 'list first first'"+ does not always produce the
3096 same result as +"`lindex` 'list first'"+ (although it often does
3097 for simple fields that aren't enclosed in braces); it does, however,
3098 produce exactly the same results as +"`list` [`lindex` 'list first']"+
3103 +*lreplace* 'list first last ?element element \...?'+
3105 Returns a new list formed by replacing one or more elements of
3106 +'list'+ with the +'element'+ arguments.
3108 +'first'+ gives the index in +'list'+ of the first element
3111 If +'first'+ is less than zero then it refers to the first
3112 element of +'list'+; the element indicated by +'first'+
3113 must exist in the list.
3115 +'last'+ gives the index in +'list'+ of the last element
3116 to be replaced; it must be greater than or equal to +'first'+.
3118 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for +'first'+ and +'last'+.
3120 The +'element'+ arguments specify zero or more new arguments to
3121 be added to the list in place of those that were deleted.
3123 Each +'element'+ argument will become a separate element of
3126 If no +'element'+ arguments are specified, then the elements
3127 between +'first'+ and +'last'+ are simply deleted.
3131 +*lrepeat* 'number element1 ?element2 \...?'+
3133 Build a list by repeating elements +'number'+ times (which must be
3134 a positive integer).
3143 Returns the list in reverse order.
3145 jim> lreverse {1 2 3}
3150 +*lsearch* '?options? list pattern'+
3152 This command searches the elements +'list'+ to see if one of them matches +'pattern'+. If so, the
3153 command returns the index of the first matching element (unless the options +-all+, +-inline+ or +-bool+ are
3154 specified.) If not, the command returns -1. The option arguments indicates how the elements of
3155 the list are to be matched against pattern and must have one of the values below:
3157 *Note* that this command is different from Tcl in that default match type is +-exact+ rather than +-glob+.
3160 +'pattern'+ is a literal string that is compared for exact equality against each list element.
3161 This is the default.
3164 +'pattern'+ is a glob-style pattern which is matched against each list element using the same
3165 rules as the string match command.
3168 +'pattern'+ is treated as a regular expression and matched against each list element using
3169 the rules described by `regexp`.
3171 +*-command* 'cmdname'+::
3172 +'cmdname'+ is a command which is used to match the pattern against each element of the
3173 list. It is invoked as +'cmdname' ?*-nocase*? 'pattern listvalue'+ and should return 1
3174 for a match, or 0 for no match.
3177 Changes the result to be the list of all matching indices (or all matching values if
3178 +-inline+ is specified as well). If indices are returned, the indices will be in numeric
3179 order. If values are returned, the order of the values will be the order of those values
3180 within the input list.
3183 The matching value is returned instead of its index (or an empty string if no value
3184 matches). If +-all+ is also specified, then the result of the command is the list of all
3185 values that matched. The +-inline+ and +-bool+ options are mutually exclusive.
3188 Changes the result to '1' if a match was found, or '0' otherwise. If +-all+ is also specified,
3189 the result will be a list of '0' and '1' for each element of the list depending upon whether
3190 the corresponding element matches. The +-inline+ and +-bool+ options are mutually exclusive.
3193 This negates the sense of the match, returning the index (or value
3194 if +-inline+ is specified) of the first non-matching value in the
3195 list. If +-bool+ is also specified, the '0' will be returned if a
3196 match is found, or '1' otherwise. If +-all+ is also specified,
3197 non-matches will be returned rather than matches.
3200 Causes comparisons to be handled in a case-insensitive manner.
3204 +*lsort* ?*-index* 'listindex'? ?*-nocase|-integer|-real|-command* 'cmdname'? ?*-unique*? ?*-decreasing*|*-increasing*? 'list'+
3206 Sort the elements of +'list'+, returning a new list in sorted order.
3207 By default, ASCII (or UTF-8) sorting is used, with the result in increasing order.
3209 If +-nocase+ is specified, comparisons are case-insensitive.
3211 If +-integer+ is specified, numeric sorting is used.
3213 If +-real+ is specified, floating point number sorting is used.
3215 If +-command 'cmdname'+ is specified, +'cmdname'+ is treated as a command
3216 name. For each comparison, +'cmdname $value1 $value2+' is called which
3217 should compare the values and return an integer less than, equal
3218 to, or greater than zero if the +'$value1'+ is to be considered less
3219 than, equal to, or greater than +'$value2'+, respectively.
3221 If +-decreasing+ is specified, the resulting list is in the opposite
3222 order to what it would be otherwise. +-increasing+ is the default.
3224 If +-unique+ is specified, then only the last set of duplicate elements found in the list will be retained.
3225 Note that duplicates are determined relative to the comparison used in the sort. Thus if +-index 0+ is used,
3226 +{1 a}+ and +{1 b}+ would be considered duplicates and only the second element, +{1 b}+, would be retained.
3228 If +-index 'listindex'+ is specified, each element of the list is treated as a list and
3229 the given index is extracted from the list for comparison. The list index may
3230 be any valid list index, such as +1+, +end+ or +end-2+.
3234 +*open* 'fileName ?access?'+
3236 +*open* '|command-pipeline ?access?'+
3238 Opens a file and returns an identifier
3239 that may be used in future invocations
3240 of commands like `read`, `puts`, and `close`.
3241 +'fileName'+ gives the name of the file to open.
3243 The +'access'+ argument indicates the way in which the file is to be accessed.
3244 It may have any of the following values:
3247 Open the file for reading only; the file must already exist.
3250 Open the file for both reading and writing; the file must
3254 Open the file for writing only. Truncate it if it exists. If it doesn't
3255 exist, create a new file.
3258 Open the file for reading and writing. Truncate it if it exists.
3259 If it doesn't exist, create a new file.
3262 Open the file for writing only. The file must already exist, and the file
3263 is positioned so that new data is appended to the file.
3266 Open the file for reading and writing. If the file doesn't
3267 exist, create a new empty file. Set the initial access position
3268 to the end of the file.
3270 +'access'+ defaults to 'r'.
3272 If a file is opened for both reading and writing, then `seek`
3273 must be invoked between a read and a write, or vice versa.
3275 If the first character of +'fileName'+ is "|" then the remaining
3276 characters of +'fileName'+ are treated as a list of arguments that
3277 describe a command pipeline to invoke, in the same style as the
3278 arguments for exec. In this case, the channel identifier returned
3279 by open may be used to write to the command's input pipe or read
3280 from its output pipe, depending on the value of +'access'+. If write-only
3281 access is used (e.g. +'access'+ is 'w'), then standard output for the
3282 pipeline is directed to the current standard output unless overridden
3283 by the command. If read-only access is used (e.g. +'access'+ is r),
3284 standard input for the pipeline is taken from the current standard
3285 input unless overridden by the command.
3287 The `pid` command may be used to return the process ids of the commands
3288 forming the command pipeline.
3290 See also `socket`, `pid`, `exec`
3294 +*package provide* 'name ?version?'+
3296 Indicates that the current script provides the package named +'name'+.
3297 If no version is specified, '1.0' is used.
3299 Any script which provides a package may include this statement
3300 as the first statement, although it is not required.
3302 +*package require* 'name ?version?'*+
3304 Searches for the package with the given +'name'+ by examining each path
3305 in '$::auto_path' and trying to load '$path/$name.so' as a dynamic extension,
3306 or '$path/$name.tcl' as a script package.
3308 The first such file which is found is considered to provide the package.
3309 (The version number is ignored).
3311 If '$name.so' exists, it is loaded with the `load` command,
3312 otherwise if '$name.tcl' exists it is loaded with the `source` command.
3314 If `load` or `source` fails, `package require` will fail immediately.
3315 No further attempt will be made to locate the file.
3323 The first form returns the process identifier of the current process.
3325 The second form accepts a handle returned by `open` and returns a list
3326 of the process ids forming the pipeline in the same form as `exec ... &`.
3327 If 'fileId' represents a regular file handle rather than a command pipeline,
3328 the empty string is returned instead.
3330 See also `open`, `exec`
3334 +*proc* 'name args ?statics? body'+
3336 The `proc` command creates a new Tcl command procedure, +'name'+.
3337 When the new command is invoked, the contents of +'body'+ will be executed.
3338 Tcl interpreter. +'args'+ specifies the formal arguments to the procedure.
3339 If specified, +'statics'+, declares static variables which are bound to the
3342 See PROCEDURES for detailed information about Tcl procedures.
3344 The `proc` command returns +'name'+ (which is useful with `local`).
3346 When a procedure is invoked, the procedure's return value is the
3347 value specified in a `return` command. If the procedure doesn't
3348 execute an explicit `return`, then its return value is the value
3349 of the last command executed in the procedure's body.
3351 If an error occurs while executing the procedure body, then the
3352 procedure-as-a-whole will return that same error.
3356 +*puts* ?*-nonewline*? '?fileId? string'+
3358 +'fileId' *puts* ?*-nonewline*? 'string'+
3360 Writes the characters given by +'string'+ to the file given
3361 by +'fileId'+. +'fileId'+ must have been the return
3362 value from a previous call to `open`, or it may be
3363 +stdout+ or +stderr+ to refer to one of the standard I/O
3364 channels; it must refer to a file that was opened for
3367 In the first form, if no +'fileId'+ is specified then it defaults to +stdout+.
3368 `puts` normally outputs a newline character after +'string'+,
3369 but this feature may be suppressed by specifying the +-nonewline+
3372 Output to files is buffered internally by Tcl; the `flush`
3373 command may be used to force buffered characters to be output.
3379 Returns the path name of the current working directory.
3383 +*rand* '?min? ?max?'+
3385 Returns a random integer between +'min'+ (defaults to 0) and +'max'+
3386 (defaults to the maximum integer).
3388 If only one argument is given, it is interpreted as +'max'+.
3392 +*range* '?start? end ?step?'+
3394 Returns a list of integers starting at +'start'+ (defaults to 0)
3395 and ranging up to but not including +'end'+ in steps of +'step'+ defaults to 1).
3408 +*read* ?*-nonewline*? 'fileId'+
3410 +'fileId' *read* ?*-nonewline*?+
3412 +*read* 'fileId numBytes'+
3414 +'fileId' *read* 'numBytes'+
3417 In the first form, all of the remaining bytes are read from the file
3418 given by +'fileId'+; they are returned as the result of the command.
3419 If the +-nonewline+ switch is specified then the last
3420 character of the file is discarded if it is a newline.
3422 In the second form, the extra argument specifies how many bytes to read;
3423 exactly this many bytes will be read and returned, unless there are fewer than
3424 +'numBytes'+ bytes left in the file; in this case, all the remaining
3427 +'fileId'+ must be +stdin+ or the return value from a previous call
3428 to `open`; it must refer to a file that was opened for reading.
3432 +*regexp ?-nocase? ?-line? ?-indices? ?-start* 'offset'? *?-all? ?-inline? ?--?* 'exp string ?matchVar? ?subMatchVar subMatchVar \...?'+
3434 Determines whether the regular expression +'exp'+ matches part or
3435 all of +'string'+ and returns 1 if it does, 0 if it doesn't.
3437 See REGULAR EXPRESSIONS above for complete information on the
3438 syntax of +'exp'+ and how it is matched against +'string'+.
3440 If additional arguments are specified after +'string'+ then they
3441 are treated as the names of variables to use to return
3442 information about which part(s) of +'string'+ matched +'exp'+.
3443 +'matchVar'+ will be set to the range of +'string'+ that
3444 matched all of +'exp'+. The first +'subMatchVar'+ will contain
3445 the characters in +'string'+ that matched the leftmost parenthesized
3446 subexpression within +'exp'+, the next +'subMatchVar'+ will
3447 contain the characters that matched the next parenthesized
3448 subexpression to the right in +'exp'+, and so on.
3450 Normally, +'matchVar'+ and the each +'subMatchVar'+ are set to hold the
3451 matching characters from `string`, however see +-indices+ and
3454 If there are more values for +'subMatchVar'+ than parenthesized subexpressions
3455 within +'exp'+, or if a particular subexpression in +'exp'+ doesn't
3456 match the string (e.g. because it was in a portion of the expression
3457 that wasn't matched), then the corresponding +'subMatchVar'+ will be
3458 set to +"-1 -1"+ if +-indices+ has been specified or to an empty
3461 The following switches modify the behaviour of +'regexp'+
3464 Causes upper-case and lower-case characters to be treated as
3465 identical during the matching process.
3468 Use newline-sensitive matching. By default, newline
3469 is a completely ordinary character with no special meaning in
3470 either REs or strings. With this flag, +[^+ bracket expressions
3471 and +.+ never match newline, an +^+ anchor matches the null
3472 string after any newline in the string in addition to its normal
3473 function, and the +$+ anchor matches the null string before any
3474 newline in the string in addition to its normal function.
3477 Changes what is stored in the subMatchVars. Instead of
3478 storing the matching characters from string, each variable
3479 will contain a list of two decimal strings giving the indices
3480 in string of the first and last characters in the matching
3481 range of characters.
3483 +*-start* 'offset'+::
3484 Specifies a character index offset into the string at which to start
3485 matching the regular expression. If +-indices+ is
3486 specified, the indices will be indexed starting from the
3487 absolute beginning of the input string. +'offset'+ will be
3488 constrained to the bounds of the input string.
3491 Causes the regular expression to be matched as many times as possible
3492 in the string, returning the total number of matches found. If this
3493 is specified with match variables, they will contain information
3494 for the last match only.
3497 Causes the command to return, as a list, the data that would otherwise
3498 be placed in match variables. When using +-inline+, match variables
3499 may not be specified. If used with +-all+, the list will be concatenated
3500 at each iteration, such that a flat list is always returned. For
3501 each match iteration, the command will append the overall match
3502 data, plus one element for each subexpression in the regular
3506 Marks the end of switches. The argument following this one will be
3507 treated as +'exp'+ even if it starts with a +-+.
3511 +*regsub ?-nocase? ?-all? ?-line? ?-start* 'offset'? ?*--*? 'exp string subSpec ?varName?'+
3513 This command matches the regular expression +'exp'+ against
3514 +'string'+ using the rules described in REGULAR EXPRESSIONS
3517 If +'varName'+ is specified, the commands stores +'string'+ to +'varName'+
3518 with the substitutions detailed below, and returns the number of
3519 substitutions made (normally 1 unless +-all+ is specified).
3520 This is 0 if there were no matches.
3522 If +'varName'+ is not specified, the substituted string will be returned
3525 When copying +'string'+, the portion of +'string'+ that
3526 matched +'exp'+ is replaced with +'subSpec'+.
3527 If +'subSpec'+ contains a +&+ or +{backslash}0+, then it is replaced
3528 in the substitution with the portion of +'string'+ that
3531 If +'subSpec'+ contains a +{backslash}n+, where +'n'+ is a digit
3532 between 1 and 9, then it is replaced in the substitution with
3533 the portion of +'string'+ that matched the +'n'+\'-th
3534 parenthesized subexpression of +'exp'+.
3535 Additional backslashes may be used in +'subSpec'+ to prevent special
3536 interpretation of +&+ or +{backslash}0+ or +{backslash}n+ or
3539 The use of backslashes in +'subSpec'+ tends to interact badly
3540 with the Tcl parser's use of backslashes, so it's generally
3541 safest to enclose +'subSpec'+ in braces if it includes
3544 The following switches modify the behaviour of +'regsub'+
3547 Upper-case characters in +'string'+ are converted to lower-case
3548 before matching against +'exp'+; however, substitutions
3549 specified by +'subSpec'+ use the original unconverted form
3553 All ranges in +'string'+ that match +'exp'+ are found and substitution
3554 is performed for each of these ranges, rather than only the
3555 first. The +&+ and +{backslash}n+ sequences are handled for
3556 each substitution using the information from the corresponding
3560 Use newline-sensitive matching. By default, newline
3561 is a completely ordinary character with no special meaning in
3562 either REs or strings. With this flag, +[^+ bracket expressions
3563 and +.+ never match newline, an +^+ anchor matches the null
3564 string after any newline in the string in addition to its normal
3565 function, and the +$+ anchor matches the null string before any
3566 newline in the string in addition to its normal function.
3568 +*-start* 'offset'+::
3569 Specifies a character index offset into the string at which to
3570 start matching the regular expression. +'offset'+ will be
3571 constrained to the bounds of the input string.
3574 Marks the end of switches. The argument following this one will be
3575 treated as +'exp'+ even if it starts with a +-+.
3579 +*ref* 'string tag ?finalizer?'+
3581 Create a new reference containing +'string'+ of type +'tag'+.
3582 If +'finalizer'+ is specified, it is a command which will be invoked
3583 when the a garbage collection cycle runs and this reference is
3584 no longer accessible.
3586 The finalizer is invoked as:
3588 finalizer reference string
3590 See GARBAGE COLLECTION, REFERENCES, LAMBDA FUNCTION for more detail.
3594 +*rename* 'oldName newName'+
3596 Rename the command that used to be called +'oldName'+ so that it
3597 is now called +'newName'+. If +'newName'+ is an empty string
3598 (e.g. {}) then +'oldName'+ is deleted. The `rename` command
3599 returns an empty string as result.
3603 +*return* ?*-code* 'code'? ?*-errorinfo* 'stacktrace'? ?*-errorcode* 'errorcode'? ?*-level* 'n'? ?'value'?+
3605 Return immediately from the current procedure (or top-level command
3606 or `source` command), with +'value'+ as the return value. If +'value'+
3607 is not specified, an empty string will be returned as result.
3609 If +-code+ is specified (as either a number or ok, error, break,
3610 continue, signal, return or exit), this code will be used instead
3611 of +JIM_OK+. This is generally useful when implementing flow of control
3614 If +-level+ is specified and greater than 1, it has the effect of delaying
3615 the new return code from +-code+. This is useful when rethrowing an error
3616 from `catch`. See the implementation of try/catch in tclcompat.tcl for
3617 an example of how this is done.
3619 Note: The following options are only used when +-code+ is JIM_ERR.
3621 If +-errorinfo+ is specified (as returned from `info stacktrace`)
3622 it is used to initialize the stacktrace.
3624 If +-errorcode+ is specified, it is used to set the global variable $::errorCode.
3628 +*scan* 'string format varName1 ?varName2 \...?'+
3630 This command parses fields from an input string in the same fashion
3631 as the C 'sscanf' procedure. +'string'+ gives the input to be parsed
3632 and +'format'+ indicates how to parse it, using '%' fields as in
3633 'sscanf'. All of the 'sscanf' options are valid; see the 'sscanf'
3634 man page for details. Each +'varName'+ gives the name of a variable;
3635 when a field is scanned from +'string'+, the result is converted back
3636 into a string and assigned to the corresponding +'varName'+. The
3637 only unusual conversion is for '%c'. For '%c' conversions a single
3638 character value is converted to a decimal string, which is then
3639 assigned to the corresponding +'varName'+; no field width may be
3640 specified for this conversion.
3644 +*seek* 'fileId offset ?origin?'+
3646 +'fileId' *seek* 'offset ?origin?'+
3648 Change the current access position for +'fileId'+.
3649 The +'offset'+ and +'origin'+ arguments specify the position at
3650 which the next read or write will occur for +'fileId'+.
3651 +'offset'+ must be a number (which may be negative) and +'origin'+
3652 must be one of the following:
3655 The new access position will be +'offset'+ bytes from the start
3659 The new access position will be +'offset'+ bytes from the current
3660 access position; a negative +'offset'+ moves the access position
3661 backwards in the file.
3664 The new access position will be +'offset'+ bytes from the end of
3665 the file. A negative +'offset'+ places the access position before
3666 the end-of-file, and a positive +'offset'+ places the access position
3667 after the end-of-file.
3669 The +'origin'+ argument defaults to +start+.
3671 +'fileId'+ must have been the return value from a previous call to
3672 `open`, or it may be +stdin+, +stdout+, or +stderr+ to refer to one
3673 of the standard I/O channels.
3675 This command returns an empty string.
3679 +*set* 'varName ?value?'+
3681 Returns the value of variable +'varName'+.
3683 If +'value'+ is specified, then set the value of +'varName'+ to +'value'+,
3684 creating a new variable if one doesn't already exist, and return
3687 If +'varName'+ contains an open parenthesis and ends with a
3688 close parenthesis, then it refers to an array element: the characters
3689 before the open parenthesis are the name of the array, and the characters
3690 between the parentheses are the index within the array.
3691 Otherwise +'varName'+ refers to a scalar variable.
3693 If no procedure is active, then +'varName'+ refers to a global
3696 If a procedure is active, then +'varName'+ refers to a parameter
3697 or local variable of the procedure, unless the +'global'+ command
3698 has been invoked to declare +'varName'+ to be global.
3700 The +::+ prefix may also be used to explicitly reference a variable
3701 in the global scope.
3705 +*setref* 'reference string'+
3707 Store a new string in +'reference'+, replacing the existing string.
3708 The reference must be a valid reference create with the `ref`
3711 See GARBAGE COLLECTION, REFERENCES, LAMBDA FUNCTION for more detail.
3715 Command for signal handling.
3717 See `kill` for the different forms which may be used to specify signals.
3719 Commands which return a list of signal names do so using the canonical form:
3722 +*signal handle* ?'signals \...'?+::
3723 If no signals are given, returns a list of all signals which are currently
3725 If signals are specified, these are added to the list of signals currently
3728 +*signal ignore* ?'signals \...'?+::
3729 If no signals are given, returns a lists all signals which are currently
3731 If signals are specified, these are added to the list of signals
3732 currently being ignored. These signals are still delivered, but
3733 are not considered by `catch -signal` or `try -signal`. Use
3734 `signal check` to determine which signals have occurred but
3737 +*signal default* ?'signals \...'?+::
3738 If no signals are given, returns a lists all signals which are currently have
3739 the default behaviour.
3740 If signals are specified, these are added to the list of signals which have
3741 the default behaviour.
3743 +*signal check ?-clear?* ?'signals \...'?+::
3744 Returns a list of signals which have been delivered to the process
3745 but are 'ignored'. If signals are specified, only that set of signals will
3746 be checked, otherwise all signals will be checked.
3747 If +-clear+ is specified, any signals returned are removed and will not be
3748 returned by subsequent calls to `signal check` unless delivered again.
3750 +*signal throw* ?'signal'?+::
3751 Raises the given signal, which defaults to +SIGINT+ if not specified.
3752 The behaviour is identical to:
3756 Note that `signal handle` and `signal ignore` represent two forms of signal
3757 handling. `signal handle` is used in conjunction with `catch -signal` or `try -signal`
3758 to immediately abort execution when the signal is delivered. Alternatively, `signal ignore`
3759 is used in conjunction with `signal check` to handle signal synchronously. Consider the
3762 Prevent a processing from taking too long
3764 signal handle SIGALRM
3767 .. possibly long running process ..
3770 puts stderr "Process took too long"
3773 Handle SIGHUP to reconfigure:
3775 signal ignore SIGHUP
3777 ... handle configuration/reconfiguration ...
3778 while {[signal check -clear SIGHUP] eq ""} {
3779 ... do processing ..
3781 # Received SIGHUP, so reconfigure
3788 Pauses for the given number of seconds, which may be a floating
3789 point value less than one to sleep for less than a second, or an
3790 integer to sleep for one or more seconds.
3794 +*source* 'fileName'+
3796 Read file +'fileName'+ and pass the contents to the Tcl interpreter
3797 as a sequence of commands to execute in the normal fashion. The return
3798 value of `source` is the return value of the last command executed
3799 from the file. If an error occurs in executing the contents of the
3800 file, then the `source` command will return that error.
3802 If a `return` command is invoked from within the file, the remainder of
3803 the file will be skipped and the `source` command will return
3804 normally with the result from the `return` command.
3808 +*split* 'string ?splitChars?'+
3810 Returns a list created by splitting +'string'+ at each character
3811 that is in the +'splitChars'+ argument.
3813 Each element of the result list will consist of the
3814 characters from +'string'+ between instances of the
3815 characters in +'splitChars'+.
3817 Empty list elements will be generated if +'string'+ contains
3818 adjacent characters in +'splitChars'+, or if the first or last
3819 character of +'string'+ is in +'splitChars'+.
3821 If +'splitChars'+ is an empty string then each character of
3822 +'string'+ becomes a separate element of the result list.
3824 +'splitChars'+ defaults to the standard white-space characters.
3827 split "comp.unix.misc" .
3829 returns +'"comp unix misc"'+ and
3831 split "Hello world" {}
3833 returns +'"H e l l o { } w o r l d"'+.
3838 +*stackdump* 'stacktrace'+
3840 Creates a human readable representation of a stack trace.
3847 Returns a live stack trace as a list of +proc file line proc file line \...+.
3848 Iteratively uses `info frame` to create the stack trace. This stack trace is in the
3849 same form as produced by `catch` and `info stacktrace`
3851 See also `stackdump`.
3856 +*string* 'option arg ?arg \...?'+
3858 Perform one of several string operations, depending on +'option'+.
3859 The legal options (which may be abbreviated) are:
3861 +*string bytelength* 'string'+::
3862 Returns the length of the string in bytes. This will return
3863 the same value as `string length` if UTF-8 support is not enabled,
3864 or if the string is composed entirely of ASCII characters.
3865 See UTF-8 AND UNICODE.
3867 +*string byterange* 'string first last'+::
3868 Like `string range` except works on bytes rather than characters.
3869 These commands are identical if UTF-8 support is not enabled.
3871 +*string cat* '?string1 string2 \...?'+::
3872 Concatenates the given strings into a single string.
3874 +*string compare ?-nocase?* ?*-length* 'len? string1 string2'+::
3875 Perform a character-by-character comparison of strings +'string1'+ and
3876 +'string2'+ in the same way as the C 'strcmp' procedure. Return
3877 -1, 0, or 1, depending on whether +'string1'+ is lexicographically
3878 less than, equal to, or greater than +'string2'+. If +-length+
3879 is specified, then only the first +'len'+ characters are used
3880 in the comparison. If +'len'+ is negative, it is ignored.
3881 Performs a case-insensitive comparison if +-nocase+ is specified.
3883 +*string equal ?-nocase?* '?*-length* len?' 'string1 string2'+::
3884 Returns 1 if the strings are equal, or 0 otherwise. If +-length+
3885 is specified, then only the first +'len'+ characters are used
3886 in the comparison. If +'len'+ is negative, it is ignored.
3887 Performs a case-insensitive comparison if +-nocase+ is specified.
3889 +*string first* 'string1 string2 ?firstIndex?'+::
3890 Search +'string2'+ for a sequence of characters that exactly match
3891 the characters in +'string1'+. If found, return the index of the
3892 first character in the first such match within +'string2'+. If not
3893 found, return -1. If +'firstIndex'+ is specified, matching will start
3894 from +'firstIndex'+ of +'string1'+.
3896 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for +'firstIndex'+.
3898 +*string index* 'string charIndex'+::
3899 Returns the +'charIndex'+'th character of the +'string'+
3900 argument. A +'charIndex'+ of 0 corresponds to the first
3901 character of the string.
3902 If +'charIndex'+ is less than 0 or greater than
3903 or equal to the length of the string then an empty string is
3906 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for +'charIndex'+.
3908 +*string is* 'class' ?*-strict*? 'string'+::
3909 Returns 1 if +'string'+ is a valid member of the specified character
3910 class, otherwise returns 0. If +-strict+ is specified, then an
3911 empty string returns 0, otherwise an empty string will return 1
3912 on any class. The following character classes are recognized
3913 (the class name can be abbreviated):
3915 +alnum+;; Any alphabet or digit character.
3916 +alpha+;; Any alphabet character.
3917 +ascii+;; Any character with a value less than 128 (those that are in the 7-bit ascii range).
3918 +boolean+;; Any of the valid string formats for a boolean value in Tcl (0, false, no, off, 1, true, yes, on)
3919 +control+;; Any control character.
3920 +digit+;; Any digit character.
3921 +double+;; Any of the valid forms for a double in Tcl, with optional surrounding whitespace.
3922 In case of under/overflow in the value, 0 is returned.
3923 +graph+;; Any printing character, except space.
3924 +integer+;; Any of the valid string formats for an integer value in Tcl, with optional surrounding whitespace.
3925 +lower+;; Any lower case alphabet character.
3926 +print+;; Any printing character, including space.
3927 +punct+;; Any punctuation character.
3928 +space+;; Any space character.
3929 +upper+;; Any upper case alphabet character.
3930 +xdigit+;; Any hexadecimal digit character ([0-9A-Fa-f]).
3932 Note that string classification does +'not'+ respect UTF-8. See UTF-8 AND UNICODE
3934 Note that only +'lowercase'+ boolean values are recognized (Tcl accepts any case).
3936 +*string last* 'string1 string2 ?lastIndex?'+::
3937 Search +'string2'+ for a sequence of characters that exactly match
3938 the characters in +'string1'+. If found, return the index of the
3939 first character in the last such match within +'string2'+. If there
3940 is no match, then return -1. If +'lastIndex'+ is specified, only characters
3941 up to +'lastIndex'+ of +'string2'+ will be considered in the match.
3943 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for +'lastIndex'+.
3945 +*string length* 'string'+::
3946 Returns a decimal string giving the number of characters in +'string'+.
3947 If UTF-8 support is enabled, this may be different than the number of bytes.
3948 See UTF-8 AND UNICODE
3950 +*string map ?-nocase?* 'mapping string'+::
3951 Replaces substrings in +'string'+ based on the key-value pairs in
3952 +'mapping'+, which is a list of +key value key value \...+ as in the form
3953 returned by `array get`. Each instance of a key in the string will be
3954 replaced with its corresponding value. If +-nocase+ is specified, then
3955 matching is done without regard to case differences. Both key and value may
3956 be multiple characters. Replacement is done in an ordered manner, so the
3957 key appearing first in the list will be checked first, and so on. +'string'+ is
3958 only iterated over once, so earlier key replacements will have no affect for
3959 later key matches. For example,
3961 string map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc
3964 will return the string +01321221+.
3966 Note that if an earlier key is a prefix of a later one, it will completely mask the later
3967 one. So if the previous example is reordered like this,
3969 string map {1 0 ab 2 a 3 abc 1} 1abcaababcabababc
3972 it will return the string +02c322c222c+.
3974 +*string match ?-nocase?* 'pattern string'+::
3975 See if +'pattern'+ matches +'string'+; return 1 if it does, 0
3976 if it doesn't. Matching is done in a fashion similar to that
3977 used by the C-shell. For the two strings to match, their contents
3978 must be identical except that the following special sequences
3979 may appear in +'pattern'+:
3982 Matches any sequence of characters in +'string'+,
3983 including a null string.
3986 Matches any single character in +'string'+.
3989 Matches any character in the set given by +'chars'+.
3990 If a sequence of the form +'x-y'+ appears in +'chars'+,
3991 then any character between +'x'+ and +'y'+, inclusive,
3995 Matches the single character +'x'+. This provides a way of
3996 avoiding the special interpretation of the characters +{backslash}*?[]+
3999 Performs a case-insensitive comparison if +-nocase+ is specified.
4001 +*string range* 'string first last'+::
4002 Returns a range of consecutive characters from +'string'+, starting
4003 with the character whose index is +'first'+ and ending with the
4004 character whose index is +'last'+. An index of 0 refers to the
4005 first character of the string.
4007 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for +'first'+ and +'last'+.
4009 If +'first'+ is less than zero then it is treated as if it were zero, and
4010 if +'last'+ is greater than or equal to the length of the string then
4011 it is treated as if it were +end+. If +'first'+ is greater than
4012 +'last'+ then an empty string is returned.
4014 +*string repeat* 'string count'+::
4015 Returns a new string consisting of +'string'+ repeated +'count'+ times.
4017 +*string replace* 'string first last ?newstring?'+::
4018 Removes a range of consecutive characters from +'string'+, starting
4019 with the character whose index is +'first'+ and ending with the
4020 character whose index is +'last'+. If +'newstring'+ is specified,
4021 then it is placed in the removed character range. If +'first'+ is
4022 less than zero then it is treated as if it were zero, and if +'last'+
4023 is greater than or equal to the length of the string then it is
4024 treated as if it were +end+. If +'first'+ is greater than +'last'+
4025 or the length of the initial string, or +'last'+ is less than 0,
4026 then the initial string is returned untouched.
4028 +*string reverse* 'string'+::
4029 Returns a string that is the same length as +'string'+ but
4030 with its characters in the reverse order.
4032 +*string tolower* 'string'+::
4033 Returns a value equal to +'string'+ except that all upper case
4034 letters have been converted to lower case.
4036 +*string totitle* 'string'+::
4037 Returns a value equal to +'string'+ except that the first character
4038 is converted to title case (or upper case if there is no UTF-8 titlecase variant)
4039 and all remaining characters have been converted to lower case.
4041 +*string toupper* 'string'+::
4042 Returns a value equal to +'string'+ except that all lower case
4043 letters have been converted to upper case.
4045 +*string trim* 'string ?chars?'+::
4046 Returns a value equal to +'string'+ except that any leading
4047 or trailing characters from the set given by +'chars'+ are
4049 If +'chars'+ is not specified then white space is removed
4050 (spaces, tabs, newlines, and carriage returns).
4052 +*string trimleft* 'string ?chars?'+::
4053 Returns a value equal to +'string'+ except that any
4054 leading characters from the set given by +'chars'+ are
4056 If +'chars'+ is not specified then white space is removed
4057 (spaces, tabs, newlines, and carriage returns).
4059 +*string trimright* 'string ?chars?'+::
4060 Returns a value equal to +'string'+ except that any
4061 trailing characters from the set given by +'chars'+ are
4063 If +'chars'+ is not specified then white space is removed
4064 (spaces, tabs, newlines, and carriage returns).
4065 Null characters are always removed.
4069 +*subst ?-nobackslashes? ?-nocommands? ?-novariables?* 'string'+
4071 This command performs variable substitutions, command substitutions,
4072 and backslash substitutions on its string argument and returns the
4073 fully-substituted result. The substitutions are performed in exactly
4074 the same way as for Tcl commands. As a result, the string argument
4075 is actually substituted twice, once by the Tcl parser in the usual
4076 fashion for Tcl commands, and again by the subst command.
4078 If any of the +-nobackslashes+, +-nocommands+, or +-novariables+ are
4079 specified, then the corresponding substitutions are not performed.
4080 For example, if +-nocommands+ is specified, no command substitution
4081 is performed: open and close brackets are treated as ordinary
4082 characters with no special interpretation.
4084 *Note*: when it performs its substitutions, subst does not give any
4085 special treatment to double quotes or curly braces. For example,
4086 the following script returns +xyz \{44\}+, not +xyz \{$a\}+.
4094 +*switch* '?options? string pattern body ?pattern body \...?'+
4096 +*switch* '?options? string {pattern body ?pattern body \...?}'+
4098 The `switch` command matches its string argument against each of
4099 the pattern arguments in order. As soon as it finds a pattern that
4100 matches string it evaluates the following body and returns the
4101 result of that evaluation. If the last pattern argument is default
4102 then it matches anything. If no pattern argument matches string and
4103 no default is given, then the `switch` command returns an empty string.
4104 If the initial arguments to switch start with - then they are treated
4105 as options. The following options are currently supported:
4108 Use exact matching when comparing string to a
4109 pattern. This is the default.
4112 When matching string to the patterns, use glob-style
4113 matching (i.e. the same as implemented by the string
4117 When matching string to the patterns, use regular
4118 expression matching (i.e. the same as implemented
4119 by the regexp command).
4121 +-command 'commandname'+::
4122 When matching string to the patterns, use the given command, which
4123 must be a single word. The command is invoked as
4124 'commandname pattern string', or 'commandname -nocase pattern string'
4125 and must return 1 if matched, or 0 if not.
4128 Marks the end of options. The argument following
4129 this one will be treated as string even if it starts
4132 Two syntaxes are provided for the pattern and body arguments. The
4133 first uses a separate argument for each of the patterns and commands;
4134 this form is convenient if substitutions are desired on some of the
4135 patterns or commands. The second form places all of the patterns
4136 and commands together into a single argument; the argument must
4137 have proper list structure, with the elements of the list being the
4138 patterns and commands. The second form makes it easy to construct
4139 multi-line `switch` commands, since the braces around the whole list
4140 make it unnecessary to include a backslash at the end of each line.
4141 Since the pattern arguments are in braces in the second form, no
4142 command or variable substitutions are performed on them; this makes
4143 the behaviour of the second form different than the first form in
4146 If a body is specified as +-+ it means that the body for the next
4147 pattern should also be used as the body for this pattern (if the
4148 next pattern also has a body of +-+ then the body after that is
4149 used, and so on). This feature makes it possible to share a single
4150 body among several patterns.
4152 Below are some examples of `switch` commands:
4154 switch abc a - b {format 1} abc {format 2} default {format 3}
4158 switch -regexp aaab {
4178 +*tailcall* 'cmd ?arg\...?'+
4180 The `tailcall` command provides an optimised way of invoking a command whilst replacing
4181 the current call frame. This is similar to 'exec' in Bourne Shell.
4183 The following are identical except the first immediately replaces the current call frame.
4187 return [uplevel 1 [list a b c]]
4189 `tailcall` is useful as a dispatch mechanism:
4192 tailcall sub_$cmd {*}$args
4203 Returns a decimal string giving the current access position in
4206 +'fileId'+ must have been the return value from a previous call to
4207 `open`, or it may be +stdin+, +stdout+, or +stderr+ to refer to one
4208 of the standard I/O channels.
4212 +*throw* 'code ?msg?'+
4214 This command throws an exception (return) code along with an optional message.
4215 This command is mostly for convenient usage with `try`.
4217 The command +throw break+ is equivalent to +break+.
4218 The command +throw 20 message+ can be caught with an +on 20 \...+ clause to `try`.
4222 +*time* 'command ?count?'+
4224 This command will call the Tcl interpreter +'count'+
4225 times to execute +'command'+ (or once if +'count'+ isn't
4226 specified). It will then return a string of the form
4228 503 microseconds per iteration
4230 which indicates the average amount of time required per iteration,
4233 Time is measured in elapsed time, not CPU time.
4237 +*try* '?catchopts? tryscript' ?*on* 'returncodes {?resultvar? ?optsvar?} handlerscript \...'? ?*finally* 'finalscript'?+
4239 The `try` command is provided as a convenience for exception handling.
4241 This interpeter first evaluates +'tryscript'+ under the effect of the catch
4242 options +'catchopts'+ (e.g. +-signal -noexit --+, see `catch`).
4244 It then evaluates the script for the first matching 'on' handler
4245 (there many be zero or more) based on the return code from the `try`
4246 section. For example a normal +JIM_ERR+ error will be matched by
4247 an 'on error' handler.
4249 Finally, any +'finalscript'+ is evaluated.
4251 The result of this command is the result of +'tryscript'+, except in the
4252 case where an exception occurs in a matching 'on' handler script or the 'finally' script,
4253 in which case the result is this new exception.
4255 The specified +'returncodes'+ is a list of return codes either as names ('ok', 'error', 'break', etc.)
4258 If +'resultvar'+ and +'optsvar'+ are specified, they are set as for `catch` before evaluating
4259 the matching handler.
4266 } on {continue break} {} {
4267 error "Unexpected break/continue"
4268 } on error {msg opts} {
4269 puts "Dealing with error"
4270 return {*}$opts $msg
4272 puts "Got signal: $sig"
4277 If break, continue or error are raised, they are dealt with by the matching
4280 In any case, the file will be closed via the 'finally' clause.
4282 See also `throw`, `catch`, `return`, `error`.
4286 +*unknown* 'cmdName ?arg arg ...?'+
4288 This command doesn't actually exist as part of Tcl, but Tcl will
4289 invoke it if it does exist.
4291 If the Tcl interpreter encounters a command name for which there
4292 is not a defined command, then Tcl checks for the existence of
4293 a command named `unknown`.
4295 If there is no such command, then the interpreter returns an
4298 If the `unknown` command exists, then it is invoked with
4299 arguments consisting of the fully-substituted name and arguments
4300 for the original non-existent command.
4302 The `unknown` command typically does things like searching
4303 through library directories for a command procedure with the name
4304 +'cmdName'+, or expanding abbreviated command names to full-length,
4305 or automatically executing unknown commands as UNIX sub-processes.
4307 In some cases (such as expanding abbreviations) `unknown` will
4308 change the original command slightly and then (re-)execute it.
4309 The result of the `unknown` command is used as the result for
4310 the original non-existent command.
4314 +*unset ?-nocomplain? ?--?* '?name name ...?'+
4317 Each +'name'+ is a variable name, specified in any of the
4318 ways acceptable to the `set` command.
4320 If a +'name'+ refers to an element of an array, then that
4321 element is removed without affecting the rest of the array.
4323 If a +'name'+ consists of an array name with no parenthesized
4324 index, then the entire array is deleted.
4326 The `unset` command returns an empty string as result.
4328 An error occurs if any of the variables doesn't exist, unless '-nocomplain'
4329 is specified. The '--' argument may be specified to stop option processing
4330 in case the variable name may be '-nocomplain'.
4334 +*upcall* 'command ?args ...?'+
4336 May be used from within a proc defined as `local` `proc` in order to call
4337 the previous, hidden version of the same command.
4339 If there is no previous definition of the command, an error is returned.
4343 +*uplevel* '?level? command ?command ...?'+
4345 All of the +'command'+ arguments are concatenated as if they had
4346 been passed to `concat`; the result is then evaluated in the
4347 variable context indicated by +'level'+. `uplevel` returns
4348 the result of that evaluation. If +'level'+ is an integer, then
4349 it gives a distance (up the procedure calling stack) to move before
4350 executing the command. If +'level'+ consists of +\#+ followed by
4351 a number then the number gives an absolute level number. If +'level'+
4352 is omitted then it defaults to +1+. +'level'+ cannot be
4353 defaulted if the first +'command'+ argument starts with a digit or +#+.
4355 For example, suppose that procedure 'a' was invoked
4356 from top-level, and that it called 'b', and that 'b' called 'c'.
4357 Suppose that 'c' invokes the `uplevel` command. If +'level'+
4358 is +1+ or +#2+ or omitted, then the command will be executed
4359 in the variable context of 'b'. If +'level'+ is +2+ or +#1+
4360 then the command will be executed in the variable context of 'a'.
4362 If +'level'+ is '3' or +#0+ then the command will be executed
4363 at top-level (only global variables will be visible).
4364 The `uplevel` command causes the invoking procedure to disappear
4365 from the procedure calling stack while the command is being executed.
4366 In the above example, suppose 'c' invokes the command
4368 uplevel 1 {set x 43; d}
4370 where 'd' is another Tcl procedure. The `set` command will
4371 modify the variable 'x' in 'b's context, and 'd' will execute
4372 at level 3, as if called from 'b'. If it in turn executes
4377 then the `set` command will modify the same variable 'x' in 'b's
4378 context: the procedure 'c' does not appear to be on the call stack
4379 when 'd' is executing. The command `info level` may
4380 be used to obtain the level of the current procedure.
4382 `uplevel` makes it possible to implement new control
4383 constructs as Tcl procedures (for example, `uplevel` could
4384 be used to implement the `while` construct as a Tcl procedure).
4388 +*upvar* '?level? otherVar myVar ?otherVar myVar ...?'+
4390 This command arranges for one or more local variables in the current
4391 procedure to refer to variables in an enclosing procedure call or
4392 to global variables.
4394 +'level'+ may have any of the forms permitted for the `uplevel`
4395 command, and may be omitted if the first letter of the first +'otherVar'+
4396 isn't +#+ or a digit (it defaults to '1').
4398 For each +'otherVar'+ argument, `upvar` makes the variable
4399 by that name in the procedure frame given by +'level'+ (or at
4400 global level, if +'level'+ is +#0+) accessible
4401 in the current procedure by the name given in the corresponding
4404 The variable named by +'otherVar'+ need not exist at the time of the
4405 call; it will be created the first time +'myVar'+ is referenced, just like
4406 an ordinary variable.
4408 `upvar` may only be invoked from within procedures.
4410 `upvar` returns an empty string.
4412 The `upvar` command simplifies the implementation of call-by-name
4413 procedure calling and also makes it easier to build new control constructs
4415 For example, consider the following procedure:
4422 'add2' is invoked with an argument giving the name of a variable,
4423 and it adds two to the value of that variable.
4424 Although 'add2' could have been implemented using `uplevel`
4425 instead of `upvar`, `upvar` makes it simpler for 'add2'
4426 to access the variable in the caller's procedure frame.
4430 +*while* 'test body'+
4432 The +'while'+ command evaluates +'test'+ as an expression
4433 (in the same way that `expr` evaluates its argument).
4434 The value of the expression must be numeric; if it is non-zero
4435 then +'body'+ is executed by passing it to the Tcl interpreter.
4437 Once +'body'+ has been executed then +'test'+ is evaluated
4438 again, and the process repeats until eventually +'test'+
4439 evaluates to a zero numeric value. `continue`
4440 commands may be executed inside +'body'+ to terminate the current
4441 iteration of the loop, and `break`
4442 commands may be executed inside +'body'+ to cause immediate
4443 termination of the `while` command.
4445 The `while` command always returns an empty string.
4450 The following extensions may or may not be available depending upon
4451 what options were selected when Jim Tcl was built.
4454 posix: os.fork, os.wait, os.gethostname, os.getids, os.uptime
4455 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4457 Invokes 'fork(2)' and returns the result.
4459 +*os.wait -nohang* 'pid'+::
4460 Invokes waitpid(2), with WNOHANG if +-nohang+ is specified.
4461 Returns a list of 3 elements.
4463 {0 none 0} if -nohang is specified, and the process is still alive.
4465 {-1 error <error-description>} if the process does not exist or has already been waited for.
4467 {<pid> exit <exit-status>} if the process exited normally.
4469 {<pid> signal <signal-number>} if the process terminated on a signal.
4471 {<pid> other 0} otherwise (core dump, stopped, continued, etc.)
4473 +*os.gethostname*+::
4474 Invokes 'gethostname(3)' and returns the result.
4477 Returns the various user/group ids for the current process.
4480 uid 1000 euid 1000 gid 100 egid 100
4483 Returns the number of seconds since system boot. See description of 'uptime' in 'sysinfo(2)'.
4485 ANSI I/O (aio) and EVENTLOOP API
4486 --------------------------------
4487 Jim provides an alternative object-based API for I/O.
4489 See `open` and `socket` for commands which return an I/O handle.
4493 +$handle *accept* ?addrvar?+::
4494 Server socket only: Accept a connection and return stream.
4495 If +'addrvar'+ is specified, the address of the connected client is stored
4496 in the named variable in the form 'addr:port'. See `socket` for details.
4498 +$handle *buffering none|line|full*+::
4499 Sets the buffering mode of the stream.
4501 +$handle *close* ?r(ead)|w(rite)?+::
4503 The two-argument form is a "half-close" on a socket. See the +shutdown(2)+ man page.
4505 +$handle *copyto* 'tofd ?size?'+::
4506 Copy bytes to the file descriptor +'tofd'+. If +'size'+ is specified, at most
4507 that many bytes will be copied. Otherwise copying continues until the end
4508 of the input file. Returns the number of bytes actually copied.
4511 Returns 1 if stream is at eof
4513 +$handle *filename*+::
4514 Returns the original filename associated with the handle.
4515 Handles returned by `socket` give the socket type instead of a filename.
4520 +$handle *gets* '?var?'+::
4521 Read one line and return it or store it in the var
4523 +$handle *isatty*+::
4524 Returns 1 if the stream is a tty device.
4527 Apply a POSIX lock to the open file associated with the handle using
4529 The handle must be open for write access.
4530 Returns 1 if the lock was successfully obtained, 0 otherwise.
4531 An error occurs if the handle is not suitable for locking (e.g.
4532 if it is not open for write)
4534 +$handle *ndelay ?0|1?*+::
4535 Set O_NDELAY (if arg). Returns current/new setting.
4536 Note that in general ANSI I/O interacts badly with non-blocking I/O.
4539 +$handle *puts ?-nonewline?* 'str'+::
4540 Write the string, with newline unless -nonewline
4542 +$handle *read ?-nonewline?* '?len?'+::
4543 Read and return bytes from the stream. To eof if no len.
4545 +$handle *recvfrom* 'maxlen ?addrvar?'+::
4546 Receives a message from the handle via recvfrom(2) and returns it.
4547 At most +'maxlen'+ bytes are read.
4548 If +'addrvar'+ is specified, the sending address of the message is stored in
4549 the named variable in the form 'addr:port'. See `socket` for details.
4551 +$handle *seek* 'offset' *?start|current|end?*+::
4552 Seeks in the stream (default 'current')
4554 +$handle *sendto* 'str ?addr:?port'+::
4555 Sends the string, +'str'+, to the given address via the socket using sendto(2).
4556 This is intended for udp/dgram sockets and may give an error or behave in unintended
4557 ways for other handle types.
4558 Returns the number of bytes written.
4561 Flush the stream, then fsync(2) to commit any changes to storage.
4562 Only available on platforms that support fsync(2).
4565 Returns the current seek position
4567 +$handle *ssl* *?-server cert priv?*+::
4568 Initiates a SSL/TLS session and returns a new stream
4570 +$handle *unlock*+::
4571 Release a POSIX lock previously acquired by `aio lock`.
4573 +$handle *verify*+::
4574 Verifies the certificate of a SSL/TLS stream peer
4576 +*load_ssl_certs* 'dir'+::
4577 Loads SSL/TLS CA certificates for use during verification
4581 +*fconfigure* 'handle' *?-blocking 0|1? ?-buffering noneline|full? ?-translation* 'mode'?+::
4582 For compatibility with Tcl, a limited form of the `fconfigure`
4583 command is supported.
4584 * `fconfigure ... -blocking` maps to `aio ndelay`
4585 * `fconfigure ... -buffering` maps to `aio buffering`
4586 * `fconfigure ... -translation` is accepted but ignored
4589 eventloop: after, vwait, update
4590 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4592 The following commands allow a script to be invoked when the given condition occurs.
4593 If no script is given, returns the current script. If the given script is the empty, the
4596 +$handle *readable* '?readable-script?'+::
4597 Sets or returns the script for when the socket is readable.
4599 +$handle *writable* '?writable-script?'+::
4600 Sets or returns the script for when the socket is writable.
4602 +$handle *onexception* '?exception-script?'+::
4603 Sets or returns the script for when oob data received.
4605 For compatibility with 'Tcl', these may be prefixed with `fileevent`. e.g.
4608 +fileevent $handle *readable* '\...'+
4610 Time-based execution is also available via the eventloop API.
4613 Sleeps for the given number of milliseconds. No events are
4614 processed during this time.
4616 +*after* 'ms'|*idle* 'script ?script \...?'+::
4617 The scripts are concatenated and executed after the given
4618 number of milliseconds have elapsed. If 'idle' is specified,
4619 the script will run the next time the event loop is processed
4620 with `vwait` or `update`. The script is only run once and
4621 then removed. Returns an event id.
4623 +*after cancel* 'id|command'+::
4624 Cancels an `after` event with the given event id or matching
4625 command (script). Returns the number of milliseconds
4626 remaining until the event would have fired. Returns the
4627 empty string if no matching event is found.
4629 +*after info* '?id?'+::
4630 If +'id'+ is not given, returns a list of current `after`
4631 events. If +'id'+ is given, returns a list containing the
4632 associated script and either 'timer' or 'idle' to indicated
4633 the type of the event. An error occurs if +'id'+ does not
4636 +*vwait* 'variable'+::
4637 A call to `vwait` enters the eventloop. `vwait` processes
4638 events until the named (global) variable changes or all
4639 event handlers are removed. The variable need not exist
4640 beforehand. If there are no event handlers defined, `vwait`
4641 returns immediately.
4643 +*update ?idletasks?*+::
4644 A call to `update` enters the eventloop to process expired events, but
4645 no new events. If 'idletasks' is specified, only expired time events are handled,
4647 Returns once handlers have been run for all expired events.
4649 Scripts are executed at the global scope. If an error occurs during a handler script,
4650 an attempt is made to call (the user-defined command) `bgerror` with the details of the error.
4651 If the `bgerror` command does not exist, the error message details are printed to stderr instead.
4653 If a file event handler script generates an error, the handler is automatically removed
4654 to prevent infinite errors. (A time event handler is always removed after execution).
4657 Called when an event handler script generates an error. Note that the normal command resolution
4658 rules are used for bgerror. First the name is resolved in the current namespace, then in the
4663 Various socket types may be created.
4665 +*socket unix* 'path'+::
4666 A unix domain socket client.
4668 +*socket unix.server* 'path'+::
4669 A unix domain socket server.
4671 +*socket ?-ipv6? stream* 'addr:port'+::
4672 A TCP socket client. (See the forms for +'addr'+ below)
4674 +*socket ?-ipv6? stream.server* '?addr:?port'+::
4675 A TCP socket server (+'addr'+ defaults to +0.0.0.0+ for IPv4 or +[::]+ for IPv6).
4677 +*socket ?-ipv6? dgram* ?'addr:port'?+::
4678 A UDP socket client. If the address is not specified,
4679 the client socket will be unbound and 'sendto' must be used
4680 to indicated the destination.
4682 +*socket ?-ipv6? dgram.server* 'addr:port'+::
4683 A UDP socket server.
4686 A pipe. Note that unlike all other socket types, this command returns
4687 a list of two channels: {read write}
4690 A socketpair (see socketpair(2)). Like `socket pipe`, this command returns
4691 a list of two channels: {s1 s2}. These channels are both readable and writable.
4693 This command creates a socket connected (client) or bound (server) to the given
4696 The returned value is channel and may generally be used with the various file I/O
4697 commands (gets, puts, read, etc.), either as object-based syntax or Tcl-compatible syntax.
4699 . set f [socket stream www.google.com:80]
4701 . $f puts -nonewline "GET / HTTP/1.0\r\n\r\n"
4706 Server sockets, however support only 'accept', which is most useful in conjunction with
4709 set f [socket stream.server 80]
4711 set client [$f accept]
4714 $client puts -nonewline "HTTP/1.1 404 Not found\r\n"
4719 The address, +'addr'+, can be given in one of the following forms:
4721 1. For IPv4 socket types, an IPv4 address such as 192.168.1.1
4722 2. For IPv6 socket types, an IPv6 address such as [fe80::1234] or [::]
4725 Note that on many systems, listening on an IPv6 address such as [::] will
4726 also accept requests via IPv4.
4728 Where a hostname is specified, the +'first'+ returned address is used
4729 which matches the socket type is used.
4731 The special type 'pipe' isn't really a socket.
4733 lassign [socket pipe] r w
4735 # Must close $w after exec
4743 +*syslog* '?options? ?priority? message'+
4745 This command sends message to system syslog facility with given
4746 priority. Valid priorities are:
4748 emerg, alert, crit, err, error, warning, notice, info, debug
4750 If a message is specified, but no priority is specified, then a
4751 priority of info is used.
4753 By default, facility user is used and the value of global tcl variable
4754 argv0 is used as ident string. However, any of the following options
4755 may be specified before priority to control these parameters:
4757 +*-facility* 'value'+::
4758 Use specified facility instead of user. The following
4759 values for facility are recognized:
4761 authpriv, cron, daemon, kernel, lpr, mail, news, syslog, user,
4764 +*-ident* 'string'+::
4765 Use given string instead of argv0 variable for ident string.
4767 +*-options* 'integer'+::
4768 Set syslog options such as +LOG_CONS+, +LOG_NDELAY+. You should
4769 use numeric values of those from your system syslog.h file,
4770 because I haven't got time to implement yet another hash
4775 The optional 'pack' extension provides commands to encode and decode binary strings.
4777 +*pack* 'varName value' *-intle|-intbe|-floatle|-floatbe|-str* 'bitwidth ?bitoffset?'+::
4778 Packs the binary representation of +'value'+ into the variable
4779 +'varName'+. The value is packed according to the given type
4780 (integer/floating point/string, big-endian/little-endian), width and bit offset.
4781 The variable is created if necessary (like `append`).
4782 The variable is expanded if necessary.
4784 +*unpack* 'binvalue' *-intbe|-intle|-uintbe|-uintle|-floatbe|-floatle|-str* 'bitpos bitwidth'+::
4785 Unpacks bits from +'binvalue'+ at bit position +'bitpos'+ and with +'bitwidth'+.
4786 Interprets the value according to the type (integer/floating point/string, big-endian/little-endian
4787 and signed/unsigned) and returns it. For integer types, +'bitwidth'+
4788 may be up to the size of a Jim Tcl integer (typically 64 bits). For floating point types,
4789 +'bitwidth'+ may be 32 bits (for single precision numbers) or 64 bits (for double precision).
4790 For the string type, both the width and the offset must be on a byte boundary (multiple of 8). Attempting to
4791 access outside the length of the value will return 0 for integer types, 0.0 for floating point types
4792 or the empty string for the string type.
4796 The optional 'zlib' extension provides a Tcl-compatible subset of the `zlib` command.
4798 +*crc32* 'data' '?startValue?'+::
4799 Returns the CRC32 checksum of a buffer. Optionally, an initial value may be specified; this is most useful
4800 for calculating the checksum of chunked data read from a stream (for instance, a pipe).
4802 +*deflate* 'string' '?level?'+::
4803 Compresses a buffer and outputs a raw, Deflate-compressed stream. Optionally, a compression level (1-9) may
4804 be specified to choose the desired speed vs. compression rate ratio.
4806 +*inflate* 'data' '?bufferSize?'+::
4807 Decompresses a raw, Deflate-compressed stream. When the uncompressed data size is known and specified, memory
4808 allocation is more efficient. Otherwise, decomperssion is chunked and therefore slower.
4810 +*gzip* 'string' '?-level level?'+::
4811 Compresses a buffer and adds a gzip header.
4813 +*gunzip* 'data' '?-buffersize size?'+::
4814 Decompresses a gzip-compressed buffer. Decompression is chunked, with a default, small buffer size of 64K
4815 which guarantees lower memory footprint at the cost of speed. It is recommended to use a bigger size, on
4816 systems without a severe memory constraint.
4820 The optional, pure-Tcl 'binary' extension provides the Tcl-compatible `binary scan` and `binary format`
4821 commands based on the low-level `pack` and `unpack` commands.
4823 See the Tcl documentation at: http://www.tcl.tk/man/tcl8.5/TclCmd/binary.htm
4825 Note that 'binary format' with f/r/R specifiers (single-precision float) uses the value of Infinity
4826 in case of overflow.
4830 The optional, pure-Tcl 'oo' extension provides object-oriented (OO) support for Jim Tcl.
4832 See the online documentation (http://jim.tcl.tk/index.html/doc/www/www/documentation/oo/) for more details.
4834 +*class* 'classname ?baseclasses? classvars'+::
4835 Create a new class, +'classname'+, with the given dictionary
4836 (+'classvars'+) as class variables. These are the initial variables
4837 which all newly created objects of this class are initialised with.
4838 If a list of baseclasses is given, methods and instance variables
4841 +*super* 'method ?args \...?'+::
4842 From within a method, invokes the given method on the base class.
4843 Note that this will only call the last baseclass given.
4847 The optional, pure-Tcl 'tree' extension implements an OO, general purpose tree structure
4848 similar to that provided by tcllib ::struct::tree (http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/struct/struct_tree.html)
4850 A tree is a collection of nodes, where each node (except the root node) has a single parent
4851 and zero or more child nodes (ordered), as well as zero or more attribute/value pairs.
4854 Creates and returns a new tree object with a single node named "root".
4855 All operations on the tree are invoked through this object.
4858 Destroy the tree and all it's nodes. (Note that the tree will also
4859 be automatically garbage collected once it goes out of scope).
4861 +$tree *set* 'nodename key value'+::
4862 Set the value for the given attribute key.
4864 +$tree *lappend* 'nodename key value \...'+::
4865 Append to the (list) value(s) for the given attribute key, or set if not yet set.
4867 +$tree *keyexists* 'nodename key'+::
4868 Returns 1 if the given attribute key exists.
4870 +$tree *get* 'nodename key'+::
4871 Returns the value associated with the given attribute key.
4873 +$tree *getall* 'nodename'+::
4874 Returns the entire attribute dictionary associated with the given key.
4876 +$tree *depth* 'nodename'+::
4877 Returns the depth of the given node. The depth of "root" is 0.
4879 +$tree *parent* 'nodename'+::
4880 Returns the node name of the parent node, or "" for the root node.
4882 +$tree *numchildren* 'nodename'+::
4883 Returns the number of child nodes.
4885 +$tree *children* 'nodename'+::
4886 Returns a list of the child nodes.
4888 +$tree *next* 'nodename'+::
4889 Returns the next sibling node, or "" if none.
4891 +$tree *insert* 'nodename ?index?'+::
4892 Add a new child node to the given node. The index is a list index
4893 such as +3+ or +end-2+. The default index is +end+.
4894 Returns the name of the newly added node.
4896 +$tree *walk* 'nodename' *dfs|bfs* {'actionvar nodevar'} 'script'+::
4897 Walks the tree starting from the given node, either breadth first (+bfs+)
4898 depth first (+dfs+).
4899 The value +"enter"+ or +"exit"+ is stored in variable +'actionvar'+.
4900 The name of each node is stored in +'nodevar'+.
4901 The script is evaluated twice for each node, on entry and exit.
4904 Dumps the tree contents to stdout
4908 The optional tclprefix extension provides the Tcl8.6-compatible 'tcl::prefix' command
4909 (http://www.tcl.tk/man/tcl8.6/TclCmd/prefix.htm) for matching strings against a table
4910 of possible values (typically commands or options).
4912 +*tcl::prefix all* 'table string'+::
4913 Returns a list of all elements in +'table'+ that begin with the prefix +'string'+.
4915 +*tcl::prefix longest* 'table string'+::
4916 Returns the longest common prefix of all elements in +'table'+ that begin with the prefix +'string'+.
4918 +*tcl::prefix match* '?options? table string'+::
4919 If +'string'+ equals one element in +'table'+ or is a prefix to
4920 exactly one element, the matched element is returned. If not, the
4921 result depends on the +-error+ option.
4923 * +*-exact*+ Accept only exact matches.
4924 * +*-message* 'string'+ Use +'string'+ in the error message at a mismatch. Default is "option".
4925 * +*-error* 'options'+ The options are used when no match is found. If +'options'+ is
4926 empty, no error is generated and an empty string is returned.
4927 Otherwise the options are used as return options when
4928 generating the error message. The default corresponds to
4933 The optional history extension provides script access to the command line editing
4934 and history support available in 'jimsh'. See 'examples/jtclsh.tcl' for an example.
4935 Note: if line editing support is not available, `history getline` acts like `gets` and
4936 the remaining subcommands do nothing.
4938 +*history load* 'filename'+::
4939 Load history from a (text) file. If the file does not exist or is not readable,
4942 +*history getline* 'prompt ?varname?'+::
4943 Displays the given prompt and allows a line to be entered. Similarly to `gets`,
4944 if +'varname'+ is given, it receives the line and the length of the line is returned,
4945 or -1 on EOF. If +'varname'+ is not given, the line is returned directly.
4947 +*history add* 'line'+::
4948 Adds the given line to the history buffer.
4950 +*history save* 'filename'+::
4951 Saves the current history buffer to the given file.
4954 Displays the current history buffer to standard output.
4958 Provides namespace-related functions. See also: http://www.tcl.tk/man/tcl8.6/TclCmd/namespace.htm
4960 +*namespace code* 'script'+::
4961 Captures the current namespace context for later execution of
4962 the script +'script'+. It returns a new script in which script has
4963 been wrapped in a +*namespace inscope*+ command.
4965 +*namespace current*+::
4966 Returns the fully-qualified name for the current namespace.
4968 +*namespace delete* '?namespace ...?'+::
4969 Deletes all commands and variables with the given namespace prefixes.
4971 +*namespace eval* 'namespace arg ?arg...?'+::
4972 Activates a namespace called +'namespace'+ and evaluates some code in that context.
4974 +*namespace origin* 'command'+::
4975 Returns the fully-qualified name of the original command to which the imported command +'command'+ refers.
4977 +*namespace parent* ?namespace?+::
4978 Returns the fully-qualified name of the parent namespace for namespace +'namespace'+, if given, otherwise
4979 for the current namespace.
4981 +*namespace qualifiers* 'string'+::
4982 Returns any leading namespace qualifiers for +'string'+
4984 +*namespace tail* 'string'+::
4985 Returns the simple name at the end of a qualified string.
4987 +*namespace upvar* 'namespace ?arg...?'+::
4988 This command arranges for zero or more local variables in the current procedure to refer to variables in +'namespace'+
4990 +*namespace which* '?-command|-variable? name'+::
4991 Looks up +'name'+ as either a command (the default) or variable and returns its fully-qualified name.
4993 [[BuiltinVariables]]
4997 The following global variables are created automatically
5001 This variable is set by Jim as an array
5002 whose elements are the environment variables for the process.
5003 Reading an element will return the value of the corresponding
5004 environment variable.
5005 This array is initialised at startup from the `env` command.
5006 It may be modified and will affect the environment passed to
5007 commands invoked with `exec`.
5010 This variable is set by Jim as an array containing information
5011 about the platform on which Jim was built. Currently this includes
5012 'os' and 'platform'.
5015 This variable contains a list of paths to search for packages.
5016 It defaults to a location based on where jim is installed
5017 (e.g. +/usr/local/lib/jim+), but may be changed by +jimsh+
5018 or the embedding application. Note that +jimsh+ will consider
5019 the environment variable +$JIMLIB+ to be a list of colon-separated
5020 list of paths to add to +*auto_path*+.
5023 This variable holds the value of the -errorcode return
5024 option set by the most recent error that occurred in this
5025 interpreter. This list value represents additional information
5026 about the error in a form that is easy to process with
5027 programs. The first element of the list identifies a general
5028 class of errors, and determines the format of the rest of
5029 the list. The following formats for -errorcode return options
5030 are used by the Tcl core; individual applications may define
5031 additional formats. Currently only `exec` sets this variable.
5032 Otherwise it will be +NONE+.
5034 The following global variables are set by jimsh.
5036 +*tcl_interactive*+::
5037 This variable is set to 1 if jimsh is started in interactive mode
5041 This variable is set by Jim as an array containing information
5042 about the platform upon which Jim was built. The following is an
5043 example of the contents of this array.
5045 tcl_platform(byteOrder) = littleEndian
5046 tcl_platform(engine) = Jim
5047 tcl_platform(os) = Darwin
5048 tcl_platform(platform) = unix
5049 tcl_platform(pointerSize) = 8
5050 tcl_platform(threaded) = 0
5051 tcl_platform(wordSize) = 8
5052 tcl_platform(pathSeparator) = :
5055 If jimsh is invoked to run a script, this variable contains the name
5059 If jimsh is invoked to run a script, this variable contains a list
5060 of any arguments supplied to the script.
5063 If jimsh is invoked to run a script, this variable contains the number
5064 of arguments supplied to the script.
5067 The value of argv[0] when jimsh was invoked.
5069 CHANGES IN PREVIOUS RELEASES
5070 ----------------------------
5074 1. +platform_tcl()+ settings are now automatically determined
5075 2. Add aio `$handle filename`
5076 3. Add `info channels`
5077 4. The 'bio' extension is gone. Now `aio` supports 'copyto'.
5078 5. Add `exists` command
5079 6. Add the pure-Tcl 'oo' extension
5080 7. The `exec` command now only uses vfork(), not fork()
5081 8. Unit test framework is less verbose and more Tcl-compatible
5082 9. Optional UTF-8 support
5083 10. Optional built-in regexp engine for better Tcl compatibility and UTF-8 support
5084 11. Command line editing in interactive mode, e.g. 'jimsh'
5088 1. `source` now checks that a script is complete (.i.e. not missing a brace)
5089 2. 'info complete' now uses the real parser and so is 100% accurate
5090 3. Better access to live stack frames with 'info frame', `stacktrace` and `stackdump`
5091 4. `tailcall` no longer loses stack trace information
5092 5. Add `alias` and `curry`
5093 6. `lambda`, `alias` and `curry` are implemented via `tailcall` for efficiency
5094 7. `local` allows procedures to be deleted automatically at the end of the current procedure
5095 8. udp sockets are now supported for both clients and servers.
5096 9. vfork-based exec is now working correctly
5097 10. Add 'file tempfile'
5098 11. Add 'socket pipe'
5099 12. Enhance 'try ... on ... finally' to be more Tcl 8.6 compatible
5100 13. It is now possible to `return` from within `try`
5101 14. IPv6 support is now included
5103 16. Event handlers works better if an error occurs. eof handler has been removed.
5104 17. `exec` now sets $::errorCode, and catch sets opts(-errorcode) for exit status
5105 18. Command pipelines via open "|..." are now supported
5106 19. `pid` can now return pids of a command pipeline
5107 20. Add 'info references'
5108 21. Add support for 'after +'ms'+', 'after idle', 'after info', `update`
5109 22. `exec` now sets environment based on $::env
5111 24. Add support for 'lsort -index'
5115 1. Add support to `exec` for '>&', '>>&', '|&', '2>@1'
5116 2. Fix `exec` error messages when special token (e.g. '>') is the last token
5117 3. Fix `subst` handling of backslash escapes.
5118 4. Allow abbreviated options for `subst`
5119 5. Add support for `return`, `break`, `continue` in subst
5120 6. Many `expr` bug fixes
5121 7. Add support for functions in `expr` (e.g. int(), abs()), and also 'in', 'ni' list operations
5122 8. The variable name argument to `regsub` is now optional
5123 9. Add support for 'unset -nocomplain'
5124 10. Add support for list commands: `lassign`, `lrepeat`
5125 11. Fully-functional `lsearch` is now implemented
5126 12. Add 'info nameofexecutable' and 'info returncodes'
5127 13. Allow `catch` to determine what return codes are caught
5128 14. Allow `incr` to increment an unset variable by first setting to 0
5129 15. Allow 'args' and optional arguments to the left or required arguments in `proc`
5131 17. Add 'try ... finally' command
5137 Copyright 2005 Salvatore Sanfilippo <antirez@invece.org>
5138 Copyright 2005 Clemens Hintze <c.hintze@gmx.net>
5139 Copyright 2005 patthoyts - Pat Thoyts <patthoyts@users.sf.net>
5140 Copyright 2008 oharboe - Oyvind Harboe - oyvind.harboe@zylin.com
5141 Copyright 2008 Andrew Lunn <andrew@lunn.ch>
5142 Copyright 2008 Duane Ellis <openocd@duaneellis.com>
5143 Copyright 2008 Uwe Klein <uklein@klein-messgeraete.de>
5144 Copyright 2009 Steve Bennett <steveb@workware.net.au>
5147 Redistribution and use in source and binary forms, with or without
5148 modification, are permitted provided that the following conditions
5150 1. Redistributions of source code must retain the above copyright
5151 notice, this list of conditions and the following disclaimer.
5152 2. Redistributions in binary form must reproduce the above
5153 copyright notice, this list of conditions and the following
5154 disclaimer in the documentation and/or other materials
5155 provided with the distribution.
5157 THIS SOFTWARE IS PROVIDED BY THE JIM TCL PROJECT ``AS IS'' AND ANY
5158 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
5159 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
5160 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
5161 JIM TCL PROJECT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
5162 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
5163 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
5164 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
5165 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
5166 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
5167 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
5168 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
5170 The views and conclusions contained in the software and documentation
5171 are those of the authors and should not be interpreted as representing
5172 official policies, either expressed or implied, of the Jim Tcl Project.