6 Jim Tcl v0.71 - overview of the Jim tool command language facilities
16 jimsh -e '<immediate-script>'
21 * <<CommandIndex,Command Reference>>
22 * <<OperatorPrecedence,Operator Precedence>>
23 * <<BuiltinVariables, Builtin Variables>>
24 * <<BackslashSequences, Backslash Sequences>>
28 Jim is a reimplementation of Tcl, combining some features from
29 earlier, smaller versions of Tcl (6.x) as well as more modern
30 features from later versions of Tcl (7.x, 8.x). It also has some some
31 entirely new features not available in any version of Tcl.
33 This version is about double the size of "tinytcl" (6.8), depending upon
34 the features selected, but is significantly faster and has many new features.
36 Note that most of this man page is the original 6.8 Tcl man page, with
37 changes made for differences with Jim.
39 The major differences with Tcl 8.5/8.6 are:
41 1. Object-based I/O (aio), but with a Tcl-compatibility layer
42 2. I/O: Support for sockets and pipes including udp, unix domain sockets and IPv6
44 4. Support for references ('ref'/'getref'/'setref') and garbage collection
45 5. Builtin dictionary type ('dict') with some limitations compared to Tcl 8.6
46 6. 'env' command to access environment variables
47 7. 'os.fork', 'os.wait', 'os.uptime', 'rand'
48 8. Much better error reporting. 'info stacktrace' as a replacement for 'errorInfo', 'errorCode'
49 9. Support for "static" variables in procedures
50 10. Namespaces are not support
51 11. Variable traces are not supported
52 12. Direct command line editing rather than the 'history' command
53 13. Expression shorthand syntax: +$(...)+
58 Changes between 0.70 and 0.71
59 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
60 1. Allow 'args' to be renamed in procs
61 2. Add +$(...)+ shorthand syntax for expressions
62 3. Add automatic reference variables in procs with +&var+ syntax
63 4. Support +jimsh --version+
64 5. Additional variables in +tcl_platform()+
65 6. 'local' procs now push existing commands and 'upcall' can call them
66 7. Add 'loop' command (TclX compatible)
67 8. Add 'aio' 'buffering' command
68 9. 'info complete' can now return the missing character
69 10. 'binary format' and 'binary scan' are now (optionally) supported
70 11. Add 'string byterange'
71 12. Built-in regexp now support non-greedy repetition (*?, +?, ??)
73 Changes between 0.63 and 0.70
74 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
75 1. +platform_tcl()+ settings are now automatically determined
76 2. Add aio '$handle filename'
77 3. Add 'info channels'
78 4. The 'bio' extension is gone. Now 'aio' supports 'copyto'.
79 5. Add 'exists' command
80 6. Add the pure-Tcl 'oo' extension
81 7. The 'exec' command now only uses vfork(), not fork()
82 8. Unit test framework is less verbose and more Tcl-compatible
83 9. Optional UTF-8 support
84 10. Optional built-in regexp engine for better Tcl compatibility and UTF-8 support
85 11. Command line editing in interactive mode, e.g. 'jimsh'
89 Tcl stands for 'tool command language' and is pronounced 'tickle.'
90 It is actually two things: a language and a library.
92 First, Tcl is a simple textual language, intended primarily for
93 issuing commands to interactive programs such as text editors,
94 debuggers, illustrators, and shells. It has a simple syntax and is also
95 programmable, so Tcl users can write command procedures to provide more
96 powerful commands than those in the built-in set.
98 Second, Tcl is a library package that can be embedded in application
99 programs. The Tcl library consists of a parser for the Tcl language,
100 routines to implement the Tcl built-in commands, and procedures that
101 allow each application to extend Tcl with additional commands specific
102 to that application. The application program generates Tcl commands and
103 passes them to the Tcl parser for execution. Commands may be generated
104 by reading characters from an input source, or by associating command
105 strings with elements of the application's user interface, such as menu
106 entries, buttons, or keystrokes.
108 When the Tcl library receives commands it parses them into component
109 fields and executes built-in commands directly. For commands implemented
110 by the application, Tcl calls back to the application to execute the
111 commands. In many cases commands will invoke recursive invocations of the
112 Tcl interpreter by passing in additional strings to execute (procedures,
113 looping commands, and conditional commands all work in this way).
115 An application program gains three advantages by using Tcl for its command
116 language. First, Tcl provides a standard syntax: once users know Tcl,
117 they will be able to issue commands easily to any Tcl-based application.
118 Second, Tcl provides programmability. All a Tcl application needs
119 to do is to implement a few application-specific low-level commands.
120 Tcl provides many utility commands plus a general programming interface
121 for building up complex command procedures. By using Tcl, applications
122 need not re-implement these features.
124 Third, Tcl can be used as a common language for communicating between
125 applications. Inter-application communication is not built into the
126 Tcl core described here, but various add-on libraries, such as the Tk
127 toolkit, allow applications to issue commands to each other. This makes
128 it possible for applications to work together in much more powerful ways
129 than was previously possible.
131 Fourth, Jim Tcl includes a command processor, +jimsh+, which can be
132 used to run standalone Tcl scripts, or to run Tcl commands interactively.
134 This manual page focuses primarily on the Tcl language. It describes
135 the language syntax and the built-in commands that will be available
136 in any application based on Tcl. The individual library procedures are
137 described in more detail in separate manual pages, one per procedure.
139 JIMSH COMMAND INTERPRETER
140 -------------------------
141 A simple, but powerful command processor, +jimsh+, is part of Jim Tcl.
142 It may be invoked in interactive mode as:
146 or to process the Tcl script in a file with:
150 It may also be invoked to execute an immediate script with:
156 Interactive mode reads Tcl commands from standard input, evaluates
157 those commands and prints the results.
160 Welcome to Jim version 0.71, Copyright (c) 2005-8 Salvatore Sanfilippo
163 . lsort [info commands p*]
164 package parray pid popen proc puts pwd
165 . foreach i {a b c} {
172 invalid command name "bad"
176 If +jimsh+ is configured with line editing (it is by default) and a VT-100-compatible
177 terminal is detected, Emacs-style line editing commands are available, including:
178 arrow keys, +\^W+ to erase a word, +\^U+ to erase the line, +^R+ for reverse incremental search
179 in history. Additionally, the +h+ command may be used to display the command history.
181 Command line history is automatically saved and loaded from +~/.jim_history+
183 In interactive mode, +jimsh+ automatically runs the script +~/.jimrc+ at startup
188 The central data structure in Tcl is an interpreter (C type 'Jim_Interp').
189 An interpreter consists of a set of command bindings, a set of variable
190 values, and a few other miscellaneous pieces of state. Each Tcl command
191 is interpreted in the context of a particular interpreter.
193 Some Tcl-based applications will maintain multiple interpreters
194 simultaneously, each associated with a different widget or portion of
195 the application. Interpreters are relatively lightweight structures.
196 They can be created and deleted quickly, so application programmers should
197 feel free to use multiple interpreters if that simplifies the application.
201 Tcl supports only one type of data: strings. All commands, all arguments
202 to commands, all command results, and all variable values are strings.
204 Where commands require numeric arguments or return numeric results,
205 the arguments and results are passed as strings. Many commands expect
206 their string arguments to have certain formats, but this interpretation
207 is up to the individual commands. For example, arguments often contain
208 Tcl command strings, which may get executed as part of the commands.
209 The easiest way to understand the Tcl interpreter is to remember that
210 everything is just an operation on a string. In many cases Tcl constructs
211 will look similar to more structured constructs from other languages.
212 However, the Tcl constructs are not structured at all; they are just
213 strings of characters, and this gives them a different behaviour than
214 the structures they may look like.
216 Although the exact interpretation of a Tcl string depends on who is doing
217 the interpretation, there are three common forms that strings take:
218 commands, expressions, and lists. The major sections below discuss
219 these three forms in more detail.
223 The Tcl language has syntactic similarities to both the Unix shells
224 and Lisp. However, the interpretation of commands is different
225 in Tcl than in either of those other two systems.
226 A Tcl command string consists of one or more commands separated
227 by newline characters or semi-colons.
228 Each command consists of a collection of fields separated by
229 white space (spaces or tabs).
230 The first field must be the name of a command, and the
231 additional fields, if any, are arguments that will be passed to
232 that command. For example, the command:
236 has three fields: the first, 'set', is the name of a Tcl command, and
237 the last two, 'a' and '22', will be passed as arguments to
238 the 'set' command. The command name may refer either to a built-in
239 Tcl command, an application-specific command bound in with the library
240 procedure 'Jim_CreateCommand', or a command procedure defined with the
241 'proc' built-in command.
243 Arguments are passed literally as text strings. Individual commands may
244 interpret those strings in any fashion they wish. The 'set' command,
245 for example, will treat its first argument as the name of a variable
246 and its second argument as a string value to assign to that variable.
247 For other commands arguments may be interpreted as integers, lists,
248 file names, or Tcl commands.
250 Command names should normally be typed completely (e.g. no abbreviations).
251 However, if the Tcl interpreter cannot locate a command it invokes a
252 special command named 'unknown' which attempts to find or create the
255 For example, at many sites 'unknown' will search through library
256 directories for the desired command and create it as a Tcl procedure if
257 it is found. The 'unknown' command often provides automatic completion
258 of abbreviated commands, but usually only for commands that were typed
261 It's probably a bad idea to use abbreviations in command scripts and
262 other forms that will be re-used over time: changes to the command set
263 may cause abbreviations to become ambiguous, resulting in scripts that
268 If the first non-blank character in a command is +\#+, then everything
269 from the +#+ up through the next newline character is treated as
270 a comment and ignored. When comments are embedded inside nested
271 commands (e.g. fields enclosed in braces) they must have properly-matched
272 braces (this is necessary because when Tcl parses the top-level command
273 it doesn't yet know that the nested field will be used as a command so
274 it cannot process the nested comment character as a comment).
276 GROUPING ARGUMENTS WITH DOUBLE-QUOTES
277 -------------------------------------
278 Normally each argument field ends at the next white space, but
279 double-quotes may be used to create arguments with embedded space.
281 If an argument field begins with a double-quote, then the argument isn't
282 terminated by white space (including newlines) or a semi-colon (see below
283 for information on semi-colons); instead it ends at the next double-quote
284 character. The double-quotes are not included in the resulting argument.
285 For example, the command
287 set a "This is a single argument"
289 will pass two arguments to 'set': 'a' and 'This is a single argument'.
291 Within double-quotes, command substitutions, variable substitutions,
292 and backslash substitutions still occur, as described below. If the
293 first character of a command field is not a quote, then quotes receive
294 no special interpretation in the parsing of that field.
296 GROUPING ARGUMENTS WITH BRACES
297 ------------------------------
298 Curly braces may also be used for grouping arguments. They are similar
299 to quotes except for two differences. First, they nest; this makes them
300 easier to use for complicated arguments like nested Tcl command strings.
301 Second, the substitutions described below for commands, variables, and
302 backslashes do *not* occur in arguments enclosed in braces, so braces
303 can be used to prevent substitutions where they are undesirable.
305 If an argument field begins with a left brace, then the argument ends
306 at the matching right brace. Tcl will strip off the outermost layer
307 of braces and pass the information between the braces to the command
308 without any further modification. For example, in the command
310 set a {xyz a {b c d}}
312 the 'set' command will receive two arguments: 'a'
315 When braces or quotes are in effect, the matching brace or quote need
316 not be on the same line as the starting quote or brace; in this case
317 the newline will be included in the argument field along with any other
318 characters up to the matching brace or quote. For example, the 'eval'
319 command takes one argument, which is a command string; 'eval' invokes
320 the Tcl interpreter to execute the command string. The command
327 will assign the value '22' to 'a' and '33' to 'b'.
329 If the first character of a command field is not a left
330 brace, then neither left nor right
331 braces in the field will be treated specially (except as part of
332 variable substitution; see below).
334 COMMAND SUBSTITUTION WITH BRACKETS
335 ----------------------------------
336 If an open bracket occurs in a field of a command, then command
337 substitution occurs (except for fields enclosed in braces). All of the
338 text up to the matching close bracket is treated as a Tcl command and
339 executed immediately. Then the result of that command is substituted
340 for the bracketed text. For example, consider the command
344 When the 'set' command has only a single argument, it is the name of a
345 variable and 'set' returns the contents of that variable. In this case,
346 if variable 'b' has the value 'foo', then the command above is equivalent
351 Brackets can be used in more complex ways. For example, if the variable
352 'b' has the value 'foo' and the variable 'c' has the value 'gorp',
355 set a xyz[set b].[set c]
357 is equivalent to the command
362 A bracketed command may contain multiple commands separated by newlines
363 or semi-colons in the usual fashion. In this case the value of the last
364 command is used for substitution. For example, the command
369 is equivalent to the command
374 If a field is enclosed in braces then the brackets and the characters
375 between them are not interpreted specially; they are passed through to
376 the argument verbatim.
378 VARIABLE SUBSTITUTION WITH $
379 ----------------------------
380 The dollar sign ('$') may be used as a special shorthand form for
381 substituting variable values. If '$' appears in an argument that isn't
382 enclosed in braces then variable substitution will occur. The characters
383 after the '$', up to the first character that isn't a number, letter,
384 or underscore, are taken as a variable name and the string value of that
385 variable is substituted for the name.
387 For example, if variable 'foo' has the value 'test', then the command
391 is equivalent to the command
395 There are two special forms for variable substitution. If the next
396 character after the name of the variable is an open parenthesis, then
397 the variable is assumed to be an array name, and all of the characters
398 between the open parenthesis and the next close parenthesis are taken as
399 an index into the array. Command substitutions and variable substitutions
400 are performed on the information between the parentheses before it is
403 For example, if the variable 'x' is an array with one element named
404 'first' and value '87' and another element named '14' and value 'more',
407 set a xyz$x(first)zyx
409 is equivalent to the command
413 If the variable 'index' has the value '14', then the command
415 set a xyz$x($index)zyx
417 is equivalent to the command
421 For more information on arrays, see VARIABLES AND ARRAYS below.
423 The second special form for variables occurs when the dollar sign is
424 followed by an open curly brace. In this case the variable name consists
425 of all the characters up to the next curly brace.
427 Array references are not possible in this form: the name between braces
428 is assumed to refer to a scalar variable. For example, if variable
429 'foo' has the value 'test', then the command
433 is equivalent to the command
438 Variable substitution does not occur in arguments that are enclosed in
439 braces: the dollar sign and variable name are passed through to the
442 The dollar sign abbreviation is simply a shorthand form. '$a' is
443 completely equivalent to '[set a]'; it is provided as a convenience
446 SEPARATING COMMANDS WITH SEMI-COLONS
447 ------------------------------------
448 Normally, each command occupies one line (the command is terminated by a
449 newline character). However, semi-colon (';') is treated as a command
450 separator character; multiple commands may be placed on one line by
451 separating them with a semi-colon. Semi-colons are not treated as
452 command separators if they appear within curly braces or double-quotes.
454 BACKSLASH SUBSTITUTION
455 ----------------------
456 Backslashes may be used to insert non-printing characters into command
457 fields and also to insert special characters like braces and brackets
458 into fields without them being interpreted specially as described above.
460 The backslash sequences understood by the Tcl interpreter are
461 listed below. In each case, the backslash
462 sequence is replaced by the given character:
463 [[BackslashSequences]]
474 Carriage-return (0xd).
497 +{backslash}<space>+::
498 Space ( ): doesn't terminate argument.
501 Semi-colon: doesn't terminate command.
506 +{backslash}<newline>+::
507 Nothing: this joins two lines together
508 into a single line. This backslash feature is unique in that
509 it will be applied even when the sequence occurs within braces.
511 +{backslash}{backslash}+::
512 Backslash ('{backslash}').
515 The digits *ddd* (one, two, or three of them) give the octal value of
516 the character. Note that Jim supports null characters in strings.
518 +{backslash}*unnnn*+::
519 The hex digits *nnnn* (between one and four of them) give a unicode codepoint.
520 The UTF-8 encoding of the codepoint is inserted.
522 For example, in the command
526 the second argument to 'set' will be '{x[ yza'.
528 If a backslash is followed by something other than one of the options
529 described above, then the backslash is transmitted to the argument
530 field without any special processing, and the Tcl scanner continues
531 normal processing with the next character. For example, in the
536 The first argument to 'set' will be '{backslash}*a' and the second
537 argument will be '{backslash}{foo'.
539 If an argument is enclosed in braces, then backslash sequences inside
540 the argument are parsed but no substitution occurs (except for
541 backslash-newline): the backslash
542 sequence is passed through to the argument as is, without making
543 any special interpretation of the characters in the backslash sequence.
544 In particular, backslashed braces are not counted in locating the
545 matching right brace that terminates the argument.
551 the second argument to 'set' will be '{backslash}{abc'.
553 This backslash mechanism is not sufficient to generate absolutely
554 any argument structure; it only covers the
555 most common cases. To produce particularly complicated arguments
556 it is probably easiest to use the 'format' command along with
557 command substitution.
559 STRING AND LIST INDEX SPECIFICATIONS
560 ------------------------------------
562 Many string and list commands take one or more 'index' parameters which
563 specify a position in the string relative to the start or end of the string/list.
565 The index may be one of the following forms:
568 A simple integer, where '0' refers to the first element of the string
571 `integer+integer` or::
573 The sum or difference of the two integers. e.g. +2+3+ refers to the 5th element.
574 This is useful when used with (e.g.) +$i+1+ rather than the more verbose
578 The last element of the string or list.
581 The 'nth-from-last' element of the string or list.
585 1. A command is just a string.
586 2. Within a string commands are separated by newlines or semi-colons
587 (unless the newline or semi-colon is within braces or brackets
589 3. A command consists of fields. The first field is the name of the command.
590 The other fields are strings that are passed to that command as arguments.
591 4. Fields are normally separated by white space.
592 5. Double-quotes allow white space and semi-colons to appear within
594 Command substitution, variable substitution, and backslash substitution
595 still occur inside quotes.
596 6. Braces defer interpretation of special characters.
597 If a field begins with a left brace, then it consists of everything
598 between the left brace and the matching right brace. The
599 braces themselves are not included in the argument.
600 No further processing is done on the information between the braces
601 except that backslash-newline sequences are eliminated.
602 7. If a field doesn't begin with a brace then backslash,
603 variable, and command substitution are done on the field. Only a
604 single level of processing is done: the results of one substitution
605 are not scanned again for further substitutions or any other
606 special treatment. Substitution can
607 occur on any field of a command, including the command name
608 as well as the arguments.
609 8. If the first non-blank character of a command is a +\#+, everything
610 from the +#+ up through the next newline is treated as a comment
615 The second major interpretation applied to strings in Tcl is
616 as expressions. Several commands, such as 'expr', 'for',
617 and 'if', treat one or more of their arguments as expressions
618 and call the Tcl expression processors ('Jim_ExprLong',
619 'Jim_ExprBoolean', etc.) to evaluate them.
621 The operators permitted in Tcl expressions are a subset of
622 the operators permitted in C expressions, and they have the
623 same meaning and precedence as the corresponding C operators.
624 Expressions almost always yield numeric results
625 (integer or floating-point values).
626 For example, the expression
632 Tcl expressions differ from C expressions in the way that
633 operands are specified, and in that Tcl expressions support
634 non-numeric operands and string comparisons.
636 A Tcl expression consists of a combination of operands, operators,
639 White space may be used between the operands and operators and
640 parentheses; it is ignored by the expression processor.
641 Where possible, operands are interpreted as integer values.
643 Integer values may be specified in decimal (the normal case), in octal (if the
644 first character of the operand is '0'), or in hexadecimal (if the first
645 two characters of the operand are '0x').
647 If an operand does not have one of the integer formats given
648 above, then it is treated as a floating-point number if that is
649 possible. Floating-point numbers may be specified in any of the
650 ways accepted by an ANSI-compliant C compiler (except that the
651 'f', 'F', 'l', and 'L' suffixes will not be permitted in
652 most installations). For example, all of the
653 following are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16.
655 If no numeric interpretation is possible, then an operand is left
656 as a string (and only a limited set of operators may be applied to
659 1. Operands may be specified in any of the following ways:
661 2. As a numeric value, either integer or floating-point.
663 3. As a Tcl variable, using standard '$' notation.
664 The variable's value will be used as the operand.
666 4. As a string enclosed in double-quotes.
667 The expression parser will perform backslash, variable, and
668 command substitutions on the information between the quotes,
669 and use the resulting value as the operand
671 5. As a string enclosed in braces.
672 The characters between the open brace and matching close brace
673 will be used as the operand without any substitutions.
675 6. As a Tcl command enclosed in brackets.
676 The command will be executed and its result will be used as
679 Where substitutions occur above (e.g. inside quoted strings), they
680 are performed by the expression processor.
681 However, an additional layer of substitution may already have
682 been performed by the command parser before the expression
683 processor was called.
685 As discussed below, it is usually best to enclose expressions
686 in braces to prevent the command parser from performing substitutions
689 For some examples of simple expressions, suppose the variable 'a' has
690 the value 3 and the variable 'b' has the value 6. Then the expression
691 on the left side of each of the lines below will evaluate to the value
692 on the right side of the line:
697 {word one} < "word $a" 0
699 The valid operators are listed below, grouped in decreasing order
701 [[OperatorPrecedence]]
702 `int() double() round() abs()`::
704 int() converts the numeric argument to an integer by truncating down.
705 double() converts the numeric argument to floating point.
706 round() converts the numeric argument to the closest integer value.
707 abs() takes the absolute value of the numeric argument.
709 `sin() cos() tan() asin() acos() atan() sinh() cosh() tanh() ceil() floor() exp() log() log10() sqrt()`::
710 Unary math functions.
711 If Jim is compiled with math support, these functions are available.
714 Unary minus, unary plus, bit-wise NOT, logical NOT. None of these operands
715 may be applied to string operands, and bit-wise NOT may be
716 applied only to integers.
719 Power. e.g. pow(). If Jim is compiled with math support, supports doubles and
720 integers. Otherwise supports integers only.
723 Multiply, divide, remainder. None of these operands may be
724 applied to string operands, and remainder may be applied only
728 Add and subtract. Valid for any numeric operands.
731 Left and right shift, left and right rotate. Valid for integer operands only.
734 Boolean less, greater, less than or equal, and greater than or equal.
735 Each operator produces 1 if the condition is true, 0 otherwise.
736 These operators may be applied to strings as well as numeric operands,
737 in which case string comparison is used.
740 Boolean equal and not equal. Each operator produces a zero/one result.
741 Valid for all operand types. *Note* that values will be converted to integers
742 if possible, then floating point types, and finally strings will be compared.
743 It is recommended that 'eq' and 'ne' should be used for string comparison.
746 String equal and not equal. Uses the string value directly without
747 attempting to convert to a number first.
750 String in list and not in list. For 'in', result is 1 if the left operand (as a string)
751 is contained in the right operand (as a list), or 0 otherwise. The result for
752 '{$a ni $list}' is equivalent to '{!($a in $list)}'.
755 Bit-wise AND. Valid for integer operands only.
758 Bit-wise OR. Valid for integer operands only.
761 Bit-wise exclusive OR. Valid for integer operands only.
764 Logical AND. Produces a 1 result if both operands are non-zero, 0 otherwise.
765 Valid for numeric operands only (integers or floating-point).
768 Logical OR. Produces a 0 result if both operands are zero, 1 otherwise.
769 Valid for numeric operands only (integers or floating-point).
772 If-then-else, as in C. If *x*
773 evaluates to non-zero, then the result is the value of *y*.
774 Otherwise the result is the value of *z*.
775 The *x* operand must have a numeric value, while *y* and *z* can
778 See the C manual for more details on the results
779 produced by each operator.
780 All of the binary operators group left-to-right within the same
781 precedence level. For example, the expression
787 The '&&', '||', and '?:' operators have 'lazy
788 evaluation', just as in C,
789 which means that operands are not evaluated if they are
790 not needed to determine the outcome. For example, in
794 only one of '[a]' or '[b]' will actually be evaluated,
795 depending on the value of '$v'.
797 All internal computations involving integers are done with the C
798 type 'long long' if available, or 'long' otherwise, and all internal
799 computations involving floating-point are done with the C type
802 When converting a string to floating-point, exponent overflow is
803 detected and results in a Tcl error.
804 For conversion to integer from string, detection of overflow depends
805 on the behaviour of some routines in the local C library, so it should
806 be regarded as unreliable.
807 In any case, overflow and underflow are generally not detected
808 reliably for intermediate results.
810 Conversion among internal representations for integer, floating-point,
811 and string operands is done automatically as needed.
812 For arithmetic computations, integers are used until some
813 floating-point number is introduced, after which floating-point is used.
818 yields the result 1, while
821 5 / ( [string length "abcd"] + 0.0 )
823 both yield the result 1.25.
825 String values may be used as operands of the comparison operators,
826 although the expression evaluator tries to do comparisons as integer
827 or floating-point when it can.
828 If one of the operands of a comparison is a string and the other
829 has a numeric value, the numeric operand is converted back to
830 a string using the C 'sprintf' format specifier
831 '%d' for integers and '%g' for floating-point values.
832 For example, the expressions
837 both evaluate to 1. The first comparison is done using integer
838 comparison, and the second is done using string comparison after
839 the second operand is converted to the string '18'.
841 In general it is safest to enclose an expression in braces when
842 entering it in a command: otherwise, if the expression contains
843 any white space then the Tcl interpreter will split it
844 among several arguments. For example, the command
848 results in three arguments being passed to 'expr': '$a',
849 '+', and '$b'. In addition, if the expression isn't in braces
850 then the Tcl interpreter will perform variable and command substitution
851 immediately (it will happen in the command parser rather than in
852 the expression parser). In many cases the expression is being
853 passed to a command that will evaluate the expression later (or
854 even many times if, for example, the expression is to be used to
855 decide when to exit a loop). Usually the desired goal is to re-do
856 the variable or command substitutions each time the expression is
857 evaluated, rather than once and for all at the beginning. For example,
860 for {set i 1} $i<=10 {incr i} {...} *** WRONG ***
862 is probably intended to iterate over all values of `i` from 1 to 10.
863 After each iteration of the body of the loop, 'for' will pass
864 its second argument to the expression evaluator to see whether or not
865 to continue processing. Unfortunately, in this case the value of `i`
866 in the second argument will be substituted once and for all when the
867 'for' command is parsed. If `i` was 0 before the 'for'
868 command was invoked then for's second argument will be `0<=10`
869 which will always evaluate to 1, even though `i` eventually
870 becomes greater than 10. In the above case the loop will never
871 terminate. Instead, the expression should be placed in braces:
873 for {set i 1} {$i<=10} {incr i} {...} *** RIGHT ***
875 This causes the substitution of 'i'
876 to be delayed; it will be re-done each time the expression is
877 evaluated, which is the desired result.
881 The third major way that strings are interpreted in Tcl is as lists.
882 A list is just a string with a list-like structure
883 consisting of fields separated by white space. For example, the
888 is a list with four elements or fields.
889 Lists have the same basic structure as command strings, except
890 that a newline character in a list is treated as a field separator
891 just like space or tab. Conventions for braces and quotes
892 and backslashes are the same for lists as for commands. For example,
897 is a list with three elements: +a+, +b c+, and +d e {f g h}+.
899 Whenever an element is extracted from a list, the same rules about
900 braces and quotes and backslashes are applied as for commands. Thus in
901 the example above when the third element is extracted from the list,
906 (when the field was extracted, all that happened was to strip off
907 the outermost layer of braces). Command substitution and
908 variable substitution are never
909 made on a list (at least, not by the list-processing commands; the
910 list can always be passed to the Tcl interpreter for evaluation).
912 The Tcl commands 'concat', 'foreach', 'lappend', 'lindex', 'linsert',
913 'list', 'llength', 'lrange', 'lreplace', 'lsearch', and 'lsort' allow
914 you to build lists, extract elements from them, search them, and perform
915 other list-related functions.
917 Advanced list commands include 'lrepeat', 'lreverse', 'lmap', 'lassign', 'lset'.
922 A new addition to Tcl 8.5 is the ability to expand a list into separate
923 arguments. Support for this feature is also available in Jim.
925 Consider the following attempt to exec a list:
930 This will attempt to exec the a command named "ls -l", which will clearly not
931 work. Typically eval and concat are required to solve this problem, however
932 it can be solved much more easily with '\{*\}'.
936 This will expand the following argument into individual elements and then evaluate
937 the resulting command.
939 Note that the official Tcl syntax is '\{*\}', however '\{expand\}' is retained
940 for backward compatibility with experimental versions of this feature.
944 Tcl provides two commands that support string matching using regular
945 expressions, 'regexp' and 'regsub', as well as 'switch -regexp' and
948 Regular expressions may be implemented one of two ways. Either using the system's C library
949 POSIX regular expression support, or using the built-in regular expression engine.
950 The differences between these are described below.
952 *NOTE* Tcl 7.x and 8.x use perl-style Advanced Regular Expressions (+ARE+).
954 POSIX Regular Expressions
955 ~~~~~~~~~~~~~~~~~~~~~~~~~
956 If the system supports POSIX regular expressions, and UTF-8 support is not enabled,
957 this support will be used by default. The type of regular expressions supported are
958 Extended Regular Expressions (+ERE+) rather than Basic Regular Expressions (+BRE+).
959 See REG_EXTENDED in the documentation.
961 Using the system-supported POSIX regular expressions will typically
962 make for the smallest code size, but some features such as UTF-8
963 and +{backslash}w+, +{backslash}d+, +{backslash}s+ are not supported.
965 See regex(3) and regex(7) for full details.
967 Jim built-in Regular Expressions
968 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
969 The Jim built-in regulare expression engine may be selected with +./configure --with-jim-regexp+
970 or it will be selected automatically if UTF-8 support is enabled.
972 This engine supports UTF-8 as well as some +ARE+ features. The differences with both Tcl 7.x/8.x
973 and POSIX are highlighted below.
975 1. UTF-8 strings and patterns are both supported
976 2. Supported character classes: +[:alnum:]+, +[:digit:]+ and +[:space:]+
977 3. Supported shorthand character classes: +{backslash}w = +[:alnum:]+, +{backslash}d+ = +[:digit:],+ +{backslash}s+ = +[:space:]+
978 4. Character classes apply to ASCII characters only
979 5. Supported constraint escapes: +{backslash}m+ = +{backslash}<+ = start of word, +{backslash}M+ = +{backslash}>+ = end of word
980 6. Backslash escapes may be used within regular expressions, such as +{backslash}n+ = newline, +{backslash}uNNNN+ = unicode
981 7. No support for the +?+ non-greedy quantifier. e.g. +*?+
985 Each command produces two results: a code and a string. The
986 code indicates whether the command completed successfully or not,
987 and the string gives additional information. The valid codes are
988 defined in jim.h, and are:
991 This is the normal return code, and indicates that the command completed
992 successfully. The string gives the command's return value.
995 Indicates that an error occurred; the string gives a message describing
999 Indicates that the 'return' command has been invoked, and that the
1000 current procedure (or top-level command or 'source' command)
1001 should return immediately. The
1002 string gives the return value for the procedure or command.
1005 Indicates that the 'break' command has been invoked, so the
1006 innermost loop should abort immediately. The string should always
1010 Indicates that the 'continue' command has been invoked, so the
1011 innermost loop should go on to the next iteration. The string
1012 should always be empty.
1015 Indicates that a signal was caught while executing a commands.
1016 The string contains the name of the signal caught.
1017 See the 'signal' and 'catch' commands.
1020 Indicates that the command called the 'exit' command.
1021 The string contains the exit code.
1023 Tcl programmers do not normally need to think about return codes,
1024 since +JIM_OK+ is almost always returned. If anything else is returned
1025 by a command, then the Tcl interpreter immediately stops processing
1026 commands and returns to its caller. If there are several nested
1027 invocations of the Tcl interpreter in progress, then each nested
1028 command will usually return the error to its caller, until eventually
1029 the error is reported to the top-level application code. The
1030 application will then display the error message for the user.
1032 In a few cases, some commands will handle certain 'error' conditions
1033 themselves and not return them upwards. For example, the 'for'
1034 command checks for the +JIM_BREAK+ code; if it occurs, then 'for'
1035 stops executing the body of the loop and returns +JIM_OK+ to its
1036 caller. The 'for' command also handles +JIM_CONTINUE+ codes and the
1037 procedure interpreter handles +JIM_RETURN+ codes. The 'catch'
1038 command allows Tcl programs to catch errors and handle them without
1039 aborting command interpretation any further.
1041 The 'info returncodes' command may be used to programmatically map between
1042 return codes and names.
1046 Tcl allows you to extend the command interface by defining
1047 procedures. A Tcl procedure can be invoked just like any other Tcl
1048 command (it has a name and it receives one or more arguments).
1049 The only difference is that its body isn't a piece of C code linked
1050 into the program; it is a string containing one or more other
1053 The 'proc' command is used to create a new Tcl command procedure:
1055 +*proc* 'name args ?statics? body'+
1057 The new command is name *name*, and it replaces any existing command
1058 there may have been by that name. Whenever the new command is
1059 invoked, the contents of *body* will be executed by the Tcl
1062 *args* specifies the formal arguments to the procedure.
1063 It consists of a list, possibly empty, of the following
1064 argument specifiers:
1067 Required Argument - A simple argument name.
1070 Optional Argument - A two-element list consisting of the
1071 argument name, followed by the default value, which will
1072 be used if the corresponding argument is not supplied.
1075 Reference Argument - The caller is expected to pass the name of
1076 an existing variable. An implicit +upvar 1 *origname* *name*+ is done
1077 to make the variable available in the proc scope.
1080 Variable Argument - The special name *args*, which is
1081 assigned all remaining arguments (including none). The
1082 variable argument may only be specified once. Note that
1083 the syntax +args newname+ may be used to retain the special
1084 behaviour of *args* with a different local name. In this case,
1085 the variable is named *newname* rather than *args*.
1087 Arguments must be provided in the following order, any of which
1090 1. Required Arguments (Left)
1091 2. Optional Arguments
1092 3. Variable Argument
1093 4. Required Arguments (Right)
1095 When the command is invoked, a local variable will be created for each of
1096 the formal arguments to the procedure; its value will be the value
1097 of corresponding argument in the invoking command or the argument's
1100 Arguments with default values need not be specified in a procedure
1101 invocation. However, there must be enough actual arguments for all
1102 required arguments, and there must not be any extra actual arguments
1103 (unless the Variable Argument is specified).
1105 Actual arguments are assigned to formal arguments as follows:
1107 1. Left Required Arguments are assigned from the left
1108 2. Right Required Arguments are assigned from the right
1109 3. Default Arguments are assigned from the left, following the Left Required Arguments.
1110 4. A list is formed from any remaining arguments, which are then
1111 are assigned to the 'args' Variable Argument (if specified). The list will be empty
1112 if there are no remaining arguments.
1114 When *body* is being executed, variable names normally refer to local
1115 variables, which are created automatically when referenced and deleted
1116 when the procedure returns. One local variable is automatically created
1117 for each of the procedure's arguments. Global variables can be
1118 accessed by invoking the 'global' command or via the '::' prefix.
1122 In addition to procedure arguments, Jim procedures may declare static variables.
1123 These variables scoped to the procedure and initialised at procedure definition.
1124 Either from the static variable definition, or from the enclosing scope.
1126 Consider the following example:
1129 jim> proc a {} {a {b 2}} {
1141 The static variable *a* has no initialiser, so it is initialised from
1142 the enclosing scope with the value 1. (Note that it is an error if there
1143 is no variable with the same name in the enclosing scope). However *b*
1144 has an initialiser, so it is initialised to 2.
1146 Unlike a local variable, the value of a static variable is retained across
1147 invocations of the procedure.
1149 See the 'proc' command for information on
1150 how to define procedures and what happens when they are invoked.
1152 VARIABLES - SCALARS AND ARRAYS
1153 ------------------------------
1154 Tcl allows the definition of variables and the use of their values
1155 either through '$'-style variable substitution, the 'set'
1156 command, or a few other mechanisms.
1158 Variables need not be declared: a new variable will automatically
1159 be created each time a new variable name is used.
1161 Tcl supports two types of variables: scalars and arrays.
1162 A scalar variable has a single value, whereas an array variable
1163 can have any number of elements, each with a name (called
1164 its 'index') and a value.
1166 Array indexes may be arbitrary strings; they need not be numeric.
1167 Parentheses are used refer to array elements in Tcl commands.
1168 For example, the command
1172 will modify the element of 'x' whose index is 'first'
1173 so that its new value is '44'.
1175 Two-dimensional arrays can be simulated in Tcl by using indexes
1176 that contain multiple concatenated values.
1177 For example, the commands
1182 set the elements of 'a' whose indexes are '2,3' and '3,6'.
1184 In general, array elements may be used anywhere in Tcl that scalar
1185 variables may be used.
1187 If an array is defined with a particular name, then there may
1188 not be a scalar variable with the same name.
1190 Similarly, if there is a scalar variable with a particular
1191 name then it is not possible to make array references to the
1194 To convert a scalar variable to an array or vice versa, remove
1195 the existing variable with the 'unset' command.
1197 The 'array' command provides several features for dealing
1198 with arrays, such as querying the names of all the elements of
1199 the array and converting between an array and a list.
1201 Variables may be either global or local. If a variable
1202 name is used when a procedure isn't being executed, then it
1203 automatically refers to a global variable. Variable names used
1204 within a procedure normally refer to local variables associated with that
1205 invocation of the procedure. Local variables are deleted whenever
1206 a procedure exits. Either 'global' command may be used to request
1207 that a name refer to a global variable for the duration of the current
1208 procedure (this is somewhat analogous to 'extern' in C), or the variable
1209 may be explicitly scoped with the '::' prefix. For example
1225 ARRAYS AS LISTS IN JIM
1226 ----------------------
1227 Unlike Tcl, Jim can automatically convert between a list (with an even
1228 number of elements) and an array value. This is similar to the way Tcl
1229 can convert between a string and a list.
1240 Thus 'array set' is equivalent to 'set' when the variable does not
1243 The reverse is also true where an array will be converted into
1246 set a(1) one; set a(2) two
1255 Tcl 8.5 introduced the dict command, and Jim Tcl has added a version
1256 of this command. Dictionaries provide efficient access to key-value
1257 pairs, just like arrays, but dictionaries are pure values. This
1258 means that you can pass them to a procedure just as a list or a
1259 string. Tcl dictionaries are therefore much more like Tcl lists,
1260 except that they represent a mapping from keys to values, rather
1261 than an ordered sequence.
1263 You can nest dictionaries, so that the value for a particular key
1264 consists of another dictionary. That way you can elegantly build
1265 complicated data structures, such as hierarchical databases. You
1266 can also combine dictionaries with other Tcl data structures. For
1267 instance, you can build a list of dictionaries that themselves
1270 Dictionaries are values that contain an efficient, order-preserving
1271 mapping from arbitrary keys to arbitrary values. Each key in the
1272 dictionary maps to a single value. They have a textual format that
1273 is exactly that of any list with an even number of elements, with
1274 each mapping in the dictionary being represented as two items in
1275 the list. When a command takes a dictionary and produces a new
1276 dictionary based on it (either returning it or writing it back into
1277 the variable that the starting dictionary was read from) the new
1278 dictionary will have the same order of keys, modulo any deleted
1279 keys and with new keys added on to the end. When a string is
1280 interpreted as a dictionary and it would otherwise have duplicate
1281 keys, only the last value for a particular key is used; the others
1282 are ignored, meaning that, "apple banana" and "apple carrot apple
1283 banana" are equivalent dictionaries (with different string
1286 Note that in Jim, arrays are implemented as dictionaries.
1287 Thus automatic conversion between lists and dictionaries applies
1288 as it does for arrays.
1290 jim> dict set a 1 one
1292 jim> dict set a 2 two
1298 jim> dict set a 3 T three
1299 1 one 2 two 3 {T three}
1301 See the 'dict' command for more details.
1303 GARBAGE COLLECTION, REFERENCES, LAMBDA
1304 --------------------------------------
1305 Unlike Tcl, Jim has some sophisticated support for functional programming.
1306 These are described briefly below.
1308 More information may be found at http://wiki.tcl.tk/13847
1312 A reference can be thought of as holding a value with one level of indirection,
1313 where the value may be garbage collected when unreferenced.
1314 Consider the following example:
1316 jim> set r [ref "One String" test]
1317 <reference.<test___>.00000000000000000000>
1321 The operation 'ref' creates a references to the value specified by the
1322 first argument. (The second argument is a "type" used for documentation purposes).
1324 The operation 'getref' is the dereferencing operation which retrieves the value
1325 stored in the reference.
1327 jim> setref $r "New String"
1332 The operation 'setref' replaces the value stored by the reference. If the old value
1333 is no longer accessible by any reference, it will eventually be automatically be garbage
1338 Normally, all values in Tcl are passed by value. As such values are copied and released
1339 automatically as necessary.
1341 With the introduction of references, it is possible to create values whose lifetime
1342 transcend their scope. To support this, case, the Jim system will periodically identify
1343 and discard objects which are no longer accessible by any reference.
1345 The 'collect' command may be used to force garbage collection. Consider a reference created
1348 jim> proc f {ref value} { puts "Finaliser called for $ref,$value" }
1349 jim> set r [ref "One String" test f]
1350 <reference.<test___>.00000000000
1355 Finaliser called for <reference.<test___>.00000000000,One String
1358 Note that once the reference, 'r', was modified so that it no longer
1359 contained a reference to the value, the garbage collector discarded
1360 the value (after calling the finalizer).
1362 The finalizer for a reference may be examined or changed with the 'finalize' command
1366 jim> finalize $r newf
1371 Jim provides a garbage collected lambda function. This is a procedure
1372 which is able to create an anonymous procedure. Consider:
1374 jim> set f [lambda {a} {{x 0}} { incr x $a }]
1381 This create an anonymous procedure (with the name stored in 'f'), with a static variable
1382 which is incremented by the supplied value and the result returned.
1384 Once the procedure name is no longer accessible, it will automatically be deleted
1385 when the garbage collector runs.
1387 The procedure may also be delete immediately by renaming it "". e.g.
1393 If Jim is built with UTF-8 support enabled (configure --enable-utf),
1394 then most string-related commands become UTF-8 aware. These include,
1395 but are not limited to, 'string match', 'split', 'glob', 'scan' and
1398 UTF-8 encoding has many advantages, but one of the complications is that
1399 characters can take a variable number of bytes. Thus the addition of
1400 'string bytelength' which returns the number of bytes in a string,
1401 while 'string length' returns the number of characters.
1403 If UTF-8 support is not enabled, all commands treat bytes as characters
1404 and 'string bytelength' returns the same value as 'string length'.
1406 Note that even if UTF-8 support is not enabled, the +{backslash}uNNNN+ syntax
1407 is still available to embed UTF-8 sequences.
1411 Commands such as 'string match', 'lsearch -glob', 'array names' and others use string
1412 pattern matching rules. These commands support UTF-8. For example:
1414 string match a\[\ua0-\ubf\]b "a\u00a3b"
1418 +format %c+ allows a unicode codepoint to be be encoded. For example, the following will return
1419 a string with two bytes and one character. The same as +{backslash}ub5+
1423 'format' respects widths as character widths, not byte widths. For example, the following will
1424 return a string with three characters, not three bytes.
1426 format %.3s \ub5\ub6\ub7\ub8
1428 Similarly, +scan ... %c+ allows a UTF-8 to be decoded to a unicode codepoint. The following will set
1429 *a* to 181 (0xb5) and *b* to 65 (0x41).
1431 scan \u00b5A %c%c a b
1433 'scan %s' will also accept a character class, including unicode ranges.
1437 'string is' has *not* been extended to classify UTF-8 characters. Therefore, the following
1438 will return 0, even though the string may be considered to be alphabetic.
1440 string is alpha \ub5Test
1442 This does not affect the string classes 'ascii', 'control', 'digit', 'double', 'integer' or 'xdigit'.
1444 Case Mapping and Conversion
1445 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1446 Jim provides a simplified unicode case mapping. This means that case conversion
1447 and comparison will not increase or decrease the number of characters in a string.
1449 'string toupper' will convert any lowercase letters to their uppercase equivalent.
1450 Any character which is not a letter or has no uppercase equivalent is left unchanged.
1451 Similarly for 'string tolower'.
1453 Commands which perform case insensitive matches, such as 'string compare -nocase'
1454 and 'lsearch -nocase' fold both strings to uppercase before comparison.
1456 Invalid UTF-8 Sequences
1457 ~~~~~~~~~~~~~~~~~~~~~~~
1458 Some UTF-8 character sequences are invalid, such as those beginning with '0xff',
1459 those which represent character sequences longer than 3 bytes (greater than U+FFFF),
1460 and those which end prematurely, such as a lone '0xc2'.
1462 In these situations, the offending bytes are treated as single characters. For example,
1463 the following returns 2.
1465 string bytelength \xff\xff
1469 If UTF-8 support is enabled, the built-in regular expression engine will be
1470 selected which supports UTF-8 strings and patterns.
1472 See REGULAR EXPRESSIONS
1476 The Tcl library provides the following built-in commands, which will
1477 be available in any application using Tcl. In addition to these
1478 built-in commands, there may be additional commands defined by each
1479 application, plus commands defined as Tcl procedures.
1481 In the command syntax descriptions below, words in +*boldface*+ are
1482 literals that you type verbatim to Tcl.
1484 Words in +'italics'+ are meta-symbols; they serve as names for any of
1485 a range of values that you can type.
1487 Optional arguments or groups of arguments are indicated by enclosing them
1488 in +?question-marks?+.
1490 Ellipses (+...+) indicate that any number of additional
1491 arguments or groups of arguments may appear, in the same format
1492 as the preceding argument(s).
1503 Delivers the 'SIGALRM' signal to the process after the given
1504 number of seconds. If the platform supports 'ualarm(3)' then
1505 the argument may be a floating point value. Otherwise it must
1508 Note that unless a signal handler for 'SIGALRM' has been installed
1509 (see 'signal'), the process will exit on this signal.
1513 +*alias* 'name args...'+
1515 Creates a single word alias (proc) for one or more words. For example,
1516 the following creates an alias for the command 'info exists'.
1523 'alias' returns *name*, allowing it to be used with 'local.
1525 See also 'proc', 'curry', 'lambda', 'local'.
1529 +*append* 'varName value ?value value ...?'+
1531 Append all of the *value* arguments to the current value
1532 of variable *varName*. If *varName* doesn't exist,
1533 it is given a value equal to the concatenation of all the
1536 This command provides an efficient way to build up long
1537 variables incrementally.
1538 For example, 'append a $b' is much more efficient than
1539 'set a $a$b' if '$a' is long.
1543 +*array* 'option arrayName ?arg arg ...?'+
1545 This command performs one of several operations on the
1546 variable given by *arrayName*.
1548 Note that in general, if the named array does not exist, the *array* command behaves
1549 as though the array exists but is empty.
1551 The *option* argument determines what action is carried out by the
1552 command. The legal *options* (which may be abbreviated) are:
1554 +*array exists* 'arrayName'+::
1555 Returns 1 if arrayName is an array variable, 0 if there is
1556 no variable by that name. This command is essentially
1557 identical to 'info exists'
1559 +*array get* 'arrayName ?pattern?'+::
1560 Returns a list containing pairs of elements. The first
1561 element in each pair is the name of an element in arrayName
1562 and the second element of each pair is the value of the
1563 array element. The order of the pairs is undefined. If
1564 pattern is not specified, then all of the elements of the
1565 array are included in the result. If pattern is specified,
1566 then only those elements whose names match pattern (using
1567 the matching rules of string match) are included. If arrayName
1568 isn't the name of an array variable, or if the array contains
1569 no elements, then an empty list is returned.
1571 +*array names* 'arrayName ?pattern?'+::
1572 Returns a list containing the names of all of the elements
1573 in the array that match pattern. If pattern is omitted then
1574 the command returns all of the element names in the array.
1575 If pattern is specified, then only those elements whose
1576 names match pattern (using the matching rules of string
1577 match) are included. If there are no (matching) elements
1578 in the array, or if arrayName isn't the name of an array
1579 variable, then an empty string is returned.
1581 +*array set* 'arrayName list'+::
1582 Sets the values of one or more elements in arrayName. list
1583 must have a form like that returned by array get, consisting
1584 of an even number of elements. Each odd-numbered element
1585 in list is treated as an element name within arrayName, and
1586 the following element in list is used as a new value for
1587 that array element. If the variable arrayName does not
1588 already exist and list is empty, arrayName is created with
1589 an empty array value.
1591 +*array size* 'arrayName'+::
1592 Returns the number of elements in the array. If arrayName
1593 isn't the name of an array then 0 is returned.
1595 +*array unset* 'arrayName ?pattern?'+::
1596 Unsets all of the elements in the array that match pattern
1597 (using the matching rules of string match). If arrayName
1598 isn't the name of an array variable or there are no matching
1599 elements in the array, no error will be raised. If pattern
1600 is omitted and arrayName is an array variable, then the
1601 command unsets the entire array. The command always returns
1608 This command may be invoked only inside the body of a loop command
1609 such as 'for' or 'foreach' or 'while'. It returns a +JIM_BREAK+ code
1610 to signal the innermost containing loop command to return immediately.
1614 +*case* 'string' ?*in*? 'patList body ?patList body ...?'+
1616 +*case* 'string' ?*in*? {'patList body ?patList body ...?'}+
1618 *Note* that the switch command should generally be preferred unless compatibility
1619 with Tcl 6.x is desired.
1621 Match *string* against each of the *patList* arguments
1622 in order. If one matches, then evaluate the following *body* argument
1623 by passing it recursively to the Tcl interpreter, and return the result
1624 of that evaluation. Each *patList* argument consists of a single
1625 pattern or list of patterns. Each pattern may contain any of the wild-cards
1626 described under 'string match'.
1628 If a *patList* argument is 'default', the corresponding body will be
1629 evaluated if no *patList* matches *string*. If no *patList* argument
1630 matches *string* and no default is given, then the 'case' command returns
1633 Two syntaxes are provided.
1635 The first uses a separate argument for each of the patterns and commands;
1636 this form is convenient if substitutions are desired on some of the
1637 patterns or commands.
1639 The second form places all of the patterns and commands together into
1640 a single argument; the argument must have proper list structure, with
1641 the elements of the list being the patterns and commands.
1643 The second form makes it easy to construct multi-line case commands,
1644 since the braces around the whole list make it unnecessary to include a
1645 backslash at the end of each line.
1647 Since the *patList* arguments are in braces in the second form,
1648 no command or variable substitutions are performed on them; this makes
1649 the behaviour of the second form different than the first form in some
1652 Below are some examples of 'case' commands:
1654 case abc in {a b} {format 1} default {format 2} a* {format 3}
1664 will return '1', and
1679 +*catch* '?-?no?code ...?' *?--?* 'command ?resultVarName? ?optionsVarName?'+
1681 The 'catch' command may be used to prevent errors from aborting
1682 command interpretation. 'Catch' evaluates *command*, and returns a
1683 +JIM_OK+ code, regardless of any errors that might occur while
1684 executing *command* (with the possible exception of +JIM_SIGNAL+ -
1687 The return value from 'catch' is a decimal string giving the code
1688 returned by the Tcl interpreter after executing *command*. This
1689 will be '0' (+JIM_OK+) if there were no errors in *command*; otherwise
1690 it will have a non-zero value corresponding to one of the exceptional
1691 return codes (see jim.h for the definitions of code values, or the
1692 'info returncodes' command).
1694 If the *resultVarName* argument is given, then it gives the name
1695 of a variable; 'catch' will set the value of the variable to the
1696 string returned from *command* (either a result or an error message).
1698 If the *optionsVarName* argument is given, then it gives the name
1699 of a variable; 'catch' will set the value of the variable to a
1700 dictionary. For any return code other than +JIM_RETURN+, the value
1701 for the key +-code+ will be set to the return code. For +JIM_RETURN+
1702 it will be set to the code given in 'return -code'. Additionally,
1703 for the return code +JIM_ERR+, the value of the key +-errorinfo+
1704 will contain the current stack trace (the same result as 'info
1705 stacktrace'), the value of the key +-errorcode+ will contain the
1706 same value as the global variable $::errorCode, and the value of
1707 the key +-level+ will be the current return level (see 'return
1708 -level'). This can be useful to rethrow an error:
1710 if {[catch {...} msg opts]} {
1711 ...maybe do something with the error...
1713 return {*}$opts $msg
1716 Normally 'catch' will *not* catch any of the codes +JIM_EXIT+, +JIM_EVAL+ or +JIM_SIGNAL+.
1717 The set of codes which will be caught may be modified by specifying the one more codes before
1720 e.g. To catch +JIM_EXIT+ but not +JIM_BREAK+ or +JIM_CONTINUE+
1722 catch -exit -nobreak -nocontinue -- { ... }
1724 The use of +--+ is optional. It signifies that no more return code options follow.
1726 Note that if a signal marked as 'signal handle' is caught with 'catch -signal', the return value
1727 (stored in *resultVarName*) is name of the signal caught.
1733 Change the current working directory to *dirName*.
1735 Returns an empty string.
1737 This command can potentially be disruptive to an application, so it may
1738 be removed in some applications.
1743 Returns the current time as seconds since the epoch.
1745 +*clock format* 'seconds' ?*-format* 'format?'+::
1746 Format the given time (seconds since the epoch) according to the given
1747 format. See strftime(3) for supported formats.
1748 If no format is supplied, "%c" is used.
1750 +*clock scan* 'str' *-format* 'format'+::
1751 Scan the given time string using the given format string.
1752 See strptime(3) for supported formats.
1760 Closes the file given by *fileId*.
1761 *fileId* must be the return value from a previous invocation
1762 of the 'open' command; after this command, it should not be
1769 Normally reference garbage collection is automatically performed periodically.
1770 However it may be run immediately with the 'collect' command.
1772 See GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail.
1776 +*concat* 'arg ?arg ...?'+
1778 This command treats each argument as a list and concatenates them
1779 into a single list. It permits any number of arguments. For example,
1782 concat a b {c d e} {f {g h}}
1794 This command may be invoked only inside the body of a loop command such
1795 as 'for' or 'foreach' or 'while'. It returns a +JIM_CONTINUE+ code to
1796 signal the innermost containing loop command to skip the remainder of
1797 the loop's body but continue with the next iteration of the loop.
1803 Similar to 'alias' except it creates an anonymous procedure (lambda) instead of
1806 the following creates a local, unnamed alias for the command 'info exists'.
1808 set e [local curry info exists]
1813 'curry' returns the name of the procedure.
1815 See also 'proc', 'alias', 'lambda', 'local'.
1819 +*dict* 'option ?arg arg ...?'+
1821 Performs one of several operations on dictionary values.
1823 The *option* argument determines what action is carried out by the
1824 command. The legal *options* are:
1826 *dict create* '?key value ...?'+::
1827 Create and return a new dictionary value that contains each of
1828 the key/value mappings listed as arguments (keys and values
1829 alternating, with each key being followed by its associated
1832 *dict exists* 'dictionary key ?key ...?'+::
1833 Returns a boolean value indicating whether the given key (or path
1834 of keys through a set of nested dictionaries) exists in the given
1835 dictionary value. This returns a true value exactly when 'dict get'
1836 on that path will succeed.
1838 *dict get* 'dictionary ?key ...?'+::
1839 Given a dictionary value (first argument) and a key (second argument),
1840 this will retrieve the value for that key. Where several keys are
1841 supplied, the behaviour of the command shall be as if the result
1842 of 'dict get $dictVal $key' was passed as the first argument to
1843 dict get with the remaining arguments as second (and possibly
1844 subsequent) arguments. This facilitates lookups in nested dictionaries.
1845 If no keys are provided, dict would return a list containing pairs
1846 of elements in a man- ner similar to array get. That is, the first
1847 element of each pair would be the key and the second element would
1848 be the value for that key. It is an error to attempt to retrieve
1849 a value for a key that is not present in the dictionary.
1851 *dict keys* 'dictionary ?pattern?'+::
1852 Returns a list of the keys in the dictionary.
1853 If pattern is specified, then only those keys whose
1854 names match *pattern* (using the matching rules of string
1855 match) are included.
1857 *dict keys* 'dictionary ?pattern?'+::
1858 Returns a list of the keys in the dictionary.
1859 If pattern is specified, then only those keys whose
1860 names match *pattern* (using the matching rules of string
1861 match) are included.
1863 *dict set* 'dictionaryName key ?key ...? value'+::
1864 This operation takes the *name* of a variable containing a dictionary
1865 value and places an updated dictionary value in that variable
1866 containing a mapping from the given key to the given value. When
1867 multiple keys are present, this operation creates or updates a chain
1868 of nested dictionaries.
1870 *dict unset* 'dictionaryName key ?key ...? value'+::
1871 This operation (the companion to 'dict set') takes the name of a
1872 variable containing a dictionary value and places an updated
1873 dictionary value in that variable that does not contain a mapping
1874 for the given key. Where multiple keys are present, this describes
1875 a path through nested dictionaries to the mapping to remove. At
1876 least one key must be specified, but the last key on the key-path
1877 need not exist. All other components on the path must exist.
1881 +*env* '?name? ?default?'+
1883 If *name* is supplied, returns the value of *name* from the initial
1884 environment (see getenv(3)). An error is returned if *name* does not
1885 exist in the environment, unless *default* is supplied - in which case
1886 that value is returned instead.
1888 If no arguments are supplied, returns a list of all environment variables
1889 and their values as +{name value ...}+
1891 See also the global variable '::env'
1899 Returns 1 if an end-of-file condition has occurred on *fileId*,
1902 *fileId* must have been the return value from a previous call to 'open',
1903 or it may be 'stdin', 'stdout', or 'stderr' to refer to one of the
1904 standard I/O channels.
1908 +*error* 'message ?stacktrace?'+
1910 Returns a +JIM_ERR+ code, which causes command interpretation to be
1911 unwound. *message* is a string that is returned to the application
1912 to indicate what went wrong.
1914 If the *stacktrace* argument is provided and is non-empty,
1915 it is used to initialize the stacktrace.
1917 This feature is most useful in conjunction with the 'catch' command:
1918 if a caught error cannot be handled successfully, *stacktrace* can be used
1919 to return a stack trace reflecting the original point of occurrence
1924 error $errMsg [info stacktrace]
1926 See also 'errorInfo', 'info stacktrace', 'catch' and 'return'
1930 +*errorInfo* 'error ?stacktrace?'+
1932 Returns a human-readable representation of the given error message and stack trace.
1935 if {[catch {...} error]} {
1936 puts stderr [errorInfo $error [info stacktrace]]
1944 +*eval* 'arg ?arg ...?'+
1946 'eval' takes one or more arguments, which together comprise a Tcl
1947 command (or collection of Tcl commands separated by newlines in the
1948 usual way). 'eval' concatenates all its arguments in the same
1949 fashion as the 'concat' command, passes the concatenated string to the
1950 Tcl interpreter recursively, and returns the result of that
1951 evaluation (or any error generated by it).
1955 +*exec* 'arg ?arg ...?'+
1957 This command treats its arguments as the specification
1958 of one or more UNIX commands to execute as subprocesses.
1959 The commands take the form of a standard shell pipeline;
1960 '|' arguments separate commands in the
1961 pipeline and cause standard output of the preceding command
1962 to be piped into standard input of the next command (or '|&' for
1963 both standard output and standard error).
1965 Under normal conditions the result of the 'exec' command
1966 consists of the standard output produced by the last command
1969 If any of the commands in the pipeline exit abnormally or
1970 are killed or suspended, then 'exec' will return an error
1971 and the error message will include the pipeline's output followed by
1972 error messages describing the abnormal terminations.
1974 If any of the commands writes to its standard error file,
1975 then 'exec' will return an error, and the error message
1976 will include the pipeline's output, followed by messages
1977 about abnormal terminations (if any), followed by the standard error
1980 If the last character of the result or error message
1981 is a newline then that character is deleted from the result
1982 or error message for consistency with normal
1985 An *arg* may have one of the following special forms:
1988 The standard output of the last command in the pipeline
1989 is redirected to the file. In this situation 'exec'
1990 will normally return an empty string.
1993 As above, but append to the file.
1996 The standard output of the last command in the pipeline is
1997 redirected to the given (writable) file descriptor (e.g. stdout,
1998 stderr, or the result of 'open'). In this situation 'exec'
1999 will normally return an empty string.
2002 The standard error of the last command in the pipeline
2003 is redirected to the file.
2006 As above, but append to the file.
2009 The standard error of the last command in the pipeline is
2010 redirected to the given (writable) file descriptor.
2013 The standard error of the last command in the pipeline is
2014 redirected to the same file descriptor as the standard output.
2017 Both the standard output and standard error of the last command
2018 in the pipeline is redirected to the file.
2021 As above, but append to the file.
2024 The standard input of the first command in the pipeline
2025 is taken from the file.
2028 The standard input of the first command is taken as the
2029 given immediate value.
2032 The standard input of the first command in the pipeline
2033 is taken from the given (readable) file descriptor.
2035 If there is no redirection of standard input, standard error
2036 or standard output, these are connected to the corresponding
2037 input or output of the application.
2039 If the last *arg* is '&' then the command will be
2040 executed in background.
2041 In this case the standard output from the last command
2042 in the pipeline will
2043 go to the application's standard output unless
2044 redirected in the command, and error output from all
2045 the commands in the pipeline will go to the application's
2046 standard error file. The return value of exec in this case
2047 is a list of process ids (pids) in the pipeline.
2049 Each *arg* becomes one word for a command, except for
2050 '|', '<', '<<', '>', and '&' arguments, and the
2051 arguments that follow '<', '<<', and '>'.
2053 The first word in each command is taken as the command name;
2054 the directories in the PATH environment variable are searched for
2055 an executable by the given name.
2057 No 'glob' expansion or other shell-like substitutions
2058 are performed on the arguments to commands.
2060 If the command fails, the global $::errorCode (and the -errorcode
2061 option in 'catch') will be set to a list, as follows:
2063 +*CHILDKILLED* 'pid sigName msg'+::
2064 This format is used when a child process has been killed
2065 because of a signal. The pid element will be the process's
2066 identifier (in decimal). The sigName element will be the
2067 symbolic name of the signal that caused the process to
2068 terminate; it will be one of the names from the include
2069 file signal.h, such as SIGPIPE. The msg element will be a
2070 short human-readable message describing the signal, such
2071 as "write on pipe with no readers" for SIGPIPE.
2073 +*CHILDSUSP* 'pid sigName msg'+::
2074 This format is used when a child process has been suspended
2075 because of a signal. The pid element will be the process's
2076 identifier, in decimal. The sigName element will be the
2077 symbolic name of the signal that caused the process to
2078 suspend; this will be one of the names from the include
2079 file signal.h, such as SIGTTIN. The msg element will be a
2080 short human-readable message describing the signal, such
2081 as "background tty read" for SIGTTIN.
2083 +*CHILDSTATUS* 'pid code'+::
2084 This format is used when a child process has exited with a
2085 non-zero exit status. The pid element will be the process's
2086 identifier (in decimal) and the code element will be the
2087 exit code returned by the process (also in decimal).
2089 The environment for the executed command is set from $::env (unless
2090 this variable is unset, in which case the original environment is used).
2094 +*exists ?-var|-proc|-command?* 'name'+
2096 Checks the existence of the given variable, procedure or command
2097 respectively and returns 1 if it exists or 0 if not. This command
2098 provides a more simplified/convenient version of 'info exists',
2099 'info procs' and 'info commands'.
2101 If the type is omitted, a type of '-var' is used. The type may be abbreviated.
2105 +*exit* '?returnCode?'+
2107 Terminate the process, returning *returnCode* to the
2108 parent as the exit status.
2110 If *returnCode* isn't specified then it defaults
2113 Note that exit can be caught with *catch*.
2119 Calls the expression processor to evaluate *arg*, and returns
2120 the result as a string. See the section EXPRESSIONS above.
2122 Note that Jim supports a shorthand syntax for 'expr' as +$(...)+
2123 The following two are identical.
2125 set x [expr {3 * 2 + 1}]
2130 +*file* 'option name ?arg arg ...?'+
2132 Operate on a file or a file name. *name* is the name of a file.
2134 *Option* indicates what to do with the file name. Any unique
2135 abbreviation for *option* is acceptable. The valid options are:
2137 +*file atime* 'name'+::
2138 Return a decimal string giving the time at which file *name*
2139 was last accessed. The time is measured in the standard UNIX
2140 fashion as seconds from a fixed starting time (often January 1, 1970).
2141 If the file doesn't exist or its access time cannot be queried then an
2144 +*file copy ?-force?* 'source target'+::
2145 Copies file *source* to file *target*. The source file must exist.
2146 The target file must not exist, unless *-force* is specified.
2148 +*file delete* 'name ...'+::
2149 Deletes file or directory *name*. If the file or directory doesn't exist, nothing happens.
2150 If it can't be deleted, an error is generated. Non-empty directories will not be deleted.
2152 +*file dirname* 'name'+::
2153 Return all of the characters in *name* up to but not including
2154 the last slash character. If there are no slashes in *name*
2155 then return '.' (a single dot). If the last slash in *name* is its first
2156 character, then return '/'.
2158 +*file executable* 'name'+::
2159 Return '1' if file *name* is executable by
2160 the current user, '0' otherwise.
2162 +*file exists* 'name'+::
2163 Return '1' if file *name* exists and the current user has
2164 search privileges for the directories leading to it, '0' otherwise.
2166 +*file extension* 'name'+::
2167 Return all of the characters in *name* after and including the
2168 last dot in *name*. If there is no dot in *name* then return
2171 +*file isdirectory* 'name'+::
2172 Return '1' if file *name* is a directory,
2175 +*file isfile* 'name'+::
2176 Return '1' if file *name* is a regular file,
2179 +*file join* 'arg arg ...'+::
2180 Joins multiple path components. Note that if any components is
2181 an absolute path, the preceding components are ignored.
2182 Thus 'file join /tmp /root' returns '/root'.
2184 +*file lstat* 'name varName'+::
2185 Same as 'stat' option (see below) except uses the *lstat*
2186 kernel call instead of *stat*. This means that if *name*
2187 refers to a symbolic link the information returned in *varName*
2188 is for the link rather than the file it refers to. On systems that
2189 don't support symbolic links this option behaves exactly the same
2190 as the 'stat' option.
2192 +*file mkdir* 'dir1 ?dir2? ...'+::
2193 Creates each directory specified. For each pathname *dir* specified,
2194 this command will create all non-existing parent directories
2195 as well as *dir* itself. If an existing directory is specified,
2196 then no action is taken and no error is returned. Trying to
2197 overwrite an existing file with a directory will result in an
2198 error. Arguments are processed in the order specified, halting
2199 at the first error, if any.
2201 +*file mtime* 'name'+::
2202 Return a decimal string giving the time at which file *name*
2203 was last modified. The time is measured in the standard UNIX
2204 fashion as seconds from a fixed starting time (often January 1, 1970).
2205 If the file doesn't exist or its modified time cannot be queried then an
2208 +*file normalize* 'name'+::
2209 Return the normalized path of *name*. See realpath(3).
2211 +*file owned* 'name'+::
2212 Return '1' if file *name* is owned by the current user,
2215 +*file readable* 'name'+::
2216 Return '1' if file *name* is readable by
2217 the current user, '0' otherwise.
2219 +*file readlink* 'name'+::
2220 Returns the value of the symbolic link given by *name* (i.e. the
2221 name of the file it points to). If
2222 *name* isn't a symbolic link or its value cannot be read, then
2223 an error is returned. On systems that don't support symbolic links
2224 this option is undefined.
2226 +*file rename* 'oldname' 'newname'+::
2227 Renames the file from the old name to the new name.
2229 +*file rootname* 'name'+::
2230 Return all of the characters in *name* up to but not including
2231 the last '.' character in the name. If *name* doesn't contain
2232 a dot, then return *name*.
2234 +*file size* 'name'+::
2235 Return a decimal string giving the size of file *name* in bytes.
2236 If the file doesn't exist or its size cannot be queried then an
2239 +*file stat* 'name varName'+::
2240 Invoke the 'stat' kernel call on *name*, and use the
2241 variable given by *varName* to hold information returned from
2243 *VarName* is treated as an array variable,
2244 and the following elements of that variable are set: 'atime',
2245 'ctime', 'dev', 'gid', 'ino', 'mode', 'mtime',
2246 'nlink', 'size', 'type', 'uid'.
2247 Each element except 'type' is a decimal string with the value of
2248 the corresponding field from the 'stat' return structure; see the
2249 manual entry for 'stat' for details on the meanings of the values.
2250 The 'type' element gives the type of the file in the same form
2251 returned by the command 'file type'.
2252 This command returns an empty string.
2254 +*file tail* 'name'+::
2255 Return all of the characters in *name* after the last slash.
2256 If *name* contains no slashes then return *name*.
2258 +*file tempfile* '?template?'+::
2259 Creates and returns the name of a unique temporary file. If *template* is omitted, a
2260 default template will be used to place the file in /tmp. See mkstemp(3) for
2261 the format of the template and security concerns.
2263 +*file type* 'name'+::
2264 Returns a string giving the type of file *name*, which will be
2265 one of 'file', 'directory', 'characterSpecial',
2266 'blockSpecial', 'fifo', 'link', or 'socket'.
2268 +*file writable* 'name'+::
2269 Return '1' if file *name* is writable by
2270 the current user, '0' otherwise.
2272 The 'file' commands that return 0/1 results are often used in
2273 conditional or looping commands, for example:
2275 if {![file exists foo]} then {error {bad file name}} else {...}
2279 +*finalize* 'reference ?command?'+
2281 If *command* is omitted, returns the finalizer command for the given reference.
2283 Otherwise, sets a new finalizer command for the given reference. *command* may be
2284 the empty string to remove the current finalizer.
2286 The reference must be a valid reference create with the 'ref'
2289 See GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail.
2297 Flushes any output that has been buffered for *fileId*. *fileId* must
2298 have been the return value from a previous call to 'open', or it may be
2299 'stdout' or 'stderr' to access one of the standard I/O streams; it must
2300 refer to a file that was opened for writing. This command returns an
2305 +*for* 'start test next body'+
2307 'For' is a looping command, similar in structure to the C 'for' statement.
2308 The *start*, *next*, and *body* arguments must be Tcl command strings,
2309 and *test* is an expression string.
2311 The 'for' command first invokes the Tcl interpreter to execute *start*.
2312 Then it repeatedly evaluates *test* as an expression; if the result is
2313 non-zero it invokes the Tcl interpreter on *body*, then invokes the Tcl
2314 interpreter on *next*, then repeats the loop. The command terminates
2315 when *test* evaluates to 0.
2317 If a 'continue' command is invoked within *body* then any remaining
2318 commands in the current execution of *body* are skipped; processing
2319 continues by invoking the Tcl interpreter on *next*, then evaluating
2322 If a 'break' command is invoked within *body* or *next*, then the 'for'
2323 command will return immediately.
2325 The operation of 'break' and 'continue' are similar to the corresponding
2328 'For' returns an empty string.
2332 +*foreach* 'varName list body'+
2334 +*foreach* 'varList list ?varList2 list2 ...? body'+
2336 In this command, *varName* is the name of a variable, *list*
2337 is a list of values to assign to *varName*, and *body* is a
2338 collection of Tcl commands.
2340 For each field in *list* (in order from left to right),'foreach' assigns
2341 the contents of the field to *varName* (as if the 'lindex' command
2342 had been used to extract the field), then calls the Tcl interpreter to
2345 If instead of being a simple name, *varList* is used, multiple assignments
2346 are made each time through the loop, one for each element of *varList*.
2348 For example, if there are two elements in *varList* and six elements in
2349 the list, the loop will be executed three times.
2351 If the length of the list doesn't evenly divide by the number of elements
2352 in *varList*, the value of the remaining variables in the last iteration
2353 of the loop are undefined.
2355 The 'break' and 'continue' statements may be invoked inside *body*,
2356 with the same effect as in the 'for' command.
2358 'foreach' returns an empty string.
2362 +*format* 'formatString ?arg arg ...?'+
2364 This command generates a formatted string in the same way as the
2365 C 'sprintf' procedure (it uses 'sprintf' in its
2366 implementation). *FormatString* indicates how to format
2367 the result, using '%' fields as in 'sprintf', and the additional
2368 arguments, if any, provide values to be substituted into the result.
2370 All of the 'sprintf' options are valid; see the 'sprintf'
2371 man page for details. Each *arg* must match the expected type
2372 from the '%' field in *formatString*; the 'format' command
2373 converts each argument to the correct type (floating, integer, etc.)
2374 before passing it to 'sprintf' for formatting.
2376 The only unusual conversion is for '%c'; in this case the argument
2377 must be a decimal string, which will then be converted to the corresponding
2378 ASCII character value.
2380 'Format' does backslash substitution on its *formatString*
2381 argument, so backslash sequences in *formatString* will be handled
2382 correctly even if the argument is in braces.
2384 The return value from 'format' is the formatted string.
2388 +*getref* 'reference'+
2390 Returns the string associated with *reference*. The reference must
2391 be a valid reference create with the 'ref' command.
2393 See GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail.
2397 +*gets* 'fileId ?varName?'+
2399 +'fileId' *gets* '?varName?'+
2401 Reads the next line from the file given by *fileId* and discards
2402 the terminating newline character.
2404 If *varName* is specified, then the line is placed in the variable
2405 by that name and the return value is a count of the number of characters
2406 read (not including the newline).
2408 If the end of the file is reached before reading
2409 any characters then -1 is returned and *varName* is set to an
2412 If *varName* is not specified then the return value will be
2413 the line (minus the newline character) or an empty string if
2414 the end of the file is reached before reading any characters.
2416 An empty string will also be returned if a line contains no characters
2417 except the newline, so 'eof' may have to be used to determine
2418 what really happened.
2420 If the last character in the file is not a newline character, then
2421 'gets' behaves as if there were an additional newline character
2422 at the end of the file.
2424 *fileId* must be 'stdin' or the return value from a previous
2425 call to 'open'; it must refer to a file that was opened
2430 +*glob* ?*-nocomplain*? 'pattern ?pattern ...?'+
2432 This command performs filename globbing, using csh rules. The returned
2433 value from 'glob' is the list of expanded filenames.
2435 If '-nocomplain' is specified as the first argument then an empty
2436 list may be returned; otherwise an error is returned if the expanded
2437 list is empty. The '-nocomplain' argument must be provided
2438 exactly: an abbreviation will not be accepted.
2443 +*global* 'varName ?varName ...?'+
2445 This command is ignored unless a Tcl procedure is being interpreted.
2446 If so, then it declares each given *varName* to be a global variable
2447 rather than a local one. For the duration of the current procedure
2448 (and only while executing in the current procedure), any reference to
2449 *varName* will be bound to a global variable instead
2452 An alternative to using 'global' is to use the '::' prefix
2453 to explicitly name a variable in the global scope.
2457 +*if* 'expr1' ?*then*? 'body1' *elseif* 'expr2' ?*then*? 'body2' *elseif* ... ?*else*? ?'bodyN'?+
2459 The 'if' command evaluates *expr1* as an expression (in the same way
2460 that 'expr' evaluates its argument). The value of the expression must
2461 be numeric; if it is non-zero then *body1* is executed by passing it to
2462 the Tcl interpreter.
2464 Otherwise *expr2* is evaluated as an expression and if it is non-zero
2465 then *body2* is executed, and so on.
2467 If none of the expressions evaluates to non-zero then *bodyN* is executed.
2469 The 'then' and 'else' arguments are optional 'noise words' to make the
2470 command easier to read.
2472 There may be any number of 'elseif' clauses, including zero. *bodyN*
2473 may also be omitted as long as 'else' is omitted too.
2475 The return value from the command is the result of the body script that
2476 was executed, or an empty string if none of the expressions was non-zero
2477 and there was no *bodyN*.
2481 +*incr* 'varName ?increment?'+
2483 Increment the value stored in the variable whose name is *varName*.
2484 The value of the variable must be integral.
2486 If *increment* is supplied then its value (which must be an
2487 integer) is added to the value of variable *varName*; otherwise
2488 1 is added to *varName*.
2490 The new value is stored as a decimal string in variable *varName*
2491 and also returned as result.
2493 If the variable does not exist, the variable is implicitly created
2494 and set to +0+ first.
2499 +*info* 'option ?arg arg ...?'+::
2501 Provide information about various internals to the Tcl interpreter.
2502 The legal *option*'s (which may be abbreviated) are:
2504 +*info args* 'procname'+::
2505 Returns a list containing the names of the arguments to procedure
2506 *procname*, in order. *Procname* must be the name of a
2507 Tcl command procedure.
2509 +*info body* 'procname'+::
2510 Returns the body of procedure *procname*. *Procname* must be
2511 the name of a Tcl command procedure.
2514 Returns a list of all open file handles from 'open' or 'socket'
2516 +*info commands* ?'pattern'?+::
2517 If *pattern* isn't specified, returns a list of names of all the
2518 Tcl commands, including both the built-in commands written in C and
2519 the command procedures defined using the 'proc' command.
2520 If *pattern* is specified, only those names matching *pattern*
2521 are returned. Matching is determined using the same rules as for
2524 +*info complete* 'command' ?'missing'?+::
2525 Returns 1 if *command* is a complete Tcl command in the sense of
2526 having no unclosed quotes, braces, brackets or array element names,
2527 If the command doesn't appear to be complete then 0 is returned.
2528 This command is typically used in line-oriented input environments
2529 to allow users to type in commands that span multiple lines; if the
2530 command isn't complete, the script can delay evaluating it until additional
2531 lines have been typed to complete the command. If *varName* is specified, the
2532 missing character is stored in the variable with that name.
2534 +*info exists* 'varName'+::
2535 Returns '1' if the variable named *varName* exists in the
2536 current context (either as a global or local variable), returns '0'
2539 +*info frame* ?'number'?+::
2540 If *number* is not specified, this command returns a number
2541 which is the same result as 'info level' - the current stack frame level.
2542 If *number* is specified, then the result is a list consisting of the procedure,
2543 filename and line number for the procedure call at level *number* on the stack.
2544 If *number* is positive then it selects a particular stack level (1 refers
2545 to the top-most active procedure, 2 to the procedure it called, and
2546 so on); otherwise it gives a level relative to the current level
2547 (0 refers to the current procedure, -1 to its caller, and so on).
2548 The level has an identical meaning to 'info level'.
2550 +*info globals* ?'pattern'?+::
2551 If *pattern* isn't specified, returns a list of all the names
2552 of currently-defined global variables.
2553 If *pattern* is specified, only those names matching *pattern*
2554 are returned. Matching is determined using the same rules as for
2558 An alias for 'os.gethostname' for compatibility with Tcl 6.x
2560 +*info level* ?'number'?+::
2561 If *number* is not specified, this command returns a number
2562 giving the stack level of the invoking procedure, or 0 if the
2563 command is invoked at top-level. If *number* is specified,
2564 then the result is a list consisting of the name and arguments for the
2565 procedure call at level *number* on the stack. If *number*
2566 is positive then it selects a particular stack level (1 refers
2567 to the top-most active procedure, 2 to the procedure it called, and
2568 so on); otherwise it gives a level relative to the current level
2569 (0 refers to the current procedure, -1 to its caller, and so on).
2570 See the 'uplevel' command for more information on what stack
2573 +*info locals* ?'pattern'?+::
2574 If *pattern* isn't specified, returns a list of all the names
2575 of currently-defined local variables, including arguments to the
2576 current procedure, if any. Variables defined with the 'global'
2577 and 'upvar' commands will not be returned. If *pattern* is
2578 specified, only those names matching *pattern* are returned.
2579 Matching is determined using the same rules as for 'string match'.
2581 +*info nameofexecutable*+::
2582 Returns the name of the binary file from which the application
2584 as a path relative to the current directory or as a full
2585 path. If the path can't be determined, returns the empty
2588 +*info procs* ?'pattern'?+::
2589 If *pattern* isn't specified, returns a list of all the
2590 names of Tcl command procedures.
2591 If *pattern* is specified, only those names matching *pattern*
2592 are returned. Matching is determined using the same rules as for
2595 +*info references*+::
2596 Returns a list of all references which have not yet been garbage
2599 +*info returncodes* ?'code'?+::
2600 Returns a list representing the mapping of standard return codes
2601 to names. e.g. +{0 ok 1 error 2 return ...}+. If a code is given,
2602 instead returns the name for the given code.
2605 If a Tcl script file is currently being evaluated (i.e. there is a
2606 call to 'Jim_EvalFile' active or there is an active invocation
2607 of the 'source' command), then this command returns the name
2608 of the innermost file being processed. Otherwise the command returns an
2611 +*info source* 'script'+::
2612 Returns the original source location of the given script as a list of
2613 +{filename linenumber}+. If the source location can't be determined, the
2614 list +{{} 0}+ is returned.
2616 +*info stacktrace*+::
2617 After an error is caught with 'catch', returns the stack trace as a list
2618 of +{procedure filename line ...}+.
2621 Returns the version number for this version of Jim in the form *x.yy*.
2623 +*info vars* ?'pattern'?+::
2624 If *pattern* isn't specified,
2625 returns a list of all the names of currently-visible variables, including
2626 both locals and currently-visible globals.
2627 If *pattern* is specified, only those names matching *pattern*
2628 are returned. Matching is determined using the same rules as for
2633 +*join* 'list ?joinString?'+
2635 The *list* argument must be a valid Tcl list. This command returns the
2636 string formed by joining all of the elements of *list* together with
2637 *joinString* separating each adjacent pair of elements.
2639 The *joinString* argument defaults to a space character.
2643 +*kill* ?'SIG'|*-0*? 'pid'+
2645 Sends the given signal to the process identified by *pid*.
2647 The signal may be specified by name or number in one of the following forms:
2655 The signal name may be in either upper or lower case.
2657 The special signal name '-0' simply checks that a signal *could* be sent.
2659 If no signal is specified, SIGTERM is used.
2661 An error is raised if the signal could not be delivered.
2665 +*lambda* 'args ?statics? body'+
2667 The 'lambda' command is identical to 'proc', except rather than
2668 creating a named procedure, it creates an anonymous procedure and returns
2669 the name of the procedure.
2671 See 'proc' and GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail.
2675 +*lappend* 'varName value ?value value ...?'+
2677 Treat the variable given by *varName* as a list and append each of
2678 the *value* arguments to that list as a separate element, with spaces
2681 If *varName* doesn't exist, it is created as a list with elements given
2682 by the *value* arguments. 'lappend' is similar to 'append' except that
2683 each *value* is appended as a list element rather than raw text.
2685 This command provides a relatively efficient way to build up large lists.
2686 For example, 'lappend a $b' is much more efficient than
2688 set a [concat $a [list $b]]
2694 +*lassign* 'list varName ?varName? ...'+
2696 This command treats the value *list* as a list and assigns successive elements from that list to
2697 the variables given by the *varName* arguments in order. If there are more variable names than
2698 list elements, the remaining variables are set to the empty string. If there are more list ele-
2699 ments than variables, a list of unassigned elements is returned.
2701 jim> lassign {1 2 3} a b; puts a=$a,b=$b
2709 Executes it's arguments as a command (per 'eval') and considers the return
2710 value to be a procedure name, which is marked as having local scope.
2711 This means that when the current procedure exits, the specified
2712 procedure is deleted. This can be useful with 'lambda' or simply
2715 In addition, if a command already exists with the same name,
2716 the existing command will be kept rather than deleted, and may be called
2717 via 'upcall'. The previous command will be restored when the current
2718 command is deleted. See 'upcall' for more details.
2720 In this example, a local procedure is created. Note that the procedure
2721 continues to have global scope while it is active.
2724 # proc ... returns "inner" which is marked local
2725 local proc inner {} {
2726 # will be deleted when 'outer' exits
2733 In this example, the lambda is deleted at the end of the procedure rather
2734 than waiting until garbage collection.
2737 set x [lambda inner {args} {
2738 # will be deleted when 'outer' exits
2740 # Use 'function' here which simply returns $x
2749 +*loop* 'var first limit ?incr? body'+
2751 Similar to 'for' except simpler and possibly more efficient.
2752 With a positive increment, equivalent to:
2754 for {set var $first} {$var < $limit} {incr var $incr} $body
2756 If *incr* is not specified, 1 is used.
2757 Note that setting the loop variable inside the loop does not
2758 affect the loop count.
2762 +*lindex* 'list index'+
2764 Treats *list* as a Tcl list and returns element *index* from it
2765 (0 refers to the first element of the list).
2766 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *index*.
2768 In extracting the element, *lindex* observes the same rules concerning
2769 braces and quotes and backslashes as the Tcl command interpreter; however,
2770 variable substitution and command substitution do not occur.
2772 If *index* is negative or greater than or equal to the number of elements
2773 in *value*, then an empty string is returned.
2777 +*linsert* 'list index element ?element element ...?'+
2779 This command produces a new list from *list* by inserting all
2780 of the *element* arguments just before the element *index*
2781 of *list*. Each *element* argument will become
2782 a separate element of the new list. If *index* is less than
2783 or equal to zero, then the new elements are inserted at the
2784 beginning of the list. If *index* is greater than or equal
2785 to the number of elements in the list, then the new elements are
2786 appended to the list.
2788 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *index*.
2793 +*list* 'arg ?arg ...?'+
2795 This command returns a list comprised of all the arguments, *arg*. Braces
2796 and backslashes get added as necessary, so that the 'index' command
2797 may be used on the result to re-extract the original arguments, and also
2798 so that 'eval' may be used to execute the resulting list, with
2799 *arg1* comprising the command's name and the other args comprising
2800 its arguments. 'List' produces slightly different results than
2801 'concat': 'concat' removes one level of grouping before forming
2802 the list, while 'list' works directly from the original arguments.
2803 For example, the command
2805 list a b {c d e} {f {g h}}
2809 a b {c d e} {f {g h}}
2811 while 'concat' with the same arguments will return
2819 Treats *list* as a list and returns a decimal string giving
2820 the number of elements in it.
2824 +*lset* 'varName ?index ..? newValue'+
2826 Sets an element in a list.
2828 The 'lset' command accepts a parameter, *varName*, which it interprets
2829 as the name of a variable containing a Tcl list. It also accepts
2830 zero or more indices into the list. Finally, it accepts a new value
2831 for an element of varName. If no indices are presented, the command
2834 lset varName newValue
2836 In this case, newValue replaces the old value of the variable
2839 When presented with a single index, the 'lset' command
2840 treats the content of the varName variable as a Tcl list. It addresses
2841 the index'th element in it (0 refers to the first element of the
2842 list). When interpreting the list, 'lset' observes the same rules
2843 concerning braces and quotes and backslashes as the Tcl command
2844 interpreter; however, variable substitution and command substitution
2845 do not occur. The command constructs a new list in which the
2846 designated element is replaced with newValue. This new list is
2847 stored in the variable varName, and is also the return value from
2850 If index is negative or greater than or equal to the number of
2851 elements in $varName, then an error occurs.
2853 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *index*.
2855 If additional index arguments are supplied, then each argument is
2856 used in turn to address an element within a sublist designated by
2857 the previous indexing operation, allowing the script to alter
2858 elements in sublists. The command,
2862 replaces element 2 of sublist 1 with *newValue*.
2864 The integer appearing in each index argument must be greater than
2865 or equal to zero. The integer appearing in each index argument must
2866 be strictly less than the length of the corresponding list. In other
2867 words, the 'lset' command cannot change the size of a list. If an
2868 index is outside the permitted range, an error is reported.
2873 +*lmap* 'varName list body'+
2875 +*lmap* 'varList list ?varList2 list2 ...? body'+
2877 'lmap' is a "collecting 'foreach'" which returns a list of its results.
2881 jim> lmap i {1 2 3 4 5} {expr $i*$i}
2883 jim> lmap a {1 2 3} b {A B C} {list $a $b}
2886 If the body invokes 'continue', no value is added for this iteration.
2887 If the body invokes 'break', the loop ends and no more values are added.
2893 Loads the dynamic extension, *filename*. Generally the filename should have
2894 the extension '.so'. The initialisation function for the module must be based
2895 on the name of the file. For example loading +hwaccess.so+ will invoke
2896 the initialisation function, +Jim_hwaccessInit+. Normally the 'load' command
2897 should not be used directly. Instead it is invoked automatically by 'package require'.
2901 +*lrange* 'list first last'+
2903 *List* must be a valid Tcl list. This command will return a new
2904 list consisting of elements *first* through *last*, inclusive.
2906 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *first* and *last*.
2908 If *last* is greater than or equal to the number of elements
2909 in the list, then it is treated as if it were 'end'.
2911 If *first* is greater than *last* then an empty string
2914 Note: 'lrange *list first first*' does not always produce the
2915 same result as 'lindex *list first*' (although it often does
2916 for simple fields that aren't enclosed in braces); it does, however,
2917 produce exactly the same results as 'list [lindex *list first*]'
2922 +*lreplace* 'list first last ?element element ...?'+
2924 Returns a new list formed by replacing one or more elements of
2925 *list* with the *element* arguments.
2927 *First* gives the index in *list* of the first element
2930 If *first* is less than zero then it refers to the first
2931 element of *list*; the element indicated by *first*
2932 must exist in the list.
2934 *Last* gives the index in *list* of the last element
2935 to be replaced; it must be greater than or equal to *first*.
2937 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *first* and *last*.
2939 The *element* arguments specify zero or more new arguments to
2940 be added to the list in place of those that were deleted.
2942 Each *element* argument will become a separate element of
2945 If no *element* arguments are specified, then the elements
2946 between *first* and *last* are simply deleted.
2950 +*lrepeat* 'number element1 ?element2 ...?'+
2952 Build a list by repeating elements *number* times (which must be
2953 a positive integer).
2962 Returns the list in reverse order.
2964 jim> lreverse {1 2 3}
2969 +*lsearch* '?options? list pattern'+
2971 This command searches the elements *list* to see if one of them matches *pattern*. If so, the
2972 command returns the index of the first matching element (unless the options -all, -inline or -bool are
2973 specified.) If not, the command returns -1. The option arguments indicates how the elements of
2974 the list are to be matched against pattern and must have one of the values below:
2976 *Note* that this command is different from Tcl in that default match type is '-exact' rather than '-glob'.
2979 *pattern* is a literal string that is compared for exact equality against each list element.
2980 This is the default.
2983 *pattern* is a glob-style pattern which is matched against each list element using the same
2984 rules as the string match command.
2987 *pattern* is treated as a regular expression and matched against each list element using
2988 the rules described by 'regexp'.
2991 Changes the result to be the list of all matching indices (or all matching values if
2992 '-inline' is specified as well). If indices are returned, the indices will be in numeric
2993 order. If values are returned, the order of the values will be the order of those values
2994 within the input list.
2997 The matching value is returned instead of its index (or an empty string if no value
2998 matches). If '-all' is also specified, then the result of the command is the list of all
2999 values that matched. The '-inline' and '-bool' options are mutually exclusive.
3002 Changes the result to '1' if a match was found, or '0' otherwise. If '-all' is also specified,
3003 the result will be a list of '0' and '1' for each element of the list depending upon whether
3004 the corresponding element matches. The '-inline' and '-bool' options are mutually exclusive.
3007 This negates the sense of the match, returning the index (or value
3008 if '-inline' is specified) of the first non-matching value in the
3009 list. If '-bool' is also specified, the '0' will be returned if a
3010 match is found, or '1' otherwise. If '-all' is also specified,
3011 non-matches will be returned rather than matches.
3014 Causes comparisons to be handled in a case-insensitive manner.
3018 +*lsort* ?*-index* 'listindex'? ?*-integer*|*-command* 'cmdname'? ?*-decreasing*|*-increasing*? 'list'+
3020 Sort the elements of *list*, returning a new list in sorted order.
3021 By default, ASCII sorting is used, with the result in increasing order.
3023 If *-integer* is specified, numeric sorting is used.
3025 If *-command cmdname* is specified, *cmdname* is treated as a command
3026 name. For each comparison, *cmdname $value1 $value2* is called which
3027 should compare the values and return an integer less than, equal
3028 to, or greater than zero if the *$value1* is to be considered less
3029 than, equal to, or greater than *$value2*, respectively.
3031 If *-decreasing* is specified, the resulting list is in the opposite
3032 order to what it would be otherwise. *-increasing* is the default.
3034 If *-index listindex* is specified, each element of the list is treated as a list and
3035 the given index is extracted from the list for comparison. The list index may
3036 be any valid list index, such as '1', 'end' or 'end-2'.
3038 If *-index listindex* is specified, each element of the list is treated as a list and
3039 the given index is extracted from the list for comparison. The list index may
3040 be any valid list index, such as '1', 'end' or 'end-2'.
3044 +*open* 'fileName ?access?'+
3046 +*open* '|command-pipeline ?access?'+
3048 Opens a file and returns an identifier
3049 that may be used in future invocations
3050 of commands like 'read', 'puts', and 'close'.
3051 *fileName* gives the name of the file to open.
3053 The *access* argument indicates the way in which the file is to be accessed.
3054 It may have any of the following values:
3057 Open the file for reading only; the file must already exist.
3060 Open the file for both reading and writing; the file must
3064 Open the file for writing only. Truncate it if it exists. If it doesn't
3065 exist, create a new file.
3068 Open the file for reading and writing. Truncate it if it exists.
3069 If it doesn't exist, create a new file.
3072 Open the file for writing only. The file must already exist, and the file
3073 is positioned so that new data is appended to the file.
3076 Open the file for reading and writing. If the file doesn't
3077 exist, create a new empty file. Set the initial access position
3078 to the end of the file.
3080 *Access* defaults to 'r'.
3082 If a file is opened for both reading and writing, then 'seek'
3083 must be invoked between a read and a write, or vice versa.
3085 If the first character of *fileName* is "|" then the remaining
3086 characters of *fileName* are treated as a list of arguments that
3087 describe a command pipeline to invoke, in the same style as the
3088 arguments for exec. In this case, the channel identifier returned
3089 by open may be used to write to the command's input pipe or read
3090 from its output pipe, depending on the value of *access*. If write-only
3091 access is used (e.g. *access* is 'w'), then standard output for the
3092 pipeline is directed to the current standard output unless overridden
3093 by the command. If read-only access is used (e.g. *access* is r),
3094 standard input for the pipeline is taken from the current standard
3095 input unless overridden by the command.
3097 The 'pid' command may be used to return the process ids of the commands
3098 forming the command pipeline.
3100 See also 'socket', 'pid', 'exec'
3104 +*package provide* 'name ?version?'+
3106 Indicates that the current script provides the package named *name*.
3107 If no version is specified, '1.0' is used.
3109 Any script which provides a package may include this statement
3110 as the first statement, although it is not required.
3112 +*package require* 'name ?version?'*+
3114 Searches for the package with the given *name* by examining each path
3115 in '$::auto_path' and trying to load '$path/$name.so' as a dynamic extension,
3116 or '$path/$name.tcl' as a script package.
3118 The first such file which is found is considered to provide the the package.
3119 (The version number is ignored).
3121 If '$name.so' exists, it is loaded with the 'load' command,
3122 otherwise if '$name.tcl' exists it is loaded with the 'source' command.
3124 If 'load' or 'source' fails, 'package require' will fail immediately.
3125 No further attempt will be made to locate the file.
3133 The first form returns the process identifier of the current process.
3135 The second form accepts a handle returned by 'open' and returns a list
3136 of the process ids forming the pipeline in the same form as 'exec ... &'.
3137 If 'fileId' represents a regular file handle rather than a command pipeline,
3138 the empty string is returned instead.
3140 See also 'open', 'exec'
3144 +*proc* 'name args ?statics? body'+
3146 The 'proc' command creates a new Tcl command procedure, *name*.
3147 When the new command is invoked, the contents of *body* will be executed.
3148 Tcl interpreter. *args* specifies the formal arguments to the procedure.
3149 If specified, *static*, declares static variables which are bound to the
3152 See PROCEDURES for detailed information about Tcl procedures.
3154 The 'proc' command returns *name* (which is useful with 'local').
3156 When a procedure is invoked, the procedure's return value is the
3157 value specified in a 'return' command. If the procedure doesn't
3158 execute an explicit 'return', then its return value is the value
3159 of the last command executed in the procedure's body.
3161 If an error occurs while executing the procedure body, then the
3162 procedure-as-a-whole will return that same error.
3166 +*puts* ?*-nonewline*? '?fileId? string'+
3168 +'fileId' *puts* ?*-nonewline*? 'string'+
3170 Writes the characters given by *string* to the file given
3171 by *fileId*. *fileId* must have been the return
3172 value from a previous call to 'open', or it may be
3173 'stdout' or 'stderr' to refer to one of the standard I/O
3174 channels; it must refer to a file that was opened for
3177 In the first form, if no *fileId* is specified then it defaults to 'stdout'.
3178 'puts' normally outputs a newline character after *string*,
3179 but this feature may be suppressed by specifying the '-nonewline'
3182 Output to files is buffered internally by Tcl; the 'flush'
3183 command may be used to force buffered characters to be output.
3189 Returns the path name of the current working directory.
3193 +*rand* '?min? ?max?'+
3195 Returns a random integer between *min* (defaults to 0) and *max*
3196 (defaults to the maximum integer).
3198 If only one argument is given, it is interpreted as *max*.
3202 +*range* '?start? end ?step?'+
3204 Returns a list of integers starting at *start* (defaults to 0)
3205 and ranging up to but not including *end* in steps of *step* defaults to 1).
3218 +*read* ?*-nonewline*? 'fileId'+
3220 +'fileId' *read* ?*-nonewline*?+
3222 +*read* 'fileId numBytes'+
3224 +'fileId' *read* 'numBytes'+
3227 In the first form, all of the remaining bytes are read from the file
3228 given by *fileId*; they are returned as the result of the command.
3229 If the '-nonewline' switch is specified then the last
3230 character of the file is discarded if it is a newline.
3232 In the second form, the extra argument specifies how many bytes to read;
3233 exactly this many bytes will be read and returned, unless there are fewer than
3234 *numBytes* bytes left in the file; in this case, all the remaining
3237 *fileId* must be 'stdin' or the return value from a previous call
3238 to 'open'; it must refer to a file that was opened for reading.
3242 +*regexp ?-nocase? ?-line? ?-indices? ?-start* 'offset'? *?-all? ?-inline? ?--?* 'exp string ?matchVar? ?subMatchVar subMatchVar ...?'+
3244 Determines whether the regular expression *exp* matches part or
3245 all of *string* and returns 1 if it does, 0 if it doesn't.
3247 See REGULAR EXPRESSIONS above for complete information on the
3248 syntax of *exp* and how it is matched against *string*.
3250 If additional arguments are specified after *string* then they
3251 are treated as the names of variables to use to return
3252 information about which part(s) of *string* matched *exp*.
3253 *matchVar* will be set to the range of *string* that
3254 matched all of *exp*. The first *subMatchVar* will contain
3255 the characters in *string* that matched the leftmost parenthesized
3256 subexpression within *exp*, the next *subMatchVar* will
3257 contain the characters that matched the next parenthesized
3258 subexpression to the right in *exp*, and so on.
3260 Normally, *matchVar* and the each *subMatchVar* are set to hold the
3261 matching characters from 'string', however see '-indices' and
3264 If there are more values for *subMatchVar* than parenthesized subexpressions
3265 within *exp*, or if a particular subexpression in *exp* doesn't
3266 match the string (e.g. because it was in a portion of the expression
3267 that wasn't matched), then the corresponding *subMatchVar* will be
3268 set to '"-1 -1"' if '-indices' has been specified or to an empty
3271 The following switches modify the behaviour of *regexp*
3274 Causes upper-case and lower-case characters to be treated as
3275 identical during the matching process.
3278 Use newline-sensitive matching. By default, newline
3279 is a completely ordinary character with no special meaning in
3280 either REs or strings. With this flag, '[^' bracket expressions
3281 and '.' never match newline, a '^' anchor matches the null
3282 string after any newline in the string in addition to its normal
3283 function, and the '$' anchor matches the null string before any
3284 newline in the string in addition to its normal function.
3287 Changes what is stored in the subMatchVars. Instead of
3288 storing the matching characters from string, each variable
3289 will contain a list of two decimal strings giving the indices
3290 in string of the first and last characters in the matching
3291 range of characters.
3293 +*-start* 'offset'+::
3294 Specifies a character index offset into the string at which to start
3295 matching the regular expression. If '-indices' is
3296 specified, the indices will be indexed starting from the
3297 absolute beginning of the input string. *offset* will be
3298 constrained to the bounds of the input string.
3301 Causes the regular expression to be matched as many times as possible
3302 in the string, returning the total number of matches found. If this
3303 is specified with match variables, they will contain information
3304 for the last match only.
3307 Causes the command to return, as a list, the data that would otherwise
3308 be placed in match variables. When using '-inline', match variables
3309 may not be specified. If used with '-all', the list will be concatenated
3310 at each iteration, such that a flat list is always returned. For
3311 each match iteration, the command will append the overall match
3312 data, plus one element for each subexpression in the regular
3316 Marks the end of switches. The argument following this one will be
3317 treated as *exp* even if it starts with a +-+.
3321 +*regsub ?-nocase? ?-all? ?-line? ?-start* 'offset'? ?*--*? 'exp string subSpec ?varName?'+
3323 This command matches the regular expression *exp* against
3324 *string* using the rules described in REGULAR EXPRESSIONS
3327 If *varName* is specified, the commands stores *string* to *varName*
3328 with the substitutions detailed below, and returns the number of
3329 substitutions made (normally 1 unless '-all' is specified).
3330 This is 0 if there were no matches.
3332 If *varName* is not specified, the substituted string will be returned
3335 When copying *string*, the portion of *string* that
3336 matched *exp* is replaced with *subSpec*.
3337 If *subSpec* contains a '&' or '{backslash}0', then it is replaced
3338 in the substitution with the portion of *string* that
3341 If *subSpec* contains a '{backslash}*n*', where *n* is a digit
3342 between 1 and 9, then it is replaced in the substitution with
3343 the portion of *string* that matched the **n**-th
3344 parenthesized subexpression of *exp*.
3345 Additional backslashes may be used in *subSpec* to prevent special
3346 interpretation of '&' or '{backslash}0' or '{backslash}*n*' or
3349 The use of backslashes in *subSpec* tends to interact badly
3350 with the Tcl parser's use of backslashes, so it's generally
3351 safest to enclose *subSpec* in braces if it includes
3354 The following switches modify the behaviour of *regsub*
3357 Upper-case characters in *string* are converted to lower-case
3358 before matching against *exp*; however, substitutions
3359 specified by *subSpec* use the original unconverted form
3363 All ranges in *string* that match *exp* are found and substitution
3364 is performed for each of these ranges, rather than only the
3365 first. The '&' and '{backslash}*n*' sequences are handled for
3366 each substitution using the information from the corresponding
3370 Use newline-sensitive matching. By default, newline
3371 is a completely ordinary character with no special meaning in
3372 either REs or strings. With this flag, '[^' bracket expressions
3373 and '.' never match newline, a '^' anchor matches the null
3374 string after any newline in the string in addition to its normal
3375 function, and the '$' anchor matches the null string before any
3376 newline in the string in addition to its normal function.
3378 +*-start* 'offset'+::
3379 Specifies a character index offset into the string at which to
3380 start matching the regular expression. *offset* will be
3381 constrained to the bounds of the input string.
3384 Marks the end of switches. The argument following this one will be
3385 treated as *exp* even if it starts with a +-+.
3389 +*ref* 'string tag ?finalizer?'+
3391 Create a new reference containing *string* of type *tag*.
3392 If *finalizer* is specified, it is a command which will be invoked
3393 when the a garbage collection cycle runs and this reference is
3394 no longer accessible.
3396 The finalizer is invoked as:
3398 +finalizer 'reference string'+
3400 See GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail.
3404 +*rename* 'oldName newName'+
3406 Rename the command that used to be called *oldName* so that it
3407 is now called *newName*. If *newName* is an empty string
3408 (e.g. {}) then *oldName* is deleted. The 'rename' command
3409 returns an empty string as result.
3413 +*return* ?*-code* 'code'? ?*-errorinfo* 'stacktrace'? ?*-errorcode* 'errorcode'? ?*-level* 'n'? ?'value'?+
3415 Return immediately from the current procedure (or top-level command
3416 or 'source' command), with *value* as the return value. If *value*
3417 is not specified, an empty string will be returned as result.
3419 If *-code* is specified (as either a number or ok, error, break,
3420 continue, signal, return or exit), this code will be used instead
3421 of +JIM_OK+. This is generally useful when implementing flow of control
3424 If *-level* is specified and greater than 1, it has the effect of delaying
3425 the new return code from *-code*. This is useful when rethrowing an error
3426 from 'catch'. See the implementation of try/catch in tclcompat.tcl for
3427 an example of how this is done.
3429 Note: The following options are only used when *-code* is JIM_ERR.
3431 If *-errorinfo* is specified (as returned from 'info stacktrace')
3432 it is used to initialize the stacktrace.
3434 If *-errorcode* is specified, it is used to set the global variable $::errorCode.
3438 +*scan* 'string format varName1 ?varName2 ...?'+
3440 This command parses fields from an input string in the same fashion
3441 as the C 'sscanf' procedure. *String* gives the input to be parsed
3442 and *format* indicates how to parse it, using '%' fields as in
3443 'sscanf'. All of the 'sscanf' options are valid; see the 'sscanf'
3444 man page for details. Each *varName* gives the name of a variable;
3445 when a field is scanned from *string*, the result is converted back
3446 into a string and assigned to the corresponding *varName*. The
3447 only unusual conversion is for '%c'. For '%c' conversions a single
3448 character value is converted to a decimal string, which is then
3449 assigned to the corresponding *varName*; no field width may be
3450 specified for this conversion.
3454 +*seek* 'fileId offset ?origin?'+
3456 +'fileId' *seek* 'offset ?origin?'+
3458 Change the current access position for *fileId*.
3459 The *offset* and *origin* arguments specify the position at
3460 which the next read or write will occur for *fileId*.
3461 *offset* must be a number (which may be negative) and *origin*
3462 must be one of the following:
3465 The new access position will be *offset* bytes from the start
3469 The new access position will be *offset* bytes from the current
3470 access position; a negative *offset* moves the access position
3471 backwards in the file.
3474 The new access position will be *offset* bytes from the end of
3475 the file. A negative *offset* places the access position before
3476 the end-of-file, and a positive *offset* places the access position
3477 after the end-of-file.
3479 The *origin* argument defaults to 'start'.
3481 *fileId* must have been the return value from a previous call to
3482 'open', or it may be 'stdin', 'stdout', or 'stderr' to refer to one
3483 of the standard I/O channels.
3485 This command returns an empty string.
3489 +*set* 'varName ?value?'+
3491 Returns the value of variable *varName*.
3493 If *value* is specified, then set the value of *varName* to *value*,
3494 creating a new variable if one doesn't already exist, and return
3497 If *varName* contains an open parenthesis and ends with a
3498 close parenthesis, then it refers to an array element: the characters
3499 before the open parenthesis are the name of the array, and the characters
3500 between the parentheses are the index within the array.
3501 Otherwise *varName* refers to a scalar variable.
3503 If no procedure is active, then *varName* refers to a global
3506 If a procedure is active, then *varName* refers to a parameter
3507 or local variable of the procedure, unless the *global* command
3508 has been invoked to declare *varName* to be global.
3510 The '::' prefix may also be used to explicitly reference a variable
3511 in the global scope.
3515 +*setref* 'reference string'+
3517 Store a new string in *reference*, replacing the existing string.
3518 The reference must be a valid reference create with the 'ref'
3521 See GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail.
3525 Command for signal handling.
3527 See 'kill' for the different forms which may be used to specify signals.
3529 Commands which return a list of signal names do so using the canonical form:
3532 +*signal handle* ?'signals ...'?+::
3533 If no signals are given, returns a list of all signals which are currently
3535 If signals are specified, these are added to the list of signals currently
3538 +*signal ignore* ?'signals ...'?+::
3539 If no signals are given, returns a lists all signals which are currently
3541 If signals are specified, these are added to the list of signals
3542 currently being ignored. These signals are still delivered, but
3543 are not considered by 'catch -signal' or 'try -signal'. Use
3544 'signal check' to determine which signals have occurred but
3547 +*signal default* ?'signals ...'?+::
3548 If no signals are given, returns a lists all signals which are currently have
3549 the default behaviour.
3550 If signals are specified, these are added to the list of signals which have
3551 the default behaviour.
3553 +*signal check ?-clear?* ?'signals ...'?+::
3554 Returns a list of signals which have been delivered to the process
3555 but are 'ignored'. If signals are specified, only that set of signals will
3556 be checked, otherwise all signals will be checked.
3557 If '-clear' is specified, any signals returned are removed and will not be
3558 returned by subsequent calls to 'signal check' unless delivered again.
3560 +*signal throw* ?'signal'?+::
3561 Raises the given signal, which defaults to +SIGINT+ if not specified.
3562 The behaviour is identical to:
3566 Note that 'signal handle' and 'signal ignore' represent two forms of signal
3567 handling. 'signal handle' is used in conjunction with 'catch -signal' or 'try -signal'
3568 to immediately abort execution when the signal is delivered. Alternatively, 'signal ignore'
3569 is used in conjunction with 'signal check' to handle signal synchronously. Consider the
3572 Prevent a processing from taking too long
3574 signal handle SIGALRM
3577 .. possibly long running process ..
3580 puts stderr "Process took too long"
3583 Handle SIGHUP to reconfigure:
3585 signal ignore SIGHUP
3587 ... handle configuration/reconfiguration ...
3588 while {[signal check -clear SIGHUP] eq ""} {
3589 ... do processing ..
3591 # Received SIGHUP, so reconfigure
3598 Pauses for the given number of seconds, which may be a floating
3599 point value less than one to sleep for less than a second, or an
3600 integer to sleep for one or more seconds.
3604 +*source* 'fileName'+
3606 Read file *fileName* and pass the contents to the Tcl interpreter
3607 as a sequence of commands to execute in the normal fashion. The return
3608 value of 'source' is the return value of the last command executed
3609 from the file. If an error occurs in executing the contents of the
3610 file, then the 'source' command will return that error.
3612 If a 'return' command is invoked from within the file, the remainder of
3613 the file will be skipped and the 'source' command will return
3614 normally with the result from the 'return' command.
3618 +*split* 'string ?splitChars?'+
3620 Returns a list created by splitting *string* at each character
3621 that is in the *splitChars* argument.
3623 Each element of the result list will consist of the
3624 characters from *string* between instances of the
3625 characters in *splitChars*.
3627 Empty list elements will be generated if *string* contains
3628 adjacent characters in *splitChars*, or if the first or last
3629 character of *string* is in *splitChars*.
3631 If *splitChars* is an empty string then each character of
3632 *string* becomes a separate element of the result list.
3634 *SplitChars* defaults to the standard white-space characters.
3637 split "comp.unix.misc" .
3639 returns +'"comp unix misc"'+ and
3641 split "Hello world" {}
3643 returns +'"H e l l o { } w o r l d"'+.
3648 +*stackdump* 'stacktrace'+
3650 Creates a human readable representation of a stack trace.
3657 Returns a live stack trace as a list of +proc file line proc file line ...+.
3658 Iteratively uses 'info frame' to create the stack trace. This stack trace is in the
3659 same form as produced by 'catch' and 'info stacktrace'
3661 See also 'stackdump'.
3666 +*string* 'option arg ?arg ...?'+
3668 Perform one of several string operations, depending on *option*.
3669 The legal options (which may be abbreviated) are:
3671 +*string bytelength 'string'+::
3672 Returns the length of the string in bytes. This will return
3673 the same value as 'string length' if UTF-8 support is not enabled,
3674 or if the string is composed entirely of ASCII characters.
3675 See UTF-8 AND UNICODE.
3677 +*string compare ?-nocase?* 'string1 string2'+::
3678 Perform a character-by-character comparison of strings *string1* and
3679 *string2* in the same way as the C 'strcmp' procedure. Return
3680 -1, 0, or 1, depending on whether *string1* is lexicographically
3681 less than, equal to, or greater than *string2*.
3682 Performs a case-insensitive comparison if '-nocase' is specified.
3684 +*string equal ?-nocase?* 'string1 string2'+::
3685 Returns 1 if the strings are equal, or 0 otherwise.
3686 Performs a case-insensitive comparison if '-nocase' is specified.
3688 +*string first* 'string1 string2 ?firstIndex?'+::
3689 Search *string2* for a sequence of characters that exactly match
3690 the characters in *string1*. If found, return the index of the
3691 first character in the first such match within *string2*. If not
3692 found, return -1. If *firstIndex* is specified, matching will start
3693 from *firstIndex* of *string1*.
3695 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *firstIndex*.
3697 +*string index* 'string charIndex'+::
3698 Returns the *charIndex*'th character of the *string*
3699 argument. A *charIndex* of 0 corresponds to the first
3700 character of the string.
3701 If *charIndex* is less than 0 or greater than
3702 or equal to the length of the string then an empty string is
3705 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *charIndex*.
3707 +*string is* 'class' ?*-strict*? 'string'+::
3708 Returns 1 if *string* is a valid member of the specified character
3709 class, otherwise returns 0. If '-strict' is specified, then an
3710 empty string returns 0, otherwise an empty string will return 1
3711 on any class. The following character classes are recognized
3712 (the class name can be abbreviated):
3713 +alnum+;; Any alphabet or digit character.
3714 +alpha+;; Any alphabet character.
3715 +ascii+;; Any character with a value less than 128 (those that are in the 7-bit ascii range).
3716 +control+;; Any control character.
3717 +digit+;; Any digit character.
3718 +double+;; Any of the valid forms for a double in Tcl, with optional surrounding whitespace.
3719 In case of under/overflow in the value, 0 is returned.
3720 +graph+;; Any printing character, except space.
3721 +integer+;; Any of the valid string formats for an integer value in Tcl, with optional surrounding whitespace.
3722 +lower+;; Any lower case alphabet character.
3723 +print+;; Any printing character, including space.
3724 +punct+;; Any punctuation character.
3725 +space+;; Any space character.
3726 +upper+;; Any upper case alphabet character.
3727 +xdigit+;; Any hexadecimal digit character ([0-9A-Fa-f]).
3729 Note that string classification does *not* respect UTF-8. See UTF-8 AND UNICODE
3731 +*string last* 'string1 string2 ?lastIndex?'+::
3732 Search *string2* for a sequence of characters that exactly match
3733 the characters in *string1*. If found, return the index of the
3734 first character in the last such match within *string2*. If there
3735 is no match, then return -1. If *lastIndex* is specified, only characters
3736 up to *lastIndex* of *string2* will be considered in the match.
3738 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *lastIndex*.
3740 +*string length* 'string'+::
3741 Returns a decimal string giving the number of characters in *string*.
3742 If UTF-8 support is enabled, this may be different than the number of bytes.
3743 See UTF-8 AND UNICODE
3745 +*string match ?-nocase?* 'pattern string'+::
3746 See if *pattern* matches *string*; return 1 if it does, 0
3747 if it doesn't. Matching is done in a fashion similar to that
3748 used by the C-shell. For the two strings to match, their contents
3749 must be identical except that the following special sequences
3750 may appear in *pattern*:
3753 Matches any sequence of characters in *string*,
3754 including a null string.
3757 Matches any single character in *string*.
3760 Matches any character in the set given by *chars*.
3761 If a sequence of the form *x*-*y* appears in *chars*,
3762 then any character between *x* and *y*, inclusive,
3766 Matches the single character *x*. This provides a way of
3767 avoiding the special interpretation of the characters \`\*?[]\`
3770 Performs a case-insensitive comparison if '-nocase' is specified.
3772 +*string range* 'string first last'+::
3773 Returns a range of consecutive characters from *string*, starting
3774 with the character whose index is *first* and ending with the
3775 character whose index is *last*. An index of 0 refers to the
3776 first character of the string.
3778 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *first* and *last*.
3780 If *first* is less than zero then it is treated as if it were zero, and
3781 if *last* is greater than or equal to the length of the string then
3782 it is treated as if it were 'end'. If *first* is greater than
3783 *last* then an empty string is returned.
3785 +*string byterange* 'string first last'+::
3786 Like 'string range' except works on bytes rather than characters. These commands
3787 are identical if UTF-8 support is not enabled
3789 +*string repeat* 'string count'+::
3790 Returns a new string consisting of *string* repeated *count* times.
3792 +*string reverse* 'string'+::
3793 Returns a string that is the same length as *string* but
3794 with its characters in the reverse order.
3796 +*string tolower* 'string'+::
3797 Returns a value equal to *string* except that all upper case
3798 letters have been converted to lower case.
3800 +*string toupper* 'string'+::
3801 Returns a value equal to *string* except that all lower case
3802 letters have been converted to upper case.
3804 +*string trim* 'string ?chars?'+::
3805 Returns a value equal to *string* except that any leading
3806 or trailing characters from the set given by *chars* are
3808 If *chars* is not specified then white space is removed
3809 (spaces, tabs, newlines, and carriage returns).
3811 +*string trimleft* 'string ?chars?'+::
3812 Returns a value equal to *string* except that any
3813 leading characters from the set given by *chars* are
3815 If *chars* is not specified then white space is removed
3816 (spaces, tabs, newlines, and carriage returns).
3818 +*string trimright* 'string ?chars?'+::
3819 Returns a value equal to *string* except that any
3820 trailing characters from the set given by *chars* are
3822 If *chars* is not specified then white space is removed
3823 (spaces, tabs, newlines, and carriage returns).
3824 Null characters are always removed.
3828 +*subst ?-nobackslashes? ?-nocommands? ?-novariables?* 'string'+
3830 This command performs variable substitutions, command substitutions,
3831 and backslash substitutions on its string argument and returns the
3832 fully-substituted result. The substitutions are performed in exactly
3833 the same way as for Tcl commands. As a result, the string argument
3834 is actually substituted twice, once by the Tcl parser in the usual
3835 fashion for Tcl commands, and again by the subst command.
3837 If any of the *-nobackslashes*, *-nocommands*, or *-novariables* are
3838 specified, then the corresponding substitutions are not performed.
3839 For example, if *-nocommands* is specified, no command substitution
3840 is performed: open and close brackets are treated as ordinary
3841 characters with no special interpretation.
3843 *Note*: when it performs its substitutions, subst does not give any
3844 special treatment to double quotes or curly braces. For example,
3845 the following script returns 'xyz \{44\}', not 'xyz \{$a\}'.
3853 +*switch* '?options? string pattern body ?pattern body ...?'+
3855 +*switch* '?options? string {pattern body ?pattern body ...?}'+
3857 The 'switch' command matches its string argument against each of
3858 the pattern arguments in order. As soon as it finds a pattern that
3859 matches string it evaluates the following body and returns the
3860 result of that evaluation. If the last pattern argument is default
3861 then it matches anything. If no pattern argument matches string and
3862 no default is given, then the switch command returns an empty string.
3863 If the initial arguments to switch start with - then they are treated
3864 as options. The following options are currently supported:
3867 Use exact matching when comparing string to a
3868 pattern. This is the default.
3871 When matching string to the patterns, use glob-style
3872 matching (i.e. the same as implemented by the string
3876 When matching string to the patterns, use regular
3877 expression matching (i.e. the same as implemented
3878 by the regexp command).
3880 +-command 'commandname'+::
3881 When matching string to the patterns, use the given command, which
3882 must be a single word. The command is invoked as
3883 'commandname pattern string', or 'commandname -nocase pattern string'
3884 and must return 1 if matched, or 0 if not.
3887 Marks the end of options. The argument following
3888 this one will be treated as string even if it starts
3891 Two syntaxes are provided for the pattern and body arguments. The
3892 first uses a separate argument for each of the patterns and commands;
3893 this form is convenient if substitutions are desired on some of the
3894 patterns or commands. The second form places all of the patterns
3895 and commands together into a single argument; the argument must
3896 have proper list structure, with the elements of the list being the
3897 patterns and commands. The second form makes it easy to construct
3898 multi-line switch commands, since the braces around the whole list
3899 make it unnecessary to include a backslash at the end of each line.
3900 Since the pattern arguments are in braces in the second form, no
3901 command or variable substitutions are performed on them; this makes
3902 the behaviour of the second form different than the first form in
3905 If a body is specified as '-' it means that the body for the next
3906 pattern should also be used as the body for this pattern (if the
3907 next pattern also has a body of ``-'' then the body after that is
3908 used, and so on). This feature makes it possible to share a single
3909 body among several patterns.
3911 Below are some examples of switch commands:
3913 switch abc a - b {format 1} abc {format 2} default {format 3}
3917 switch -regexp aaab {
3937 +*tailcall* 'cmd ?arg...?'+
3939 The 'tailcall' command provides an optimised way of invoking a command whilst replacing
3940 the current call frame. This is similar to 'exec' in Bourne Shell.
3942 The following are identical except the first immediately replaces the current call frame.
3946 return [uplevel 1 a b c]
3948 'tailcall' is useful for a dispatch mechanism:
3951 tailcall sub_$cmd {*}$args
3962 Returns a decimal string giving the current access position in
3965 *fileId* must have been the return value from a previous call to
3966 'open', or it may be 'stdin', 'stdout', or 'stderr' to refer to one
3967 of the standard I/O channels.
3971 +*throw* 'code ?msg?'+
3973 This command throws an exception (return) code along with an optional message.
3974 This command is mostly for convenient usage with 'try'.
3976 The command +throw break+ is equivalent to +break+.
3977 The command +throw 20 message+ can be caught with an +on 20 ...+ clause to 'try'.
3981 +*time* 'command ?count?'+
3983 This command will call the Tcl interpreter *count*
3984 times to execute *command* (or once if *count* isn't
3985 specified). It will then return a string of the form
3987 503 microseconds per iteration
3989 which indicates the average amount of time required per iteration,
3992 Time is measured in elapsed time, not CPU time.
3996 +*try* '?catchopts? tryscript' ?*on* 'returncodes {?resultvar? ?optsvar?} handlerscript ...'? ?*finally* 'finalscript'?+
3998 The 'try' command is provided as a convenience for exception handling.
4000 This interpeter first evaluates *tryscript* under the effect of the catch
4001 options *catchopts* (e.g. +-signal -noexit --+, see 'catch').
4003 It then evaluates the script for the first matching 'on' handler
4004 (there many be zero or more) based on the return code from the 'try'
4005 section. For example a normal +JIM_ERR+ error will be matched by
4006 an 'on error' handler.
4008 Finally, any *finalscript* is evaluated.
4010 The result of this command is the result of *tryscript*, except in the
4011 case where an exception occurs in a matching 'on' handler script or the 'finally' script,
4012 in which case the result is this new exception.
4014 The specified *returncodes* is a list of return codes either as names ('ok', 'error', 'break', etc.)
4017 If *resultvar* and *optsvar* are specified, they are set as for 'catch' before evaluating
4018 the matching handler.
4025 } on {continue break} {} {
4026 error "Unexpected break/continue"
4027 } on error {msg opts} {
4028 puts "Dealing with error"
4029 return {*}$opts $msg
4031 puts "Got signal: $sig"
4036 If break, continue or error are raised, they are dealt with by the matching
4039 In any case, the file will be closed via the 'finally' clause.
4041 See also 'throw', 'catch', 'return', 'error'.
4045 +*unknown* 'cmdName ?arg arg ...?'+
4047 This command doesn't actually exist as part of Tcl, but Tcl will
4048 invoke it if it does exist.
4050 If the Tcl interpreter encounters a command name for which there
4051 is not a defined command, then Tcl checks for the existence of
4052 a command named 'unknown'.
4054 If there is no such command, then the interpreter returns an
4057 If the 'unknown' command exists, then it is invoked with
4058 arguments consisting of the fully-substituted name and arguments
4059 for the original non-existent command.
4061 The 'unknown' command typically does things like searching
4062 through library directories for a command procedure with the name
4063 *cmdName*, or expanding abbreviated command names to full-length,
4064 or automatically executing unknown commands as UNIX sub-processes.
4066 In some cases (such as expanding abbreviations) 'unknown' will
4067 change the original command slightly and then (re-)execute it.
4068 The result of the 'unknown' command is used as the result for
4069 the original non-existent command.
4073 +*unset ?-nocomplain? ?--?* '?name name ...?'+
4076 Each *name* is a variable name, specified in any of the
4077 ways acceptable to the 'set' command.
4079 If a *name* refers to an element of an array, then that
4080 element is removed without affecting the rest of the array.
4082 If a *name* consists of an array name with no parenthesized
4083 index, then the entire array is deleted.
4085 The 'unset' command returns an empty string as result.
4087 An error occurs if any of the variables doesn't exist, unless '-nocomplain'
4088 is specified. The '--' argument may be specified to stop option processing
4089 in case the variable name may be '-nocomplain'.
4093 +*upcall* 'command ?args ...?'+
4095 May be used from within a proc defined as +local proc+ in order to call
4096 the previous, hidden version of the same command.
4098 If there is no previous definition of the command, an error is returned.
4102 +*uplevel* '?level? command ?command ...?'+
4104 All of the *command* arguments are concatenated as if they had
4105 been passed to 'concat'; the result is then evaluated in the
4106 variable context indicated by *level*. 'Uplevel' returns
4107 the result of that evaluation. If *level* is an integer, then
4108 it gives a distance (up the procedure calling stack) to move before
4109 executing the command. If *level* consists of '\#' followed by
4110 a number then the number gives an absolute level number. If *level*
4111 is omitted then it defaults to '1'. *Level* cannot be
4112 defaulted if the first *command* argument starts with a digit or '#'.
4114 For example, suppose that procedure 'a' was invoked
4115 from top-level, and that it called 'b', and that 'b' called 'c'.
4116 Suppose that 'c' invokes the 'uplevel' command. If *level*
4117 is '1' or '#2' or omitted, then the command will be executed
4118 in the variable context of 'b'. If *level* is '2' or '#1'
4119 then the command will be executed in the variable context of 'a'.
4121 If *level* is '3' or '#0' then the command will be executed
4122 at top-level (only global variables will be visible).
4123 The 'uplevel' command causes the invoking procedure to disappear
4124 from the procedure calling stack while the command is being executed.
4125 In the above example, suppose 'c' invokes the command
4127 uplevel 1 {set x 43; d}
4129 where 'd' is another Tcl procedure. The 'set' command will
4130 modify the variable 'x' in 'b's context, and 'd' will execute
4131 at level 3, as if called from 'b'. If it in turn executes
4136 then the 'set' command will modify the same variable 'x' in 'b's
4137 context: the procedure 'c' does not appear to be on the call stack
4138 when 'd' is executing. The command 'info level' may
4139 be used to obtain the level of the current procedure.
4141 'Uplevel' makes it possible to implement new control
4142 constructs as Tcl procedures (for example, 'uplevel' could
4143 be used to implement the 'while' construct as a Tcl procedure).
4147 +*upvar* '?level? otherVar myVar ?otherVar myVar ...?'+
4149 This command arranges for one or more local variables in the current
4150 procedure to refer to variables in an enclosing procedure call or
4151 to global variables.
4153 *Level* may have any of the forms permitted for the 'uplevel'
4154 command, and may be omitted if the first letter of the first *otherVar*
4155 isn't '#' or a digit (it defaults to '1').
4157 For each *otherVar* argument, 'upvar' makes the variable
4158 by that name in the procedure frame given by *level* (or at
4159 global level, if *level* is '#0') accessible
4160 in the current procedure by the name given in the corresponding
4163 The variable named by *otherVar* need not exist at the time of the
4164 call; it will be created the first time *myVar* is referenced, just like
4165 an ordinary variable.
4167 'Upvar' may only be invoked from within procedures.
4169 'Upvar' returns an empty string.
4171 The 'upvar' command simplifies the implementation of call-by-name
4172 procedure calling and also makes it easier to build new control constructs
4174 For example, consider the following procedure:
4181 'Add2' is invoked with an argument giving the name of a variable,
4182 and it adds two to the value of that variable.
4183 Although 'add2' could have been implemented using 'uplevel'
4184 instead of 'upvar', 'upvar' makes it simpler for 'add2'
4185 to access the variable in the caller's procedure frame.
4189 +*while* 'test body'+
4191 The *while* command evaluates *test* as an expression
4192 (in the same way that 'expr' evaluates its argument).
4193 The value of the expression must be numeric; if it is non-zero
4194 then *body* is executed by passing it to the Tcl interpreter.
4196 Once *body* has been executed then *test* is evaluated
4197 again, and the process repeats until eventually *test*
4198 evaluates to a zero numeric value. 'Continue'
4199 commands may be executed inside *body* to terminate the current
4200 iteration of the loop, and 'break'
4201 commands may be executed inside *body* to cause immediate
4202 termination of the 'while' command.
4204 The 'while' command always returns an empty string.
4209 The following extensions may or may not be available depending upon
4210 what options were selected when Jim Tcl was built.
4212 posix: os.fork, os.wait, os.gethostname, os.getids, os.uptime
4213 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4215 Invokes 'fork(2)' and returns the result.
4217 +*os.wait -nohang* 'pid'+::
4218 Invokes waitpid(2), with WNOHANG if *-nohang* is specified.
4219 Returns a list of 3 elements.
4221 {0 none 0} if -nohang is specified, and the process is still alive.
4223 {-1 error <error-description>} if the process does not exist or has already been waited for.
4225 {<pid> exit <exit-status>} if the process exited normally.
4227 {<pid> signal <signal-number>} if the process terminated on a signal.
4229 {<pid> other 0} otherwise (core dump, stopped, continued, etc.)
4231 +*os.gethostname*+::
4232 Invokes 'gethostname(3)' and returns the result.
4235 Returns the various user/group ids for the current process.
4238 uid 1000 euid 1000 gid 100 egid 100
4241 Returns the number of seconds since system boot. See description of 'uptime' in 'sysinfo(2)'.
4243 ANSI I/O (aio) and EVENTLOOP API
4244 --------------------------------
4245 Jim provides an alternative object-based API for I/O.
4247 See '<<_open,open>>' and '<<_socket,socket>>' for commands which return an I/O handle.
4251 +$handle *read ?-nonewline?* '?len?'+::
4252 Read and return bytes from the stream. To eof if no len.
4254 +$handle *gets* '?var?'+::
4255 Read one line and return it or store it in the var
4257 +$handle *puts ?-nonewline?* 'str'+::
4258 Write the string, with newline unless -nonewline
4260 +$handle *copyto* 'tofd ?size?'+::
4261 Copy bytes to the file descriptor *tofd*. If *size* is specified, at most
4262 that many bytes will be copied. Otherwise copying continues until the end
4263 of the input file. Returns the number of bytes actually copied.
4268 +$handle *filename*+::
4269 Returns the original filename associated with the handle.
4270 Handles returned by 'socket' give the socket type instead of a filename.
4273 Returns 1 if stream is at eof
4278 +$handle *seek* 'offset' *?start|current|end?*+::
4279 Seeks in the stream (default 'current')
4282 Returns the current seek position
4284 +$handle *filename*+::
4285 Returns the original filename used when opening the file.
4286 If the handle was returned from 'socket', the type of the
4287 handle is returned instead.
4289 +$handle *ndelay ?0|1?*+::
4290 Set O_NDELAY (if arg). Returns current/new setting.
4291 Note that in general ANSI I/O interacts badly with non-blocking I/O.
4294 +$handle *buffering none|line|full*+::
4295 Sets the buffering mode of the stream.
4297 +$handle *accept*+::
4298 Server socket only: Accept a connection and return stream
4300 +$handle *sendto* 'str ?hostname:?port'+::
4301 Sends the string, *str*, to the given address via the socket using sendto(2).
4302 This is intended for udp sockets and may give an error or behave in unintended
4303 ways for other handle types.
4304 Returns the number of bytes written.
4306 +$handle *recvfrom* 'maxlen ?addrvar?'+::
4307 Receives a message from the handle via recvfrom(2) and returns it.
4308 At most *maxlen* bytes are read.
4309 If *addrvar* is specified, the sending address of the message is stored in
4310 the named variable in the form 'addr:port'. See 'socket' for details.
4312 eventloop: after, vwait, update
4313 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4315 The following commands allow a script to be invoked when the given condition occurs.
4316 If no script is given, returns the current script. If the given script is the empty, the
4319 +$handle *readable* '?readable-script?'+::
4320 Sets or returns the script for when the socket is readable.
4322 +$handle *writable* '?writable-script?'+::
4323 Sets or returns the script for when the socket is writable.
4325 +$handle *onexception* '?exception-script?'+::
4326 Sets or returns the script for when when oob data received.
4328 For compatibility with 'Tcl', these may be prefixed with 'fileevent'. e.g.
4331 +fileevent $handle *readable* '...'+
4333 Time-based execution is also available via the eventloop API.
4336 Sleeps for the given number of milliseconds. No events are
4337 processed during this time.
4339 +*after* 'ms|*idle* script ?script ...?'+::
4340 The scripts are concatenated and executed after the given
4341 number of milliseconds have elapsed. If 'idle' is specified,
4342 the script will run the next time the event loop is processed
4343 with 'vwait' or 'update'. The script is only run once and
4344 then removed. Returns an event id.
4346 +*after cancel* 'id|command'+::
4347 Cancels an 'after' event with the given event id or matching
4348 command (script). Returns the number of milliseconds
4349 remaining until the event would have fired. Returns the
4350 empty string if no matching event is found.
4352 +*after info* '?id?'+::
4353 If *id* is not given, returns a list of current 'after'
4354 events. If *id* is given, returns a list containing the
4355 associated script and either 'timer' or 'idle' to indicated
4356 the type of the event. An error occurs if *id* does not
4359 +*vwait* 'variable'+::
4360 A call to 'vwait' is enters the eventloop. 'vwait' processes
4361 events until the named (global) variable changes or all
4362 event handlers are removed. The variable need not exist
4363 beforehand. If there are no event handlers defined, 'vwait'
4364 returns immediately.
4366 +*update ?idletasks?*+::
4367 A call to 'update' enters the eventloop to process expired events, but
4368 no new events. If 'idletasks' is specified, only expired time events are handled,
4370 Returns once handlers have been run for all expired events.
4372 Scripts are executed at the global scope. If an error occurs during a handler script,
4373 an attempt is made to call (the user-defined command) 'bgerror' with the details of the error.
4374 If the 'bgerror' commands does not exist, it is printed to stderr instead.
4376 If a file event handler script generates an error, the handler is automatically removed
4377 to prevent infinite errors. (A time event handler is always removed after execution).
4379 +*bgerror* 'error'+::
4380 Called when an event handler script generates an error.
4384 Various socket types may be created.
4386 +*socket unix* 'path'+::
4387 A unix domain socket client.
4389 +*socket unix.server* 'path'+::
4390 A unix domain socket server.
4392 +*socket ?-ipv6? stream* 'addr:port'+::
4393 A TCP socket client.
4395 +*socket ?-ipv6? stream.server '?addr:?port'+::
4396 A TCP socket server (*addr* defaults to 0.0.0.0 for IPv4 or [::] for IPv6).
4398 +*socket ?-ipv6? dgram* ?'addr:port'?+::
4399 A UDP socket client. If the address is not specified,
4400 the client socket will be unbound and 'sendto' must be used
4401 to indicated the destination.
4403 +*socket ?-ipv6? dgram.server* 'addr:port'+::
4404 A UDP socket server.
4407 A pipe. Note that unlike all other socket types, this command returns
4408 a list of two channels: {read write}
4410 This command creates a socket connected (client) or bound (server) to the given
4413 The returned value is channel and may generally be used with the various file I/O
4414 commands (gets, puts, read, etc.), either as object-based syntax or Tcl-compatible syntax.
4416 set f [socket stream www.google.com:80]
4418 $f puts -nonewline "GET / HTTP/1.0\r\n\r\n"
4423 Server sockets, however support only 'accept', which is most useful in conjunction with
4426 set f [socket stream.server 80]
4428 set client [$f accept]
4431 $client puts -nonewline "HTTP/1.1 404 Not found\r\n"
4436 The address, *addr*, can be given in one of the following forms:
4438 1. For IPv4 socket types, an IPv4 address such as 192.168.1.1
4439 2. For IPv6 socket types, an IPv6 address such as [fe80::1234] or [::]
4442 Note that on many systems, listening on an IPv6 address such as [::] will
4443 also accept requests via IPv4.
4445 Where a hostname is specified, the *first* returned address is used
4446 which matches the socket type is used.
4448 The special type 'pipe' isn't really a socket.
4450 lassign [socket pipe] r w
4452 # Must close $w after exec
4460 +*syslog* '?options? ?priority? message'+
4462 This command sends message to system syslog facility with given
4463 priority. Valid priorities are:
4465 emerg, alert, crit, err, error, warning, notice, info, debug
4467 If a message is specified, but no priority is specified, then a
4468 priority of info is used.
4470 By default, facility user is used and the value of global tcl variable
4471 argv0 is used as ident string. However, any of the following options
4472 may be specified before priority to control these parameters:
4474 +*-facility* 'value'+::
4475 Use specified facility instead of user. The following
4476 values for facility are recognized:
4478 authpriv, cron, daemon, kernel, lpr, mail, news, syslog, user,
4481 +*-ident* 'string'+::
4482 Use given string instead of argv0 variable for ident string.
4484 +*-options* 'integer'+::
4485 Set syslog options such as +LOG_CONS+, +LOG_NDELAY+. You should
4486 use numeric values of those from your system syslog.h file,
4487 because I haven't got time to implement yet another hash
4490 [[BuiltinVariables]]
4494 The following global variables are created automatically
4498 This variable is set by Jim as an array
4499 whose elements are the environment variables for the process.
4500 Reading an element will return the value of the corresponding
4501 environment variable.
4502 This array is initialised at startup from the 'env' command.
4503 It may be modified and will affect the environment passed to
4504 commands invoked with 'exec'.
4507 This variable is set by Jim as an array containing information
4508 about the platform on which Jim was built. Currently this includes
4509 'os' and 'platform'.
4512 This variable contains a list of paths to search for packages.
4513 It defaults to a location based on where jim is installed
4514 (e.g. +/usr/local/lib/jim+), but may be changed by +jimsh+
4515 or the embedding application. Note that +jimsh+ will consider
4516 the environment variable +$JIMLIB+ to be a list of colon-separated
4517 list of paths to add to *auto_path*.
4520 This variable holds the value of the -errorcode return
4521 option set by the most recent error that occurred in this
4522 interpreter. This list value represents additional information
4523 about the error in a form that is easy to process with
4524 programs. The first element of the list identifies a general
4525 class of errors, and determines the format of the rest of
4526 the list. The following formats for -errorcode return options
4527 are used by the Tcl core; individual applications may define
4528 additional formats. Currently only 'exec' sets this variable.
4529 Otherwise it will be *NONE*.
4531 The following global variables are set by jimsh.
4533 +*tcl_interactive*+::
4534 This variable is set to 1 if jimsh is started in interactive mode
4538 This variable is set by Jim as an array containing information
4539 about the platform upon which Jim was built. The following is an
4540 example of the contents of this array.
4542 tcl_platform(byteOrder) = littleEndian
4543 tcl_platform(os) = Darwin
4544 tcl_platform(platform) = unix
4545 tcl_platform(pointerSize) = 8
4546 tcl_platform(threaded) = 0
4547 tcl_platform(wordSize) = 8
4550 If jimsh is invoked to run a script, this variable contains the name
4554 If jimsh is invoked to run a script, this variable contains a list
4555 of any arguments supplied to the script.
4558 If jimsh is invoked to run a script, this variable contains the number
4559 of arguments supplied to the script.
4562 The value of argv[0] when jimsh was invoked.
4564 CHANGES IN PREVIOUS RELEASES
4565 ----------------------------
4569 1. 'source' now checks that a script is complete (.i.e. not missing a brace)
4570 2. 'info complete' now uses the real parser and so is 100% accurate
4571 3. Better access to live stack frames with 'info frame', 'stacktrace' and 'stackdump'
4572 4. 'tailcall' no longer loses stack trace information
4573 5. Add 'alias' and 'curry'
4574 6. 'lambda', 'alias' and 'curry' are implemented via 'tailcall' for efficiency
4575 7. 'local' allows procedures to be deleted automatically at the end of the current procedure
4576 8. udp sockets are now supported for both clients and servers.
4577 9. vfork-based exec is now working correctly
4578 10. Add 'file tempfile'
4579 11. Add 'socket pipe'
4580 12. Enhance 'try ... on ... finally' to be more Tcl 8.6 compatible
4581 13. It is now possible to 'return' from within 'try'
4582 14. IPv6 support is now included
4584 16. Event handlers works better if an error occurs. eof handler has been removed.
4585 17. 'exec' now sets $::errorCode, and catch sets opts(-errorcode) for exit status
4586 18. Command pipelines via open "|..." are now supported
4587 19. 'pid' can now return pids of a command pipeline
4588 20. Add 'info references'
4589 21. Add support for 'after *ms*', 'after idle', 'after info', 'update'
4590 22. 'exec' now sets environment based on $::env
4592 24. Add support for 'lsort -index'
4596 1. Add support to 'exec' for '>&', '>>&', '|&', '2>@1'
4597 2. Fix 'exec' error messages when special token (e.g. '>') is the last token
4598 3. Fix 'subst' handling of backslash escapes.
4599 4. Allow abbreviated options for 'subst'
4600 5. Add support for 'return', 'break', 'continue' in subst
4601 6. Many 'expr' bug fixes
4602 7. Add support for functions in 'expr' (e.g. int(), abs()), and also 'in', 'ni' list operations
4603 8. The variable name argument to 'regsub' is now optional
4604 9. Add support for 'unset -nocomplain'
4605 10. Add support for list commands: 'lassign', 'lrepeat'
4606 11. Fully-functional 'lsearch' is now implemented
4607 12. Add 'info nameofexecutable' and 'info returncodes'
4608 13. Allow 'catch' to determine what return codes are caught
4609 14. Allow 'incr' to increment an unset variable by first setting to 0
4610 15. Allow 'args' and optional arguments to the left or required arguments in 'proc'
4612 17. Add 'try ... finally' command
4618 Copyright 2005 Salvatore Sanfilippo <antirez@invece.org>
4619 Copyright 2005 Clemens Hintze <c.hintze@gmx.net>
4620 Copyright 2005 patthoyts - Pat Thoyts <patthoyts@users.sf.net>
4621 Copyright 2008 oharboe - Oyvind Harboe - oyvind.harboe@zylin.com
4622 Copyright 2008 Andrew Lunn <andrew@lunn.ch>
4623 Copyright 2008 Duane Ellis <openocd@duaneellis.com>
4624 Copyright 2008 Uwe Klein <uklein@klein-messgeraete.de>
4625 Copyright 2009 Steve Bennett <steveb@workware.net.au>
4628 Redistribution and use in source and binary forms, with or without
4629 modification, are permitted provided that the following conditions
4631 1. Redistributions of source code must retain the above copyright
4632 notice, this list of conditions and the following disclaimer.
4633 2. Redistributions in binary form must reproduce the above
4634 copyright notice, this list of conditions and the following
4635 disclaimer in the documentation and/or other materials
4636 provided with the distribution.
4638 THIS SOFTWARE IS PROVIDED BY THE JIM TCL PROJECT ``AS IS'' AND ANY
4639 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
4640 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
4641 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
4642 JIM TCL PROJECT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
4643 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
4644 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
4645 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
4646 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
4647 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
4648 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
4649 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
4651 The views and conclusions contained in the software and documentation
4652 are those of the authors and should not be interpreted as representing
4653 official policies, either expressed or implied, of the Jim Tcl Project.