| blob | 7ed5274c96b8dea15220904c76ac42a90cdc2725 |
4 <head>
9 /* Shared CSS for AsciiDoc xhtml11 and html5 backends */
11 /* Default font. */
12 body {
14 }
16 /* Title font. */
24 }
26 body {
28 }
30 a {
33 }
36 }
38 em {
41 }
43 strong {
46 }
53 }
57 }
58 h2 {
60 }
61 h3 {
63 }
64 h3 + * {
66 }
67 h5 {
69 }
73 }
75 hr {
77 }
79 p {
82 }
86 }
96 }
97 pre {
99 }
105 }
107 }
109 }
116 }
120 }
124 }
129 }
135 }
141 }
145 }
147 /* Block element titles. */
154 }
157 }
161 }
164 }
167 }
174 }
181 }
189 }
194 }
199 }
203 }
204 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
207 }
216 }
220 }
225 }
231 dl {
234 }
235 dt {
240 }
243 }
247 }
250 }
253 }
256 }
259 }
262 }
269 }
271 tfoot {
273 }
276 }
281 }
284 }
287 }
293 }
296 }
300 }
304 }
308 }
312 }
317 }
321 }
331 }
337 }
340 }
344 }
348 }
356 }
361 }
365 }
369 }
373 }
419 /*
420 * xhtml11 specific
421 *
422 * */
427 }
430 }
434 }
437 }
438 /* Because the table frame attribute is overriden by CSS in most browsers. */
441 }
445 }
449 }
452 /*
453 * html5 specific
454 *
455 * */
460 }
464 }
467 }
474 }
480 }
485 }
489 }
492 }
496 }
499 }
502 }
506 }
509 }
512 }
515 /*
516 * manpage specific
517 *
518 * */
525 }
528 }
531 }
535 }
538 </style>
540 /*<![CDATA[*/
543 /////////////////////////////////////////////////////////////////////
544 // Table Of Contents generator
545 /////////////////////////////////////////////////////////////////////
547 /* Author: Mihai Bazon, September 2002
548 * http://students.infoiasi.ro/~mishoo
549 *
550 * Table Of Content generator
551 * Version: 0.4
552 *
553 * Feel free to use this script under the terms of the GNU General Public
554 * License, as long as you do not remove or alter this notice.
555 */
557 /* modified by Troy D. Hanson, September 2006. License: GPL */
558 /* modified by Stuart Rackham, 2006, 2009. License: GPL */
560 // toclevels = 1..4.
570 }
572 }
578 }
583 // Function that scans the DOM tree for header elements (the DOM2
584 // nodeIterator API would be a better technique but not supported by all
585 // browsers).
592 }
594 }
595 }
596 }
599 }
604 }
606 // Delete existing TOC entries in case we're reloading the TOC.
615 }
618 }
620 // Rebuild TOC entries.
633 }
636 },
639 /////////////////////////////////////////////////////////////////////
640 // Footnotes generator
641 /////////////////////////////////////////////////////////////////////
643 /* Based on footnote generation code from:
644 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
645 */
648 // Delete existing footnote entries in case we're reloading the footnodes.
653 }
659 }
662 }
664 // Rebuild footnote entries.
671 n++;
674 // Use [\s\S] in place of . so multi-line matches work.
675 // Because JavaScript has no s (dotall) regex flag.
681 }
688 }
689 }
693 // Process footnoterefs.
702 }
703 }
704 }
705 },
714 }
715 }
720 }
725 else
727 }
729 }
731 /*]]>*/
732 </script>
733 </head>
736 <h1>
737 Jim Tcl(n) Manual Page
738 </h1>
741 <p>Jim Tcl v0.76+ -
742 reference manual for the Jim Tcl scripting language
743 </p>
744 </div>
745 </div>
753 </div></div>
759 jimsh --version</code></pre>
760 </div></div>
762 <li>
763 <p>
765 </p>
766 </li>
767 <li>
768 <p>
770 </p>
771 </li>
772 <li>
773 <p>
775 </p>
776 </li>
777 <li>
778 <p>
780 </p>
781 </li>
782 </ul></div>
783 </div>
784 </div>
788 <div class="paragraph"><p>Jim Tcl is a small footprint reimplementation of the Tcl scripting language.
789 The core language engine is compatible with Tcl 8.5+, while implementing
790 a significant subset of the Tcl 8.6 command set, plus additional features
791 available only in Jim Tcl.</p></div>
794 <li>
795 <p>
796 Object-based I/O (aio), but with a Tcl-compatibility layer
797 </p>
798 </li>
799 <li>
800 <p>
801 I/O: Support for sockets and pipes including udp, unix domain sockets and IPv6
802 </p>
803 </li>
804 <li>
805 <p>
806 Integers are 64bit
807 </p>
808 </li>
809 <li>
810 <p>
811 Support for references (<a href="#_ref"><strong><code>ref</code></strong></a>/<a href="#_getref"><strong><code>getref</code></strong></a>/<a href="#_setref"><strong><code>setref</code></strong></a>) and garbage collection
812 </p>
813 </li>
814 <li>
815 <p>
816 Builtin dictionary type (<a href="#_dict"><strong><code>dict</code></strong></a>) with some limitations compared to Tcl 8.6
817 </p>
818 </li>
819 <li>
820 <p>
822 </p>
823 </li>
824 <li>
825 <p>
826 Operating system features: <a href="#cmd_1"><strong><code>os.fork</code></strong></a>, <a href="#cmd_1"><strong><code>os.wait</code></strong></a>, <a href="#cmd_1"><strong><code>os.uptime</code></strong></a>, <a href="#_signal"><strong><code>signal</code></strong></a>, <a href="#_alarm"><strong><code>alarm</code></strong></a>, <a href="#_sleep"><strong><code>sleep</code></strong></a>
827 </p>
828 </li>
829 <li>
830 <p>
831 Much better error reporting. <a href="#_info"><strong><code>info</code></strong></a> <code>stacktrace</code> as a replacement for <em>$errorInfo</em>, <em>$errorCode</em>
832 </p>
833 </li>
834 <li>
835 <p>
836 Support for "static" variables in procedures
837 </p>
838 </li>
839 <li>
840 <p>
841 Threads and coroutines are not supported
842 </p>
843 </li>
844 <li>
845 <p>
846 Command and variable traces are not supported
847 </p>
848 </li>
849 <li>
850 <p>
851 Built-in command line editing
852 </p>
853 </li>
854 <li>
855 <p>
857 </p>
858 </li>
859 <li>
860 <p>
861 Modular build allows many features to be omitted or built as dynamic, loadable modules
862 </p>
863 </li>
864 <li>
865 <p>
866 Highly suitable for use in an embedded environment
867 </p>
868 </li>
869 <li>
870 <p>
871 Support for UDP, IPv6, Unix-Domain sockets in addition to TCP sockets
872 </p>
873 </li>
874 </ol></div>
875 </div>
876 </div>
883 <li>
884 <p>
886 </p>
887 </li>
888 <li>
889 <p>
890 Add SSL and TLS support in aio
891 </p>
892 </li>
893 </ol></div>
894 </div>
898 <li>
899 <p>
901 </p>
902 </li>
903 <li>
904 <p>
905 <a href="#_glob"><strong><code>glob</code></strong></a> now supports the <em>--tails</em> option
906 </p>
907 </li>
908 <li>
909 <p>
911 </p>
912 </li>
913 <li>
914 <p>
915 Allow <a href="#_info"><strong><code>info</code></strong></a> <code>source</code> to add source info
916 </p>
917 </li>
918 </ol></div>
919 </div>
923 <li>
924 <p>
925 <a href="#_binary"><strong><code>binary</code></strong></a>, <a href="#cmd_3"><strong><code>pack</code></strong></a> and <a href="#cmd_3"><strong><code>unpack</code></strong></a> now support floating point
926 </p>
927 </li>
928 <li>
929 <p>
930 <a href="#_file"><strong><code>file</code></strong></a> <code>copy</code> <em>-force</em> handles source and target as the same file
931 </p>
932 </li>
933 <li>
934 <p>
935 <a href="#_format"><strong><code>format</code></strong></a> now supports <code>%b</code> for binary conversion
936 </p>
937 </li>
938 <li>
939 <p>
940 <a href="#_lsort"><strong><code>lsort</code></strong></a> now supports <em>-unique</em> and <em>-real</em>
941 </p>
942 </li>
943 <li>
944 <p>
945 Add support for half-close with <a href="#_aio"><strong><code>aio</code></strong></a> <code>close</code> ?r|w?
946 </p>
947 </li>
948 <li>
949 <p>
950 Add <a href="#_socket"><strong><code>socket</code></strong></a> <code>pair</code> for a bidirectional pipe
951 </p>
952 </li>
953 <li>
954 <p>
956 </p>
957 </li>
958 <li>
959 <p>
960 <a href="#_dict"><strong><code>dict</code></strong></a> now supports <em>for</em>, <em>values</em>, <em>incr</em>, <em>append</em>, <em>lappend</em>, <em>update</em>, <em>info</em> and <em>replace</em>
961 </p>
962 </li>
963 <li>
964 <p>
965 <a href="#_file"><strong><code>file</code></strong></a> <code>stat</code> no longer requires the variable name
966 </p>
967 </li>
968 </ol></div>
969 </div>
973 <li>
974 <p>
975 Numbers with leading zeros are treated as decimal, not octal
976 </p>
977 </li>
978 <li>
979 <p>
981 </p>
982 </li>
983 <li>
984 <p>
985 Add LFS (64 bit) support for <a href="#_aio"><strong><code>aio</code></strong></a> <code>seek</code>, <a href="#_aio"><strong><code>aio</code></strong></a> <code>tell</code>, <a href="#_aio"><strong><code>aio</code></strong></a> <code>copyto</code>, <a href="#_file"><strong><code>file</code></strong></a> <code>copy</code>
986 </p>
987 </li>
988 <li>
989 <p>
990 <a href="#_string"><strong><code>string</code></strong></a> <code>compare</code> and <a href="#_string"><strong><code>string</code></strong></a> <code>equal</code> now support <em>-length</em>
991 </p>
992 </li>
993 <li>
994 <p>
996 </p>
997 </li>
998 </ol></div>
999 </div>
1003 <li>
1004 <p>
1005 Built-in regexp now support non-capturing parentheses: (?:…)
1006 </p>
1007 </li>
1008 <li>
1009 <p>
1011 </p>
1012 </li>
1013 <li>
1014 <p>
1016 </p>
1017 </li>
1018 <li>
1019 <p>
1021 </p>
1022 </li>
1023 <li>
1024 <p>
1026 </p>
1027 </li>
1028 <li>
1029 <p>
1030 <a href="#_local"><strong><code>local</code></strong></a> now works with any command, not just procs
1031 </p>
1032 </li>
1033 <li>
1034 <p>
1035 Add <a href="#_info"><strong><code>info</code></strong></a> <code>alias</code> to access the target of an alias
1036 </p>
1037 </li>
1038 <li>
1039 <p>
1040 UTF-8 encoding past the basic multilingual plane (BMP) is supported
1041 </p>
1042 </li>
1043 <li>
1044 <p>
1046 </p>
1047 </li>
1048 <li>
1049 <p>
1051 </p>
1052 </li>
1053 <li>
1054 <p>
1055 Most extensions are now enabled by default
1056 </p>
1057 </li>
1058 <li>
1059 <p>
1060 Add support for namespaces and the <a href="#_namespace"><strong><code>namespace</code></strong></a> command
1061 </p>
1062 </li>
1063 <li>
1064 <p>
1066 </p>
1067 </li>
1068 </ol></div>
1069 </div>
1073 <li>
1074 <p>
1076 </p>
1077 </li>
1078 <li>
1079 <p>
1080 Add Tcl-compatible expr functions, <code>rand()</code>, <code>srand()</code> and <code>pow()</code>
1081 </p>
1082 </li>
1083 <li>
1084 <p>
1085 Add support for the <em>-force</em> option to <a href="#_file"><strong><code>file</code></strong></a> <code>delete</code>
1086 </p>
1087 </li>
1088 <li>
1089 <p>
1090 Better diagnostics when <a href="#_source"><strong><code>source</code></strong></a> fails to load a script with a missing quote or bracket
1091 </p>
1092 </li>
1093 <li>
1094 <p>
1096 </p>
1097 </li>
1098 <li>
1099 <p>
1100 Add support settings the modification time with <a href="#_file"><strong><code>file</code></strong></a> <code>mtime</code>
1101 </p>
1102 </li>
1103 <li>
1104 <p>
1105 <a href="#_exec"><strong><code>exec</code></strong></a> is now fully supported on win32 (mingw32)
1106 </p>
1107 </li>
1108 <li>
1109 <p>
1110 <a href="#_file"><strong><code>file</code></strong></a> <code>join</code>, <a href="#_pwd"><strong><code>pwd</code></strong></a>, <a href="#_glob"><strong><code>glob</code></strong></a> etc. now work for mingw32
1111 </p>
1112 </li>
1113 <li>
1114 <p>
1115 Line editing is now supported for the win32 console (mingw32)
1116 </p>
1117 </li>
1118 <li>
1119 <p>
1121 </p>
1122 </li>
1123 </ol></div>
1124 </div>
1128 <li>
1129 <p>
1131 </p>
1132 </li>
1133 <li>
1134 <p>
1136 </p>
1137 </li>
1138 <li>
1139 <p>
1141 </p>
1142 </li>
1143 <li>
1144 <p>
1146 </p>
1147 </li>
1148 <li>
1149 <p>
1151 </p>
1152 </li>
1153 <li>
1154 <p>
1155 <a href="#_local"><strong><code>local</code></strong></a> procs now push existing commands and <a href="#_upcall"><strong><code>upcall</code></strong></a> can call them
1156 </p>
1157 </li>
1158 <li>
1159 <p>
1161 </p>
1162 </li>
1163 <li>
1164 <p>
1166 </p>
1167 </li>
1168 <li>
1169 <p>
1170 <a href="#_info"><strong><code>info</code></strong></a> <code>complete</code> can now return the missing character
1171 </p>
1172 </li>
1173 <li>
1174 <p>
1175 <a href="#_binary"><strong><code>binary</code></strong></a> <code>format</code> and <a href="#_binary"><strong><code>binary</code></strong></a> <code>scan</code> are now (optionally) supported
1176 </p>
1177 </li>
1178 <li>
1179 <p>
1181 </p>
1182 </li>
1183 <li>
1184 <p>
1185 Built-in regexp now support non-greedy repetition (*?, +?, ??)
1186 </p>
1187 </li>
1188 </ol></div>
1189 </div>
1190 </div>
1191 </div>
1196 <em><a href="http://www.oxforddictionaries.com/definition/american_english/tickle">tickle</a></em>.
1197 It is actually two things: a language and a library.</p></div>
1199 issuing commands to interactive programs such as text editors,
1200 debuggers, illustrators, and shells. It has a simple syntax and is also
1201 programmable, so Tcl users can write command procedures to provide more
1202 powerful commands than those in the built-in set.</p></div>
1204 programs. The Tcl library consists of a parser for the Tcl language,
1205 routines to implement the Tcl built-in commands, and procedures that
1206 allow each application to extend Tcl with additional commands specific
1207 to that application. The application program generates Tcl commands and
1208 passes them to the Tcl parser for execution. Commands may be generated
1209 by reading characters from an input source, or by associating command
1210 strings with elements of the application’s user interface, such as menu
1211 entries, buttons, or keystrokes.</p></div>
1213 fields and executes built-in commands directly. For commands implemented
1214 by the application, Tcl calls back to the application to execute the
1215 commands. In many cases commands will invoke recursive invocations of the
1216 Tcl interpreter by passing in additional strings to execute (procedures,
1217 looping commands, and conditional commands all work in this way).</p></div>
1218 <div class="paragraph"><p>An application program gains three advantages by using Tcl for its command
1219 language. First, Tcl provides a standard syntax: once users know Tcl,
1220 they will be able to issue commands easily to any Tcl-based application.
1221 Second, Tcl provides programmability. All a Tcl application needs
1222 to do is to implement a few application-specific low-level commands.
1223 Tcl provides many utility commands plus a general programming interface
1224 for building up complex command procedures. By using Tcl, applications
1225 need not re-implement these features.</p></div>
1226 <div class="paragraph"><p>Third, Tcl can be used as a common language for communicating between
1227 applications. Inter-application communication is not built into the
1228 Tcl core described here, but various add-on libraries, such as the Tk
1229 toolkit, allow applications to issue commands to each other. This makes
1230 it possible for applications to work together in much more powerful ways
1231 than was previously possible.</p></div>
1232 <div class="paragraph"><p>Fourth, Jim Tcl includes a command processor, <code>jimsh</code>, which can be
1233 used to run standalone Tcl scripts, or to run Tcl commands interactively.</p></div>
1235 the language syntax and the built-in commands that will be available
1236 in any application based on Tcl. The individual library procedures are
1237 described in more detail in separate manual pages, one per procedure.</p></div>
1238 </div>
1239 </div>
1243 <div class="paragraph"><p>A simple, but powerful command processor, <code>jimsh</code>, is part of Jim Tcl.
1244 It may be invoked in interactive mode as:</p></div>
1248 </div></div>
1253 </div></div>
1254 <div class="paragraph"><p>It may also be invoked to execute an immediate script with:</p></div>
1258 </div></div>
1262 those commands and prints the results.</p></div>
1265 <pre><code>$ jimsh
1267 . info version
1268 0.73
1269 . lsort [info commands p*]
1270 package parray pid popen proc puts pwd
1271 . foreach i {a b c} {
1272 {> puts $i
1273 {> }
1274 a
1275 b
1276 c
1277 . bad
1278 invalid command name "bad"
1279 [error] . exit
1280 $</code></pre>
1281 </div></div>
1282 <div class="paragraph"><p>If <code>jimsh</code> is configured with line editing (it is by default) and a VT-100-compatible
1283 terminal is detected, Emacs-style line editing commands are available, including:
1284 arrow keys, <code>^W</code> to erase a word, <code>^U</code> to erase the line, <code>^R</code> for reverse incremental search
1285 in history. Additionally, the <code>h</code> command may be used to display the command history.</p></div>
1286 <div class="paragraph"><p>Command line history is automatically saved and loaded from <code>~/.jim_history</code></p></div>
1287 <div class="paragraph"><p>In interactive mode, <code>jimsh</code> automatically runs the script <code>~/.jimrc</code> at startup
1288 if it exists.</p></div>
1289 </div>
1290 </div>
1291 </div>
1295 <div class="paragraph"><p>The central data structure in Tcl is an interpreter (C type <em>Jim_Interp</em>).
1296 An interpreter consists of a set of command bindings, a set of variable
1297 values, and a few other miscellaneous pieces of state. Each Tcl command
1298 is interpreted in the context of a particular interpreter.</p></div>
1300 simultaneously, each associated with a different widget or portion of
1301 the application. Interpreters are relatively lightweight structures.
1302 They can be created and deleted quickly, so application programmers should
1303 feel free to use multiple interpreters if that simplifies the application.</p></div>
1304 </div>
1305 </div>
1309 <div class="paragraph"><p>Tcl supports only one type of data: strings. All commands, all arguments
1310 to commands, all command results, and all variable values are strings.</p></div>
1312 the arguments and results are passed as strings. Many commands expect
1313 their string arguments to have certain formats, but this interpretation
1314 is up to the individual commands. For example, arguments often contain
1315 Tcl command strings, which may get executed as part of the commands.
1316 The easiest way to understand the Tcl interpreter is to remember that
1317 everything is just an operation on a string. In many cases Tcl constructs
1318 will look similar to more structured constructs from other languages.
1319 However, the Tcl constructs are not structured at all; they are just
1320 strings of characters, and this gives them a different behaviour than
1321 the structures they may look like.</p></div>
1322 <div class="paragraph"><p>Although the exact interpretation of a Tcl string depends on who is doing
1323 the interpretation, there are three common forms that strings take:
1324 commands, expressions, and lists. The major sections below discuss
1325 these three forms in more detail.</p></div>
1326 </div>
1327 </div>
1332 and Lisp. However, the interpretation of commands is different
1333 in Tcl than in either of those other two systems.
1334 A Tcl command string consists of one or more commands separated
1335 by newline characters or semi-colons.
1336 Each command consists of a collection of fields separated by
1337 white space (spaces or tabs).
1338 The first field must be the name of a command, and the
1339 additional fields, if any, are arguments that will be passed to
1340 that command. For example, the command:</p></div>
1344 </div></div>
1345 <div class="paragraph"><p>has three fields: the first, <a href="#_set"><strong><code>set</code></strong></a>, is the name of a Tcl command, and
1347 the <a href="#_set"><strong><code>set</code></strong></a> command. The command name may refer either to a built-in
1348 Tcl command, an application-specific command bound in with the library
1351 <div class="paragraph"><p>Arguments are passed literally as text strings. Individual commands may
1352 interpret those strings in any fashion they wish. The <a href="#_set"><strong><code>set</code></strong></a> command,
1353 for example, will treat its first argument as the name of a variable
1354 and its second argument as a string value to assign to that variable.
1355 For other commands arguments may be interpreted as integers, lists,
1356 file names, or Tcl commands.</p></div>
1357 <div class="paragraph"><p>Command names should normally be typed completely (e.g. no abbreviations).
1358 However, if the Tcl interpreter cannot locate a command it invokes a
1359 special command named <a href="#_unknown"><strong><code>unknown</code></strong></a> which attempts to find or create the
1360 command.</p></div>
1361 <div class="paragraph"><p>For example, at many sites <a href="#_unknown"><strong><code>unknown</code></strong></a> will search through library
1362 directories for the desired command and create it as a Tcl procedure if
1363 it is found. The <a href="#_unknown"><strong><code>unknown</code></strong></a> command often provides automatic completion
1364 of abbreviated commands, but usually only for commands that were typed
1365 interactively.</p></div>
1366 <div class="paragraph"><p>It’s probably a bad idea to use abbreviations in command scripts and
1367 other forms that will be re-used over time: changes to the command set
1368 may cause abbreviations to become ambiguous, resulting in scripts that
1369 no longer work.</p></div>
1370 </div>
1371 </div>
1375 <div class="paragraph"><p>If the first non-blank character in a command is <code>#</code>, then everything
1377 a comment and ignored. When comments are embedded inside nested
1378 commands (e.g. fields enclosed in braces) they must have properly-matched
1379 braces (this is necessary because when Tcl parses the top-level command
1380 it doesn’t yet know that the nested field will be used as a command so
1381 it cannot process the nested comment character as a comment).</p></div>
1382 </div>
1383 </div>
1388 double-quotes may be used to create arguments with embedded space.</p></div>
1389 <div class="paragraph"><p>If an argument field begins with a double-quote, then the argument isn’t
1390 terminated by white space (including newlines) or a semi-colon (see below
1391 for information on semi-colons); instead it ends at the next double-quote
1392 character. The double-quotes are not included in the resulting argument.
1393 For example, the command</p></div>
1397 </div></div>
1398 <div class="paragraph"><p>will pass two arguments to <a href="#_set"><strong><code>set</code></strong></a>: <em>a</em> and <em>This is a single argument</em>.</p></div>
1400 and backslash substitutions still occur, as described below. If the
1401 first character of a command field is not a quote, then quotes receive
1402 no special interpretation in the parsing of that field.</p></div>
1403 </div>
1404 </div>
1408 <div class="paragraph"><p>Curly braces may also be used for grouping arguments. They are similar
1409 to quotes except for two differences. First, they nest; this makes them
1410 easier to use for complicated arguments like nested Tcl command strings.
1411 Second, the substitutions described below for commands, variables, and
1413 can be used to prevent substitutions where they are undesirable.</p></div>
1414 <div class="paragraph"><p>If an argument field begins with a left brace, then the argument ends
1415 at the matching right brace. Tcl will strip off the outermost layer
1416 of braces and pass the information between the braces to the command
1417 without any further modification. For example, in the command</p></div>
1421 </div></div>
1422 <div class="paragraph"><p>the <a href="#_set"><strong><code>set</code></strong></a> command will receive two arguments: <em>a</em>
1424 <div class="paragraph"><p>When braces or quotes are in effect, the matching brace or quote need
1425 not be on the same line as the starting quote or brace; in this case
1426 the newline will be included in the argument field along with any other
1427 characters up to the matching brace or quote. For example, the <a href="#_eval"><strong><code>eval</code></strong></a>
1428 command takes one argument, which is a command string; <a href="#_eval"><strong><code>eval</code></strong></a> invokes
1429 the Tcl interpreter to execute the command string. The command</p></div>
1432 <pre><code>eval {
1433 set a 22
1434 set b 33
1435 }</code></pre>
1436 </div></div>
1437 <div class="paragraph"><p>will assign the value <em>22</em> to <em>a</em> and <em>33</em> to <em>b</em>.</p></div>
1439 brace, then neither left nor right
1440 braces in the field will be treated specially (except as part of
1441 variable substitution; see below).</p></div>
1442 </div>
1443 </div>
1448 substitution occurs (except for fields enclosed in braces). All of the
1449 text up to the matching close bracket is treated as a Tcl command and
1450 executed immediately. Then the result of that command is substituted
1451 for the bracketed text. For example, consider the command</p></div>
1455 </div></div>
1456 <div class="paragraph"><p>When the <a href="#_set"><strong><code>set</code></strong></a> command has only a single argument, it is the name of a
1457 variable and <a href="#_set"><strong><code>set</code></strong></a> returns the contents of that variable. In this case,
1459 to the command</p></div>
1463 </div></div>
1464 <div class="paragraph"><p>Brackets can be used in more complex ways. For example, if the variable
1466 then the command</p></div>
1470 </div></div>
1475 </div></div>
1476 <div class="paragraph"><p>A bracketed command may contain multiple commands separated by newlines
1477 or semi-colons in the usual fashion. In this case the value of the last
1478 command is used for substitution. For example, the command</p></div>
1483 </div></div>
1488 </div></div>
1489 <div class="paragraph"><p>If a field is enclosed in braces then the brackets and the characters
1490 between them are not interpreted specially; they are passed through to
1491 the argument verbatim.</p></div>
1492 </div>
1493 </div>
1497 <div class="paragraph"><p>The dollar sign (<code>$</code>) may be used as a special shorthand form for
1499 enclosed in braces then variable substitution will occur. The characters
1501 or underscore, are taken as a variable name and the string value of that
1502 variable is substituted for the name.</p></div>
1503 <div class="paragraph"><p>For example, if variable <em>foo</em> has the value <em>test</em>, then the command</p></div>
1507 </div></div>
1512 </div></div>
1514 character after the name of the variable is an open parenthesis, then
1515 the variable is assumed to be an array name, and all of the characters
1516 between the open parenthesis and the next close parenthesis are taken as
1517 an index into the array. Command substitutions and variable substitutions
1518 are performed on the information between the parentheses before it is
1519 used as an index.</p></div>
1520 <div class="paragraph"><p>For example, if the variable <em>x</em> is an array with one element named
1521 <em>first</em> and value <em>87</em> and another element named <em>14</em> and value <em>more</em>,
1522 then the command</p></div>
1526 </div></div>
1531 </div></div>
1532 <div class="paragraph"><p>If the variable <em>index</em> has the value <em>14</em>, then the command</p></div>
1536 </div></div>
1541 </div></div>
1542 <div class="paragraph"><p>For more information on arrays, see VARIABLES AND ARRAYS below.</p></div>
1544 followed by an open curly brace. In this case the variable name consists
1545 of all the characters up to the next curly brace.</p></div>
1546 <div class="paragraph"><p>Array references are not possible in this form: the name between braces
1547 is assumed to refer to a scalar variable. For example, if variable
1552 </div></div>
1557 </div></div>
1558 <div class="paragraph"><p>Variable substitution does not occur in arguments that are enclosed in
1559 braces: the dollar sign and variable name are passed through to the
1560 argument verbatim.</p></div>
1561 <div class="paragraph"><p>The dollar sign abbreviation is simply a shorthand form. <code>$a</code> is
1563 to reduce typing.</p></div>
1564 </div>
1565 </div>
1569 <div class="paragraph"><p>Normally, each command occupies one line (the command is terminated by a
1571 separator character; multiple commands may be placed on one line by
1572 separating them with a semi-colon. Semi-colons are not treated as
1573 command separators if they appear within curly braces or double-quotes.</p></div>
1574 </div>
1575 </div>
1579 <div class="paragraph"><p>Backslashes may be used to insert non-printing characters into command
1580 fields and also to insert special characters like braces and brackets
1581 into fields without them being interpreted specially as described above.</p></div>
1583 listed below. In each case, the backslash
1584 sequence is replaced by the given character:</p></div>
1588 </dt>
1589 <dd>
1590 <p>
1591 Backspace (0x8)
1592 </p>
1593 </dd>
1596 </dt>
1597 <dd>
1598 <p>
1599 Form feed (0xc)
1600 </p>
1601 </dd>
1604 </dt>
1605 <dd>
1606 <p>
1607 Newline (0xa)
1608 </p>
1609 </dd>
1612 </dt>
1613 <dd>
1614 <p>
1615 Carriage-return (0xd).
1616 </p>
1617 </dd>
1620 </dt>
1621 <dd>
1622 <p>
1623 Tab (0x9).
1624 </p>
1625 </dd>
1628 </dt>
1629 <dd>
1630 <p>
1631 Vertical tab (0xb).
1632 </p>
1633 </dd>
1636 </dt>
1637 <dd>
1638 <p>
1639 Left brace ({).
1640 </p>
1641 </dd>
1644 </dt>
1645 <dd>
1646 <p>
1647 Right brace (}).
1648 </p>
1649 </dd>
1652 </dt>
1653 <dd>
1654 <p>
1655 Open bracket ([).
1656 </p>
1657 </dd>
1660 </dt>
1661 <dd>
1662 <p>
1663 Close bracket (]).
1664 </p>
1665 </dd>
1668 </dt>
1669 <dd>
1670 <p>
1671 Dollar sign ($).
1672 </p>
1673 </dd>
1676 </dt>
1677 <dd>
1678 <p>
1679 Space ( ): doesn’t terminate argument.
1680 </p>
1681 </dd>
1684 </dt>
1685 <dd>
1686 <p>
1687 Semi-colon: doesn’t terminate command.
1688 </p>
1689 </dd>
1692 </dt>
1693 <dd>
1694 <p>
1695 Double-quote.
1696 </p>
1697 </dd>
1699 <code>\<newline></code>
1700 </dt>
1701 <dd>
1702 <p>
1703 Nothing: this joins two lines together
1704 into a single line. This backslash feature is unique in that
1705 it will be applied even when the sequence occurs within braces.
1706 </p>
1707 </dd>
1709 <code>\\</code>
1710 </dt>
1711 <dd>
1712 <p>
1713 Backslash (<em>\</em>).
1714 </p>
1715 </dd>
1717 <code>\ddd</code>
1718 </dt>
1719 <dd>
1720 <p>
1721 The digits <code><em>ddd</em></code> (one, two, or three of them) give the octal value of
1722 the character. Note that Jim supports null characters in strings.
1723 </p>
1724 </dd>
1726 <code>\unnnn</code>
1727 </dt>
1729 <code>\u{nnn}</code>
1730 </dt>
1732 <code>\Unnnnnnnn</code>
1733 </dt>
1734 <dd>
1735 <p>
1736 The UTF-8 encoding of the unicode codepoint represented by the hex digits, <code><em>nnnn</em></code>, is inserted.
1737 The <em>u</em> form allows for one to four hex digits.
1738 The <em>U</em> form allows for one to eight hex digits.
1739 The <em>u{nnn}</em> form allows for one to eight hex digits, but makes it easier to insert
1740 characters UTF-8 characters which are followed by a hex digit.
1741 </p>
1742 </dd>
1743 </dl></div>
1747 <pre><code>set a \{x\[\ yz\141</code></pre>
1748 </div></div>
1749 <div class="paragraph"><p>the second argument to <a href="#_set"><strong><code>set</code></strong></a> will be <code>{x[ yza</code>.</p></div>
1750 <div class="paragraph"><p>If a backslash is followed by something other than one of the options
1751 described above, then the backslash is transmitted to the argument
1752 field without any special processing, and the Tcl scanner continues
1753 normal processing with the next character. For example, in the
1754 command</p></div>
1757 <pre><code>set \*a \\\{foo</code></pre>
1758 </div></div>
1759 <div class="paragraph"><p>The first argument to <a href="#_set"><strong><code>set</code></strong></a> will be <code>\*a</code> and the second
1760 argument will be <code>\{foo</code>.</p></div>
1761 <div class="paragraph"><p>If an argument is enclosed in braces, then backslash sequences inside
1762 the argument are parsed but no substitution occurs (except for
1763 backslash-newline): the backslash
1764 sequence is passed through to the argument as is, without making
1765 any special interpretation of the characters in the backslash sequence.
1766 In particular, backslashed braces are not counted in locating the
1767 matching right brace that terminates the argument.
1768 For example, in the
1769 command</p></div>
1772 <pre><code>set a {\{abc}</code></pre>
1773 </div></div>
1774 <div class="paragraph"><p>the second argument to <a href="#_set"><strong><code>set</code></strong></a> will be <code>\{abc</code>.</p></div>
1776 any argument structure; it only covers the
1777 most common cases. To produce particularly complicated arguments
1778 it is probably easiest to use the <a href="#_format"><strong><code>format</code></strong></a> command along with
1779 command substitution.</p></div>
1780 </div>
1781 </div>
1785 <div class="paragraph"><p>Many string and list commands take one or more <em>index</em> parameters which
1786 specify a position in the string relative to the start or end of the string/list.</p></div>
1790 <code>integer</code>
1791 </dt>
1792 <dd>
1793 <p>
1794 A simple integer, where <em>0</em> refers to the first element of the string
1795 or list.
1796 </p>
1797 </dd>
1799 <code>integer+integer</code> or
1800 </dt>
1802 <code>integer-integer</code>
1803 </dt>
1804 <dd>
1805 <p>
1806 The sum or difference of the two integers. e.g. <code>2+3</code> refers to the 5th element.
1807 This is useful when used with (e.g.) <code>$i+1</code> rather than the more verbose
1808 <code>[expr {$i+1}]</code>
1809 </p>
1810 </dd>
1812 <code>end</code>
1813 </dt>
1814 <dd>
1815 <p>
1816 The last element of the string or list.
1817 </p>
1818 </dd>
1820 <code>end-integer</code>
1821 </dt>
1822 <dd>
1823 <p>
1824 The <em>nth-from-last</em> element of the string or list.
1825 </p>
1826 </dd>
1827 </dl></div>
1828 </div>
1829 </div>
1834 <li>
1835 <p>
1836 A command is just a string.
1837 </p>
1838 </li>
1839 <li>
1840 <p>
1841 Within a string commands are separated by newlines or semi-colons
1842 (unless the newline or semi-colon is within braces or brackets
1843 or is backslashed).
1844 </p>
1845 </li>
1846 <li>
1847 <p>
1848 A command consists of fields. The first field is the name of the command.
1849 The other fields are strings that are passed to that command as arguments.
1850 </p>
1851 </li>
1852 <li>
1853 <p>
1854 Fields are normally separated by white space.
1855 </p>
1856 </li>
1857 <li>
1858 <p>
1859 Double-quotes allow white space and semi-colons to appear within
1860 a single argument.
1861 Command substitution, variable substitution, and backslash substitution
1862 still occur inside quotes.
1863 </p>
1864 </li>
1865 <li>
1866 <p>
1867 Braces defer interpretation of special characters.
1868 If a field begins with a left brace, then it consists of everything
1869 between the left brace and the matching right brace. The
1870 braces themselves are not included in the argument.
1871 No further processing is done on the information between the braces
1872 except that backslash-newline sequences are eliminated.
1873 </p>
1874 </li>
1875 <li>
1876 <p>
1877 If a field doesn’t begin with a brace then backslash,
1878 variable, and command substitution are done on the field. Only a
1879 single level of processing is done: the results of one substitution
1880 are not scanned again for further substitutions or any other
1881 special treatment. Substitution can
1882 occur on any field of a command, including the command name
1883 as well as the arguments.
1884 </p>
1885 </li>
1886 <li>
1887 <p>
1888 If the first non-blank character of a command is a <code>#</code>, everything
1889 from the <code>#</code> up through the next newline is treated as a comment
1890 and ignored.
1891 </p>
1892 </li>
1893 </ol></div>
1894 </div>
1895 </div>
1900 as expressions. Several commands, such as <a href="#_expr"><strong><code>expr</code></strong></a>, <a href="#_for"><strong><code>for</code></strong></a>,
1901 and <a href="#_if"><strong><code>if</code></strong></a>, treat one or more of their arguments as expressions
1902 and call the Tcl expression processors (<em>Jim_ExprLong</em>,
1903 <em>Jim_ExprBoolean</em>, etc.) to evaluate them.</p></div>
1905 the operators permitted in C expressions, and they have the
1906 same meaning and precedence as the corresponding C operators.
1907 Expressions almost always yield numeric results
1908 (integer or floating-point values).
1909 For example, the expression</p></div>
1912 <pre><code>8.2 + 6</code></pre>
1913 </div></div>
1916 operands are specified, and in that Tcl expressions support
1917 non-numeric operands and string comparisons.</p></div>
1919 and parentheses.</p></div>
1921 parentheses; it is ignored by the expression processor.
1922 Where possible, operands are interpreted as integer values.</p></div>
1924 hexadecimal (if the first two characters of the operand are <em>0x</em>).
1925 Note that Jim Tcl does <strong>not</strong> treat numbers with leading zeros as octal.</p></div>
1927 above, then it is treated as a floating-point number if that is
1928 possible. Floating-point numbers may be specified in any of the
1929 ways accepted by an ANSI-compliant C compiler (except that the
1930 <em>f</em>, <em>F</em>, <em>l</em>, and <em>L</em> suffixes will not be permitted in
1931 most installations). For example, all of the
1932 following are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16.</p></div>
1934 as a string (and only a limited set of operators may be applied to
1935 it).</p></div>
1937 <li>
1938 <p>
1939 Operands may be specified in any of the following ways:
1940 </p>
1941 </li>
1942 <li>
1943 <p>
1944 As a numeric value, either integer or floating-point.
1945 </p>
1946 </li>
1947 <li>
1948 <p>
1949 As a Tcl variable, using standard <em>$</em> notation.
1950 The variable’s value will be used as the operand.
1951 </p>
1952 </li>
1953 <li>
1954 <p>
1955 As a string enclosed in double-quotes.
1956 The expression parser will perform backslash, variable, and
1957 command substitutions on the information between the quotes,
1958 and use the resulting value as the operand
1959 </p>
1960 </li>
1961 <li>
1962 <p>
1963 As a string enclosed in braces.
1964 The characters between the open brace and matching close brace
1965 will be used as the operand without any substitutions.
1966 </p>
1967 </li>
1968 <li>
1969 <p>
1970 As a Tcl command enclosed in brackets.
1971 The command will be executed and its result will be used as
1972 the operand.
1973 </p>
1974 </li>
1975 </ol></div>
1977 are performed by the expression processor.
1978 However, an additional layer of substitution may already have
1979 been performed by the command parser before the expression
1980 processor was called.</p></div>
1982 in braces to prevent the command parser from performing substitutions
1983 on the contents.</p></div>
1984 <div class="paragraph"><p>For some examples of simple expressions, suppose the variable <em>a</em> has
1985 the value 3 and the variable <em>b</em> has the value 6. Then the expression
1986 on the left side of each of the lines below will evaluate to the value
1987 on the right side of the line:</p></div>
1990 <pre><code>$a + 3.1 6.1
1994 </div></div>
1996 of precedence:</p></div>
1999 <code>int() double() round() abs(), rand(), srand()</code>
2000 </dt>
2001 <dd>
2002 <p>
2003 Unary functions (except rand() which takes no arguments)
2004 </p>
2006 <li>
2007 <p>
2008 <code><em>int()</em></code> converts the numeric argument to an integer by truncating down.
2009 </p>
2010 </li>
2011 <li>
2012 <p>
2013 <code><em>double()</em></code> converts the numeric argument to floating point.
2014 </p>
2015 </li>
2016 <li>
2017 <p>
2018 <code><em>round()</em></code> converts the numeric argument to the closest integer value.
2019 </p>
2020 </li>
2021 <li>
2022 <p>
2023 <code><em>abs()</em></code> takes the absolute value of the numeric argument.
2024 </p>
2025 </li>
2026 <li>
2027 <p>
2028 <code><em>rand()</em></code> returns a pseudo-random floating-point value in the range (0,1).
2029 </p>
2030 </li>
2031 <li>
2032 <p>
2033 <code><em>srand()</em></code> takes an integer argument to (re)seed the random number generator. Returns the first random number from that seed.
2034 </p>
2035 </li>
2036 </ul></div>
2037 </dd>
2039 <code>sin() cos() tan() asin() acos() atan() sinh() cosh() tanh() ceil() floor() exp() log() log10() sqrt()</code>
2040 </dt>
2041 <dd>
2042 <p>
2043 Unary math functions.
2044 If Jim is compiled with math support, these functions are available.
2045 </p>
2046 </dd>
2048 <code>- + ~ !</code>
2049 </dt>
2050 <dd>
2051 <p>
2052 Unary minus, unary plus, bit-wise NOT, logical NOT. None of these operands
2053 may be applied to string operands, and bit-wise NOT may be
2054 applied only to integers.
2055 </p>
2056 </dd>
2058 <code>** pow(x,y)</code>
2059 </dt>
2060 <dd>
2061 <p>
2062 Power. e.g. <em>x<sup>y</sup></em>. If Jim is compiled with math support, supports doubles and
2063 integers. Otherwise supports integers only. (Note that the math-function form
2064 has the same highest precedence)
2065 </p>
2066 </dd>
2068 <code>* / %</code>
2069 </dt>
2070 <dd>
2071 <p>
2072 Multiply, divide, remainder. None of these operands may be
2073 applied to string operands, and remainder may be applied only
2074 to integers.
2075 </p>
2076 </dd>
2078 <code>+ -</code>
2079 </dt>
2080 <dd>
2081 <p>
2082 Add and subtract. Valid for any numeric operands.
2083 </p>
2084 </dd>
2086 <code><< >> <<< >>></code>
2087 </dt>
2088 <dd>
2089 <p>
2090 Left and right shift, left and right rotate. Valid for integer operands only.
2091 </p>
2092 </dd>
2094 <code>< > <= >=</code>
2095 </dt>
2096 <dd>
2097 <p>
2098 Boolean less, greater, less than or equal, and greater than or equal.
2099 Each operator produces 1 if the condition is true, 0 otherwise.
2100 These operators may be applied to strings as well as numeric operands,
2101 in which case string comparison is used.
2102 </p>
2103 </dd>
2105 <code>== !=</code>
2106 </dt>
2107 <dd>
2108 <p>
2109 Boolean equal and not equal. Each operator produces a zero/one result.
2110 Valid for all operand types. <strong>Note</strong> that values will be converted to integers
2111 if possible, then floating point types, and finally strings will be compared.
2112 It is recommended that <em>eq</em> and <em>ne</em> should be used for string comparison.
2113 </p>
2114 </dd>
2116 <code>eq ne</code>
2117 </dt>
2118 <dd>
2119 <p>
2120 String equal and not equal. Uses the string value directly without
2121 attempting to convert to a number first.
2122 </p>
2123 </dd>
2125 <code>in ni</code>
2126 </dt>
2127 <dd>
2128 <p>
2129 String in list and not in list. For <em>in</em>, result is 1 if the left operand (as a string)
2130 is contained in the right operand (as a list), or 0 otherwise. The result for
2131 <code>{$a ni $list}</code> is equivalent to <code>{!($a in $list)}</code>.
2132 </p>
2133 </dd>
2135 <code>&</code>
2136 </dt>
2137 <dd>
2138 <p>
2139 Bit-wise AND. Valid for integer operands only.
2140 </p>
2141 </dd>
2143 <code>|</code>
2144 </dt>
2145 <dd>
2146 <p>
2147 Bit-wise OR. Valid for integer operands only.
2148 </p>
2149 </dd>
2151 <code>^</code>
2152 </dt>
2153 <dd>
2154 <p>
2155 Bit-wise exclusive OR. Valid for integer operands only.
2156 </p>
2157 </dd>
2159 <code>&&</code>
2160 </dt>
2161 <dd>
2162 <p>
2163 Logical AND. Produces a 1 result if both operands are non-zero, 0 otherwise.
2164 Valid for numeric operands only (integers or floating-point).
2165 </p>
2166 </dd>
2168 <code>||</code>
2169 </dt>
2170 <dd>
2171 <p>
2172 Logical OR. Produces a 0 result if both operands are zero, 1 otherwise.
2173 Valid for numeric operands only (integers or floating-point).
2174 </p>
2175 </dd>
2177 <code>x ? y : z</code>
2178 </dt>
2179 <dd>
2180 <p>
2181 If-then-else, as in C. If <code><em>x</em></code>
2182 evaluates to non-zero, then the result is the value of <code><em>y</em></code>.
2183 Otherwise the result is the value of <code><em>z</em></code>.
2184 The <code><em>x</em></code> operand must have a numeric value, while <code><em>y</em></code> and <code><em>z</em></code> can
2185 be of any type.
2186 </p>
2187 </dd>
2188 </dl></div>
2190 produced by each operator.
2191 All of the binary operators group left-to-right within the same
2192 precedence level. For example, the expression</p></div>
2195 <pre><code>4*2 < 7</code></pre>
2196 </div></div>
2198 <div class="paragraph"><p>The <code>&&</code>, <code>||</code>, and <code>?:</code> operators have <em>lazy evaluation</em>, just as
2199 in C, which means that operands are not evaluated if they are not
2200 needed to determine the outcome. For example, in</p></div>
2203 <pre><code>$v ? [a] : [b]</code></pre>
2204 </div></div>
2205 <div class="paragraph"><p>only one of <code>[a]</code> or <code>[b]</code> will actually be evaluated,
2206 depending on the value of <code>$v</code>.</p></div>
2208 type <em>long long</em> if available, or <em>long</em> otherwise, and all internal
2209 computations involving floating-point are done with the C type
2210 <em>double</em>.</p></div>
2212 detected and results in a Tcl error.
2213 For conversion to integer from string, detection of overflow depends
2214 on the behaviour of some routines in the local C library, so it should
2215 be regarded as unreliable.
2216 In any case, overflow and underflow are generally not detected
2217 reliably for intermediate results.</p></div>
2218 <div class="paragraph"><p>Conversion among internal representations for integer, floating-point,
2219 and string operands is done automatically as needed.
2220 For arithmetic computations, integers are used until some
2221 floating-point number is introduced, after which floating-point is used.
2222 For example,</p></div>
2225 <pre><code>5 / 4</code></pre>
2226 </div></div>
2230 <pre><code>5 / 4.0
2232 </div></div>
2235 although the expression evaluator tries to do comparisons as integer
2236 or floating-point when it can.
2237 If one of the operands of a comparison is a string and the other
2238 has a numeric value, the numeric operand is converted back to
2239 a string using the C <em>sprintf</em> format specifier
2240 <em>%d</em> for integers and <em>%g</em> for floating-point values.
2241 For example, the expressions</p></div>
2246 </div></div>
2248 comparison, and the second is done using string comparison after
2249 the second operand is converted to the string <em>18</em>.</p></div>
2251 entering it in a command: otherwise, if the expression contains
2252 any white space then the Tcl interpreter will split it
2253 among several arguments. For example, the command</p></div>
2256 <pre><code>expr $a + $b</code></pre>
2257 </div></div>
2258 <div class="paragraph"><p>results in three arguments being passed to <a href="#_expr"><strong><code>expr</code></strong></a>: <code>$a</code>,
2259 +, and <code>$b</code>. In addition, if the expression isn’t in braces
2260 then the Tcl interpreter will perform variable and command substitution
2261 immediately (it will happen in the command parser rather than in
2262 the expression parser). In many cases the expression is being
2263 passed to a command that will evaluate the expression later (or
2264 even many times if, for example, the expression is to be used to
2265 decide when to exit a loop). Usually the desired goal is to re-do
2266 the variable or command substitutions each time the expression is
2267 evaluated, rather than once and for all at the beginning. For example,
2268 the command</p></div>
2271 <pre><code>for {set i 1} $i<=10 {incr i} {...} ** WRONG **</code></pre>
2272 </div></div>
2273 <div class="paragraph"><p>is probably intended to iterate over all values of <code>i</code> from 1 to 10.
2274 After each iteration of the body of the loop, <a href="#_for"><strong><code>for</code></strong></a> will pass
2275 its second argument to the expression evaluator to see whether or not
2276 to continue processing. Unfortunately, in this case the value of <code>i</code>
2277 in the second argument will be substituted once and for all when the
2278 <a href="#_for"><strong><code>for</code></strong></a> command is parsed. If <code>i</code> was 0 before the <a href="#_for"><strong><code>for</code></strong></a>
2279 command was invoked then the second argument of <a href="#_for"><strong><code>for</code></strong></a> will be <code>0<=10</code>
2280 which will always evaluate to 1, even though <code>i</code> eventually
2281 becomes greater than 10. In the above case the loop will never
2282 terminate. Instead, the expression should be placed in braces:</p></div>
2285 <pre><code>for {set i 1} {$i<=10} {incr i} {...} ** RIGHT **</code></pre>
2286 </div></div>
2288 to be delayed; it will be re-done each time the expression is
2289 evaluated, which is the desired result.</p></div>
2290 </div>
2291 </div>
2296 A list is just a string with a list-like structure
2297 consisting of fields separated by white space. For example, the
2298 string</p></div>
2301 <pre><code>Al Sue Anne John</code></pre>
2302 </div></div>
2304 Lists have the same basic structure as command strings, except
2305 that a newline character in a list is treated as a field separator
2306 just like space or tab. Conventions for braces and quotes
2307 and backslashes are the same for lists as for commands. For example,
2308 the string</p></div>
2311 <pre><code>a b\ c {d e {f g h}}</code></pre>
2312 </div></div>
2313 <div class="paragraph"><p>is a list with three elements: <code>a</code>, <code>b c</code>, and <code>d e {f g h}</code>.</p></div>
2315 braces and quotes and backslashes are applied as for commands. Thus in
2316 the example above when the third element is extracted from the list,
2317 the result is</p></div>
2320 <pre><code>d e {f g h}</code></pre>
2321 </div></div>
2323 the outermost layer of braces). Command substitution and
2324 variable substitution are never
2325 made on a list (at least, not by the list-processing commands; the
2326 list can always be passed to the Tcl interpreter for evaluation).</p></div>
2327 <div class="paragraph"><p>The Tcl commands <a href="#_concat"><strong><code>concat</code></strong></a>, <a href="#_foreach"><strong><code>foreach</code></strong></a>, <a href="#_lappend"><strong><code>lappend</code></strong></a>, <a href="#_lindex"><strong><code>lindex</code></strong></a>, <a href="#_linsert"><strong><code>linsert</code></strong></a>,
2328 <a href="#_list"><strong><code>list</code></strong></a>, <a href="#_llength"><strong><code>llength</code></strong></a>, <a href="#_lrange"><strong><code>lrange</code></strong></a>, <a href="#_lreplace"><strong><code>lreplace</code></strong></a>, <a href="#_lsearch"><strong><code>lsearch</code></strong></a>, and <a href="#_lsort"><strong><code>lsort</code></strong></a> allow
2329 you to build lists, extract elements from them, search them, and perform
2330 other list-related functions.</p></div>
2331 <div class="paragraph"><p>Advanced list commands include <a href="#_lrepeat"><strong><code>lrepeat</code></strong></a>, <a href="#_lreverse"><strong><code>lreverse</code></strong></a>, <a href="#_lmap"><strong><code>lmap</code></strong></a>, <a href="#_lassign"><strong><code>lassign</code></strong></a>, <a href="#_lset"><strong><code>lset</code></strong></a>.</p></div>
2332 </div>
2333 </div>
2337 <div class="paragraph"><p>A new addition to Tcl 8.5 is the ability to expand a list into separate
2338 arguments. Support for this feature is also available in Jim.</p></div>
2342 <pre><code>set cmd {ls -l}
2343 exec $cmd</code></pre>
2344 </div></div>
2345 <div class="paragraph"><p>This will attempt to exec a command named "ls -l", which will clearly not
2346 work. Typically eval and concat are required to solve this problem, however
2347 it can be solved much more easily with <code>{*}</code>.</p></div>
2350 <pre><code>exec {*}$cmd</code></pre>
2351 </div></div>
2352 <div class="paragraph"><p>This will expand the following argument into individual elements and then evaluate
2353 the resulting command.</p></div>
2354 <div class="paragraph"><p>Note that the official Tcl syntax is <code>{*}</code>, however <code>{expand}</code> is retained
2355 for backward compatibility with experimental versions of this feature.</p></div>
2356 </div>
2357 </div>
2362 expressions, <a href="#_regexp"><strong><code>regexp</code></strong></a> and <a href="#_regsub"><strong><code>regsub</code></strong></a>, as well as <a href="#_switch"><strong><code>switch</code></strong></a> <code>-regexp</code> and
2364 <div class="paragraph"><p>Regular expressions may be implemented one of two ways. Either using the system’s C library
2365 POSIX regular expression support, or using the built-in regular expression engine.
2366 The differences between these are described below.</p></div>
2367 <div class="paragraph"><p><strong>NOTE</strong> Tcl 7.x and 8.x use perl-style Advanced Regular Expressions (<code>ARE</code>).</p></div>
2370 <div class="paragraph"><p>If the system supports POSIX regular expressions, and UTF-8 support is not enabled,
2371 this support will be used by default. The type of regular expressions supported are
2372 Extended Regular Expressions (<code>ERE</code>) rather than Basic Regular Expressions (<code>BRE</code>).
2373 See REG_EXTENDED in the documentation.</p></div>
2375 make for the smallest code size, but some features such as UTF-8
2376 and <code>\w</code>, <code>\d</code>, <code>\s</code> are not supported, and null characters
2377 in strings are not supported.</p></div>
2379 </div>
2382 <div class="paragraph"><p>The Jim built-in regular expression engine may be selected with <code>./configure --with-jim-regexp</code>
2383 or it will be selected automatically if UTF-8 support is enabled.</p></div>
2384 <div class="paragraph"><p>This engine supports UTF-8 as well as some <code>ARE</code> features. The differences with both Tcl 7.x/8.x
2385 and POSIX are highlighted below.</p></div>
2387 <li>
2388 <p>
2389 UTF-8 strings and patterns are both supported
2390 </p>
2391 </li>
2392 <li>
2393 <p>
2394 Supported character classes: <code>[:alnum:]</code>, <code>[:digit:]</code> and <code>[:space:]</code>
2395 </p>
2396 </li>
2397 <li>
2398 <p>
2399 Supported shorthand character classes: <code>\w</code> = <code>[:alnum:]</code>, <code>\d</code> = <code>[:digit:],</code> <code>\s</code> = <code>[:space:]</code>
2400 </p>
2401 </li>
2402 <li>
2403 <p>
2404 Character classes apply to ASCII characters only
2405 </p>
2406 </li>
2407 <li>
2408 <p>
2409 Supported constraint escapes: <code>\m</code> = <code>\<</code> = start of word, <code>\M</code> = <code>\></code> = end of word
2410 </p>
2411 </li>
2412 <li>
2413 <p>
2414 Backslash escapes may be used within regular expressions, such as <code>\n</code> = newline, <code>\uNNNN</code> = unicode
2415 </p>
2416 </li>
2417 <li>
2418 <p>
2419 Support for the <code>?</code> non-greedy quantifier. e.g. <code>*?</code>
2420 </p>
2421 </li>
2422 <li>
2423 <p>
2424 Support for non-capturing parentheses <code>(?:…)</code>
2425 </p>
2426 </li>
2427 <li>
2428 <p>
2429 Jim Tcl considers that both patterns and strings end at a null character (<code>\x00</code>)
2430 </p>
2431 </li>
2432 </ol></div>
2433 </div>
2434 </div>
2435 </div>
2440 code indicates whether the command completed successfully or not,
2441 and the string gives additional information. The valid codes are
2442 defined in jim.h, and are:</p></div>
2445 <code>JIM_OK(0)</code>
2446 </dt>
2447 <dd>
2448 <p>
2449 This is the normal return code, and indicates that the command completed
2450 successfully. The string gives the command’s return value.
2451 </p>
2452 </dd>
2454 <code>JIM_ERR(1)</code>
2455 </dt>
2456 <dd>
2457 <p>
2458 Indicates that an error occurred; the string gives a message describing
2459 the error.
2460 </p>
2461 </dd>
2463 <code>JIM_RETURN(2)</code>
2464 </dt>
2465 <dd>
2466 <p>
2467 Indicates that the <a href="#_return"><strong><code>return</code></strong></a> command has been invoked, and that the
2468 current procedure (or top-level command or <a href="#_source"><strong><code>source</code></strong></a> command)
2469 should return immediately. The
2470 string gives the return value for the procedure or command.
2471 </p>
2472 </dd>
2474 <code>JIM_BREAK(3)</code>
2475 </dt>
2476 <dd>
2477 <p>
2478 Indicates that the <a href="#_break"><strong><code>break</code></strong></a> command has been invoked, so the
2479 innermost loop should abort immediately. The string should always
2480 be empty.
2481 </p>
2482 </dd>
2484 <code>JIM_CONTINUE(4)</code>
2485 </dt>
2486 <dd>
2487 <p>
2488 Indicates that the <a href="#_continue"><strong><code>continue</code></strong></a> command has been invoked, so the
2489 innermost loop should go on to the next iteration. The string
2490 should always be empty.
2491 </p>
2492 </dd>
2494 <code>JIM_SIGNAL(5)</code>
2495 </dt>
2496 <dd>
2497 <p>
2498 Indicates that a signal was caught while executing a commands.
2499 The string contains the name of the signal caught.
2500 See the <a href="#_signal"><strong><code>signal</code></strong></a> and <a href="#_catch"><strong><code>catch</code></strong></a> commands.
2501 </p>
2502 </dd>
2504 <code>JIM_EXIT(6)</code>
2505 </dt>
2506 <dd>
2507 <p>
2508 Indicates that the command called the <a href="#_exit"><strong><code>exit</code></strong></a> command.
2509 The string contains the exit code.
2510 </p>
2511 </dd>
2512 </dl></div>
2514 since <code>JIM_OK</code> is almost always returned. If anything else is returned
2515 by a command, then the Tcl interpreter immediately stops processing
2516 commands and returns to its caller. If there are several nested
2517 invocations of the Tcl interpreter in progress, then each nested
2518 command will usually return the error to its caller, until eventually
2519 the error is reported to the top-level application code. The
2520 application will then display the error message for the user.</p></div>
2521 <div class="paragraph"><p>In a few cases, some commands will handle certain <a href="#_error"><strong><code>error</code></strong></a> conditions
2522 themselves and not return them upwards. For example, the <a href="#_for"><strong><code>for</code></strong></a>
2523 command checks for the <code>JIM_BREAK</code> code; if it occurs, then <a href="#_for"><strong><code>for</code></strong></a>
2524 stops executing the body of the loop and returns <code>JIM_OK</code> to its
2525 caller. The <a href="#_for"><strong><code>for</code></strong></a> command also handles <code>JIM_CONTINUE</code> codes and the
2526 procedure interpreter handles <code>JIM_RETURN</code> codes. The <a href="#_catch"><strong><code>catch</code></strong></a>
2527 command allows Tcl programs to catch errors and handle them without
2528 aborting command interpretation any further.</p></div>
2529 <div class="paragraph"><p>The <a href="#_info"><strong><code>info</code></strong></a> <code>returncodes</code> command may be used to programmatically map between
2530 return codes and names.</p></div>
2531 </div>
2532 </div>
2537 procedures. A Tcl procedure can be invoked just like any other Tcl
2538 command (it has a name and it receives one or more arguments).
2539 The only difference is that its body isn’t a piece of C code linked
2540 into the program; it is a string containing one or more other
2541 Tcl commands.</p></div>
2542 <div class="paragraph"><p>The <a href="#_proc"><strong><code>proc</code></strong></a> command is used to create a new Tcl command procedure:</p></div>
2543 <div class="paragraph"><p><code><strong>proc</strong> <em>name arglist ?statics? body</em></code></p></div>
2544 <div class="paragraph"><p>The new command is named <code><em>name</em></code>, and it replaces any existing command
2545 there may have been by that name. Whenever the new command is
2546 invoked, the contents of <code><em>body</em></code> will be executed by the Tcl
2547 interpreter.</p></div>
2548 <div class="paragraph"><p><code><em>arglist</em></code> specifies the formal arguments to the procedure.
2549 It consists of a list, possibly empty, of the following
2550 argument specifiers:</p></div>
2553 <code>name</code>
2554 </dt>
2555 <dd>
2556 <p>
2557 Required Argument - A simple argument name.
2558 </p>
2559 </dd>
2561 <code>name default</code>
2562 </dt>
2563 <dd>
2564 <p>
2565 Optional Argument - A two-element list consisting of the
2566 argument name, followed by the default value, which will
2567 be used if the corresponding argument is not supplied.
2568 </p>
2569 </dd>
2571 <code>&name</code>
2572 </dt>
2573 <dd>
2574 <p>
2575 Reference Argument - The caller is expected to pass the name of
2576 an existing variable. An implicit <a href="#_upvar"><strong><code>upvar</code></strong></a> <code>1 'origname' 'name'</code> is done
2577 to make the variable available in the proc scope.
2578 </p>
2579 </dd>
2581 <code><strong>args</strong></code>
2582 </dt>
2583 <dd>
2584 <p>
2585 Variable Argument - The special name <code><em>args</em></code>, which is
2586 assigned all remaining arguments (including none) as a list. The
2587 variable argument may only be specified once. Note that
2588 the syntax <code>args newname</code> may be used to retain the special
2589 behaviour of <code><em>args</em></code> with a different local name. In this case,
2590 the variable is named <code><em>newname</em></code> rather than <code><em>args</em></code>.
2591 </p>
2592 </dd>
2593 </dl></div>
2594 <div class="paragraph"><p>When the command is invoked, a local variable will be created for each of
2595 the formal arguments to the procedure; its value will be the value
2596 of corresponding argument in the invoking command or the argument’s
2597 default value.</p></div>
2599 invocation. However, there must be enough actual arguments for all
2600 required arguments, and there must not be any extra actual arguments
2601 (unless the Variable Argument is specified).</p></div>
2602 <div class="paragraph"><p>Actual arguments are assigned to formal arguments as in left-to-right
2603 order with the following precedence.</p></div>
2605 <li>
2606 <p>
2607 Required Arguments (including Reference Arguments)
2608 </p>
2609 </li>
2610 <li>
2611 <p>
2612 Optional Arguments
2613 </p>
2614 </li>
2615 <li>
2616 <p>
2617 Variable Argument
2618 </p>
2619 </li>
2620 </ol></div>
2621 <div class="paragraph"><p>The following example illustrates precedence. Assume a procedure declaration:</p></div>
2624 <pre><code>proc p {{a A} args b {c C} d} {...}</code></pre>
2625 </div></div>
2626 <div class="paragraph"><p>This procedure requires at least two arguments, but can accept an unlimited number.
2627 The following table shows how various numbers of arguments are assigned.
2628 Values marked as <code>-</code> are assigned the default value.</p></div>
2640 <thead>
2641 <tr>
2648 </tr>
2649 </thead>
2650 <tbody>
2651 <tr>
2658 </tr>
2659 <tr>
2666 </tr>
2667 <tr>
2674 </tr>
2675 <tr>
2682 </tr>
2683 <tr>
2690 </tr>
2691 </tbody>
2692 </table>
2693 </div>
2694 <div class="paragraph"><p>When <code><em>body</em></code> is being executed, variable names normally refer to local
2695 variables, which are created automatically when referenced and deleted
2696 when the procedure returns. One local variable is automatically created
2697 for each of the procedure’s arguments. Global variables can be
2698 accessed by invoking the <a href="#_global"><strong><code>global</code></strong></a> command or via the <code>::</code> prefix.</p></div>
2701 <div class="paragraph"><p>In addition to procedure arguments, Jim procedures may declare static variables.
2702 These variables scoped to the procedure and initialised at procedure definition.
2703 Either from the static variable definition, or from the enclosing scope.</p></div>
2707 <pre><code>jim> set a 1
2708 jim> proc a {} {a {b 2}} {
2709 set c 1
2711 incr a
2712 incr b
2713 incr c
2714 }
2715 jim> a
2716 1 2 1
2717 jim> a
2718 2 3 1</code></pre>
2719 </div></div>
2720 <div class="paragraph"><p>The static variable <code><em>a</em></code> has no initialiser, so it is initialised from
2721 the enclosing scope with the value 1. (Note that it is an error if there
2722 is no variable with the same name in the enclosing scope). However <code><em>b</em></code>
2723 has an initialiser, so it is initialised to 2.</p></div>
2724 <div class="paragraph"><p>Unlike a local variable, the value of a static variable is retained across
2725 invocations of the procedure.</p></div>
2726 <div class="paragraph"><p>See the <a href="#_proc"><strong><code>proc</code></strong></a> command for information on how to define procedures
2727 and what happens when they are invoked. See also NAMESPACES.</p></div>
2728 </div>
2729 </div>
2730 </div>
2735 either through <em>$</em>-style variable substitution, the <a href="#_set"><strong><code>set</code></strong></a>
2736 command, or a few other mechanisms.</p></div>
2738 be created each time a new variable name is used.</p></div>
2740 A scalar variable has a single value, whereas an array variable
2741 can have any number of elements, each with a name (called
2742 its <em>index</em>) and a value.</p></div>
2744 Parentheses are used refer to array elements in Tcl commands.
2745 For example, the command</p></div>
2748 <pre><code>set x(first) 44</code></pre>
2749 </div></div>
2751 so that its new value is <em>44</em>.</p></div>
2753 that contain multiple concatenated values.
2754 For example, the commands</p></div>
2757 <pre><code>set a(2,3) 1
2758 set a(3,6) 2</code></pre>
2759 </div></div>
2760 <div class="paragraph"><p>set the elements of <em>a</em> whose indexes are <em>2,3</em> and <em>3,6</em>.</p></div>
2762 variables may be used.</p></div>
2764 not be a scalar variable with the same name.</p></div>
2766 name then it is not possible to make array references to the
2767 variable.</p></div>
2769 the existing variable with the <a href="#_unset"><strong><code>unset</code></strong></a> command.</p></div>
2770 <div class="paragraph"><p>The <a href="#_array"><strong><code>array</code></strong></a> command provides several features for dealing
2771 with arrays, such as querying the names of all the elements of
2772 the array and converting between an array and a list.</p></div>
2774 name is used when a procedure isn’t being executed, then it
2775 automatically refers to a global variable. Variable names used
2776 within a procedure normally refer to local variables associated with that
2777 invocation of the procedure. Local variables are deleted whenever
2778 a procedure exits. Either <a href="#_global"><strong><code>global</code></strong></a> command may be used to request
2779 that a name refer to a global variable for the duration of the current
2780 procedure (this is somewhat analogous to <em>extern</em> in C), or the variable
2781 may be explicitly scoped with the <code>::</code> prefix. For example</p></div>
2784 <pre><code>set a 1
2785 set b 2
2786 proc p {} {
2787 set c 3
2788 global a</code></pre>
2789 </div></div>
2793 }
2794 p</code></pre>
2795 </div></div>
2799 <pre><code>1 2 3</code></pre>
2800 </div></div>
2801 </div>
2802 </div>
2806 <div class="paragraph"><p>Unlike Tcl, Jim can automatically convert between a list (with an even
2807 number of elements) and an array value. This is similar to the way Tcl
2808 can convert between a string and a list.</p></div>
2812 <pre><code>set a {1 one 2 two}
2813 puts $a(2)</code></pre>
2814 </div></div>
2818 <pre><code>two</code></pre>
2819 </div></div>
2820 <div class="paragraph"><p>Thus <a href="#_array"><strong><code>array</code></strong></a> <code>set</code> is equivalent to <a href="#_set"><strong><code>set</code></strong></a> when the variable does not
2821 exist or is empty.</p></div>
2823 a list.</p></div>
2826 <pre><code>set a(1) one; set a(2) two
2827 puts $a</code></pre>
2828 </div></div>
2832 <pre><code>1 one 2 two</code></pre>
2833 </div></div>
2834 </div>
2835 </div>
2840 of this command. Dictionaries provide efficient access to key-value
2841 pairs, just like arrays, but dictionaries are pure values. This
2842 means that you can pass them to a procedure just as a list or a
2843 string. Tcl dictionaries are therefore much more like Tcl lists,
2844 except that they represent a mapping from keys to values, rather
2845 than an ordered sequence.</p></div>
2847 consists of another dictionary. That way you can elegantly build
2848 complicated data structures, such as hierarchical databases. You
2849 can also combine dictionaries with other Tcl data structures. For
2850 instance, you can build a list of dictionaries that themselves
2851 contain lists.</p></div>
2853 mapping from arbitrary keys to arbitrary values. Each key in the
2854 dictionary maps to a single value. They have a textual format that
2855 is exactly that of any list with an even number of elements, with
2856 each mapping in the dictionary being represented as two items in
2857 the list. When a command takes a dictionary and produces a new
2858 dictionary based on it (either returning it or writing it back into
2859 the variable that the starting dictionary was read from) the new
2860 dictionary will have the same order of keys, modulo any deleted
2861 keys and with new keys added on to the end. When a string is
2862 interpreted as a dictionary and it would otherwise have duplicate
2863 keys, only the last value for a particular key is used; the others
2865 banana" are equivalent dictionaries (with different string
2866 representations).</p></div>
2868 Thus automatic conversion between lists and dictionaries applies
2869 as it does for arrays.</p></div>
2872 <pre><code>jim> dict set a 1 one
2873 1 one
2874 jim> dict set a 2 two
2875 1 one 2 two
2876 jim> puts $a
2877 1 one 2 two
2878 jim> puts $a(2)
2879 two
2880 jim> dict set a 3 T three
2881 1 one 2 two 3 {T three}</code></pre>
2882 </div></div>
2883 <div class="paragraph"><p>See the <a href="#_dict"><strong><code>dict</code></strong></a> command for more details.</p></div>
2884 </div>
2885 </div>
2889 <div class="paragraph"><p>Tcl added namespaces as a mechanism avoiding name clashes, especially in applications
2890 including a number of 3rd party components. While there is less need for namespaces
2891 in Jim Tcl (which does not strive to support large applications), it is convenient to
2892 provide a subset of the support for namespaces to easy porting code from Tcl.</p></div>
2893 <div class="paragraph"><p>Jim Tcl currently supports "light-weight" namespaces which should be adequate for most
2894 purposes. This feature is currently experimental. See README.namespaces for more information
2895 and the documentation of the <a href="#_namespace"><strong><code>namespace</code></strong></a> command.</p></div>
2896 </div>
2897 </div>
2899 <h2 id="_garbage_collection_references_lambda_function">GARBAGE COLLECTION, REFERENCES, LAMBDA FUNCTION</h2>
2901 <div class="paragraph"><p>Unlike Tcl, Jim has some sophisticated support for functional programming.
2902 These are described briefly below.</p></div>
2903 <div class="paragraph"><p>More information may be found at <a href="http://wiki.tcl.tk/13847">http://wiki.tcl.tk/13847</a></p></div>
2906 <div class="paragraph"><p>A reference can be thought of as holding a value with one level of indirection,
2907 where the value may be garbage collected when unreferenced.
2908 Consider the following example:</p></div>
2912 <reference.<test___>.00000000000000000000>
2913 jim> getref $r
2914 One String</code></pre>
2915 </div></div>
2916 <div class="paragraph"><p>The operation <a href="#_ref"><strong><code>ref</code></strong></a> creates a references to the value specified by the
2918 <div class="paragraph"><p>The operation <a href="#_getref"><strong><code>getref</code></strong></a> is the dereferencing operation which retrieves the value
2919 stored in the reference.</p></div>
2923 New String
2924 jim> getref $r
2925 New String</code></pre>
2926 </div></div>
2927 <div class="paragraph"><p>The operation <a href="#_setref"><strong><code>setref</code></strong></a> replaces the value stored by the reference. If the old value
2928 is no longer accessible by any reference, it will eventually be automatically be garbage
2929 collected.</p></div>
2930 </div>
2933 <div class="paragraph"><p>Normally, all values in Tcl are passed by value. As such values are copied and released
2934 automatically as necessary.</p></div>
2935 <div class="paragraph"><p>With the introduction of references, it is possible to create values whose lifetime
2936 transcend their scope. To support this, case, the Jim system will periodically identify
2937 and discard objects which are no longer accessible by any reference.</p></div>
2938 <div class="paragraph"><p>The <a href="#_collect"><strong><code>collect</code></strong></a> command may be used to force garbage collection. Consider a reference created
2939 with a finalizer:</p></div>
2944 <reference.<test___>.00000000000
2945 jim> collect
2946 0
2948 jim> collect
2949 Finaliser called for <reference.<test___>.00000000000,One String
2950 1</code></pre>
2951 </div></div>
2952 <div class="paragraph"><p>Note that once the reference, <em>r</em>, was modified so that it no longer
2953 contained a reference to the value, the garbage collector discarded
2954 the value (after calling the finalizer).</p></div>
2955 <div class="paragraph"><p>The finalizer for a reference may be examined or changed with the <a href="#_finalize"><strong><code>finalize</code></strong></a> command</p></div>
2958 <pre><code>jim> finalize $r
2959 f
2960 jim> finalize $r newf
2961 newf</code></pre>
2962 </div></div>
2963 </div>
2966 <div class="paragraph"><p>Jim provides a garbage collected <a href="#_lambda"><strong><code>lambda</code></strong></a> function. This is a procedure
2967 which is able to create an anonymous procedure. Consider:</p></div>
2970 <pre><code>jim> set f [lambda {a} {{x 0}} { incr x $a }]
2971 jim> $f 1
2972 1
2973 jim> $f 2
2974 3
2976 </div></div>
2977 <div class="paragraph"><p>This create an anonymous procedure (with the name stored in <em>f</em>), with a static variable
2978 which is incremented by the supplied value and the result returned.</p></div>
2979 <div class="paragraph"><p>Once the procedure name is no longer accessible, it will automatically be deleted
2980 when the garbage collector runs.</p></div>
2981 <div class="paragraph"><p>The procedure may also be delete immediately by renaming it "". e.g.</p></div>
2985 </div></div>
2986 </div>
2987 </div>
2988 </div>
2993 then most string-related commands become UTF-8 aware. These include,
2994 but are not limited to, <a href="#_string"><strong><code>string</code></strong></a> <code>match</code>, <a href="#_split"><strong><code>split</code></strong></a>, <a href="#_glob"><strong><code>glob</code></strong></a>, <a href="#_scan"><strong><code>scan</code></strong></a> and
2996 <div class="paragraph"><p>UTF-8 encoding has many advantages, but one of the complications is that
2997 characters can take a variable number of bytes. Thus the addition of
2998 <a href="#_string"><strong><code>string</code></strong></a> <code>bytelength</code> which returns the number of bytes in a string,
2999 while <a href="#_string"><strong><code>string</code></strong></a> <code>length</code> returns the number of characters.</p></div>
3000 <div class="paragraph"><p>If UTF-8 support is not enabled, all commands treat bytes as characters
3001 and <a href="#_string"><strong><code>string</code></strong></a> <code>bytelength</code> returns the same value as <a href="#_string"><strong><code>string</code></strong></a> <code>length</code>.</p></div>
3002 <div class="paragraph"><p>Note that even if UTF-8 support is not enabled, the <code>\uNNNN</code> and related syntax
3003 is still available to embed UTF-8 sequences.</p></div>
3004 <div class="paragraph"><p>Jim Tcl supports all currently defined unicode codepoints. That is 21 bits, up to +<em>U+1FFFFF</em>.</p></div>
3007 <div class="paragraph"><p>Commands such as <a href="#_string"><strong><code>string</code></strong></a> <code>match</code>, <a href="#_lsearch"><strong><code>lsearch</code></strong></a> <code>-glob</code>, <a href="#_array"><strong><code>array</code></strong></a> <code>names</code> and others use string
3008 pattern matching rules. These commands support UTF-8. For example:</p></div>
3012 </div></div>
3013 </div>
3016 <div class="paragraph"><p><code>format %c</code> allows a unicode codepoint to be be encoded. For example, the following will return
3017 a string with two bytes and one character. The same as <code>\ub5</code></p></div>
3020 <pre><code>format %c 0xb5</code></pre>
3021 </div></div>
3022 <div class="paragraph"><p><a href="#_format"><strong><code>format</code></strong></a> respects widths as character widths, not byte widths. For example, the following will
3023 return a string with three characters, not three bytes.</p></div>
3026 <pre><code>format %.3s \ub5\ub6\ub7\ub8</code></pre>
3027 </div></div>
3028 <div class="paragraph"><p>Similarly, <code>scan … %c</code> allows a UTF-8 to be decoded to a unicode codepoint. The following will set
3029 <code><em>a</em></code> to 181 (0xb5) and <code><em>b</em></code> to 65 (0x41).</p></div>
3032 <pre><code>scan \u00b5A %c%c a b</code></pre>
3033 </div></div>
3034 <div class="paragraph"><p><a href="#_scan"><strong><code>scan</code></strong></a> <code>%s</code> will also accept a character class, including unicode ranges.</p></div>
3035 </div>
3038 <div class="paragraph"><p><a href="#_string"><strong><code>string</code></strong></a> <code>is</code> has <strong>not</strong> been extended to classify UTF-8 characters. Therefore, the following
3039 will return 0, even though the string may be considered to be alphabetic.</p></div>
3042 <pre><code>string is alpha \ub5Test</code></pre>
3043 </div></div>
3044 <div class="paragraph"><p>This does not affect the string classes <em>ascii</em>, <em>control</em>, <em>digit</em>, <em>double</em>, <em>integer</em> or <em>xdigit</em>.</p></div>
3045 </div>
3048 <div class="paragraph"><p>Jim provides a simplified unicode case mapping. This means that case conversion
3049 and comparison will not increase or decrease the number of characters in a string.
3050 (Although it may change the number of bytes).</p></div>
3051 <div class="paragraph"><p><a href="#_string"><strong><code>string</code></strong></a> <code>toupper</code> will convert any lowercase letters to their uppercase equivalent.
3052 Any character which is not a letter or has no uppercase equivalent is left unchanged.
3053 Similarly for <a href="#_string"><strong><code>string</code></strong></a> <code>tolower</code> and <a href="#_string"><strong><code>string</code></strong></a> <code>totitle</code>.</p></div>
3054 <div class="paragraph"><p>Commands which perform case insensitive matches, such as <a href="#_string"><strong><code>string</code></strong></a> <code>compare -nocase</code>
3055 and <a href="#_lsearch"><strong><code>lsearch</code></strong></a> <code>-nocase</code> fold both strings to uppercase before comparison.</p></div>
3056 </div>
3059 <div class="paragraph"><p>Some UTF-8 character sequences are invalid, such as those beginning with <em>0xff</em>,
3060 those which represent character sequences longer than 3 bytes (greater than U+FFFF),
3061 and those which end prematurely, such as a lone <em>0xc2</em>.</p></div>
3062 <div class="paragraph"><p>In these situations, the offending bytes are treated as single characters. For example,
3063 the following returns 2.</p></div>
3066 <pre><code>string bytelength \xff\xff</code></pre>
3067 </div></div>
3068 </div>
3071 <div class="paragraph"><p>If UTF-8 support is enabled, the built-in regular expression engine will be
3072 selected which supports UTF-8 strings and patterns.</p></div>
3074 </div>
3075 </div>
3076 </div>
3081 be available in any application using Tcl. In addition to these
3082 built-in commands, there may be additional commands defined by each
3083 application, plus commands defined as Tcl procedures.</p></div>
3084 <div class="paragraph"><p>In the command syntax descriptions below, words in <code><strong>boldface</strong></code> are
3085 literals that you type verbatim to Tcl.</p></div>
3086 <div class="paragraph"><p>Words in <code><em>italics</em></code> are meta-symbols; they serve as names for any of
3087 a range of values that you can type.</p></div>
3088 <div class="paragraph"><p>Optional arguments or groups of arguments are indicated by enclosing them
3089 in <code>?question-marks?</code>.</p></div>
3091 arguments or groups of arguments may appear, in the same format
3092 as the preceding argument(s).</p></div>
3108 <tbody>
3109 <tr>
3110 <td align="left" valign="top"><p class="table"><a href="#cmd_2"><strong><code>after</code></strong></a></p></td>
3111 <td align="left" valign="top"><p class="table"><a href="#_aio"><strong><code>aio</code></strong></a></p></td>
3112 <td align="left" valign="top"><p class="table"><a href="#_alarm"><strong><code>alarm</code></strong></a></p></td>
3113 <td align="left" valign="top"><p class="table"><a href="#_alias"><strong><code>alias</code></strong></a></p></td>
3114 <td align="left" valign="top"><p class="table"><a href="#_append"><strong><code>append</code></strong></a></p></td>
3115 <td align="left" valign="top"><p class="table"><a href="#_apply"><strong><code>apply</code></strong></a></p></td>
3116 <td align="left" valign="top"><p class="table"><a href="#_array"><strong><code>array</code></strong></a></p></td>
3117 <td align="left" valign="top"><p class="table"><a href="#_binary"><strong><code>binary</code></strong></a></p></td>
3118 </tr>
3119 <tr>
3120 <td align="left" valign="top"><p class="table"><a href="#_break"><strong><code>break</code></strong></a></p></td>
3121 <td align="left" valign="top"><p class="table"><a href="#_case"><strong><code>case</code></strong></a></p></td>
3122 <td align="left" valign="top"><p class="table"><a href="#_catch"><strong><code>catch</code></strong></a></p></td>
3123 <td align="left" valign="top"><p class="table"><a href="#_cd"><strong><code>cd</code></strong></a></p></td>
3124 <td align="left" valign="top"><p class="table"><a href="#cmd_4"><strong><code>class</code></strong></a></p></td>
3125 <td align="left" valign="top"><p class="table"><a href="#_clock"><strong><code>clock</code></strong></a></p></td>
3126 <td align="left" valign="top"><p class="table"><a href="#_close"><strong><code>close</code></strong></a></p></td>
3127 <td align="left" valign="top"><p class="table"><a href="#_collect"><strong><code>collect</code></strong></a></p></td>
3128 </tr>
3129 <tr>
3130 <td align="left" valign="top"><p class="table"><a href="#_concat"><strong><code>concat</code></strong></a></p></td>
3131 <td align="left" valign="top"><p class="table"><a href="#_continue"><strong><code>continue</code></strong></a></p></td>
3132 <td align="left" valign="top"><p class="table"><a href="#_curry"><strong><code>curry</code></strong></a></p></td>
3133 <td align="left" valign="top"><p class="table"><a href="#_dict"><strong><code>dict</code></strong></a></p></td>
3134 <td align="left" valign="top"><p class="table"><a href="#_env"><strong><code>env</code></strong></a></p></td>
3135 <td align="left" valign="top"><p class="table"><a href="#_eof"><strong><code>eof</code></strong></a></p></td>
3136 <td align="left" valign="top"><p class="table"><a href="#_error"><strong><code>error</code></strong></a></p></td>
3137 <td align="left" valign="top"><p class="table"><a href="#_eval"><strong><code>eval</code></strong></a></p></td>
3138 </tr>
3139 <tr>
3140 <td align="left" valign="top"><p class="table"><a href="#cmd_2"><strong><code>eventloop</code></strong></a></p></td>
3141 <td align="left" valign="top"><p class="table"><a href="#_exec"><strong><code>exec</code></strong></a></p></td>
3142 <td align="left" valign="top"><p class="table"><a href="#_exists"><strong><code>exists</code></strong></a></p></td>
3143 <td align="left" valign="top"><p class="table"><a href="#_exit"><strong><code>exit</code></strong></a></p></td>
3144 <td align="left" valign="top"><p class="table"><a href="#_expr"><strong><code>expr</code></strong></a></p></td>
3145 <td align="left" valign="top"><p class="table"><a href="#_fconfigure"><strong><code>fconfigure</code></strong></a></p></td>
3146 <td align="left" valign="top"><p class="table"><a href="#_file"><strong><code>file</code></strong></a></p></td>
3147 <td align="left" valign="top"><p class="table"><a href="#_finalize"><strong><code>finalize</code></strong></a></p></td>
3148 </tr>
3149 <tr>
3150 <td align="left" valign="top"><p class="table"><a href="#_flush"><strong><code>flush</code></strong></a></p></td>
3151 <td align="left" valign="top"><p class="table"><a href="#_for"><strong><code>for</code></strong></a></p></td>
3152 <td align="left" valign="top"><p class="table"><a href="#_foreach"><strong><code>foreach</code></strong></a></p></td>
3153 <td align="left" valign="top"><p class="table"><a href="#_format"><strong><code>format</code></strong></a></p></td>
3154 <td align="left" valign="top"><p class="table"><a href="#_getref"><strong><code>getref</code></strong></a></p></td>
3155 <td align="left" valign="top"><p class="table"><a href="#_gets"><strong><code>gets</code></strong></a></p></td>
3156 <td align="left" valign="top"><p class="table"><a href="#_glob"><strong><code>glob</code></strong></a></p></td>
3157 <td align="left" valign="top"><p class="table"><a href="#_global"><strong><code>global</code></strong></a></p></td>
3158 </tr>
3159 <tr>
3160 <td align="left" valign="top"><p class="table"><a href="#_history"><strong><code>history</code></strong></a></p></td>
3161 <td align="left" valign="top"><p class="table"><a href="#_if"><strong><code>if</code></strong></a></p></td>
3162 <td align="left" valign="top"><p class="table"><a href="#_incr"><strong><code>incr</code></strong></a></p></td>
3163 <td align="left" valign="top"><p class="table"><a href="#_info"><strong><code>info</code></strong></a></p></td>
3164 <td align="left" valign="top"><p class="table"><a href="#_join"><strong><code>join</code></strong></a></p></td>
3165 <td align="left" valign="top"><p class="table"><a href="#_kill"><strong><code>kill</code></strong></a></p></td>
3166 <td align="left" valign="top"><p class="table"><a href="#_lambda"><strong><code>lambda</code></strong></a></p></td>
3167 <td align="left" valign="top"><p class="table"><a href="#_lappend"><strong><code>lappend</code></strong></a></p></td>
3168 </tr>
3169 <tr>
3170 <td align="left" valign="top"><p class="table"><a href="#_lassign"><strong><code>lassign</code></strong></a></p></td>
3171 <td align="left" valign="top"><p class="table"><a href="#_lindex"><strong><code>lindex</code></strong></a></p></td>
3172 <td align="left" valign="top"><p class="table"><a href="#_linsert"><strong><code>linsert</code></strong></a></p></td>
3173 <td align="left" valign="top"><p class="table"><a href="#_list"><strong><code>list</code></strong></a></p></td>
3174 <td align="left" valign="top"><p class="table"><a href="#_llength"><strong><code>llength</code></strong></a></p></td>
3175 <td align="left" valign="top"><p class="table"><a href="#_lmap"><strong><code>lmap</code></strong></a></p></td>
3176 <td align="left" valign="top"><p class="table"><a href="#_load"><strong><code>load</code></strong></a></p></td>
3177 <td align="left" valign="top"><p class="table"><a href="#_local"><strong><code>local</code></strong></a></p></td>
3178 </tr>
3179 <tr>
3180 <td align="left" valign="top"><p class="table"><a href="#_loop"><strong><code>loop</code></strong></a></p></td>
3181 <td align="left" valign="top"><p class="table"><a href="#_lrange"><strong><code>lrange</code></strong></a></p></td>
3182 <td align="left" valign="top"><p class="table"><a href="#_lrepeat"><strong><code>lrepeat</code></strong></a></p></td>
3183 <td align="left" valign="top"><p class="table"><a href="#_lreplace"><strong><code>lreplace</code></strong></a></p></td>
3184 <td align="left" valign="top"><p class="table"><a href="#_lreverse"><strong><code>lreverse</code></strong></a></p></td>
3185 <td align="left" valign="top"><p class="table"><a href="#_lsearch"><strong><code>lsearch</code></strong></a></p></td>
3186 <td align="left" valign="top"><p class="table"><a href="#_lset"><strong><code>lset</code></strong></a></p></td>
3187 <td align="left" valign="top"><p class="table"><a href="#_lsort"><strong><code>lsort</code></strong></a></p></td>
3188 </tr>
3189 <tr>
3190 <td align="left" valign="top"><p class="table"><a href="#_namespace"><strong><code>namespace</code></strong></a></p></td>
3191 <td align="left" valign="top"><p class="table"><a href="#cmd_4"><strong><code>oo</code></strong></a></p></td>
3192 <td align="left" valign="top"><p class="table"><a href="#_open"><strong><code>open</code></strong></a></p></td>
3193 <td align="left" valign="top"><p class="table"><a href="#cmd_1"><strong><code>os.fork</code></strong></a></p></td>
3194 <td align="left" valign="top"><p class="table"><a href="#cmd_1"><strong><code>os.gethostname</code></strong></a></p></td>
3195 <td align="left" valign="top"><p class="table"><a href="#cmd_1"><strong><code>os.getids</code></strong></a></p></td>
3196 <td align="left" valign="top"><p class="table"><a href="#cmd_1"><strong><code>os.uptime</code></strong></a></p></td>
3197 <td align="left" valign="top"><p class="table"><a href="#cmd_1"><strong><code>os.wait</code></strong></a></p></td>
3198 </tr>
3199 <tr>
3200 <td align="left" valign="top"><p class="table"><a href="#cmd_3"><strong><code>pack</code></strong></a></p></td>
3201 <td align="left" valign="top"><p class="table"><a href="#cmd_3"><strong><code>pack</code></strong></a></p></td>
3202 <td align="left" valign="top"><p class="table"><a href="#_package"><strong><code>package</code></strong></a></p></td>
3203 <td align="left" valign="top"><p class="table"><a href="#_pid"><strong><code>pid</code></strong></a></p></td>
3204 <td align="left" valign="top"><p class="table"><a href="#cmd_1"><strong><code>posix</code></strong></a></p></td>
3205 <td align="left" valign="top"><p class="table"><a href="#_proc"><strong><code>proc</code></strong></a></p></td>
3206 <td align="left" valign="top"><p class="table"><a href="#_puts"><strong><code>puts</code></strong></a></p></td>
3207 <td align="left" valign="top"><p class="table"><a href="#_pwd"><strong><code>pwd</code></strong></a></p></td>
3208 </tr>
3209 <tr>
3210 <td align="left" valign="top"><p class="table"><a href="#_rand"><strong><code>rand</code></strong></a></p></td>
3211 <td align="left" valign="top"><p class="table"><a href="#_range"><strong><code>range</code></strong></a></p></td>
3212 <td align="left" valign="top"><p class="table"><a href="#_read"><strong><code>read</code></strong></a></p></td>
3213 <td align="left" valign="top"><p class="table"><a href="#_ref"><strong><code>ref</code></strong></a></p></td>
3214 <td align="left" valign="top"><p class="table"><a href="#_regexp"><strong><code>regexp</code></strong></a></p></td>
3215 <td align="left" valign="top"><p class="table"><a href="#_regsub"><strong><code>regsub</code></strong></a></p></td>
3216 <td align="left" valign="top"><p class="table"><a href="#_rename"><strong><code>rename</code></strong></a></p></td>
3217 <td align="left" valign="top"><p class="table"><a href="#_return"><strong><code>return</code></strong></a></p></td>
3218 </tr>
3219 <tr>
3220 <td align="left" valign="top"><p class="table"><a href="#_scan"><strong><code>scan</code></strong></a></p></td>
3221 <td align="left" valign="top"><p class="table"><a href="#_seek"><strong><code>seek</code></strong></a></p></td>
3222 <td align="left" valign="top"><p class="table"><a href="#_set"><strong><code>set</code></strong></a></p></td>
3223 <td align="left" valign="top"><p class="table"><a href="#_setref"><strong><code>setref</code></strong></a></p></td>
3224 <td align="left" valign="top"><p class="table"><a href="#_signal"><strong><code>signal</code></strong></a></p></td>
3225 <td align="left" valign="top"><p class="table"><a href="#_sleep"><strong><code>sleep</code></strong></a></p></td>
3226 <td align="left" valign="top"><p class="table"><a href="#_socket"><strong><code>socket</code></strong></a></p></td>
3227 <td align="left" valign="top"><p class="table"><a href="#_source"><strong><code>source</code></strong></a></p></td>
3228 </tr>
3229 <tr>
3230 <td align="left" valign="top"><p class="table"><a href="#_split"><strong><code>split</code></strong></a></p></td>
3231 <td align="left" valign="top"><p class="table"><a href="#_stackdump"><strong><code>stackdump</code></strong></a></p></td>
3232 <td align="left" valign="top"><p class="table"><a href="#_stacktrace"><strong><code>stacktrace</code></strong></a></p></td>
3233 <td align="left" valign="top"><p class="table"><a href="#_string"><strong><code>string</code></strong></a></p></td>
3234 <td align="left" valign="top"><p class="table"><a href="#_subst"><strong><code>subst</code></strong></a></p></td>
3235 <td align="left" valign="top"><p class="table"><a href="#cmd_4"><strong><code>super</code></strong></a></p></td>
3236 <td align="left" valign="top"><p class="table"><a href="#_switch"><strong><code>switch</code></strong></a></p></td>
3237 <td align="left" valign="top"><p class="table"><a href="#_syslog"><strong><code>syslog</code></strong></a></p></td>
3238 </tr>
3239 <tr>
3240 <td align="left" valign="top"><p class="table"><a href="#_tailcall"><strong><code>tailcall</code></strong></a></p></td>
3241 <td align="left" valign="top"><p class="table"><a href="#_tcl_prefix"><strong><code>tcl::prefix</code></strong></a></p></td>
3242 <td align="left" valign="top"><p class="table"><a href="#_tell"><strong><code>tell</code></strong></a></p></td>
3243 <td align="left" valign="top"><p class="table"><a href="#_throw"><strong><code>throw</code></strong></a></p></td>
3244 <td align="left" valign="top"><p class="table"><a href="#_time"><strong><code>time</code></strong></a></p></td>
3245 <td align="left" valign="top"><p class="table"><a href="#_tree"><strong><code>tree</code></strong></a></p></td>
3246 <td align="left" valign="top"><p class="table"><a href="#_try"><strong><code>try</code></strong></a></p></td>
3247 <td align="left" valign="top"><p class="table"><a href="#_unknown"><strong><code>unknown</code></strong></a></p></td>
3248 </tr>
3249 <tr>
3250 <td align="left" valign="top"><p class="table"><a href="#cmd_3"><strong><code>unpack</code></strong></a></p></td>
3251 <td align="left" valign="top"><p class="table"><a href="#_unset"><strong><code>unset</code></strong></a></p></td>
3252 <td align="left" valign="top"><p class="table"><a href="#_upcall"><strong><code>upcall</code></strong></a></p></td>
3253 <td align="left" valign="top"><p class="table"><a href="#cmd_2"><strong><code>update</code></strong></a></p></td>
3254 <td align="left" valign="top"><p class="table"><a href="#_uplevel"><strong><code>uplevel</code></strong></a></p></td>
3255 <td align="left" valign="top"><p class="table"><a href="#_upvar"><strong><code>upvar</code></strong></a></p></td>
3256 <td align="left" valign="top"><p class="table"><a href="#cmd_2"><strong><code>vwait</code></strong></a></p></td>
3257 <td align="left" valign="top"><p class="table"><a href="#_while"><strong><code>while</code></strong></a></p></td>
3258 </tr>
3259 </tbody>
3260 </table>
3261 </div>
3262 </div>
3266 <div class="paragraph"><p>Delivers the <code>SIGALRM</code> signal to the process after the given
3267 number of seconds. If the platform supports <em>ualarm(3)</em> then
3268 the argument may be a floating point value. Otherwise it must
3269 be an integer.</p></div>
3270 <div class="paragraph"><p>Note that unless a signal handler for <code>SIGALRM</code> has been installed
3271 (see <a href="#_signal"><strong><code>signal</code></strong></a>), the process will exit on this signal.</p></div>
3272 </div>
3276 <div class="paragraph"><p>Creates a single word alias (command) for one or more words. For example,
3277 the following creates an alias for the command <a href="#_info"><strong><code>info</code></strong></a> <code>exists</code>.</p></div>
3280 <pre><code>alias e info exists
3281 if {[e var]} {
3282 ...
3283 }</code></pre>
3284 </div></div>
3285 <div class="paragraph"><p><a href="#_alias"><strong><code>alias</code></strong></a> returns <code><em>name</em></code>, allowing it to be used with <a href="#_local"><strong><code>local</code></strong></a>.</p></div>
3286 <div class="paragraph"><p>See also <a href="#_proc"><strong><code>proc</code></strong></a>, <a href="#_curry"><strong><code>curry</code></strong></a>, <a href="#_lambda"><strong><code>lambda</code></strong></a>, <a href="#_local"><strong><code>local</code></strong></a>, <a href="#_info"><strong><code>info</code></strong></a> <code>alias</code>, <a href="#_exists"><strong><code>exists</code></strong></a> <code>-alias</code></p></div>
3287 </div>
3290 <div class="paragraph"><p><code><strong>append</strong> <em>varName value ?value value …?</em></code></p></div>
3291 <div class="paragraph"><p>Append all of the <code><em>value</em></code> arguments to the current value
3292 of variable <code><em>varName</em></code>. If <code><em>varName</em></code> doesn’t exist,
3293 it is given a value equal to the concatenation of all the
3294 <code><em>value</em></code> arguments.</p></div>
3296 variables incrementally.
3297 For example, "<a href="#_append"><strong><code>append</code></strong></a> <code>a $b</code>" is much more efficient than
3298 "<a href="#_set"><strong><code>set</code></strong></a> <code>a $a$b</code>" if <code>$a</code> is long.</p></div>
3299 </div>
3302 <div class="paragraph"><p><code><strong>apply</strong> <em>lambdaExpr ?arg1 arg2 ...?</em></code></p></div>
3303 <div class="paragraph"><p>The command <a href="#_apply"><strong><code>apply</code></strong></a> provides for anonymous procedure calls,
3304 similar to <a href="#_lambda"><strong><code>lambda</code></strong></a>, but without command name being created, even temporarily.</p></div>
3305 <div class="paragraph"><p>The function <code><em>lambdaExpr</em></code> is a two element list <code>{args body}</code>
3306 or a three element list <code>{args body namespace}</code>. The first element
3307 args specifies the formal arguments, in the same form as the <a href="#_proc"><strong><code>proc</code></strong></a> and <a href="#_lambda"><strong><code>lambda</code></strong></a> commands.</p></div>
3308 </div>
3311 <div class="paragraph"><p><code><strong>array</strong> <em>option arrayName ?arg...?</em></code></p></div>
3313 variable given by <code><em>arrayName</em></code>.</p></div>
3314 <div class="paragraph"><p>Note that in general, if the named array does not exist, the <code><em>array</em></code> command behaves
3315 as though the array exists but is empty.</p></div>
3316 <div class="paragraph"><p>The <code><em>option</em></code> argument determines what action is carried out by the
3317 command. The legal <code><em>options</em></code> (which may be abbreviated) are:</p></div>
3320 <code><strong>array exists</strong> <em>arrayName</em></code>
3321 </dt>
3322 <dd>
3323 <p>
3324 Returns 1 if arrayName is an array variable, 0 if there is
3325 no variable by that name. This command is essentially
3327 </p>
3328 </dd>
3330 <code><strong>array get</strong> <em>arrayName ?pattern?</em></code>
3331 </dt>
3332 <dd>
3333 <p>
3334 Returns a list containing pairs of elements. The first
3335 element in each pair is the name of an element in arrayName
3336 and the second element of each pair is the value of the
3337 array element. The order of the pairs is undefined. If
3338 pattern is not specified, then all of the elements of the
3339 array are included in the result. If pattern is specified,
3340 then only those elements whose names match pattern (using
3341 the matching rules of string match) are included. If arrayName
3342 isn’t the name of an array variable, or if the array contains
3343 no elements, then an empty list is returned.
3344 </p>
3345 </dd>
3347 <code><strong>array names</strong> <em>arrayName ?pattern?</em></code>
3348 </dt>
3349 <dd>
3350 <p>
3351 Returns a list containing the names of all of the elements
3352 in the array that match pattern. If pattern is omitted then
3353 the command returns all of the element names in the array.
3354 If pattern is specified, then only those elements whose
3355 names match pattern (using the matching rules of string
3356 match) are included. If there are no (matching) elements
3357 in the array, or if arrayName isn’t the name of an array
3358 variable, then an empty string is returned.
3359 </p>
3360 </dd>
3362 <code><strong>array set</strong> <em>arrayName list</em></code>
3363 </dt>
3364 <dd>
3365 <p>
3366 Sets the values of one or more elements in arrayName. list
3367 must have a form like that returned by array get, consisting
3368 of an even number of elements. Each odd-numbered element
3369 in list is treated as an element name within arrayName, and
3370 the following element in list is used as a new value for
3371 that array element. If the variable arrayName does not
3372 already exist and list is empty, arrayName is created with
3373 an empty array value.
3374 </p>
3375 </dd>
3377 <code><strong>array size</strong> <em>arrayName</em></code>
3378 </dt>
3379 <dd>
3380 <p>
3381 Returns the number of elements in the array. If arrayName
3382 isn’t the name of an array then 0 is returned.
3383 </p>
3384 </dd>
3386 <code><strong>array unset</strong> <em>arrayName ?pattern?</em></code>
3387 </dt>
3388 <dd>
3389 <p>
3390 Unsets all of the elements in the array that match pattern
3391 (using the matching rules of string match). If arrayName
3392 isn’t the name of an array variable or there are no matching
3393 elements in the array, no error will be raised. If pattern
3394 is omitted and arrayName is an array variable, then the
3395 command unsets the entire array. The command always returns
3396 an empty string.
3397 </p>
3398 </dd>
3399 </dl></div>
3400 </div>
3405 such as <a href="#_for"><strong><code>for</code></strong></a> or <a href="#_foreach"><strong><code>foreach</code></strong></a> or <a href="#_while"><strong><code>while</code></strong></a>. It returns a <code>JIM_BREAK</code> code
3406 to signal the innermost containing loop command to return immediately.</p></div>
3407 </div>
3410 <div class="paragraph"><p><code><strong>case</strong> <em>string</em> ?in? <em>patList body ?patList body …?</em></code></p></div>
3411 <div class="paragraph"><p><code><strong>case</strong> <em>string</em> ?in? {<em>patList body ?patList body …?</em>}</code></p></div>
3412 <div class="paragraph"><p><strong>Note</strong> that the <a href="#_switch"><strong><code>switch</code></strong></a> command should generally be preferred unless compatibility
3413 with Tcl 6.x is desired.</p></div>
3414 <div class="paragraph"><p>Match <code><em>string</em></code> against each of the <code><em>patList</em></code> arguments
3415 in order. If one matches, then evaluate the following <code><em>body</em></code> argument
3416 by passing it recursively to the Tcl interpreter, and return the result
3417 of that evaluation. Each <code><em>patList</em></code> argument consists of a single
3418 pattern or list of patterns. Each pattern may contain any of the wild-cards
3419 described under <a href="#_string"><strong><code>string</code></strong></a> <code>match</code>.</p></div>
3420 <div class="paragraph"><p>If a <code><em>patList</em></code> argument is <code>default</code>, the corresponding body will be
3421 evaluated if no <code><em>patList</em></code> matches <code><em>string</em></code>. If no <code><em>patList</em></code> argument
3422 matches <code><em>string</em></code> and no default is given, then the <a href="#_case"><strong><code>case</code></strong></a> command returns
3423 an empty string.</p></div>
3425 <div class="paragraph"><p>The first uses a separate argument for each of the patterns and commands;
3426 this form is convenient if substitutions are desired on some of the
3427 patterns or commands.</p></div>
3428 <div class="paragraph"><p>The second form places all of the patterns and commands together into
3429 a single argument; the argument must have proper list structure, with
3430 the elements of the list being the patterns and commands.</p></div>
3432 since the braces around the whole list make it unnecessary to include a
3433 backslash at the end of each line.</p></div>
3434 <div class="paragraph"><p>Since the <code><em>patList</em></code> arguments are in braces in the second form,
3435 no command or variable substitutions are performed on them; this makes
3436 the behaviour of the second form different than the first form in some
3437 cases.</p></div>
3438 <div class="paragraph"><p>Below are some examples of <a href="#_case"><strong><code>case</code></strong></a> commands:</p></div>
3441 <pre><code>case abc in {a b} {format 1} default {format 2} a* {format 3}</code></pre>
3442 </div></div>
3446 <pre><code>case a in {
3447 {a b} {format 1}
3448 default {format 2}
3449 a* {format 3}
3450 }</code></pre>
3451 </div></div>
3455 <pre><code>case xyz {
3456 {a b}
3457 {format 1}
3458 default
3459 {format 2}
3460 a*
3461 {format 3}
3462 }</code></pre>
3463 </div></div>
3465 </div>
3468 <div class="paragraph"><p><code><strong>catch</strong> ?-?no?<em>code ...</em>? ?--? <em>command ?resultVarName? ?optionsVarName?</em></code></p></div>
3469 <div class="paragraph"><p>The <a href="#_catch"><strong><code>catch</code></strong></a> command may be used to prevent errors from aborting
3470 command interpretation. <a href="#_catch"><strong><code>catch</code></strong></a> evaluates <code><em>command</em></code>, and returns a
3471 <code>JIM_OK</code> code, regardless of any errors that might occur while
3472 executing <code><em>command</em></code> (with the possible exception of <code>JIM_SIGNAL</code> -
3473 see below).</p></div>
3474 <div class="paragraph"><p>The return value from <a href="#_catch"><strong><code>catch</code></strong></a> is a decimal string giving the code
3475 returned by the Tcl interpreter after executing <code><em>command</em></code>. This
3476 will be <em>0</em> (<code>JIM_OK</code>) if there were no errors in <code><em>command</em></code>; otherwise
3477 it will have a non-zero value corresponding to one of the exceptional
3478 return codes (see jim.h for the definitions of code values, or the
3479 <a href="#_info"><strong><code>info</code></strong></a> <code>returncodes</code> command).</p></div>
3480 <div class="paragraph"><p>If the <code><em>resultVarName</em></code> argument is given, then it gives the name
3481 of a variable; <a href="#_catch"><strong><code>catch</code></strong></a> will set the value of the variable to the
3482 string returned from <code><em>command</em></code> (either a result or an error message).</p></div>
3483 <div class="paragraph"><p>If the <code><em>optionsVarName</em></code> argument is given, then it gives the name
3484 of a variable; <a href="#_catch"><strong><code>catch</code></strong></a> will set the value of the variable to a
3485 dictionary. For any return code other than <code>JIM_RETURN</code>, the value
3486 for the key <code>-code</code> will be set to the return code. For <code>JIM_RETURN</code>
3487 it will be set to the code given in <a href="#_return"><strong><code>return</code></strong></a> <code>-code</code>. Additionally,
3488 for the return code <code>JIM_ERR</code>, the value of the key <code>-errorinfo</code>
3489 will contain the current stack trace (the same result as <a href="#_info"><strong><code>info</code></strong></a> <code>stacktrace</code>),
3490 the value of the key <code>-errorcode</code> will contain the
3491 same value as the global variable $::errorCode, and the value of
3492 the key <code>-level</code> will be the current return level (see <a href="#_return"><strong><code>return</code></strong></a> <code>-level</code>).
3493 This can be useful to rethrow an error:</p></div>
3496 <pre><code>if {[catch {...} msg opts]} {
3497 ...maybe do something with the error...
3498 incr opts(-level)
3499 return {*}$opts $msg
3500 }</code></pre>
3501 </div></div>
3502 <div class="paragraph"><p>Normally <a href="#_catch"><strong><code>catch</code></strong></a> will <code><em>not</em></code> catch any of the codes <code>JIM_EXIT</code>, <code>JIM_EVAL</code> or <code>JIM_SIGNAL</code>.
3503 The set of codes which will be caught may be modified by specifying the one more codes before
3504 <code><em>command</em></code>.</p></div>
3505 <div class="paragraph"><p>e.g. To catch <code>JIM_EXIT</code> but not <code>JIM_BREAK</code> or <code>JIM_CONTINUE</code></p></div>
3508 <pre><code>catch -exit -nobreak -nocontinue -- { ... }</code></pre>
3509 </div></div>
3510 <div class="paragraph"><p>The use of <code>--</code> is optional. It signifies that no more return code options follow.</p></div>
3511 <div class="paragraph"><p>Note that if a signal marked as <a href="#_signal"><strong><code>signal</code></strong></a> <code>handle</code> is caught with <a href="#_catch"><strong><code>catch</code></strong></a> <code>-signal</code>, the return value
3512 (stored in <code><em>resultVarName</em></code>) is name of the signal caught.</p></div>
3513 </div>
3517 <div class="paragraph"><p>Change the current working directory to <code><em>dirName</em></code>.</p></div>
3519 <div class="paragraph"><p>This command can potentially be disruptive to an application, so it may
3520 be removed in some applications.</p></div>
3521 </div>
3526 <code><strong>clock seconds</strong></code>
3527 </dt>
3528 <dd>
3529 <p>
3530 Returns the current time as seconds since the epoch.
3531 </p>
3532 </dd>
3534 <code><strong>clock clicks</strong></code>
3535 </dt>
3536 <dd>
3537 <p>
3538 Returns the current time in ‘clicks’.
3539 </p>
3540 </dd>
3542 <code><strong>clock microseconds</strong></code>
3543 </dt>
3544 <dd>
3545 <p>
3546 Returns the current time in microseconds.
3547 </p>
3548 </dd>
3550 <code><strong>clock milliseconds</strong></code>
3551 </dt>
3552 <dd>
3553 <p>
3554 Returns the current time in milliseconds.
3555 </p>
3556 </dd>
3558 <code><strong>clock format</strong> <em>seconds</em> ?<strong>-format</strong> <em>format?</em></code>
3559 </dt>
3560 <dd>
3561 <p>
3562 Format the given time (seconds since the epoch) according to the given
3563 format. See strftime(3) for supported formats.
3565 </p>
3566 </dd>
3568 <code><strong>clock scan</strong> <em>str</em> <strong>-format</strong> <em>format</em></code>
3569 </dt>
3570 <dd>
3571 <p>
3572 Scan the given time string using the given format string.
3573 See strptime(3) for supported formats.
3574 </p>
3575 </dd>
3576 </dl></div>
3577 </div>
3583 <code><em>fileId</em></code> must be the return value from a previous invocation
3584 of the <a href="#_open"><strong><code>open</code></strong></a> command; after this command, it should not be
3585 used anymore.</p></div>
3586 </div>
3590 <div class="paragraph"><p>Normally reference garbage collection is automatically performed periodically.
3591 However it may be run immediately with the <a href="#_collect"><strong><code>collect</code></strong></a> command.</p></div>
3592 <div class="paragraph"><p>See GARBAGE COLLECTION, REFERENCES, LAMBDA FUNCTION for more detail.</p></div>
3593 </div>
3596 <div class="paragraph"><p><code><strong>concat</strong> <em>arg ?arg ...?</em></code></p></div>
3598 into a single list. It permits any number of arguments. For example,
3599 the command</p></div>
3602 <pre><code>concat a b {c d e} {f {g h}}</code></pre>
3603 </div></div>
3607 <pre><code>a b c d e f {g h}</code></pre>
3608 </div></div>
3610 </div>
3614 <div class="paragraph"><p>This command may be invoked only inside the body of a loop command such
3615 as <a href="#_for"><strong><code>for</code></strong></a> or <a href="#_foreach"><strong><code>foreach</code></strong></a> or <a href="#_while"><strong><code>while</code></strong></a>. It returns a <code>JIM_CONTINUE</code> code to
3616 signal the innermost containing loop command to skip the remainder of
3617 the loop’s body but continue with the next iteration of the loop.</p></div>
3618 </div>
3622 <div class="paragraph"><p>Similar to <a href="#_alias"><strong><code>alias</code></strong></a> except it creates an anonymous procedure (lambda) instead of
3623 a named procedure.</p></div>
3624 <div class="paragraph"><p>the following creates a local, unnamed alias for the command <a href="#_info"><strong><code>info</code></strong></a> <code>exists</code>.</p></div>
3627 <pre><code>set e [local curry info exists]
3628 if {[$e var]} {
3629 ...
3630 }</code></pre>
3631 </div></div>
3632 <div class="paragraph"><p><a href="#_curry"><strong><code>curry</code></strong></a> returns the name of the procedure.</p></div>
3633 <div class="paragraph"><p>See also <a href="#_proc"><strong><code>proc</code></strong></a>, <a href="#_alias"><strong><code>alias</code></strong></a>, <a href="#_lambda"><strong><code>lambda</code></strong></a>, <a href="#_local"><strong><code>local</code></strong></a>.</p></div>
3634 </div>
3637 <div class="paragraph"><p><code><strong>dict</strong> <em>option ?arg...?</em></code></p></div>
3639 <div class="paragraph"><p>The <code><em>option</em></code> argument determines what action is carried out by the
3640 command. The legal <code><em>options</em></code> are:</p></div>
3643 <code><strong>dict create</strong> <em>?key value ...?</em></code>
3644 </dt>
3645 <dd>
3646 <p>
3647 Create and return a new dictionary value that contains each of
3648 the key/value mappings listed as arguments (keys and values
3649 alternating, with each key being followed by its associated
3650 value.)
3651 </p>
3652 </dd>
3654 <code><strong>dict exists</strong> <em>dictionary key ?key ...?</em></code>
3655 </dt>
3656 <dd>
3657 <p>
3658 Returns a boolean value indicating whether the given key (or path
3659 of keys through a set of nested dictionaries) exists in the given
3660 dictionary value. This returns a true value exactly when <a href="#_dict"><strong><code>dict</code></strong></a> <code>get</code>
3661 on that path will succeed.
3662 </p>
3663 </dd>
3665 <code><strong>dict get</strong> <em>dictionary ?key ...?</em></code>
3666 </dt>
3667 <dd>
3668 <p>
3669 Given a dictionary value (first argument) and a key (second argument),
3670 this will retrieve the value for that key. Where several keys are
3671 supplied, the behaviour of the command shall be as if the result
3672 of "<a href="#_dict"><strong><code>dict</code></strong></a> <code>get $dictVal $key</code>" was passed as the first argument to
3673 dict get with the remaining arguments as second (and possibly
3674 subsequent) arguments. This facilitates lookups in nested dictionaries.
3675 If no keys are provided, dict would return a list containing pairs
3676 of elements in a manner similar to array get. That is, the first
3677 element of each pair would be the key and the second element would
3678 be the value for that key. It is an error to attempt to retrieve
3679 a value for a key that is not present in the dictionary.
3680 </p>
3681 </dd>
3683 <code><strong>dict keys</strong> <em>dictionary ?pattern?</em></code>
3684 </dt>
3685 <dd>
3686 <p>
3687 Returns a list of the keys in the dictionary.
3688 If pattern is specified, then only those keys whose
3689 names match <code><em>pattern</em></code> (using the matching rules of string
3690 match) are included.
3691 </p>
3692 </dd>
3694 <code><strong>dict merge</strong> ?<em>dictionary ...</em>?</code>
3695 </dt>
3696 <dd>
3697 <p>
3698 Return a dictionary that contains the contents of each of the
3699 <code><em>dictionary</em></code> arguments. Where two (or more) dictionaries
3700 contain a mapping for the same key, the resulting dictionary
3701 maps that key to the value according to the last dictionary on
3702 the command line containing a mapping for that key.
3703 </p>
3704 </dd>
3706 <code><strong>dict set</strong> <em>dictionaryName key ?key ...? value</em></code>
3707 </dt>
3708 <dd>
3709 <p>
3710 This operation takes the <code><em>name</em></code> of a variable containing a dictionary
3711 value and places an updated dictionary value in that variable
3712 containing a mapping from the given key to the given value. When
3713 multiple keys are present, this operation creates or updates a chain
3714 of nested dictionaries.
3715 </p>
3716 </dd>
3718 <code><strong>dict size</strong> <em>dictionary</em></code>
3719 </dt>
3720 <dd>
3721 <p>
3722 Return the number of key/value mappings in the given dictionary value.
3723 </p>
3724 </dd>
3726 <code><strong>dict unset</strong> <em>dictionaryName key ?key ...? value</em></code>
3727 </dt>
3728 <dd>
3729 <p>
3730 This operation (the companion to <a href="#_dict"><strong><code>dict</code></strong></a> <code>set</code>) takes the name of a
3731 variable containing a dictionary value and places an updated
3732 dictionary value in that variable that does not contain a mapping
3733 for the given key. Where multiple keys are present, this describes
3734 a path through nested dictionaries to the mapping to remove. At
3735 least one key must be specified, but the last key on the key-path
3736 need not exist. All other components on the path must exist.
3737 </p>
3738 </dd>
3740 <code><strong>dict with</strong> <em>dictionaryName key ?key ...? script</em></code>
3741 </dt>
3742 <dd>
3743 <p>
3744 Execute the Tcl script in <code><em>script</em></code> with the value for each
3745 key in <code><em>dictionaryName</em></code> mapped to a variable with the same
3746 name. Where one or more keys are given, these indicate a chain
3747 of nested dictionaries, with the innermost dictionary being the
3748 one opened out for the execution of body. Making <code><em>dictionaryName</em></code>
3749 unreadable will make the updates to the dictionary be discarded,
3750 and this also happens if the contents of <code><em>dictionaryName</em></code> are
3751 adjusted so that the chain of dictionaries no longer exists.
3752 The result of <a href="#_dict"><strong><code>dict</code></strong></a> <code>with</code> is (unless some kind of error occurs)
3753 the result of the evaluation of body.
3754 </p>
3755 </dd>
3758 </dt>
3759 <dd>
3760 <p>
3761 The variables are mapped in the scope enclosing the <a href="#_dict"><strong><code>dict</code></strong></a> <code>with</code>;
3762 it is recommended that this command only be used in a local
3763 scope (procedure). Because of this, the variables set by
3764 <a href="#_dict"><strong><code>dict</code></strong></a> <code>with</code> will continue to exist after the command finishes (unless
3765 explicitly unset). Note that changes to the contents of <code><em>dictionaryName</em></code>
3766 only happen when <code><em>script</em></code> terminates.
3767 </p>
3768 </dd>
3769 </dl></div>
3770 <div class="paragraph"><p><code><strong>dict for, values, incr, append, lappend, update, info, replace</strong></code> to be documented…</p></div>
3771 </div>
3774 <div class="paragraph"><p><code><strong>env</strong> <em>?name? ?default?</em></code></p></div>
3775 <div class="paragraph"><p>If <code><em>name</em></code> is supplied, returns the value of <code><em>name</em></code> from the initial
3776 environment (see getenv(3)). An error is returned if <code><em>name</em></code> does not
3777 exist in the environment, unless <code><em>default</em></code> is supplied - in which case
3778 that value is returned instead.</p></div>
3779 <div class="paragraph"><p>If no arguments are supplied, returns a list of all environment variables
3780 and their values as <code>{name value ...}</code></p></div>
3782 </div>
3787 <div class="paragraph"><p>Returns 1 if an end-of-file condition has occurred on <code><em>fileId</em></code>,
3788 0 otherwise.</p></div>
3789 <div class="paragraph"><p><code><em>fileId</em></code> must have been the return value from a previous call to <a href="#_open"><strong><code>open</code></strong></a>,
3790 or it may be <code>stdin</code>, <code>stdout</code>, or <code>stderr</code> to refer to one of the
3791 standard I/O channels.</p></div>
3792 </div>
3795 <div class="paragraph"><p><code><strong>error</strong> <em>message ?stacktrace?</em></code></p></div>
3796 <div class="paragraph"><p>Returns a <code>JIM_ERR</code> code, which causes command interpretation to be
3797 unwound. <code><em>message</em></code> is a string that is returned to the application
3798 to indicate what went wrong.</p></div>
3799 <div class="paragraph"><p>If the <code><em>stacktrace</em></code> argument is provided and is non-empty,
3800 it is used to initialize the stacktrace.</p></div>
3801 <div class="paragraph"><p>This feature is most useful in conjunction with the <a href="#_catch"><strong><code>catch</code></strong></a> command:
3802 if a caught error cannot be handled successfully, <code><em>stacktrace</em></code> can be used
3803 to return a stack trace reflecting the original point of occurrence
3804 of the error:</p></div>
3807 <pre><code>catch {...} errMsg
3808 ...
3809 error $errMsg [info stacktrace]</code></pre>
3810 </div></div>
3811 <div class="paragraph"><p>See also <code>errorInfo</code>, <a href="#_info"><strong><code>info</code></strong></a> <code>stacktrace</code>, <a href="#_catch"><strong><code>catch</code></strong></a> and <a href="#_return"><strong><code>return</code></strong></a></p></div>
3812 </div>
3815 <div class="paragraph"><p><code><strong>errorInfo</strong> <em>error ?stacktrace?</em></code></p></div>
3816 <div class="paragraph"><p>Returns a human-readable representation of the given error message and stack trace.
3817 Typical usage is:</p></div>
3820 <pre><code>if {[catch {...} error]} {
3821 puts stderr [errorInfo $error [info stacktrace]]
3822 exit 1
3823 }</code></pre>
3824 </div></div>
3825 <div class="paragraph"><p>See also <a href="#_error"><strong><code>error</code></strong></a>.</p></div>
3826 </div>
3830 <div class="paragraph"><p><a href="#_eval"><strong><code>eval</code></strong></a> takes one or more arguments, which together comprise a Tcl
3831 command (or collection of Tcl commands separated by newlines in the
3832 usual way). <a href="#_eval"><strong><code>eval</code></strong></a> concatenates all its arguments in the same
3833 fashion as the <a href="#_concat"><strong><code>concat</code></strong></a> command, passes the concatenated string to the
3834 Tcl interpreter recursively, and returns the result of that
3835 evaluation (or any error generated by it).</p></div>
3836 </div>
3841 of one or more UNIX commands to execute as subprocesses.
3842 The commands take the form of a standard shell pipeline;
3843 <code>|</code> arguments separate commands in the
3844 pipeline and cause standard output of the preceding command
3845 to be piped into standard input of the next command (or <code>|&</code> for
3846 both standard output and standard error).</p></div>
3847 <div class="paragraph"><p>Under normal conditions the result of the <a href="#_exec"><strong><code>exec</code></strong></a> command
3848 consists of the standard output produced by the last command
3849 in the pipeline followed by the standard error output.</p></div>
3851 then this will be included in the result after the standard output
3852 of the last command.</p></div>
3856 are killed or suspended, then <a href="#_exec"><strong><code>exec</code></strong></a> will return an error.
3857 If no standard error output was produced, or is redirected,
3858 the error message will include the normal result, as above,
3859 followed by error messages describing the abnormal terminations.</p></div>
3860 <div class="paragraph"><p>If any standard error output was produced, these abnormal termination
3861 messages are suppressed.</p></div>
3863 is a newline then that character is deleted from the result
3864 or error message for consistency with normal
3865 Tcl return values.</p></div>
3866 <div class="paragraph"><p>An <code><em>arg</em></code> may have one of the following special forms:</p></div>
3869 <code>>filename</code>
3870 </dt>
3871 <dd>
3872 <p>
3873 The standard output of the last command in the pipeline
3874 is redirected to the file. In this situation <a href="#_exec"><strong><code>exec</code></strong></a>
3875 will normally return an empty string.
3876 </p>
3877 </dd>
3879 <code>>>filename</code>
3880 </dt>
3881 <dd>
3882 <p>
3883 As above, but append to the file.
3884 </p>
3885 </dd>
3887 <code>>@fileId</code>
3888 </dt>
3889 <dd>
3890 <p>
3891 The standard output of the last command in the pipeline is
3892 redirected to the given (writable) file descriptor (e.g. stdout,
3893 stderr, or the result of <a href="#_open"><strong><code>open</code></strong></a>). In this situation <a href="#_exec"><strong><code>exec</code></strong></a>
3894 will normally return an empty string.
3895 </p>
3896 </dd>
3898 <code>2>filename</code>
3899 </dt>
3900 <dd>
3901 <p>
3902 The standard error of the last command in the pipeline
3903 is redirected to the file.
3904 </p>
3905 </dd>
3907 <code>2>>filename</code>
3908 </dt>
3909 <dd>
3910 <p>
3911 As above, but append to the file.
3912 </p>
3913 </dd>
3915 <code>2>@fileId</code>
3916 </dt>
3917 <dd>
3918 <p>
3919 The standard error of the last command in the pipeline is
3920 redirected to the given (writable) file descriptor.
3921 </p>
3922 </dd>
3924 <code>2>@1</code>
3925 </dt>
3926 <dd>
3927 <p>
3928 The standard error of the last command in the pipeline is
3929 redirected to the same file descriptor as the standard output.
3930 </p>
3931 </dd>
3933 <code>>&filename</code>
3934 </dt>
3935 <dd>
3936 <p>
3937 Both the standard output and standard error of the last command
3938 in the pipeline is redirected to the file.
3939 </p>
3940 </dd>
3942 <code>>>&filename</code>
3943 </dt>
3944 <dd>
3945 <p>
3946 As above, but append to the file.
3947 </p>
3948 </dd>
3950 <code><filename</code>
3951 </dt>
3952 <dd>
3953 <p>
3954 The standard input of the first command in the pipeline
3955 is taken from the file.
3956 </p>
3957 </dd>
3959 <code><<string</code>
3960 </dt>
3961 <dd>
3962 <p>
3963 The standard input of the first command is taken as the
3964 given immediate value.
3965 </p>
3966 </dd>
3968 <code><@fileId</code>
3969 </dt>
3970 <dd>
3971 <p>
3972 The standard input of the first command in the pipeline
3973 is taken from the given (readable) file descriptor.
3974 </p>
3975 </dd>
3976 </dl></div>
3978 or standard output, these are connected to the corresponding
3979 input or output of the application.</p></div>
3980 <div class="paragraph"><p>If the last <code><em>arg</em></code> is <code>&</code> then the command will be
3981 executed in background.
3982 In this case the standard output from the last command
3983 in the pipeline will
3984 go to the application’s standard output unless
3985 redirected in the command, and error output from all
3986 the commands in the pipeline will go to the application’s
3987 standard error file. The return value of exec in this case
3988 is a list of process ids (pids) in the pipeline.</p></div>
3989 <div class="paragraph"><p>Each <code><em>arg</em></code> becomes one word for a command, except for
3990 <code>|</code>, <code><</code>, <code><<</code>, <code>></code>, and <code>&</code> arguments, and the
3991 arguments that follow <code><</code>, <code><<</code>, and <code>></code>.</p></div>
3993 the directories in the PATH environment variable are searched for
3994 an executable by the given name.</p></div>
3995 <div class="paragraph"><p>No <a href="#_glob"><strong><code>glob</code></strong></a> expansion or other shell-like substitutions
3996 are performed on the arguments to commands.</p></div>
3998 option in <a href="#_catch"><strong><code>catch</code></strong></a>) will be set to a list, as follows:</p></div>
4001 <code><strong>CHILDKILLED</strong> <em>pid sigName msg</em></code>
4002 </dt>
4003 <dd>
4004 <p>
4005 This format is used when a child process has been killed
4006 because of a signal. The pid element will be the process’s
4007 identifier (in decimal). The sigName element will be the
4008 symbolic name of the signal that caused the process to
4009 terminate; it will be one of the names from the include
4010 file signal.h, such as SIGPIPE. The msg element will be a
4011 short human-readable message describing the signal, such
4013 </p>
4014 </dd>
4016 <code><strong>CHILDSUSP</strong> <em>pid sigName msg</em></code>
4017 </dt>
4018 <dd>
4019 <p>
4020 This format is used when a child process has been suspended
4021 because of a signal. The pid element will be the process’s
4022 identifier, in decimal. The sigName element will be the
4023 symbolic name of the signal that caused the process to
4024 suspend; this will be one of the names from the include
4025 file signal.h, such as SIGTTIN. The msg element will be a
4026 short human-readable message describing the signal, such
4028 </p>
4029 </dd>
4031 <code><strong>CHILDSTATUS</strong> <em>pid code</em></code>
4032 </dt>
4033 <dd>
4034 <p>
4035 This format is used when a child process has exited with a
4036 non-zero exit status. The pid element will be the process’s
4037 identifier (in decimal) and the code element will be the
4038 exit code returned by the process (also in decimal).
4039 </p>
4040 </dd>
4041 </dl></div>
4043 this variable is unset, in which case the original environment is used).</p></div>
4044 </div>
4047 <div class="paragraph"><p><code><strong>exists ?-var|-proc|-command|-alias?</strong> <em>name</em></code></p></div>
4049 or alias respectively and returns 1 if it exists or 0 if not. This command
4050 provides a more simplified/convenient version of <a href="#_info"><strong><code>info</code></strong></a> <code>exists</code>,
4051 <a href="#_info"><strong><code>info</code></strong></a> <code>procs</code> and <a href="#_info"><strong><code>info</code></strong></a> <code>commands</code>.</p></div>
4052 <div class="paragraph"><p>If the type is omitted, a type of <em>-var</em> is used. The type may be abbreviated.</p></div>
4053 </div>
4057 <div class="paragraph"><p>Terminate the process, returning <code><em>returnCode</em></code> to the
4058 parent as the exit status.</p></div>
4059 <div class="paragraph"><p>If <code><em>returnCode</em></code> isn’t specified then it defaults
4060 to 0.</p></div>
4061 <div class="paragraph"><p>Note that exit can be caught with <a href="#_catch"><strong><code>catch</code></strong></a>.</p></div>
4062 </div>
4066 <div class="paragraph"><p>Calls the expression processor to evaluate <code><em>arg</em></code>, and returns
4067 the result as a string. See the section EXPRESSIONS above.</p></div>
4068 <div class="paragraph"><p>Note that Jim supports a shorthand syntax for <a href="#_expr"><strong><code>expr</code></strong></a> as <code>$(...)</code>
4069 The following two are identical.</p></div>
4072 <pre><code>set x [expr {3 * 2 + 1}]
4073 set x $(3 * 2 + 1)</code></pre>
4074 </div></div>
4075 </div>
4078 <div class="paragraph"><p><code><strong>file</strong> <em>option name ?arg...?</em></code></p></div>
4079 <div class="paragraph"><p>Operate on a file or a file name. <code><em>name</em></code> is the name of a file.</p></div>
4080 <div class="paragraph"><p><code><em>option</em></code> indicates what to do with the file name. Any unique
4081 abbreviation for <code><em>option</em></code> is acceptable. The valid options are:</p></div>
4084 <code><strong>file atime</strong> <em>name</em></code>
4085 </dt>
4086 <dd>
4087 <p>
4088 Return a decimal string giving the time at which file <code><em>name</em></code>
4089 was last accessed. The time is measured in the standard UNIX
4090 fashion as seconds from a fixed starting time (often January 1, 1970).
4091 If the file doesn’t exist or its access time cannot be queried then an
4092 error is generated.
4093 </p>
4094 </dd>
4096 <code><strong>file copy ?-force?</strong> <em>source target</em></code>
4097 </dt>
4098 <dd>
4099 <p>
4100 Copies file <code><em>source</em></code> to file <code><em>target</em></code>. The source file must exist.
4101 The target file must not exist, unless <code>-force</code> is specified.
4102 </p>
4103 </dd>
4105 <code><strong>file delete ?-force? ?--?</strong> <em>name...</em></code>
4106 </dt>
4107 <dd>
4108 <p>
4109 Deletes file or directory <code><em>name</em></code>. If the file or directory doesn’t exist, nothing happens.
4110 If it can’t be deleted, an error is generated. Non-empty directories will not be deleted
4111 unless the <code>-force</code> options is given. In this case no errors will be generated, even
4112 if the file/directory can’t be deleted. Use <code><em>--</em></code> if there is any possibility of
4113 the first name being <code><em>-force</em></code>.
4114 </p>
4115 </dd>
4117 <code><strong>file dirname</strong> <em>name</em></code>
4118 </dt>
4119 <dd>
4120 <p>
4121 Return all of the characters in <code><em>name</em></code> up to but not including
4122 the last slash character. If there are no slashes in <code><em>name</em></code>
4123 then return <code>.</code> (a single dot). If the last slash in <code><em>name</em></code> is its first
4124 character, then return <code>/</code>.
4125 </p>
4126 </dd>
4128 <code><strong>file executable</strong> <em>name</em></code>
4129 </dt>
4130 <dd>
4131 <p>
4132 Return <em>1</em> if file <code><em>name</em></code> is executable by
4133 the current user, <em>0</em> otherwise.
4134 </p>
4135 </dd>
4137 <code><strong>file exists</strong> <em>name</em></code>
4138 </dt>
4139 <dd>
4140 <p>
4141 Return <em>1</em> if file <code><em>name</em></code> exists and the current user has
4142 search privileges for the directories leading to it, <em>0</em> otherwise.
4143 </p>
4144 </dd>
4146 <code><strong>file extension</strong> <em>name</em></code>
4147 </dt>
4148 <dd>
4149 <p>
4150 Return all of the characters in <code><em>name</em></code> after and including the
4151 last dot in <code><em>name</em></code>. If there is no dot in <code><em>name</em></code> then return
4152 the empty string.
4153 </p>
4154 </dd>
4156 <code><strong>file isdirectory</strong> <em>name</em></code>
4157 </dt>
4158 <dd>
4159 <p>
4160 Return <em>1</em> if file <code><em>name</em></code> is a directory,
4161 <em>0</em> otherwise.
4162 </p>
4163 </dd>
4165 <code><strong>file isfile</strong> <em>name</em></code>
4166 </dt>
4167 <dd>
4168 <p>
4169 Return <em>1</em> if file <code><em>name</em></code> is a regular file,
4170 <em>0</em> otherwise.
4171 </p>
4172 </dd>
4174 <code><strong>file join</strong> <em>arg...</em></code>
4175 </dt>
4176 <dd>
4177 <p>
4178 Joins multiple path components. Note that if any components is
4179 an absolute path, the preceding components are ignored.
4180 Thus <code>"<a href="#_file"><strong><code>file</code></strong></a> join /tmp /root"</code> returns <code>"/root"</code>.
4181 </p>
4182 </dd>
4184 <code><strong>file link</strong> ?<strong>-hard|-symbolic</strong>? <em>newname target</em></code>
4185 </dt>
4186 <dd>
4187 <p>
4188 Creates a hard link (default) or symbolic link from <code><em>newname</em></code> to <code><em>target</em></code>.
4189 Note that the sense of this command is the opposite of <a href="#_file"><strong><code>file</code></strong></a> <code>rename</code> and <a href="#_file"><strong><code>file</code></strong></a> <code>copy</code>
4190 and also of <code>ln</code>, but this is compatible with Tcl.
4191 An error is returned if <code><em>target</em></code> doesn’t exist or <code><em>newname</em></code> already exists.
4192 </p>
4193 </dd>
4195 <code><strong>file lstat</strong> <em>name varName</em></code>
4196 </dt>
4197 <dd>
4198 <p>
4199 Same as <em>stat</em> option (see below) except uses the <code><em>lstat</em></code>
4200 kernel call instead of <code><em>stat</em></code>. This means that if <code><em>name</em></code>
4201 refers to a symbolic link the information returned in <code><em>varName</em></code>
4202 is for the link rather than the file it refers to. On systems that
4203 don’t support symbolic links this option behaves exactly the same
4204 as the <em>stat</em> option.
4205 </p>
4206 </dd>
4208 <code><strong>file mkdir</strong> <em>dir1 ?dir2...?</em></code>
4209 </dt>
4210 <dd>
4211 <p>
4212 Creates each directory specified. For each pathname <code><em>dir</em></code> specified,
4213 this command will create all non-existing parent directories
4214 as well as <code><em>dir</em></code> itself. If an existing directory is specified,
4215 then no action is taken and no error is returned. Trying to
4216 overwrite an existing file with a directory will result in an
4217 error. Arguments are processed in the order specified, halting
4218 at the first error, if any.
4219 </p>
4220 </dd>
4222 <code><strong>file mtime</strong> <em>name ?time?</em></code>
4223 </dt>
4224 <dd>
4225 <p>
4226 Return a decimal string giving the time at which file <code><em>name</em></code>
4227 was last modified. The time is measured in the standard UNIX
4228 fashion as seconds from a fixed starting time (often January 1, 1970).
4229 If the file doesn’t exist or its modified time cannot be queried then an
4230 error is generated. If <code><em>time</em></code> is given, sets the modification time
4231 of the file to the given value.
4232 </p>
4233 </dd>
4235 <code><strong>file normalize</strong> <em>name</em></code>
4236 </dt>
4237 <dd>
4238 <p>
4239 Return the normalized path of <code><em>name</em></code>. See <em>realpath(3)</em>.
4240 </p>
4241 </dd>
4243 <code><strong>file owned</strong> <em>name</em></code>
4244 </dt>
4245 <dd>
4246 <p>
4247 Return <em>1</em> if file <code><em>name</em></code> is owned by the current user,
4248 <em>0</em> otherwise.
4249 </p>
4250 </dd>
4252 <code><strong>file readable</strong> <em>name</em></code>
4253 </dt>
4254 <dd>
4255 <p>
4256 Return <em>1</em> if file <code><em>name</em></code> is readable by
4257 the current user, <em>0</em> otherwise.
4258 </p>
4259 </dd>
4261 <code><strong>file readlink</strong> <em>name</em></code>
4262 </dt>
4263 <dd>
4264 <p>
4265 Returns the value of the symbolic link given by <code><em>name</em></code> (i.e. the
4266 name of the file it points to). If
4267 <code><em>name</em></code> isn’t a symbolic link or its value cannot be read, then
4268 an error is returned. On systems that don’t support symbolic links
4269 this option is undefined.
4270 </p>
4271 </dd>
4273 <code><strong>file rename</strong> ?<strong>-force</strong>? <em>oldname</em> <em>newname</em></code>
4274 </dt>
4275 <dd>
4276 <p>
4277 Renames the file from the old name to the new name.
4278 If <code><em>newname</em></code> already exists, an error is returned unless <code><em>-force</em></code> is
4279 specified.
4280 </p>
4281 </dd>
4283 <code><strong>file rootname</strong> <em>name</em></code>
4284 </dt>
4285 <dd>
4286 <p>
4287 Return all of the characters in <code><em>name</em></code> up to but not including
4288 the last <em>.</em> character in the name. If <code><em>name</em></code> doesn’t contain
4289 a dot, then return <code><em>name</em></code>.
4290 </p>
4291 </dd>
4293 <code><strong>file size</strong> <em>name</em></code>
4294 </dt>
4295 <dd>
4296 <p>
4297 Return a decimal string giving the size of file <code><em>name</em></code> in bytes.
4298 If the file doesn’t exist or its size cannot be queried then an
4299 error is generated.
4300 </p>
4301 </dd>
4303 <code><strong>file stat</strong> <em>name ?varName?</em></code>
4304 </dt>
4305 <dd>
4306 <p>
4307 Invoke the <em>stat</em> kernel call on <code><em>name</em></code>, and return the result
4308 as a dictionary with the following keys: <em>atime</em>,
4309 <em>ctime</em>, <em>dev</em>, <em>gid</em>, <em>ino</em>, <em>mode</em>, <em>mtime</em>,
4310 <em>nlink</em>, <em>size</em>, <em>type</em>, <em>uid</em>.
4311 Each element except <em>type</em> is a decimal string with the value of
4312 the corresponding field from the <em>stat</em> return structure; see the
4313 manual entry for <em>stat</em> for details on the meanings of the values.
4314 The <em>type</em> element gives the type of the file in the same form
4315 returned by the command <a href="#_file"><strong><code>file</code></strong></a> <code>type</code>.
4316 If <code><em>varName</em></code> is specified, it is taken to be the name of an array
4317 variable and the values are also stored into the array.
4318 </p>
4319 </dd>
4321 <code><strong>file tail</strong> <em>name</em></code>
4322 </dt>
4323 <dd>
4324 <p>
4325 Return all of the characters in <code><em>name</em></code> after the last slash.
4326 If <code><em>name</em></code> contains no slashes then return <code><em>name</em></code>.
4327 </p>
4328 </dd>
4330 <code><strong>file tempfile</strong> <em>?template?</em></code>
4331 </dt>
4332 <dd>
4333 <p>
4334 Creates and returns the name of a unique temporary file. If <code><em>template</em></code> is omitted, a
4335 default template will be used to place the file in /tmp. See <em>mkstemp(3)</em> for
4336 the format of the template and security concerns.
4337 </p>
4338 </dd>
4340 <code><strong>file type</strong> <em>name</em></code>
4341 </dt>
4342 <dd>
4343 <p>
4344 Returns a string giving the type of file <code><em>name</em></code>, which will be
4345 one of <code>file</code>, <code>directory</code>, <code>characterSpecial</code>,
4346 <code>blockSpecial</code>, <code>fifo</code>, <code>link</code>, or <code>socket</code>.
4347 </p>
4348 </dd>
4350 <code><strong>file writable</strong> <em>name</em></code>
4351 </dt>
4352 <dd>
4353 <p>
4354 Return <em>1</em> if file <code><em>name</em></code> is writable by
4355 the current user, <em>0</em> otherwise.
4356 </p>
4357 </dd>
4358 </dl></div>
4359 <div class="paragraph"><p>The <a href="#_file"><strong><code>file</code></strong></a> commands that return 0/1 results are often used in
4360 conditional or looping commands, for example:</p></div>
4363 <pre><code>if {![file exists foo]} {
4364 error {bad file name}
4365 } else {
4366 ...
4367 }</code></pre>
4368 </div></div>
4369 </div>
4372 <div class="paragraph"><p><code><strong>finalize</strong> <em>reference ?command?</em></code></p></div>
4373 <div class="paragraph"><p>If <code><em>command</em></code> is omitted, returns the finalizer command for the given reference.</p></div>
4374 <div class="paragraph"><p>Otherwise, sets a new finalizer command for the given reference. <code><em>command</em></code> may be
4375 the empty string to remove the current finalizer.</p></div>
4376 <div class="paragraph"><p>The reference must be a valid reference create with the <a href="#_ref"><strong><code>ref</code></strong></a>
4377 command.</p></div>
4378 <div class="paragraph"><p>See GARBAGE COLLECTION, REFERENCES, LAMBDA FUNCTION for more detail.</p></div>
4379 </div>
4384 <div class="paragraph"><p>Flushes any output that has been buffered for <code><em>fileId</em></code>. <code><em>fileId</em></code> must
4385 have been the return value from a previous call to <a href="#_open"><strong><code>open</code></strong></a>, or it may be
4386 <code>stdout</code> or <code>stderr</code> to access one of the standard I/O streams; it must
4387 refer to a file that was opened for writing. This command returns an
4388 empty string.</p></div>
4389 </div>
4392 <div class="paragraph"><p><code><strong>for</strong> <em>start test next body</em></code></p></div>
4393 <div class="paragraph"><p><a href="#_for"><strong><code>for</code></strong></a> is a looping command, similar in structure to the C <a href="#_for"><strong><code>for</code></strong></a> statement.
4394 The <code><em>start</em></code>, <code><em>next</em></code>, and <code><em>body</em></code> arguments must be Tcl command strings,
4395 and <code><em>test</em></code> is an expression string.</p></div>
4396 <div class="paragraph"><p>The <a href="#_for"><strong><code>for</code></strong></a> command first invokes the Tcl interpreter to execute <code><em>start</em></code>.
4397 Then it repeatedly evaluates <code><em>test</em></code> as an expression; if the result is
4398 non-zero it invokes the Tcl interpreter on <code><em>body</em></code>, then invokes the Tcl
4399 interpreter on <code><em>next</em></code>, then repeats the loop. The command terminates
4400 when <code><em>test</em></code> evaluates to 0.</p></div>
4401 <div class="paragraph"><p>If a <a href="#_continue"><strong><code>continue</code></strong></a> command is invoked within <code><em>body</em></code> then any remaining
4402 commands in the current execution of <code><em>body</em></code> are skipped; processing
4403 continues by invoking the Tcl interpreter on <code><em>next</em></code>, then evaluating
4404 <code><em>test</em></code>, and so on.</p></div>
4405 <div class="paragraph"><p>If a <a href="#_break"><strong><code>break</code></strong></a> command is invoked within <code><em>body</em></code> or <code><em>next</em></code>, then the <a href="#_for"><strong><code>for</code></strong></a>
4406 command will return immediately.</p></div>
4407 <div class="paragraph"><p>The operation of <a href="#_break"><strong><code>break</code></strong></a> and <a href="#_continue"><strong><code>continue</code></strong></a> are similar to the corresponding
4408 statements in C.</p></div>
4409 <div class="paragraph"><p><a href="#_for"><strong><code>for</code></strong></a> returns an empty string.</p></div>
4410 </div>
4413 <div class="paragraph"><p><code><strong>foreach</strong> <em>varName list body</em></code></p></div>
4414 <div class="paragraph"><p><code><strong>foreach</strong> <em>varList list ?varList2 list2 ...? body</em></code></p></div>
4415 <div class="paragraph"><p>In this command, <code><em>varName</em></code> is the name of a variable, <code><em>list</em></code>
4416 is a list of values to assign to <code><em>varName</em></code>, and <code><em>body</em></code> is a
4417 collection of Tcl commands.</p></div>
4418 <div class="paragraph"><p>For each field in <code><em>list</em></code> (in order from left to right), <a href="#_foreach"><strong><code>foreach</code></strong></a> assigns
4419 the contents of the field to <code><em>varName</em></code> (as if the <a href="#_lindex"><strong><code>lindex</code></strong></a> command
4420 had been used to extract the field), then calls the Tcl interpreter to
4421 execute <code><em>body</em></code>.</p></div>
4422 <div class="paragraph"><p>If instead of being a simple name, <code><em>varList</em></code> is used, multiple assignments
4423 are made each time through the loop, one for each element of <code><em>varList</em></code>.</p></div>
4424 <div class="paragraph"><p>For example, if there are two elements in <code><em>varList</em></code> and six elements in
4425 the list, the loop will be executed three times.</p></div>
4426 <div class="paragraph"><p>If the length of the list doesn’t evenly divide by the number of elements
4427 in <code><em>varList</em></code>, the value of the remaining variables in the last iteration
4428 of the loop are undefined.</p></div>
4429 <div class="paragraph"><p>The <a href="#_break"><strong><code>break</code></strong></a> and <a href="#_continue"><strong><code>continue</code></strong></a> statements may be invoked inside <code><em>body</em></code>,
4430 with the same effect as in the <a href="#_for"><strong><code>for</code></strong></a> command.</p></div>
4431 <div class="paragraph"><p><a href="#_foreach"><strong><code>foreach</code></strong></a> returns an empty string.</p></div>
4432 </div>
4435 <div class="paragraph"><p><code><strong>format</strong> <em>formatString ?arg ...?</em></code></p></div>
4437 C <em>sprintf</em> procedure (it uses <em>sprintf</em> in its
4438 implementation). <code><em>formatString</em></code> indicates how to format
4439 the result, using <code>%</code> fields as in <em>sprintf</em>, and the additional
4440 arguments, if any, provide values to be substituted into the result.</p></div>
4441 <div class="paragraph"><p>All of the <em>sprintf</em> options are valid; see the <em>sprintf</em>
4442 man page for details. Each <code><em>arg</em></code> must match the expected type
4443 from the <code>%</code> field in <code><em>formatString</em></code>; the <a href="#_format"><strong><code>format</code></strong></a> command
4444 converts each argument to the correct type (floating, integer, etc.)
4445 before passing it to <em>sprintf</em> for formatting.</p></div>
4446 <div class="paragraph"><p>The only unusual conversion is for <code>%c</code>; in this case the argument
4447 must be a decimal string, which will then be converted to the corresponding
4448 ASCII (or UTF-8) character value.</p></div>
4449 <div class="paragraph"><p>In addition, Jim Tcl provides basic support for conversion to binary with <code>%b</code>.</p></div>
4450 <div class="paragraph"><p><a href="#_format"><strong><code>format</code></strong></a> does backslash substitution on its <code><em>formatString</em></code>
4451 argument, so backslash sequences in <code><em>formatString</em></code> will be handled
4452 correctly even if the argument is in braces.</p></div>
4453 <div class="paragraph"><p>The return value from <a href="#_format"><strong><code>format</code></strong></a> is the formatted string.</p></div>
4454 </div>
4458 <div class="paragraph"><p>Returns the string associated with <code><em>reference</em></code>. The reference must
4459 be a valid reference create with the <a href="#_ref"><strong><code>ref</code></strong></a> command.</p></div>
4460 <div class="paragraph"><p>See GARBAGE COLLECTION, REFERENCES, LAMBDA FUNCTION for more detail.</p></div>
4461 </div>
4464 <div class="paragraph"><p><code><strong>gets</strong> <em>fileId ?varName?</em></code></p></div>
4465 <div class="paragraph"><p><code><em>fileId</em> <strong>gets</strong> <em>?varName?</em></code></p></div>
4466 <div class="paragraph"><p>Reads the next line from the file given by <code><em>fileId</em></code> and discards
4467 the terminating newline character.</p></div>
4468 <div class="paragraph"><p>If <code><em>varName</em></code> is specified, then the line is placed in the variable
4469 by that name and the return value is a count of the number of characters
4470 read (not including the newline).</p></div>
4472 any characters then -1 is returned and <code><em>varName</em></code> is set to an
4473 empty string.</p></div>
4474 <div class="paragraph"><p>If <code><em>varName</em></code> is not specified then the return value will be
4475 the line (minus the newline character) or an empty string if
4476 the end of the file is reached before reading any characters.</p></div>
4477 <div class="paragraph"><p>An empty string will also be returned if a line contains no characters
4478 except the newline, so <a href="#_eof"><strong><code>eof</code></strong></a> may have to be used to determine
4479 what really happened.</p></div>
4481 <a href="#_gets"><strong><code>gets</code></strong></a> behaves as if there were an additional newline character
4482 at the end of the file.</p></div>
4483 <div class="paragraph"><p><code><em>fileId</em></code> must be <code>stdin</code> or the return value from a previous
4484 call to <a href="#_open"><strong><code>open</code></strong></a>; it must refer to a file that was opened
4485 for reading.</p></div>
4486 </div>
4489 <div class="paragraph"><p><code><strong>glob</strong> ?<strong>-nocomplain</strong>? ?<strong>-directory</strong> <em>dir</em>? ?<strong>-tails</strong>? ?<strong>--</strong>? <em>pattern ?pattern ...?</em></code></p></div>
4490 <div class="paragraph"><p>This command performs filename globbing, using csh rules. The returned
4491 value from <a href="#_glob"><strong><code>glob</code></strong></a> is the list of expanded filenames.</p></div>
4492 <div class="paragraph"><p>If <code>-nocomplain</code> is specified as the first argument then an empty
4493 list may be returned; otherwise an error is returned if the expanded
4494 list is empty. The <code>-nocomplain</code> argument must be provided
4495 exactly: an abbreviation will not be accepted.</p></div>
4496 <div class="paragraph"><p>If <code>-directory</code> is given, the <code><em>dir</em></code> is understood to contain a
4497 directory name to search in. This allows globbing inside directories
4498 whose names may contain glob-sensitive characters. The returned names
4499 include the directory name unless <code><em>-tails</em></code> is specified.</p></div>
4500 <div class="paragraph"><p>If <code><em>-tails</em></code> is specified, along with <code>-directory</code>, the returned names
4501 are relative to the given directory.</p></div>
4502 </div>
4505 <div class="paragraph"><p><code><strong>global</strong> <em>varName ?varName ...?</em></code></p></div>
4507 If so, then it declares each given <code><em>varName</em></code> to be a global variable
4508 rather than a local one. For the duration of the current procedure
4509 (and only while executing in the current procedure), any reference to
4510 <code><em>varName</em></code> will be bound to a global variable instead
4511 of a local one.</p></div>
4512 <div class="paragraph"><p>An alternative to using <a href="#_global"><strong><code>global</code></strong></a> is to use the <code>::</code> prefix
4513 to explicitly name a variable in the global scope.</p></div>
4514 </div>
4517 <div class="paragraph"><p><code><strong>if</strong> <em>expr1</em> ?<strong>then</strong>? <em>body1</em> <strong>elseif</strong> <em>expr2</em> ?<strong>then</strong>? <em>body2</em> <strong>elseif</strong> ... ?<strong>else</strong>? ?<em>bodyN</em>?</code></p></div>
4518 <div class="paragraph"><p>The <a href="#_if"><strong><code>if</code></strong></a> command evaluates <code><em>expr1</em></code> as an expression (in the same way
4519 that <a href="#_expr"><strong><code>expr</code></strong></a> evaluates its argument). The value of the expression must
4520 be numeric; if it is non-zero then <code><em>body1</em></code> is executed by passing it to
4521 the Tcl interpreter.</p></div>
4522 <div class="paragraph"><p>Otherwise <code><em>expr2</em></code> is evaluated as an expression and if it is non-zero
4523 then <code><em>body2</em></code> is executed, and so on.</p></div>
4524 <div class="paragraph"><p>If none of the expressions evaluates to non-zero then <code><em>bodyN</em></code> is executed.</p></div>
4525 <div class="paragraph"><p>The <code>then</code> and <code>else</code> arguments are optional "noise words" to make the
4526 command easier to read.</p></div>
4527 <div class="paragraph"><p>There may be any number of <code>elseif</code> clauses, including zero. <code><em>bodyN</em></code>
4528 may also be omitted as long as <code>else</code> is omitted too.</p></div>
4529 <div class="paragraph"><p>The return value from the command is the result of the body script that
4530 was executed, or an empty string if none of the expressions was non-zero
4531 and there was no <code><em>bodyN</em></code>.</p></div>
4532 </div>
4535 <div class="paragraph"><p><code><strong>incr</strong> <em>varName ?increment?</em></code></p></div>
4536 <div class="paragraph"><p>Increment the value stored in the variable whose name is <code><em>varName</em></code>.
4537 The value of the variable must be integral.</p></div>
4538 <div class="paragraph"><p>If <code><em>increment</em></code> is supplied then its value (which must be an
4539 integer) is added to the value of variable <code><em>varName</em></code>; otherwise
4540 1 is added to <code><em>varName</em></code>.</p></div>
4541 <div class="paragraph"><p>The new value is stored as a decimal string in variable <code><em>varName</em></code>
4542 and also returned as result.</p></div>
4544 and set to <code>0</code> first.</p></div>
4545 </div>
4550 <code><strong>info</strong> <em>option ?arg...?</em></code>
4551 </dt>
4552 <dd>
4553 <p>
4554 Provide information about various internals to the Tcl interpreter.
4555 The legal <code><em>option</em></code>'s (which may be abbreviated) are:
4556 </p>
4557 </dd>
4559 <code><strong>info args</strong> <em>procname</em></code>
4560 </dt>
4561 <dd>
4562 <p>
4563 Returns a list containing the names of the arguments to procedure
4564 <code><em>procname</em></code>, in order. <code><em>procname</em></code> must be the name of a
4565 Tcl command procedure.
4566 </p>
4567 </dd>
4569 <code><strong>info alias</strong> <em>command</em></code>
4570 </dt>
4571 <dd>
4572 <p>
4573 <code><em>command</em></code> must be an alias created with <a href="#_alias"><strong><code>alias</code></strong></a>. In which case the target
4574 command and arguments, as passed to <a href="#_alias"><strong><code>alias</code></strong></a> are returned. See <a href="#_exists"><strong><code>exists</code></strong></a> <code>-alias</code>
4575 </p>
4576 </dd>
4578 <code><strong>info body</strong> <em>procname</em></code>
4579 </dt>
4580 <dd>
4581 <p>
4582 Returns the body of procedure <code><em>procname</em></code>. <code><em>procname</em></code> must be
4583 the name of a Tcl command procedure.
4584 </p>
4585 </dd>
4587 <code><strong>info channels</strong></code>
4588 </dt>
4589 <dd>
4590 <p>
4591 Returns a list of all open file handles from <a href="#_open"><strong><code>open</code></strong></a> or <a href="#_socket"><strong><code>socket</code></strong></a>
4592 </p>
4593 </dd>
4595 <code><strong>info commands</strong> ?<em>pattern</em>?</code>
4596 </dt>
4597 <dd>
4598 <p>
4599 If <code><em>pattern</em></code> isn’t specified, returns a list of names of all the
4600 Tcl commands, including both the built-in commands written in C and
4601 the command procedures defined using the <a href="#_proc"><strong><code>proc</code></strong></a> command.
4602 If <code><em>pattern</em></code> is specified, only those names matching <code><em>pattern</em></code>
4603 are returned. Matching is determined using the same rules as for
4605 </p>
4606 </dd>
4608 <code><strong>info complete</strong> <em>command</em> ?<em>missing</em>?</code>
4609 </dt>
4610 <dd>
4611 <p>
4612 Returns 1 if <code><em>command</em></code> is a complete Tcl command in the sense of
4613 having no unclosed quotes, braces, brackets or array element names,
4614 If the command doesn’t appear to be complete then 0 is returned.
4615 This command is typically used in line-oriented input environments
4616 to allow users to type in commands that span multiple lines; if the
4617 command isn’t complete, the script can delay evaluating it until additional
4618 lines have been typed to complete the command. If <code><em>varName</em></code> is specified, the
4619 missing character is stored in the variable with that name.
4620 </p>
4621 </dd>
4623 <code><strong>info exists</strong> <em>varName</em></code>
4624 </dt>
4625 <dd>
4626 <p>
4627 Returns <em>1</em> if the variable named <code><em>varName</em></code> exists in the
4628 current context (either as a global or local variable), returns <em>0</em>
4629 otherwise.
4630 </p>
4631 </dd>
4633 <code><strong>info frame</strong> ?<em>number</em>?</code>
4634 </dt>
4635 <dd>
4636 <p>
4637 If <code><em>number</em></code> is not specified, this command returns a number
4638 which is the same result as <a href="#_info"><strong><code>info</code></strong></a> <code>level</code> - the current stack frame level.
4639 If <code><em>number</em></code> is specified, then the result is a list consisting of the procedure,
4640 filename and line number for the procedure call at level <code><em>number</em></code> on the stack.
4641 If <code><em>number</em></code> is positive then it selects a particular stack level (1 refers
4642 to the top-most active procedure, 2 to the procedure it called, and
4643 so on); otherwise it gives a level relative to the current level
4644 (0 refers to the current procedure, -1 to its caller, and so on).
4645 The level has an identical meaning to <a href="#_info"><strong><code>info</code></strong></a> <code>level</code>.
4646 </p>
4647 </dd>
4649 <code><strong>info globals</strong> ?<em>pattern</em>?</code>
4650 </dt>
4651 <dd>
4652 <p>
4653 If <code><em>pattern</em></code> isn’t specified, returns a list of all the names
4654 of currently-defined global variables.
4655 If <code><em>pattern</em></code> is specified, only those names matching <code><em>pattern</em></code>
4656 are returned. Matching is determined using the same rules as for
4658 </p>
4659 </dd>
4661 <code><strong>info hostname</strong></code>
4662 </dt>
4663 <dd>
4664 <p>
4665 An alias for <a href="#cmd_1"><strong><code>os.gethostname</code></strong></a> for compatibility with Tcl 6.x
4666 </p>
4667 </dd>
4669 <code><strong>info level</strong> ?<em>number</em>?</code>
4670 </dt>
4671 <dd>
4672 <p>
4673 If <code><em>number</em></code> is not specified, this command returns a number
4674 giving the stack level of the invoking procedure, or 0 if the
4675 command is invoked at top-level. If <code><em>number</em></code> is specified,
4676 then the result is a list consisting of the name and arguments for the
4677 procedure call at level <code><em>number</em></code> on the stack. If <code><em>number</em></code>
4678 is positive then it selects a particular stack level (1 refers
4679 to the top-most active procedure, 2 to the procedure it called, and
4680 so on); otherwise it gives a level relative to the current level
4681 (0 refers to the current procedure, -1 to its caller, and so on).
4682 See the <a href="#_uplevel"><strong><code>uplevel</code></strong></a> command for more information on what stack
4683 levels mean.
4684 </p>
4685 </dd>
4687 <code><strong>info locals</strong> ?<em>pattern</em>?</code>
4688 </dt>
4689 <dd>
4690 <p>
4691 If <code><em>pattern</em></code> isn’t specified, returns a list of all the names
4692 of currently-defined local variables, including arguments to the
4693 current procedure, if any. Variables defined with the <a href="#_global"><strong><code>global</code></strong></a>
4694 and <a href="#_upvar"><strong><code>upvar</code></strong></a> commands will not be returned. If <code><em>pattern</em></code> is
4695 specified, only those names matching <code><em>pattern</em></code> are returned.
4696 Matching is determined using the same rules as for <a href="#_string"><strong><code>string</code></strong></a> <code>match</code>.
4697 </p>
4698 </dd>
4700 <code><strong>info nameofexecutable</strong></code>
4701 </dt>
4702 <dd>
4703 <p>
4704 Returns the name of the binary file from which the application
4705 was invoked. A full path will be returned, unless the path
4706 can’t be determined, in which case the empty string will be returned.
4707 </p>
4708 </dd>
4710 <code><strong>info procs</strong> ?<em>pattern</em>?</code>
4711 </dt>
4712 <dd>
4713 <p>
4714 If <code><em>pattern</em></code> isn’t specified, returns a list of all the
4715 names of Tcl command procedures.
4716 If <code><em>pattern</em></code> is specified, only those names matching <code><em>pattern</em></code>
4717 are returned. Matching is determined using the same rules as for
4719 </p>
4720 </dd>
4722 <code><strong>info references</strong></code>
4723 </dt>
4724 <dd>
4725 <p>
4726 Returns a list of all references which have not yet been garbage
4727 collected.
4728 </p>
4729 </dd>
4731 <code><strong>info returncodes</strong> ?<em>code</em>?</code>
4732 </dt>
4733 <dd>
4734 <p>
4735 Returns a list representing the mapping of standard return codes
4736 to names. e.g. <code>{0 ok 1 error 2 return ...}</code>. If a code is given,
4737 instead returns the name for the given code.
4738 </p>
4739 </dd>
4741 <code><strong>info script</strong></code>
4742 </dt>
4743 <dd>
4744 <p>
4745 If a Tcl script file is currently being evaluated (i.e. there is a
4746 call to <em>Jim_EvalFile</em> active or there is an active invocation
4747 of the <a href="#_source"><strong><code>source</code></strong></a> command), then this command returns the name
4748 of the innermost file being processed. Otherwise the command returns an
4749 empty string.
4750 </p>
4751 </dd>
4753 <code><strong>info source</strong> <em>script ?filename line?</em></code>
4754 </dt>
4755 <dd>
4756 <p>
4757 With a single argument, returns the original source location of the given script as a list of
4758 <code>{filename linenumber}</code>. If the source location can’t be determined, the
4759 list <code>{{} 0}</code> is returned. If <code><em>filename</em></code> and <code><em>line</em></code> are given, returns a copy
4760 of <code><em>script</em></code> with the associate source information. This can be useful to produce
4761 useful messages from <a href="#_eval"><strong><code>eval</code></strong></a>, etc. if the original source information may be lost.
4762 </p>
4763 </dd>
4765 <code><strong>info stacktrace</strong></code>
4766 </dt>
4767 <dd>
4768 <p>
4769 After an error is caught with <a href="#_catch"><strong><code>catch</code></strong></a>, returns the stack trace as a list
4770 of <code>{procedure filename line ...}</code>.
4771 </p>
4772 </dd>
4774 <code><strong>info statics</strong> <em>procname</em></code>
4775 </dt>
4776 <dd>
4777 <p>
4778 Returns a dictionary of the static variables of procedure
4779 <code><em>procname</em></code>. <code><em>procname</em></code> must be the name of a Tcl command
4780 procedure. An empty dictionary is returned if the procedure has
4781 no static variables.
4782 </p>
4783 </dd>
4785 <code><strong>info version</strong></code>
4786 </dt>
4787 <dd>
4788 <p>
4789 Returns the version number for this version of Jim in the form <code><strong>x.yy</strong></code>.
4790 </p>
4791 </dd>
4793 <code><strong>info vars</strong> ?<em>pattern</em>?</code>
4794 </dt>
4795 <dd>
4796 <p>
4797 If <code><em>pattern</em></code> isn’t specified,
4798 returns a list of all the names of currently-visible variables, including
4799 both locals and currently-visible globals.
4800 If <code><em>pattern</em></code> is specified, only those names matching <code><em>pattern</em></code>
4801 are returned. Matching is determined using the same rules as for
4803 </p>
4804 </dd>
4805 </dl></div>
4806 </div>
4809 <div class="paragraph"><p><code><strong>join</strong> <em>list ?joinString?</em></code></p></div>
4810 <div class="paragraph"><p>The <code><em>list</em></code> argument must be a valid Tcl list. This command returns the
4811 string formed by joining all of the elements of <code><em>list</em></code> together with
4812 <code><em>joinString</em></code> separating each adjacent pair of elements.</p></div>
4813 <div class="paragraph"><p>The <code><em>joinString</em></code> argument defaults to a space character.</p></div>
4814 </div>
4817 <div class="paragraph"><p><code><strong>kill</strong> ?<em>SIG</em>|<strong>-0</strong>? <em>pid</em></code></p></div>
4818 <div class="paragraph"><p>Sends the given signal to the process identified by <code><em>pid</em></code>.</p></div>
4819 <div class="paragraph"><p>The signal may be specified by name or number in one of the following forms:</p></div>
4821 <li>
4822 <p>
4823 <code>TERM</code>
4824 </p>
4825 </li>
4826 <li>
4827 <p>
4828 <code>SIGTERM</code>
4829 </p>
4830 </li>
4831 <li>
4832 <p>
4833 <code>-TERM</code>
4834 </p>
4835 </li>
4836 <li>
4837 <p>
4838 <code>15</code>
4839 </p>
4840 </li>
4841 <li>
4842 <p>
4843 <code>-15</code>
4844 </p>
4845 </li>
4846 </ul></div>
4848 <div class="paragraph"><p>The special signal name <code>-0</code> simply checks that a signal <code><em>could</em></code> be sent.</p></div>
4851 </div>
4854 <div class="paragraph"><p><code><strong>lambda</strong> <em>args ?statics? body</em></code></p></div>
4855 <div class="paragraph"><p>The <a href="#_lambda"><strong><code>lambda</code></strong></a> command is identical to <a href="#_proc"><strong><code>proc</code></strong></a>, except rather than
4856 creating a named procedure, it creates an anonymous procedure and returns
4857 the name of the procedure.</p></div>
4858 <div class="paragraph"><p>See <a href="#_proc"><strong><code>proc</code></strong></a> and GARBAGE COLLECTION, REFERENCES, LAMBDA FUNCTION for more detail.</p></div>
4859 </div>
4862 <div class="paragraph"><p><code><strong>lappend</strong> <em>varName value ?value value ...?</em></code></p></div>
4863 <div class="paragraph"><p>Treat the variable given by <code><em>varName</em></code> as a list and append each of
4864 the <code><em>value</em></code> arguments to that list as a separate element, with spaces
4865 between elements.</p></div>
4866 <div class="paragraph"><p>If <code><em>varName</em></code> doesn’t exist, it is created as a list with elements given
4867 by the <code><em>value</em></code> arguments. <a href="#_lappend"><strong><code>lappend</code></strong></a> is similar to <a href="#_append"><strong><code>append</code></strong></a> except that
4868 each <code><em>value</em></code> is appended as a list element rather than raw text.</p></div>
4869 <div class="paragraph"><p>This command provides a relatively efficient way to build up large lists.
4870 For example,</p></div>
4873 <pre><code>lappend a $b</code></pre>
4874 </div></div>
4878 <pre><code>set a [concat $a [list $b]]</code></pre>
4879 </div></div>
4881 </div>
4884 <div class="paragraph"><p><code><strong>lassign</strong> <em>list varName ?varName ...?</em></code></p></div>
4885 <div class="paragraph"><p>This command treats the value <code><em>list</em></code> as a list and assigns successive elements from that list to
4886 the variables given by the <code><em>varName</em></code> arguments in order. If there are more variable names than
4887 list elements, the remaining variables are set to the empty string. If there are more list elements
4888 than variables, a list of unassigned elements is returned.</p></div>
4891 <pre><code>jim> lassign {1 2 3} a b; puts a=$a,b=$b
4892 3
4893 a=1,b=2</code></pre>
4894 </div></div>
4895 </div>
4899 <div class="paragraph"><p>First, <a href="#_local"><strong><code>local</code></strong></a> evaluates <code><em>cmd</em></code> with the given arguments. The return value must
4900 be the name of an existing command, which is marked as having local scope.
4901 This means that when the current procedure exits, the specified
4902 command is deleted. This can be useful with <a href="#_lambda"><strong><code>lambda</code></strong></a>, local procedures or
4903 to automatically close a filehandle.</p></div>
4905 the existing command will be kept rather than deleted, and may be called
4906 via <a href="#_upcall"><strong><code>upcall</code></strong></a>. The previous command will be restored when the current
4907 procedure exits. See <a href="#_upcall"><strong><code>upcall</code></strong></a> for more details.</p></div>
4908 <div class="paragraph"><p>In this example, a local procedure is created. Note that the procedure
4909 continues to have global scope while it is active.</p></div>
4912 <pre><code>proc outer {} {
4914 local proc inner {} {
4915 # will be deleted when 'outer' exits
4916 }</code></pre>
4917 </div></div>
4920 <pre><code> inner
4921 ...
4922 }</code></pre>
4923 </div></div>
4924 <div class="paragraph"><p>In this example, the lambda is deleted at the end of the procedure rather
4925 than waiting until garbage collection.</p></div>
4928 <pre><code>proc outer {} {
4929 set x [lambda inner {args} {
4930 # will be deleted when 'outer' exits
4931 }]
4932 # Use 'function' here which simply returns $x
4933 local function $x</code></pre>
4934 </div></div>
4937 <pre><code> $x ...
4938 ...
4939 }</code></pre>
4940 </div></div>
4941 </div>
4944 <div class="paragraph"><p><code><strong>loop</strong> <em>var first limit ?incr? body</em></code></p></div>
4945 <div class="paragraph"><p>Similar to <a href="#_for"><strong><code>for</code></strong></a> except simpler and possibly more efficient.
4946 With a positive increment, equivalent to:</p></div>
4949 <pre><code>for {set var $first} {$var < $limit} {incr var $incr} $body</code></pre>
4950 </div></div>
4952 Note that setting the loop variable inside the loop does not
4953 affect the loop count.</p></div>
4954 </div>
4957 <div class="paragraph"><p><code><strong>lindex</strong> <em>list ?index …?</em></code></p></div>
4958 <div class="paragraph"><p>Treats <code><em>list</em></code> as a Tcl list and returns element <code><em>index</em></code> from it
4959 (0 refers to the first element of the list).
4960 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for <code><em>index</em></code>.</p></div>
4961 <div class="paragraph"><p>In extracting the element, <code><em>lindex</em></code> observes the same rules concerning
4962 braces and quotes and backslashes as the Tcl command interpreter; however,
4963 variable substitution and command substitution do not occur.</p></div>
4964 <div class="paragraph"><p>If no index values are given, simply returns <code><em>list</em></code></p></div>
4965 <div class="paragraph"><p>If <code><em>index</em></code> is negative or greater than or equal to the number of elements
4966 in <code><em>list</em></code>, then an empty string is returned.</p></div>
4968 used in turn to select an element from the previous indexing
4969 operation, allowing the script to select elements from sublists.</p></div>
4970 </div>
4973 <div class="paragraph"><p><code><strong>linsert</strong> <em>list index element ?element element ...?</em></code></p></div>
4974 <div class="paragraph"><p>This command produces a new list from <code><em>list</em></code> by inserting all
4975 of the <code><em>element</em></code> arguments just before the element <code><em>index</em></code>
4976 of <code><em>list</em></code>. Each <code><em>element</em></code> argument will become
4977 a separate element of the new list. If <code><em>index</em></code> is less than
4978 or equal to zero, then the new elements are inserted at the
4979 beginning of the list. If <code><em>index</em></code> is greater than or equal
4980 to the number of elements in the list, then the new elements are
4981 appended to the list.</p></div>
4982 <div class="paragraph"><p>See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for <code><em>index</em></code>.</p></div>
4983 </div>
4987 <div class="paragraph"><p>This command returns a list comprised of all the arguments, <code><em>arg</em></code>. Braces
4988 and backslashes get added as necessary, so that the <a href="#_lindex"><strong><code>lindex</code></strong></a> command
4989 may be used on the result to re-extract the original arguments, and also
4990 so that <a href="#_eval"><strong><code>eval</code></strong></a> may be used to execute the resulting list, with
4991 <code><em>arg1</em></code> comprising the command’s name and the other args comprising
4992 its arguments. <a href="#_list"><strong><code>list</code></strong></a> produces slightly different results than
4993 <a href="#_concat"><strong><code>concat</code></strong></a>: <a href="#_concat"><strong><code>concat</code></strong></a> removes one level of grouping before forming
4994 the list, while <a href="#_list"><strong><code>list</code></strong></a> works directly from the original arguments.
4995 For example, the command</p></div>
4998 <pre><code>list a b {c d e} {f {g h}}</code></pre>
4999 </div></div>
5003 <pre><code>a b {c d e} {f {g h}}</code></pre>
5004 </div></div>
5005 <div class="paragraph"><p>while <a href="#_concat"><strong><code>concat</code></strong></a> with the same arguments will return</p></div>
5008 <pre><code>a b c d e f {g h}</code></pre>
5009 </div></div>
5010 </div>
5014 <div class="paragraph"><p>Treats <code><em>list</em></code> as a list and returns a decimal string giving
5015 the number of elements in it.</p></div>
5016 </div>
5019 <div class="paragraph"><p><code><strong>lset</strong> <em>varName ?index ..? newValue</em></code></p></div>
5021 <div class="paragraph"><p>The <a href="#_lset"><strong><code>lset</code></strong></a> command accepts a parameter, <code><em>varName</em></code>, which it interprets
5022 as the name of a variable containing a Tcl list. It also accepts
5023 zero or more indices into the list. Finally, it accepts a new value
5024 for an element of varName. If no indices are presented, the command
5025 takes the form:</p></div>
5028 <pre><code>lset varName newValue</code></pre>
5029 </div></div>
5031 varName.</p></div>
5032 <div class="paragraph"><p>When presented with a single index, the <a href="#_lset"><strong><code>lset</code></strong></a> command
5033 treats the content of the varName variable as a Tcl list. It addresses
5034 the index’th element in it (0 refers to the first element of the
5035 list). When interpreting the list, <a href="#_lset"><strong><code>lset</code></strong></a> observes the same rules
5036 concerning braces and quotes and backslashes as the Tcl command
5037 interpreter; however, variable substitution and command substitution
5038 do not occur. The command constructs a new list in which the
5039 designated element is replaced with newValue. This new list is
5040 stored in the variable varName, and is also the return value from
5043 elements in $varName, then an error occurs.</p></div>
5044 <div class="paragraph"><p>See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for <code><em>index</em></code>.</p></div>
5046 used in turn to address an element within a sublist designated by
5047 the previous indexing operation, allowing the script to alter
5048 elements in sublists. The command,</p></div>
5051 <pre><code>lset a 1 2 newValue</code></pre>
5052 </div></div>
5053 <div class="paragraph"><p>replaces element 2 of sublist 1 with <code><em>newValue</em></code>.</p></div>
5055 or equal to zero. The integer appearing in each index argument must
5056 be strictly less than the length of the corresponding list. In other
5057 words, the <a href="#_lset"><strong><code>lset</code></strong></a> command cannot change the size of a list. If an
5058 index is outside the permitted range, an error is reported.</p></div>
5059 </div>
5062 <div class="paragraph"><p><code><strong>lmap</strong> <em>varName list body</em></code></p></div>
5063 <div class="paragraph"><p><code><strong>lmap</strong> <em>varList list ?varList2 list2 ...? body</em></code></p></div>
5064 <div class="paragraph"><p><a href="#_lmap"><strong><code>lmap</code></strong></a> is a "collecting" <a href="#_foreach"><strong><code>foreach</code></strong></a> which returns a list of its results.</p></div>
5068 <pre><code>jim> lmap i {1 2 3 4 5} {expr $i*$i}
5069 1 4 9 16 25
5070 jim> lmap a {1 2 3} b {A B C} {list $a $b}
5071 {1 A} {2 B} {3 C}</code></pre>
5072 </div></div>
5073 <div class="paragraph"><p>If the body invokes <a href="#_continue"><strong><code>continue</code></strong></a>, no value is added for this iteration.
5074 If the body invokes <a href="#_break"><strong><code>break</code></strong></a>, the loop ends and no more values are added.</p></div>
5075 </div>
5079 <div class="paragraph"><p>Loads the dynamic extension, <code><em>filename</em></code>. Generally the filename should have
5080 the extension <code>.so</code>. The initialisation function for the module must be based
5081 on the name of the file. For example loading <code>hwaccess.so</code> will invoke
5082 the initialisation function, <code>Jim_hwaccessInit</code>. Normally the <a href="#_load"><strong><code>load</code></strong></a> command
5083 should not be used directly. Instead it is invoked automatically by <a href="#_package"><strong><code>package</code></strong></a> <code>require</code>.</p></div>
5084 </div>
5087 <div class="paragraph"><p><code><strong>lrange</strong> <em>list first last</em></code></p></div>
5088 <div class="paragraph"><p><code><em>list</em></code> must be a valid Tcl list. This command will return a new
5089 list consisting of elements <code><em>first</em></code> through <code><em>last</em></code>, inclusive.</p></div>
5090 <div class="paragraph"><p>See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for <code><em>first</em></code> and <code><em>last</em></code>.</p></div>
5091 <div class="paragraph"><p>If <code><em>last</em></code> is greater than or equal to the number of elements
5092 in the list, then it is treated as if it were <code>end</code>.</p></div>
5093 <div class="paragraph"><p>If <code><em>first</em></code> is greater than <code><em>last</em></code> then an empty string
5094 is returned.</p></div>
5095 <div class="paragraph"><p>Note: <code>"<a href="#_lrange"><strong><code>lrange</code></strong></a> <em>list first first</em>"</code> does not always produce the
5096 same result as <code>"<a href="#_lindex"><strong><code>lindex</code></strong></a> <em>list first</em>"</code> (although it often does
5097 for simple fields that aren’t enclosed in braces); it does, however,
5098 produce exactly the same results as <code>"<a href="#_list"><strong><code>list</code></strong></a> [<a href="#_lindex"><strong><code>lindex</code></strong></a> <em>list first</em>]"</code></p></div>
5099 </div>
5102 <div class="paragraph"><p><code><strong>lreplace</strong> <em>list first last ?element element ...?</em></code></p></div>
5104 <code><em>list</em></code> with the <code><em>element</em></code> arguments.</p></div>
5105 <div class="paragraph"><p><code><em>first</em></code> gives the index in <code><em>list</em></code> of the first element
5106 to be replaced.</p></div>
5107 <div class="paragraph"><p>If <code><em>first</em></code> is less than zero then it refers to the first
5108 element of <code><em>list</em></code>; the element indicated by <code><em>first</em></code>
5109 must exist in the list.</p></div>
5110 <div class="paragraph"><p><code><em>last</em></code> gives the index in <code><em>list</em></code> of the last element
5111 to be replaced; it must be greater than or equal to <code><em>first</em></code>.</p></div>
5112 <div class="paragraph"><p>See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for <code><em>first</em></code> and <code><em>last</em></code>.</p></div>
5113 <div class="paragraph"><p>The <code><em>element</em></code> arguments specify zero or more new arguments to
5114 be added to the list in place of those that were deleted.</p></div>
5115 <div class="paragraph"><p>Each <code><em>element</em></code> argument will become a separate element of
5116 the list.</p></div>
5117 <div class="paragraph"><p>If no <code><em>element</em></code> arguments are specified, then the elements
5118 between <code><em>first</em></code> and <code><em>last</em></code> are simply deleted.</p></div>
5119 </div>
5122 <div class="paragraph"><p><code><strong>lrepeat</strong> <em>number element1 ?element2 ...?</em></code></p></div>
5123 <div class="paragraph"><p>Build a list by repeating elements <code><em>number</em></code> times (which must be
5124 a positive integer).</p></div>
5127 <pre><code>jim> lrepeat 3 a b
5128 a b a b a b</code></pre>
5129 </div></div>
5130 </div>
5137 <pre><code>jim> lreverse {1 2 3}
5138 3 2 1</code></pre>
5139 </div></div>
5140 </div>
5143 <div class="paragraph"><p><code><strong>lsearch</strong> <em>?options? list pattern</em></code></p></div>
5144 <div class="paragraph"><p>This command searches the elements <code><em>list</em></code> to see if one of them matches <code><em>pattern</em></code>. If so, the
5145 command returns the index of the first matching element (unless the options <code>-all</code>, <code>-inline</code> or <code>-bool</code> are
5146 specified.) If not, the command returns -1. The option arguments indicates how the elements of
5147 the list are to be matched against pattern and must have one of the values below:</p></div>
5148 <div class="paragraph"><p><strong>Note</strong> that this command is different from Tcl in that default match type is <code>-exact</code> rather than <code>-glob</code>.</p></div>
5151 <code><strong>-exact</strong></code>
5152 </dt>
5153 <dd>
5154 <p>
5155 <code><em>pattern</em></code> is a literal string that is compared for exact equality against each list element.
5156 This is the default.
5157 </p>
5158 </dd>
5160 <code><strong>-glob</strong></code>
5161 </dt>
5162 <dd>
5163 <p>
5164 <code><em>pattern</em></code> is a glob-style pattern which is matched against each list element using the same
5165 rules as the string match command.
5166 </p>
5167 </dd>
5169 <code><strong>-regexp</strong></code>
5170 </dt>
5171 <dd>
5172 <p>
5173 <code><em>pattern</em></code> is treated as a regular expression and matched against each list element using
5175 </p>
5176 </dd>
5178 <code><strong>-command</strong> <em>cmdname</em></code>
5179 </dt>
5180 <dd>
5181 <p>
5182 <code><em>cmdname</em></code> is a command which is used to match the pattern against each element of the
5183 list. It is invoked as <code><em>cmdname</em> ?<strong>-nocase</strong>? <em>pattern listvalue</em></code> and should return 1
5184 for a match, or 0 for no match.
5185 </p>
5186 </dd>
5188 <code><strong>-all</strong></code>
5189 </dt>
5190 <dd>
5191 <p>
5192 Changes the result to be the list of all matching indices (or all matching values if
5193 <code>-inline</code> is specified as well). If indices are returned, the indices will be in numeric
5194 order. If values are returned, the order of the values will be the order of those values
5195 within the input list.
5196 </p>
5197 </dd>
5199 <code><strong>-inline</strong></code>
5200 </dt>
5201 <dd>
5202 <p>
5203 The matching value is returned instead of its index (or an empty string if no value
5204 matches). If <code>-all</code> is also specified, then the result of the command is the list of all
5205 values that matched. The <code>-inline</code> and <code>-bool</code> options are mutually exclusive.
5206 </p>
5207 </dd>
5209 <code><strong>-bool</strong></code>
5210 </dt>
5211 <dd>
5212 <p>
5213 Changes the result to <em>1</em> if a match was found, or <em>0</em> otherwise. If <code>-all</code> is also specified,
5214 the result will be a list of <em>0</em> and <em>1</em> for each element of the list depending upon whether
5215 the corresponding element matches. The <code>-inline</code> and <code>-bool</code> options are mutually exclusive.
5216 </p>
5217 </dd>
5219 <code><strong>-not</strong></code>
5220 </dt>
5221 <dd>
5222 <p>
5223 This negates the sense of the match, returning the index (or value
5224 if <code>-inline</code> is specified) of the first non-matching value in the
5225 list. If <code>-bool</code> is also specified, the <em>0</em> will be returned if a
5226 match is found, or <em>1</em> otherwise. If <code>-all</code> is also specified,
5227 non-matches will be returned rather than matches.
5228 </p>
5229 </dd>
5231 <code><strong>-nocase</strong></code>
5232 </dt>
5233 <dd>
5234 <p>
5235 Causes comparisons to be handled in a case-insensitive manner.
5236 </p>
5237 </dd>
5238 </dl></div>
5239 </div>
5242 <div class="paragraph"><p><code><strong>lsort</strong> ?<strong>-index</strong> <em>listindex</em>? ?<strong>-nocase|-integer|-real|-command</strong> <em>cmdname</em>? ?<strong>-unique</strong>? ?<strong>-decreasing</strong>|<strong>-increasing</strong>? <em>list</em></code></p></div>
5243 <div class="paragraph"><p>Sort the elements of <code><em>list</em></code>, returning a new list in sorted order.
5244 By default, ASCII (or UTF-8) sorting is used, with the result in increasing order.</p></div>
5245 <div class="paragraph"><p>If <code>-nocase</code> is specified, comparisons are case-insensitive.</p></div>
5246 <div class="paragraph"><p>If <code>-integer</code> is specified, numeric sorting is used.</p></div>
5247 <div class="paragraph"><p>If <code>-real</code> is specified, floating point number sorting is used.</p></div>
5248 <div class="paragraph"><p>If <code>-command <em>cmdname</em></code> is specified, <code><em>cmdname</em></code> is treated as a command
5249 name. For each comparison, <code><em>cmdname $value1 $value2</code></em> is called which
5250 should compare the values and return an integer less than, equal
5251 to, or greater than zero if the <code><em>$value1</em></code> is to be considered less
5252 than, equal to, or greater than <code><em>$value2</em></code>, respectively.</p></div>
5253 <div class="paragraph"><p>If <code>-decreasing</code> is specified, the resulting list is in the opposite
5254 order to what it would be otherwise. <code>-increasing</code> is the default.</p></div>
5255 <div class="paragraph"><p>If <code>-unique</code> is specified, then only the last set of duplicate elements found in the list will be retained.
5256 Note that duplicates are determined relative to the comparison used in the sort. Thus if <code>-index 0</code> is used,
5257 <code>{1 a}</code> and <code>{1 b}</code> would be considered duplicates and only the second element, <code>{1 b}</code>, would be retained.</p></div>
5258 <div class="paragraph"><p>If <code>-index <em>listindex</em></code> is specified, each element of the list is treated as a list and
5259 the given index is extracted from the list for comparison. The list index may
5260 be any valid list index, such as <code>1</code>, <code>end</code> or <code>end-2</code>.</p></div>
5261 </div>
5264 <div class="paragraph"><p><code><strong>open</strong> <em>fileName ?access?</em></code></p></div>
5265 <div class="paragraph"><p><code><strong>open</strong> <em>|command-pipeline ?access?</em></code></p></div>
5267 that may be used in future invocations
5268 of commands like <a href="#_read"><strong><code>read</code></strong></a>, <a href="#_puts"><strong><code>puts</code></strong></a>, and <a href="#_close"><strong><code>close</code></strong></a>.
5269 <code><em>fileName</em></code> gives the name of the file to open.</p></div>
5270 <div class="paragraph"><p>The <code><em>access</em></code> argument indicates the way in which the file is to be accessed.
5271 It may have any of the following values:</p></div>
5274 <code>r</code>
5275 </dt>
5276 <dd>
5277 <p>
5278 Open the file for reading only; the file must already exist.
5279 </p>
5280 </dd>
5282 <code>r</code>+
5283 </dt>
5284 <dd>
5285 <p>
5286 Open the file for both reading and writing; the file must
5287 already exist.
5288 </p>
5289 </dd>
5291 <code>w</code>
5292 </dt>
5293 <dd>
5294 <p>
5295 Open the file for writing only. Truncate it if it exists. If it doesn’t
5296 exist, create a new file.
5297 </p>
5298 </dd>
5300 <code>w</code>+
5301 </dt>
5302 <dd>
5303 <p>
5304 Open the file for reading and writing. Truncate it if it exists.
5305 If it doesn’t exist, create a new file.
5306 </p>
5307 </dd>
5309 <code>a</code>
5310 </dt>
5311 <dd>
5312 <p>
5313 Open the file for writing only. The file must already exist, and the file
5314 is positioned so that new data is appended to the file.
5315 </p>
5316 </dd>
5318 <code>a</code>+
5319 </dt>
5320 <dd>
5321 <p>
5322 Open the file for reading and writing. If the file doesn’t
5323 exist, create a new empty file. Set the initial access position
5324 to the end of the file.
5325 </p>
5326 </dd>
5327 </dl></div>
5329 <div class="paragraph"><p>If a file is opened for both reading and writing, then <a href="#_seek"><strong><code>seek</code></strong></a>
5330 must be invoked between a read and a write, or vice versa.</p></div>
5331 <div class="paragraph"><p>If the first character of <code><em>fileName</em></code> is "|" then the remaining
5332 characters of <code><em>fileName</em></code> are treated as a list of arguments that
5333 describe a command pipeline to invoke, in the same style as the
5334 arguments for exec. In this case, the channel identifier returned
5335 by open may be used to write to the command’s input pipe or read
5336 from its output pipe, depending on the value of <code><em>access</em></code>. If write-only
5337 access is used (e.g. <code><em>access</em></code> is <em>w</em>), then standard output for the
5338 pipeline is directed to the current standard output unless overridden
5339 by the command. If read-only access is used (e.g. <code><em>access</em></code> is r),
5340 standard input for the pipeline is taken from the current standard
5341 input unless overridden by the command.</p></div>
5342 <div class="paragraph"><p>The <a href="#_pid"><strong><code>pid</code></strong></a> command may be used to return the process ids of the commands
5343 forming the command pipeline.</p></div>
5344 <div class="paragraph"><p>See also <a href="#_socket"><strong><code>socket</code></strong></a>, <a href="#_pid"><strong><code>pid</code></strong></a>, <a href="#_exec"><strong><code>exec</code></strong></a></p></div>
5345 </div>
5348 <div class="paragraph"><p><code><strong>package provide</strong> <em>name ?version?</em></code></p></div>
5349 <div class="paragraph"><p>Indicates that the current script provides the package named <code><em>name</em></code>.
5350 If no version is specified, <em>1.0</em> is used.</p></div>
5352 as the first statement, although it is not required.</p></div>
5353 <div class="paragraph"><p><code><strong>package require</strong> <em>name ?version?</em>*</code></p></div>
5354 <div class="paragraph"><p>Searches for the package with the given <code><em>name</em></code> by examining each path
5355 in <em>$::auto_path</em> and trying to load <em>$path/$name.so</em> as a dynamic extension,
5356 or <em>$path/$name.tcl</em> as a script package.</p></div>
5357 <div class="paragraph"><p>The first such file which is found is considered to provide the package.
5358 (The version number is ignored).</p></div>
5359 <div class="paragraph"><p>If <em>$name.so</em> exists, it is loaded with the <a href="#_load"><strong><code>load</code></strong></a> command,
5360 otherwise if <em>$name.tcl</em> exists it is loaded with the <a href="#_source"><strong><code>source</code></strong></a> command.</p></div>
5361 <div class="paragraph"><p>If <a href="#_load"><strong><code>load</code></strong></a> or <a href="#_source"><strong><code>source</code></strong></a> fails, <a href="#_package"><strong><code>package</code></strong></a> <code>require</code> will fail immediately.
5362 No further attempt will be made to locate the file.</p></div>
5363 </div>
5368 <div class="paragraph"><p>The first form returns the process identifier of the current process.</p></div>
5369 <div class="paragraph"><p>The second form accepts a handle returned by <a href="#_open"><strong><code>open</code></strong></a> and returns a list
5370 of the process ids forming the pipeline in the same form as <a href="#_exec"><strong><code>exec</code></strong></a> <code>... &</code>.
5371 If <em>fileId</em> represents a regular file handle rather than a command pipeline,
5372 the empty string is returned instead.</p></div>
5373 <div class="paragraph"><p>See also <a href="#_open"><strong><code>open</code></strong></a>, <a href="#_exec"><strong><code>exec</code></strong></a></p></div>
5374 </div>
5377 <div class="paragraph"><p><code><strong>proc</strong> <em>name args ?statics? body</em></code></p></div>
5378 <div class="paragraph"><p>The <a href="#_proc"><strong><code>proc</code></strong></a> command creates a new Tcl command procedure, <code><em>name</em></code>.
5379 When the new command is invoked, the contents of <code><em>body</em></code> will be executed.
5380 Tcl interpreter. <code><em>args</em></code> specifies the formal arguments to the procedure.
5381 If specified, <code><em>static</em></code>, declares static variables which are bound to the
5382 procedure.</p></div>
5383 <div class="paragraph"><p>See PROCEDURES for detailed information about Tcl procedures.</p></div>
5384 <div class="paragraph"><p>The <a href="#_proc"><strong><code>proc</code></strong></a> command returns <code><em>name</em></code> (which is useful with <a href="#_local"><strong><code>local</code></strong></a>).</p></div>
5385 <div class="paragraph"><p>When a procedure is invoked, the procedure’s return value is the
5386 value specified in a <a href="#_return"><strong><code>return</code></strong></a> command. If the procedure doesn’t
5387 execute an explicit <a href="#_return"><strong><code>return</code></strong></a>, then its return value is the value
5388 of the last command executed in the procedure’s body.</p></div>
5390 procedure-as-a-whole will return that same error.</p></div>
5391 </div>
5394 <div class="paragraph"><p><code><strong>puts</strong> ?<strong>-nonewline</strong>? <em>?fileId? string</em></code></p></div>
5395 <div class="paragraph"><p><code><em>fileId</em> <strong>puts</strong> ?<strong>-nonewline</strong>? <em>string</em></code></p></div>
5396 <div class="paragraph"><p>Writes the characters given by <code><em>string</em></code> to the file given
5397 by <code><em>fileId</em></code>. <code><em>fileId</em></code> must have been the return
5398 value from a previous call to <a href="#_open"><strong><code>open</code></strong></a>, or it may be
5399 <code>stdout</code> or <code>stderr</code> to refer to one of the standard I/O
5400 channels; it must refer to a file that was opened for
5401 writing.</p></div>
5402 <div class="paragraph"><p>In the first form, if no <code><em>fileId</em></code> is specified then it defaults to <code>stdout</code>.
5403 <a href="#_puts"><strong><code>puts</code></strong></a> normally outputs a newline character after <code><em>string</em></code>,
5404 but this feature may be suppressed by specifying the <code>-nonewline</code>
5405 switch.</p></div>
5406 <div class="paragraph"><p>Output to files is buffered internally by Tcl; the <a href="#_flush"><strong><code>flush</code></strong></a>
5407 command may be used to force buffered characters to be output.</p></div>
5408 </div>
5413 </div>
5417 <div class="paragraph"><p>Returns a random integer between <code><em>min</em></code> (defaults to 0) and <code><em>max</em></code>
5418 (defaults to the maximum integer).</p></div>
5419 <div class="paragraph"><p>If only one argument is given, it is interpreted as <code><em>max</em></code>.</p></div>
5420 </div>
5423 <div class="paragraph"><p><code><strong>range</strong> <em>?start? end ?step?</em></code></p></div>
5424 <div class="paragraph"><p>Returns a list of integers starting at <code><em>start</em></code> (defaults to 0)
5425 and ranging up to but not including <code><em>end</em></code> in steps of <code><em>step</em></code> defaults to 1).</p></div>
5428 <pre><code>jim> range 5
5429 0 1 2 3 4
5430 jim> range 2 5
5431 2 3 4
5432 jim> range 2 10 4
5433 2 6
5434 jim> range 7 4 -2
5435 7 5</code></pre>
5436 </div></div>
5437 </div>
5440 <div class="paragraph"><p><code><strong>read</strong> ?<strong>-nonewline</strong>? <em>fileId</em></code></p></div>
5441 <div class="paragraph"><p><code><em>fileId</em> <strong>read</strong> ?<strong>-nonewline</strong>?</code></p></div>
5442 <div class="paragraph"><p><code><strong>read</strong> <em>fileId numBytes</em></code></p></div>
5443 <div class="paragraph"><p><code><em>fileId</em> <strong>read</strong> <em>numBytes</em></code></p></div>
5445 given by <code><em>fileId</em></code>; they are returned as the result of the command.
5446 If the <code>-nonewline</code> switch is specified then the last
5447 character of the file is discarded if it is a newline.</p></div>
5448 <div class="paragraph"><p>In the second form, the extra argument specifies how many bytes to read;
5449 exactly this many bytes will be read and returned, unless there are fewer than
5450 <code><em>numBytes</em></code> bytes left in the file; in this case, all the remaining
5451 bytes are returned.</p></div>
5452 <div class="paragraph"><p><code><em>fileId</em></code> must be <code>stdin</code> or the return value from a previous call
5453 to <a href="#_open"><strong><code>open</code></strong></a>; it must refer to a file that was opened for reading.</p></div>
5454 </div>
5457 <div class="paragraph"><p><code><strong>regexp ?-nocase? ?-line? ?-indices? ?-start</strong> <em>offset</em>? <strong>?-all? ?-inline? ?--?</strong> <em>exp string ?matchVar? ?subMatchVar subMatchVar ...?</em></code></p></div>
5458 <div class="paragraph"><p>Determines whether the regular expression <code><em>exp</em></code> matches part or
5459 all of <code><em>string</em></code> and returns 1 if it does, 0 if it doesn’t.</p></div>
5461 syntax of <code><em>exp</em></code> and how it is matched against <code><em>string</em></code>.</p></div>
5462 <div class="paragraph"><p>If additional arguments are specified after <code><em>string</em></code> then they
5463 are treated as the names of variables to use to return
5464 information about which part(s) of <code><em>string</em></code> matched <code><em>exp</em></code>.
5465 <code><em>matchVar</em></code> will be set to the range of <code><em>string</em></code> that
5466 matched all of <code><em>exp</em></code>. The first <code><em>subMatchVar</em></code> will contain
5467 the characters in <code><em>string</em></code> that matched the leftmost parenthesized
5468 subexpression within <code><em>exp</em></code>, the next <code><em>subMatchVar</em></code> will
5469 contain the characters that matched the next parenthesized
5470 subexpression to the right in <code><em>exp</em></code>, and so on.</p></div>
5471 <div class="paragraph"><p>Normally, <code><em>matchVar</em></code> and the each <code><em>subMatchVar</em></code> are set to hold the
5472 matching characters from <a href="#_string"><strong><code>string</code></strong></a>, however see <code>-indices</code> and
5473 <code>-inline</code> below.</p></div>
5474 <div class="paragraph"><p>If there are more values for <code><em>subMatchVar</em></code> than parenthesized subexpressions
5475 within <code><em>exp</em></code>, or if a particular subexpression in <code><em>exp</em></code> doesn’t
5476 match the string (e.g. because it was in a portion of the expression
5477 that wasn’t matched), then the corresponding <code><em>subMatchVar</em></code> will be
5479 string otherwise.</p></div>
5480 <div class="paragraph"><p>The following switches modify the behaviour of <code><em>regexp</em></code></p></div>
5483 <code><strong>-nocase</strong></code>
5484 </dt>
5485 <dd>
5486 <p>
5487 Causes upper-case and lower-case characters to be treated as
5488 identical during the matching process.
5489 </p>
5490 </dd>
5492 <code><strong>-line</strong></code>
5493 </dt>
5494 <dd>
5495 <p>
5496 Use newline-sensitive matching. By default, newline
5497 is a completely ordinary character with no special meaning in
5498 either REs or strings. With this flag, <code>[<sup></code> bracket expressions
5499 and <code>.</code> never match newline, an <code></sup></code> anchor matches the null
5500 string after any newline in the string in addition to its normal
5501 function, and the <code>$</code> anchor matches the null string before any
5502 newline in the string in addition to its normal function.
5503 </p>
5504 </dd>
5506 <code><strong>-indices</strong></code>
5507 </dt>
5508 <dd>
5509 <p>
5510 Changes what is stored in the subMatchVars. Instead of
5511 storing the matching characters from string, each variable
5512 will contain a list of two decimal strings giving the indices
5513 in string of the first and last characters in the matching
5514 range of characters.
5515 </p>
5516 </dd>
5518 <code><strong>-start</strong> <em>offset</em></code>
5519 </dt>
5520 <dd>
5521 <p>
5522 Specifies a character index offset into the string at which to start
5523 matching the regular expression. If <code>-indices</code> is
5524 specified, the indices will be indexed starting from the
5525 absolute beginning of the input string. <code><em>offset</em></code> will be
5526 constrained to the bounds of the input string.
5527 </p>
5528 </dd>
5530 <code><strong>-all</strong></code>
5531 </dt>
5532 <dd>
5533 <p>
5534 Causes the regular expression to be matched as many times as possible
5535 in the string, returning the total number of matches found. If this
5536 is specified with match variables, they will contain information
5537 for the last match only.
5538 </p>
5539 </dd>
5541 <code><strong>-inline</strong></code>
5542 </dt>
5543 <dd>
5544 <p>
5545 Causes the command to return, as a list, the data that would otherwise
5546 be placed in match variables. When using <code>-inline</code>, match variables
5547 may not be specified. If used with <code>-all</code>, the list will be concatenated
5548 at each iteration, such that a flat list is always returned. For
5549 each match iteration, the command will append the overall match
5550 data, plus one element for each subexpression in the regular
5551 expression.
5552 </p>
5553 </dd>
5555 <code><strong>--</strong></code>
5556 </dt>
5557 <dd>
5558 <p>
5559 Marks the end of switches. The argument following this one will be
5560 treated as <code><em>exp</em></code> even if it starts with a <code>-</code>.
5561 </p>
5562 </dd>
5563 </dl></div>
5564 </div>
5567 <div class="paragraph"><p><code><strong>regsub ?-nocase? ?-all? ?-line? ?-start</strong> <em>offset</em>? ?<strong>--</strong>? <em>exp string subSpec ?varName?</em></code></p></div>
5568 <div class="paragraph"><p>This command matches the regular expression <code><em>exp</em></code> against
5569 <code><em>string</em></code> using the rules described in REGULAR EXPRESSIONS
5570 above.</p></div>
5571 <div class="paragraph"><p>If <code><em>varName</em></code> is specified, the commands stores <code><em>string</em></code> to <code><em>varName</em></code>
5572 with the substitutions detailed below, and returns the number of
5573 substitutions made (normally 1 unless <code>-all</code> is specified).
5574 This is 0 if there were no matches.</p></div>
5575 <div class="paragraph"><p>If <code><em>varName</em></code> is not specified, the substituted string will be returned
5576 instead.</p></div>
5577 <div class="paragraph"><p>When copying <code><em>string</em></code>, the portion of <code><em>string</em></code> that
5578 matched <code><em>exp</em></code> is replaced with <code><em>subSpec</em></code>.
5579 If <code><em>subSpec</em></code> contains a <code>&</code> or <code>\0</code>, then it is replaced
5580 in the substitution with the portion of <code><em>string</em></code> that
5581 matched <code><em>exp</em></code>.</p></div>
5582 <div class="paragraph"><p>If <code><em>subSpec</em></code> contains a <code>\n</code>, where <code><em>n</em></code> is a digit
5583 between 1 and 9, then it is replaced in the substitution with
5584 the portion of <code><em>string</em></code> that matched the <code><em>n</em></code>'-th
5585 parenthesized subexpression of <code><em>exp</em></code>.
5586 Additional backslashes may be used in <code><em>subSpec</em></code> to prevent special
5587 interpretation of <code>&</code> or <code>\0</code> or <code>\n</code> or
5588 backslash.</p></div>
5589 <div class="paragraph"><p>The use of backslashes in <code><em>subSpec</em></code> tends to interact badly
5590 with the Tcl parser’s use of backslashes, so it’s generally
5591 safest to enclose <code><em>subSpec</em></code> in braces if it includes
5592 backslashes.</p></div>
5593 <div class="paragraph"><p>The following switches modify the behaviour of <code><em>regsub</em></code></p></div>
5596 <code><strong>-nocase</strong></code>
5597 </dt>
5598 <dd>
5599 <p>
5600 Upper-case characters in <code><em>string</em></code> are converted to lower-case
5601 before matching against <code><em>exp</em></code>; however, substitutions
5602 specified by <code><em>subSpec</em></code> use the original unconverted form
5603 of <code><em>string</em></code>.
5604 </p>
5605 </dd>
5607 <code><strong>-all</strong></code>
5608 </dt>
5609 <dd>
5610 <p>
5611 All ranges in <code><em>string</em></code> that match <code><em>exp</em></code> are found and substitution
5612 is performed for each of these ranges, rather than only the
5613 first. The <code>&</code> and <code>\n</code> sequences are handled for
5614 each substitution using the information from the corresponding
5615 match.
5616 </p>
5617 </dd>
5619 <code><strong>-line</strong></code>
5620 </dt>
5621 <dd>
5622 <p>
5623 Use newline-sensitive matching. By default, newline
5624 is a completely ordinary character with no special meaning in
5625 either REs or strings. With this flag, <code>[<sup></code> bracket expressions
5626 and <code>.</code> never match newline, an <code></sup></code> anchor matches the null
5627 string after any newline in the string in addition to its normal
5628 function, and the <code>$</code> anchor matches the null string before any
5629 newline in the string in addition to its normal function.
5630 </p>
5631 </dd>
5633 <code><strong>-start</strong> <em>offset</em></code>
5634 </dt>
5635 <dd>
5636 <p>
5637 Specifies a character index offset into the string at which to
5638 start matching the regular expression. <code><em>offset</em></code> will be
5639 constrained to the bounds of the input string.
5640 </p>
5641 </dd>
5643 <code><strong>--</strong></code>
5644 </dt>
5645 <dd>
5646 <p>
5647 Marks the end of switches. The argument following this one will be
5648 treated as <code><em>exp</em></code> even if it starts with a <code>-</code>.
5649 </p>
5650 </dd>
5651 </dl></div>
5652 </div>
5655 <div class="paragraph"><p><code><strong>ref</strong> <em>string tag ?finalizer?</em></code></p></div>
5656 <div class="paragraph"><p>Create a new reference containing <code><em>string</em></code> of type <code><em>tag</em></code>.
5657 If <code><em>finalizer</em></code> is specified, it is a command which will be invoked
5658 when the a garbage collection cycle runs and this reference is
5659 no longer accessible.</p></div>
5663 <pre><code>finalizer reference string</code></pre>
5664 </div></div>
5665 <div class="paragraph"><p>See GARBAGE COLLECTION, REFERENCES, LAMBDA FUNCTION for more detail.</p></div>
5666 </div>
5669 <div class="paragraph"><p><code><strong>rename</strong> <em>oldName newName</em></code></p></div>
5670 <div class="paragraph"><p>Rename the command that used to be called <code><em>oldName</em></code> so that it
5671 is now called <code><em>newName</em></code>. If <code><em>newName</em></code> is an empty string
5672 (e.g. {}) then <code><em>oldName</em></code> is deleted. The <a href="#_rename"><strong><code>rename</code></strong></a> command
5673 returns an empty string as result.</p></div>
5674 </div>
5677 <div class="paragraph"><p><code><strong>return</strong> ?<strong>-code</strong> <em>code</em>? ?<strong>-errorinfo</strong> <em>stacktrace</em>? ?<strong>-errorcode</strong> <em>errorcode</em>? ?<strong>-level</strong> <em>n</em>? ?<em>value</em>?</code></p></div>
5679 or <a href="#_source"><strong><code>source</code></strong></a> command), with <code><em>value</em></code> as the return value. If <code><em>value</em></code>
5680 is not specified, an empty string will be returned as result.</p></div>
5681 <div class="paragraph"><p>If <code>-code</code> is specified (as either a number or ok, error, break,
5682 continue, signal, return or exit), this code will be used instead
5683 of <code>JIM_OK</code>. This is generally useful when implementing flow of control
5684 commands.</p></div>
5685 <div class="paragraph"><p>If <code>-level</code> is specified and greater than 1, it has the effect of delaying
5686 the new return code from <code>-code</code>. This is useful when rethrowing an error
5687 from <a href="#_catch"><strong><code>catch</code></strong></a>. See the implementation of try/catch in tclcompat.tcl for
5688 an example of how this is done.</p></div>
5689 <div class="paragraph"><p>Note: The following options are only used when <code>-code</code> is JIM_ERR.</p></div>
5690 <div class="paragraph"><p>If <code>-errorinfo</code> is specified (as returned from <a href="#_info"><strong><code>info</code></strong></a> <code>stacktrace</code>)
5691 it is used to initialize the stacktrace.</p></div>
5692 <div class="paragraph"><p>If <code>-errorcode</code> is specified, it is used to set the global variable $::errorCode.</p></div>
5693 </div>
5696 <div class="paragraph"><p><code><strong>scan</strong> <em>string format varName1 ?varName2 ...?</em></code></p></div>
5698 as the C <em>sscanf</em> procedure. <code><em>string</em></code> gives the input to be parsed
5699 and <code><em>format</em></code> indicates how to parse it, using <em>%</em> fields as in
5700 <em>sscanf</em>. All of the <em>sscanf</em> options are valid; see the <em>sscanf</em>
5701 man page for details. Each <code><em>varName</em></code> gives the name of a variable;
5702 when a field is scanned from <code><em>string</em></code>, the result is converted back
5703 into a string and assigned to the corresponding <code><em>varName</em></code>. The
5704 only unusual conversion is for <em>%c</em>. For <em>%c</em> conversions a single
5705 character value is converted to a decimal string, which is then
5706 assigned to the corresponding <code><em>varName</em></code>; no field width may be
5707 specified for this conversion.</p></div>
5708 </div>
5711 <div class="paragraph"><p><code><strong>seek</strong> <em>fileId offset ?origin?</em></code></p></div>
5712 <div class="paragraph"><p><code><em>fileId</em> <strong>seek</strong> <em>offset ?origin?</em></code></p></div>
5714 The <code><em>offset</em></code> and <code><em>origin</em></code> arguments specify the position at
5715 which the next read or write will occur for <code><em>fileId</em></code>.
5716 <code><em>offset</em></code> must be a number (which may be negative) and <code><em>origin</em></code>
5717 must be one of the following:</p></div>
5720 <code><strong>start</strong></code>
5721 </dt>
5722 <dd>
5723 <p>
5724 The new access position will be <code><em>offset</em></code> bytes from the start
5725 of the file.
5726 </p>
5727 </dd>
5729 <code><strong>current</strong></code>
5730 </dt>
5731 <dd>
5732 <p>
5733 The new access position will be <code><em>offset</em></code> bytes from the current
5734 access position; a negative <code><em>offset</em></code> moves the access position
5735 backwards in the file.
5736 </p>
5737 </dd>
5739 <code><strong>end</strong></code>
5740 </dt>
5741 <dd>
5742 <p>
5743 The new access position will be <code><em>offset</em></code> bytes from the end of
5744 the file. A negative <code><em>offset</em></code> places the access position before
5745 the end-of-file, and a positive <code><em>offset</em></code> places the access position
5746 after the end-of-file.
5747 </p>
5748 </dd>
5749 </dl></div>
5750 <div class="paragraph"><p>The <code><em>origin</em></code> argument defaults to <code>start</code>.</p></div>
5751 <div class="paragraph"><p><code><em>fileId</em></code> must have been the return value from a previous call to
5752 <a href="#_open"><strong><code>open</code></strong></a>, or it may be <code>stdin</code>, <code>stdout</code>, or <code>stderr</code> to refer to one
5753 of the standard I/O channels.</p></div>
5755 </div>
5759 <div class="paragraph"><p>Returns the value of variable <code><em>varName</em></code>.</p></div>
5760 <div class="paragraph"><p>If <code><em>value</em></code> is specified, then set the value of <code><em>varName</em></code> to <code><em>value</em></code>,
5761 creating a new variable if one doesn’t already exist, and return
5762 its value.</p></div>
5763 <div class="paragraph"><p>If <code><em>varName</em></code> contains an open parenthesis and ends with a
5764 close parenthesis, then it refers to an array element: the characters
5765 before the open parenthesis are the name of the array, and the characters
5766 between the parentheses are the index within the array.
5767 Otherwise <code><em>varName</em></code> refers to a scalar variable.</p></div>
5768 <div class="paragraph"><p>If no procedure is active, then <code><em>varName</em></code> refers to a global
5769 variable.</p></div>
5770 <div class="paragraph"><p>If a procedure is active, then <code><em>varName</em></code> refers to a parameter
5771 or local variable of the procedure, unless the <code><em>global</em></code> command
5772 has been invoked to declare <code><em>varName</em></code> to be global.</p></div>
5773 <div class="paragraph"><p>The <code>::</code> prefix may also be used to explicitly reference a variable
5774 in the global scope.</p></div>
5775 </div>
5778 <div class="paragraph"><p><code><strong>setref</strong> <em>reference string</em></code></p></div>
5779 <div class="paragraph"><p>Store a new string in <code><em>reference</em></code>, replacing the existing string.
5780 The reference must be a valid reference create with the <a href="#_ref"><strong><code>ref</code></strong></a>
5781 command.</p></div>
5782 <div class="paragraph"><p>See GARBAGE COLLECTION, REFERENCES, LAMBDA FUNCTION for more detail.</p></div>
5783 </div>
5787 <div class="paragraph"><p>See <a href="#_kill"><strong><code>kill</code></strong></a> for the different forms which may be used to specify signals.</p></div>
5788 <div class="paragraph"><p>Commands which return a list of signal names do so using the canonical form:
5792 <code><strong>signal handle</strong> ?<em>signals ...</em>?</code>
5793 </dt>
5794 <dd>
5795 <p>
5796 If no signals are given, returns a list of all signals which are currently
5797 being handled.
5798 If signals are specified, these are added to the list of signals currently
5799 being handled.
5800 </p>
5801 </dd>
5803 <code><strong>signal ignore</strong> ?<em>signals ...</em>?</code>
5804 </dt>
5805 <dd>
5806 <p>
5807 If no signals are given, returns a lists all signals which are currently
5808 being ignored.
5809 If signals are specified, these are added to the list of signals
5810 currently being ignored. These signals are still delivered, but
5811 are not considered by <a href="#_catch"><strong><code>catch</code></strong></a> <code>-signal</code> or <a href="#_try"><strong><code>try</code></strong></a> <code>-signal</code>. Use
5812 <a href="#_signal"><strong><code>signal</code></strong></a> <code>check</code> to determine which signals have occurred but
5813 been ignored.
5814 </p>
5815 </dd>
5817 <code><strong>signal default</strong> ?<em>signals ...</em>?</code>
5818 </dt>
5819 <dd>
5820 <p>
5821 If no signals are given, returns a lists all signals which are currently have
5822 the default behaviour.
5823 If signals are specified, these are added to the list of signals which have
5824 the default behaviour.
5825 </p>
5826 </dd>
5828 <code><strong>signal check ?-clear?</strong> ?<em>signals ...</em>?</code>
5829 </dt>
5830 <dd>
5831 <p>
5832 Returns a list of signals which have been delivered to the process
5833 but are <em>ignored</em>. If signals are specified, only that set of signals will
5834 be checked, otherwise all signals will be checked.
5835 If <code>-clear</code> is specified, any signals returned are removed and will not be
5836 returned by subsequent calls to <a href="#_signal"><strong><code>signal</code></strong></a> <code>check</code> unless delivered again.
5837 </p>
5838 </dd>
5840 <code><strong>signal throw</strong> ?<em>signal</em>?</code>
5841 </dt>
5842 <dd>
5843 <p>
5844 Raises the given signal, which defaults to <code>SIGINT</code> if not specified.
5845 The behaviour is identical to:
5846 </p>
5849 <pre><code>kill signal [pid]</code></pre>
5850 </div></div>
5851 </dd>
5852 </dl></div>
5853 <div class="paragraph"><p>Note that <a href="#_signal"><strong><code>signal</code></strong></a> <code>handle</code> and <a href="#_signal"><strong><code>signal</code></strong></a> <code>ignore</code> represent two forms of signal
5854 handling. <a href="#_signal"><strong><code>signal</code></strong></a> <code>handle</code> is used in conjunction with <a href="#_catch"><strong><code>catch</code></strong></a> <code>-signal</code> or <a href="#_try"><strong><code>try</code></strong></a> <code>-signal</code>
5855 to immediately abort execution when the signal is delivered. Alternatively, <a href="#_signal"><strong><code>signal</code></strong></a> <code>ignore</code>
5856 is used in conjunction with <a href="#_signal"><strong><code>signal</code></strong></a> <code>check</code> to handle signal synchronously. Consider the
5857 two examples below.</p></div>
5861 <pre><code>signal handle SIGALRM
5862 alarm 20
5863 try -signal {
5864 .. possibly long running process ..
5865 alarm 0
5866 } on signal {sig} {
5868 }</code></pre>
5869 </div></div>
5873 <pre><code>signal ignore SIGHUP
5874 while {1} {
5875 ... handle configuration/reconfiguration ...
5877 ... do processing ..
5878 }
5879 # Received SIGHUP, so reconfigure
5880 }</code></pre>
5881 </div></div>
5882 </div>
5887 point value less than one to sleep for less than a second, or an
5888 integer to sleep for one or more seconds.</p></div>
5889 </div>
5893 <div class="paragraph"><p>Read file <code><em>fileName</em></code> and pass the contents to the Tcl interpreter
5894 as a sequence of commands to execute in the normal fashion. The return
5895 value of <a href="#_source"><strong><code>source</code></strong></a> is the return value of the last command executed
5896 from the file. If an error occurs in executing the contents of the
5897 file, then the <a href="#_source"><strong><code>source</code></strong></a> command will return that error.</p></div>
5898 <div class="paragraph"><p>If a <a href="#_return"><strong><code>return</code></strong></a> command is invoked from within the file, the remainder of
5899 the file will be skipped and the <a href="#_source"><strong><code>source</code></strong></a> command will return
5900 normally with the result from the <a href="#_return"><strong><code>return</code></strong></a> command.</p></div>
5901 </div>
5904 <div class="paragraph"><p><code><strong>split</strong> <em>string ?splitChars?</em></code></p></div>
5905 <div class="paragraph"><p>Returns a list created by splitting <code><em>string</em></code> at each character
5906 that is in the <code><em>splitChars</em></code> argument.</p></div>
5908 characters from <code><em>string</em></code> between instances of the
5909 characters in <code><em>splitChars</em></code>.</p></div>
5910 <div class="paragraph"><p>Empty list elements will be generated if <code><em>string</em></code> contains
5911 adjacent characters in <code><em>splitChars</em></code>, or if the first or last
5912 character of <code><em>string</em></code> is in <code><em>splitChars</em></code>.</p></div>
5913 <div class="paragraph"><p>If <code><em>splitChars</em></code> is an empty string then each character of
5914 <code><em>string</em></code> becomes a separate element of the result list.</p></div>
5915 <div class="paragraph"><p><code><em>splitChars</em></code> defaults to the standard white-space characters.
5916 For example,</p></div>
5920 </div></div>
5925 </div></div>
5927 </div>
5930 <div class="paragraph"><p><code><strong>stackdump</strong> <em>stacktrace</em></code></p></div>
5932 </div>
5936 <div class="paragraph"><p>Returns a live stack trace as a list of <code>proc file line proc file line ...</code>.
5937 Iteratively uses <a href="#_info"><strong><code>info</code></strong></a> <code>frame</code> to create the stack trace. This stack trace is in the
5938 same form as produced by <a href="#_catch"><strong><code>catch</code></strong></a> and <a href="#_info"><strong><code>info</code></strong></a> <code>stacktrace</code></p></div>
5939 <div class="paragraph"><p>See also <a href="#_stackdump"><strong><code>stackdump</code></strong></a>.</p></div>
5940 </div>
5943 <div class="paragraph"><p><code><strong>string</strong> <em>option arg ?arg ...?</em></code></p></div>
5944 <div class="paragraph"><p>Perform one of several string operations, depending on <code><em>option</em></code>.
5945 The legal options (which may be abbreviated) are:</p></div>
5948 <code><strong>string bytelength</strong> <em>string</em></code>
5949 </dt>
5950 <dd>
5951 <p>
5952 Returns the length of the string in bytes. This will return
5953 the same value as <a href="#_string"><strong><code>string</code></strong></a> <code>length</code> if UTF-8 support is not enabled,
5954 or if the string is composed entirely of ASCII characters.
5955 See UTF-8 AND UNICODE.
5956 </p>
5957 </dd>
5959 <code><strong>string byterange</strong> <em>string first last</em></code>
5960 </dt>
5961 <dd>
5962 <p>
5963 Like <a href="#_string"><strong><code>string</code></strong></a> <code>range</code> except works on bytes rather than characters.
5964 These commands are identical if UTF-8 support is not enabled.
5965 </p>
5966 </dd>
5968 <code><strong>string cat</strong> <em>?string1 string2 ...?</em></code>
5969 </dt>
5970 <dd>
5971 <p>
5972 Concatenates the given strings into a single string.
5973 </p>
5974 </dd>
5976 <code><strong>string compare ?-nocase?</strong> ?<strong>-length</strong> <em>len? string1 string2</em></code>
5977 </dt>
5978 <dd>
5979 <p>
5980 Perform a character-by-character comparison of strings <code><em>string1</em></code> and
5981 <code><em>string2</em></code> in the same way as the C <em>strcmp</em> procedure. Return
5982 -1, 0, or 1, depending on whether <code><em>string1</em></code> is lexicographically
5983 less than, equal to, or greater than <code><em>string2</em></code>. If <code>-length</code>
5984 is specified, then only the first <code><em>len</em></code> characters are used
5985 in the comparison. If <code><em>len</em></code> is negative, it is ignored.
5986 Performs a case-insensitive comparison if <code>-nocase</code> is specified.
5987 </p>
5988 </dd>
5990 <code><strong>string equal ?-nocase?</strong> <em>?<strong>-length</strong> len?</em> <em>string1 string2</em></code>
5991 </dt>
5992 <dd>
5993 <p>
5994 Returns 1 if the strings are equal, or 0 otherwise. If <code>-length</code>
5995 is specified, then only the first <code><em>len</em></code> characters are used
5996 in the comparison. If <code><em>len</em></code> is negative, it is ignored.
5997 Performs a case-insensitive comparison if <code>-nocase</code> is specified.
5998 </p>
5999 </dd>
6001 <code><strong>string first</strong> <em>string1 string2 ?firstIndex?</em></code>
6002 </dt>
6003 <dd>
6004 <p>
6005 Search <code><em>string2</em></code> for a sequence of characters that exactly match
6006 the characters in <code><em>string1</em></code>. If found, return the index of the
6007 first character in the first such match within <code><em>string2</em></code>. If not
6008 found, return -1. If <code><em>firstIndex</em></code> is specified, matching will start
6009 from <code><em>firstIndex</em></code> of <code><em>string1</em></code>.
6010 </p>
6011 </dd>
6014 </dt>
6015 <dd>
6016 <p>
6017 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for <code><em>firstIndex</em></code>.
6018 </p>
6019 </dd>
6021 <code><strong>string index</strong> <em>string charIndex</em></code>
6022 </dt>
6023 <dd>
6024 <p>
6025 Returns the <code><em>charIndex</em></code><em>th character of the <code>'string</em></code>
6026 argument. A <code><em>charIndex</em></code> of 0 corresponds to the first
6027 character of the string.
6028 If <code><em>charIndex</em></code> is less than 0 or greater than
6029 or equal to the length of the string then an empty string is
6030 returned.
6031 </p>
6032 </dd>
6035 </dt>
6036 <dd>
6037 <p>
6038 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for <code><em>charIndex</em></code>.
6039 </p>
6040 </dd>
6042 <code><strong>string is</strong> <em>class</em> ?<strong>-strict</strong>? <em>string</em></code>
6043 </dt>
6044 <dd>
6045 <p>
6046 Returns 1 if <code><em>string</em></code> is a valid member of the specified character
6047 class, otherwise returns 0. If <code>-strict</code> is specified, then an
6048 empty string returns 0, otherwise an empty string will return 1
6049 on any class. The following character classes are recognized
6050 (the class name can be abbreviated):
6051 </p>
6052 </dd>
6055 </dt>
6056 <dd>
6059 <code>alnum</code>
6060 </dt>
6061 <dd>
6062 <p>
6063 Any alphabet or digit character.
6064 </p>
6065 </dd>
6067 <code>alpha</code>
6068 </dt>
6069 <dd>
6070 <p>
6071 Any alphabet character.
6072 </p>
6073 </dd>
6075 <code>ascii</code>
6076 </dt>
6077 <dd>
6078 <p>
6079 Any character with a value less than 128 (those that are in the 7-bit ascii range).
6080 </p>
6081 </dd>
6083 <code>control</code>
6084 </dt>
6085 <dd>
6086 <p>
6087 Any control character.
6088 </p>
6089 </dd>
6091 <code>digit</code>
6092 </dt>
6093 <dd>
6094 <p>
6095 Any digit character.
6096 </p>
6097 </dd>
6099 <code>double</code>
6100 </dt>
6101 <dd>
6102 <p>
6103 Any of the valid forms for a double in Tcl, with optional surrounding whitespace.
6104 In case of under/overflow in the value, 0 is returned.
6105 </p>
6106 </dd>
6108 <code>graph</code>
6109 </dt>
6110 <dd>
6111 <p>
6112 Any printing character, except space.
6113 </p>
6114 </dd>
6116 <code>integer</code>
6117 </dt>
6118 <dd>
6119 <p>
6120 Any of the valid string formats for an integer value in Tcl, with optional surrounding whitespace.
6121 </p>
6122 </dd>
6124 <code>lower</code>
6125 </dt>
6126 <dd>
6127 <p>
6128 Any lower case alphabet character.
6129 </p>
6130 </dd>
6132 <code>print</code>
6133 </dt>
6134 <dd>
6135 <p>
6136 Any printing character, including space.
6137 </p>
6138 </dd>
6140 <code>punct</code>
6141 </dt>
6142 <dd>
6143 <p>
6144 Any punctuation character.
6145 </p>
6146 </dd>
6148 <code>space</code>
6149 </dt>
6150 <dd>
6151 <p>
6152 Any space character.
6153 </p>
6154 </dd>
6156 <code>upper</code>
6157 </dt>
6158 <dd>
6159 <p>
6160 Any upper case alphabet character.
6161 </p>
6162 </dd>
6164 <code>xdigit</code>
6165 </dt>
6166 <dd>
6167 <p>
6168 Any hexadecimal digit character ([0-9A-Fa-f]).
6169 </p>
6170 </dd>
6171 </dl></div>
6172 </dd>
6175 </dt>
6176 <dd>
6177 <p>
6178 Note that string classification does <code><em>not</em></code> respect UTF-8. See UTF-8 AND UNICODE
6179 </p>
6180 </dd>
6182 <code><strong>string last</strong> <em>string1 string2 ?lastIndex?</em></code>
6183 </dt>
6184 <dd>
6185 <p>
6186 Search <code><em>string2</em></code> for a sequence of characters that exactly match
6187 the characters in <code><em>string1</em></code>. If found, return the index of the
6188 first character in the last such match within <code><em>string2</em></code>. If there
6189 is no match, then return -1. If <code><em>lastIndex</em></code> is specified, only characters
6190 up to <code><em>lastIndex</em></code> of <code><em>string2</em></code> will be considered in the match.
6191 </p>
6192 </dd>
6195 </dt>
6196 <dd>
6197 <p>
6198 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for <code><em>lastIndex</em></code>.
6199 </p>
6200 </dd>
6202 <code><strong>string length</strong> <em>string</em></code>
6203 </dt>
6204 <dd>
6205 <p>
6206 Returns a decimal string giving the number of characters in <code><em>string</em></code>.
6207 If UTF-8 support is enabled, this may be different than the number of bytes.
6208 See UTF-8 AND UNICODE
6209 </p>
6210 </dd>
6212 <code><strong>string map ?-nocase?</strong> <em>mapping string</em></code>
6213 </dt>
6214 <dd>
6215 <p>
6216 Replaces substrings in <code><em>string</em></code> based on the key-value pairs in
6217 <code><em>mapping</em></code>, which is a list of <code>key value key value ...</code> as in the form
6218 returned by <a href="#_array"><strong><code>array</code></strong></a> <code>get</code>. Each instance of a key in the string will be
6219 replaced with its corresponding value. If <code>-nocase</code> is specified, then
6220 matching is done without regard to case differences. Both key and value may
6221 be multiple characters. Replacement is done in an ordered manner, so the
6222 key appearing first in the list will be checked first, and so on. <code><em>string</em></code> is
6223 only iterated over once, so earlier key replacements will have no affect for
6224 later key matches. For example,
6225 </p>
6228 <pre><code>string map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc</code></pre>
6229 </div></div>
6230 </dd>
6233 </dt>
6234 <dd>
6235 <p>
6236 will return the string <code>01321221</code>.
6237 </p>
6238 </dd>
6241 </dt>
6242 <dd>
6243 <p>
6244 Note that if an earlier key is a prefix of a later one, it will completely mask the later
6245 one. So if the previous example is reordered like this,
6246 </p>
6249 <pre><code>string map {1 0 ab 2 a 3 abc 1} 1abcaababcabababc</code></pre>
6250 </div></div>
6251 </dd>
6254 </dt>
6255 <dd>
6256 <p>
6257 it will return the string <code>02c322c222c</code>.
6258 </p>
6259 </dd>
6261 <code><strong>string match ?-nocase?</strong> <em>pattern string</em></code>
6262 </dt>
6263 <dd>
6264 <p>
6265 See if <code><em>pattern</em></code> matches <code><em>string</em></code>; return 1 if it does, 0
6266 if it doesn’t. Matching is done in a fashion similar to that
6267 used by the C-shell. For the two strings to match, their contents
6268 must be identical except that the following special sequences
6269 may appear in <code><em>pattern</em></code>:
6270 </p>
6273 <code>*</code>
6274 </dt>
6275 <dd>
6276 <p>
6277 Matches any sequence of characters in <code><em>string</em></code>,
6278 including a null string.
6279 </p>
6280 </dd>
6282 <code>?</code>
6283 </dt>
6284 <dd>
6285 <p>
6286 Matches any single character in <code><em>string</em></code>.
6287 </p>
6288 </dd>
6290 <code>[<em>chars</em>]</code>
6291 </dt>
6292 <dd>
6293 <p>
6294 Matches any character in the set given by <code><em>chars</em></code>.
6295 If a sequence of the form <code><em>x-y</em></code> appears in <code><em>chars</em></code>,
6296 then any character between <code><em>x</em></code> and <code><em>y</em></code>, inclusive,
6297 will match.
6298 </p>
6299 </dd>
6301 <code>\x</code>
6302 </dt>
6303 <dd>
6304 <p>
6305 Matches the single character <code><em>x</em></code>. This provides a way of
6306 avoiding the special interpretation of the characters <code>\*?[]</code>
6307 in <code><em>pattern</em></code>.
6308 </p>
6309 </dd>
6310 </dl></div>
6311 </dd>
6314 </dt>
6315 <dd>
6316 <p>
6317 Performs a case-insensitive comparison if <code>-nocase</code> is specified.
6318 </p>
6319 </dd>
6321 <code><strong>string range</strong> <em>string first last</em></code>
6322 </dt>
6323 <dd>
6324 <p>
6325 Returns a range of consecutive characters from <code><em>string</em></code>, starting
6326 with the character whose index is <code><em>first</em></code> and ending with the
6327 character whose index is <code><em>last</em></code>. An index of 0 refers to the
6328 first character of the string.
6329 </p>
6330 </dd>
6333 </dt>
6334 <dd>
6335 <p>
6336 See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for <code><em>first</em></code> and <code><em>last</em></code>.
6337 </p>
6338 </dd>
6341 </dt>
6342 <dd>
6343 <p>
6344 If <code><em>first</em></code> is less than zero then it is treated as if it were zero, and
6345 if <code><em>last</em></code> is greater than or equal to the length of the string then
6346 it is treated as if it were <code>end</code>. If <code><em>first</em></code> is greater than
6347 <code><em>last</em></code> then an empty string is returned.
6348 </p>
6349 </dd>
6351 <code><strong>string repeat</strong> <em>string count</em></code>
6352 </dt>
6353 <dd>
6354 <p>
6355 Returns a new string consisting of <code><em>string</em></code> repeated <code><em>count</em></code> times.
6356 </p>
6357 </dd>
6359 <code><strong>string replace</strong> <em>string first last ?newstring?</em></code>
6360 </dt>
6361 <dd>
6362 <p>
6363 Removes a range of consecutive characters from <code><em>string</em></code>, starting
6364 with the character whose index is <code><em>first</em></code> and ending with the
6365 character whose index is <code><em>last</em></code>. If <code><em>newstring</em></code> is specified,
6366 then it is placed in the removed character range. If <code><em>first</em></code> is
6367 less than zero then it is treated as if it were zero, and if <code><em>last</em></code>
6368 is greater than or equal to the length of the string then it is
6369 treated as if it were <code>end</code>. If <code><em>first</em></code> is greater than <code><em>last</em></code>
6370 or the length of the initial string, or <code><em>last</em></code> is less than 0,
6371 then the initial string is returned untouched.
6372 </p>
6373 </dd>
6375 <code><strong>string reverse</strong> <em>string</em></code>
6376 </dt>
6377 <dd>
6378 <p>
6379 Returns a string that is the same length as <code><em>string</em></code> but
6380 with its characters in the reverse order.
6381 </p>
6382 </dd>
6384 <code><strong>string tolower</strong> <em>string</em></code>
6385 </dt>
6386 <dd>
6387 <p>
6388 Returns a value equal to <code><em>string</em></code> except that all upper case
6389 letters have been converted to lower case.
6390 </p>
6391 </dd>
6393 <code><strong>string totitle</strong> <em>string</em></code>
6394 </dt>
6395 <dd>
6396 <p>
6397 Returns a value equal to <code><em>string</em></code> except that the first character
6398 is converted to title case (or upper case if there is no UTF-8 titlecase variant)
6399 and all remaining characters have been converted to lower case.
6400 </p>
6401 </dd>
6403 <code><strong>string toupper</strong> <em>string</em></code>
6404 </dt>
6405 <dd>
6406 <p>
6407 Returns a value equal to <code><em>string</em></code> except that all lower case
6408 letters have been converted to upper case.
6409 </p>
6410 </dd>
6412 <code><strong>string trim</strong> <em>string ?chars?</em></code>
6413 </dt>
6414 <dd>
6415 <p>
6416 Returns a value equal to <code><em>string</em></code> except that any leading
6417 or trailing characters from the set given by <code><em>chars</em></code> are
6418 removed.
6419 If <code><em>chars</em></code> is not specified then white space is removed
6420 (spaces, tabs, newlines, and carriage returns).
6421 </p>
6422 </dd>
6424 <code><strong>string trimleft</strong> <em>string ?chars?</em></code>
6425 </dt>
6426 <dd>
6427 <p>
6428 Returns a value equal to <code><em>string</em></code> except that any
6429 leading characters from the set given by <code><em>chars</em></code> are
6430 removed.
6431 If <code><em>chars</em></code> is not specified then white space is removed
6432 (spaces, tabs, newlines, and carriage returns).
6433 </p>
6434 </dd>
6436 <code><strong>string trimright</strong> <em>string ?chars?</em></code>
6437 </dt>
6438 <dd>
6439 <p>
6440 Returns a value equal to <code><em>string</em></code> except that any
6441 trailing characters from the set given by <code><em>chars</em></code> are
6442 removed.
6443 If <code><em>chars</em></code> is not specified then white space is removed
6444 (spaces, tabs, newlines, and carriage returns).
6445 Null characters are always removed.
6446 </p>
6447 </dd>
6448 </dl></div>
6449 </div>
6452 <div class="paragraph"><p><code><strong>subst ?-nobackslashes? ?-nocommands? ?-novariables?</strong> <em>string</em></code></p></div>
6454 and backslash substitutions on its string argument and returns the
6455 fully-substituted result. The substitutions are performed in exactly
6456 the same way as for Tcl commands. As a result, the string argument
6457 is actually substituted twice, once by the Tcl parser in the usual
6458 fashion for Tcl commands, and again by the subst command.</p></div>
6459 <div class="paragraph"><p>If any of the <code>-nobackslashes</code>, <code>-nocommands</code>, or <code>-novariables</code> are
6460 specified, then the corresponding substitutions are not performed.
6461 For example, if <code>-nocommands</code> is specified, no command substitution
6462 is performed: open and close brackets are treated as ordinary
6463 characters with no special interpretation.</p></div>
6464 <div class="paragraph"><p><strong>Note</strong>: when it performs its substitutions, subst does not give any
6465 special treatment to double quotes or curly braces. For example,
6466 the following script returns <code>xyz {44}</code>, not <code>xyz {$a}</code>.</p></div>
6469 <pre><code>set a 44
6470 subst {xyz {$a}}</code></pre>
6471 </div></div>
6472 </div>
6475 <div class="paragraph"><p><code><strong>switch</strong> <em>?options? string pattern body ?pattern body ...?</em></code></p></div>
6476 <div class="paragraph"><p><code><strong>switch</strong> <em>?options? string {pattern body ?pattern body ...?}</em></code></p></div>
6477 <div class="paragraph"><p>The <a href="#_switch"><strong><code>switch</code></strong></a> command matches its string argument against each of
6478 the pattern arguments in order. As soon as it finds a pattern that
6479 matches string it evaluates the following body and returns the
6480 result of that evaluation. If the last pattern argument is default
6481 then it matches anything. If no pattern argument matches string and
6482 no default is given, then the <a href="#_switch"><strong><code>switch</code></strong></a> command returns an empty string.
6483 If the initial arguments to switch start with - then they are treated
6484 as options. The following options are currently supported:</p></div>
6487 <code>-exact</code>
6488 </dt>
6489 <dd>
6490 <p>
6491 Use exact matching when comparing string to a
6492 pattern. This is the default.
6493 </p>
6494 </dd>
6496 <code>-glob</code>
6497 </dt>
6498 <dd>
6499 <p>
6500 When matching string to the patterns, use glob-style
6501 matching (i.e. the same as implemented by the string
6502 match command).
6503 </p>
6504 </dd>
6506 <code>-regexp</code>
6507 </dt>
6508 <dd>
6509 <p>
6510 When matching string to the patterns, use regular
6511 expression matching (i.e. the same as implemented
6512 by the regexp command).
6513 </p>
6514 </dd>
6516 <code>-command <em>commandname</em></code>
6517 </dt>
6518 <dd>
6519 <p>
6520 When matching string to the patterns, use the given command, which
6521 must be a single word. The command is invoked as
6522 <em>commandname pattern string</em>, or <em>commandname -nocase pattern string</em>
6523 and must return 1 if matched, or 0 if not.
6524 </p>
6525 </dd>
6527 <code>--</code>
6528 </dt>
6529 <dd>
6530 <p>
6531 Marks the end of options. The argument following
6532 this one will be treated as string even if it starts
6533 with a <code>-</code>.
6534 </p>
6535 </dd>
6536 </dl></div>
6538 first uses a separate argument for each of the patterns and commands;
6539 this form is convenient if substitutions are desired on some of the
6540 patterns or commands. The second form places all of the patterns
6541 and commands together into a single argument; the argument must
6542 have proper list structure, with the elements of the list being the
6543 patterns and commands. The second form makes it easy to construct
6544 multi-line <a href="#_switch"><strong><code>switch</code></strong></a> commands, since the braces around the whole list
6545 make it unnecessary to include a backslash at the end of each line.
6546 Since the pattern arguments are in braces in the second form, no
6547 command or variable substitutions are performed on them; this makes
6548 the behaviour of the second form different than the first form in
6549 some cases.</p></div>
6550 <div class="paragraph"><p>If a body is specified as <code>-</code> it means that the body for the next
6551 pattern should also be used as the body for this pattern (if the
6552 next pattern also has a body of <code>-</code> then the body after that is
6553 used, and so on). This feature makes it possible to share a single
6554 body among several patterns.</p></div>
6555 <div class="paragraph"><p>Below are some examples of <a href="#_switch"><strong><code>switch</code></strong></a> commands:</p></div>
6558 <pre><code>switch abc a - b {format 1} abc {format 2} default {format 3}</code></pre>
6559 </div></div>
6563 <pre><code>switch -regexp aaab {
6564 ^a.*b$ -
6565 b {format 1}
6566 a* {format 2}
6567 default {format 3}
6568 }</code></pre>
6569 </div></div>
6573 <pre><code>switch xyz {
6574 a -
6575 b {format 1}
6576 a* {format 2}
6577 default {format 3}
6578 }</code></pre>
6579 </div></div>
6581 </div>
6584 <div class="paragraph"><p><code><strong>tailcall</strong> <em>cmd ?arg...?</em></code></p></div>
6585 <div class="paragraph"><p>The <a href="#_tailcall"><strong><code>tailcall</code></strong></a> command provides an optimised way of invoking a command whilst replacing
6586 the current call frame. This is similar to <em>exec</em> in Bourne Shell.</p></div>
6587 <div class="paragraph"><p>The following are identical except the first immediately replaces the current call frame.</p></div>
6590 <pre><code>tailcall a b c</code></pre>
6591 </div></div>
6594 <pre><code>return [uplevel 1 [list a b c]]</code></pre>
6595 </div></div>
6596 <div class="paragraph"><p><a href="#_tailcall"><strong><code>tailcall</code></strong></a> is useful as a dispatch mechanism:</p></div>
6599 <pre><code>proc a {cmd args} {
6600 tailcall sub_$cmd {*}$args
6601 }
6602 proc sub_cmd1 ...
6603 proc sub_cmd2 ...</code></pre>
6604 </div></div>
6605 </div>
6611 <code><em>fileId</em></code>.</p></div>
6612 <div class="paragraph"><p><code><em>fileId</em></code> must have been the return value from a previous call to
6613 <a href="#_open"><strong><code>open</code></strong></a>, or it may be <code>stdin</code>, <code>stdout</code>, or <code>stderr</code> to refer to one
6614 of the standard I/O channels.</p></div>
6615 </div>
6619 <div class="paragraph"><p>This command throws an exception (return) code along with an optional message.
6620 This command is mostly for convenient usage with <a href="#_try"><strong><code>try</code></strong></a>.</p></div>
6621 <div class="paragraph"><p>The command <code>throw break</code> is equivalent to <code>break</code>.
6622 The command <code>throw 20 message</code> can be caught with an <code>on 20 ...</code> clause to <a href="#_try"><strong><code>try</code></strong></a>.</p></div>
6623 </div>
6626 <div class="paragraph"><p><code><strong>time</strong> <em>command ?count?</em></code></p></div>
6627 <div class="paragraph"><p>This command will call the Tcl interpreter <code><em>count</em></code>
6628 times to execute <code><em>command</em></code> (or once if <code><em>count</em></code> isn’t
6629 specified). It will then return a string of the form</p></div>
6632 <pre><code>503 microseconds per iteration</code></pre>
6633 </div></div>
6635 in microseconds.</p></div>
6637 </div>
6640 <div class="paragraph"><p><code><strong>try</strong> <em>?catchopts? tryscript</em> ?<strong>on</strong> <em>returncodes {?resultvar? ?optsvar?} handlerscript ...</em>? ?<strong>finally</strong> <em>finalscript</em>?</code></p></div>
6641 <div class="paragraph"><p>The <a href="#_try"><strong><code>try</code></strong></a> command is provided as a convenience for exception handling.</p></div>
6642 <div class="paragraph"><p>This interpeter first evaluates <code><em>tryscript</em></code> under the effect of the catch
6643 options <code><em>catchopts</em></code> (e.g. <code>-signal -noexit --</code>, see <a href="#_catch"><strong><code>catch</code></strong></a>).</p></div>
6644 <div class="paragraph"><p>It then evaluates the script for the first matching <em>on</em> handler
6645 (there many be zero or more) based on the return code from the <a href="#_try"><strong><code>try</code></strong></a>
6646 section. For example a normal <code>JIM_ERR</code> error will be matched by
6647 an <em>on error</em> handler.</p></div>
6648 <div class="paragraph"><p>Finally, any <code><em>finalscript</em></code> is evaluated.</p></div>
6649 <div class="paragraph"><p>The result of this command is the result of <code><em>tryscript</em></code>, except in the
6650 case where an exception occurs in a matching <em>on</em> handler script or the <em>finally</em> script,
6651 in which case the result is this new exception.</p></div>
6652 <div class="paragraph"><p>The specified <code><em>returncodes</em></code> is a list of return codes either as names (<em>ok</em>, <em>error</em>, <em>break</em>, etc.)
6653 or as integers.</p></div>
6654 <div class="paragraph"><p>If <code><em>resultvar</em></code> and <code><em>optsvar</em></code> are specified, they are set as for <a href="#_catch"><strong><code>catch</code></strong></a> before evaluating
6655 the matching handler.</p></div>
6659 <pre><code>set f [open input]
6660 try -signal {
6661 process $f
6662 } on {continue break} {} {
6664 } on error {msg opts} {
6666 return {*}$opts $msg
6667 } on signal sig {
6669 } finally {
6670 $f close
6671 }</code></pre>
6672 </div></div>
6673 <div class="paragraph"><p>If break, continue or error are raised, they are dealt with by the matching
6674 handler.</p></div>
6675 <div class="paragraph"><p>In any case, the file will be closed via the <em>finally</em> clause.</p></div>
6676 <div class="paragraph"><p>See also <a href="#_throw"><strong><code>throw</code></strong></a>, <a href="#_catch"><strong><code>catch</code></strong></a>, <a href="#_return"><strong><code>return</code></strong></a>, <a href="#_error"><strong><code>error</code></strong></a>.</p></div>
6677 </div>
6680 <div class="paragraph"><p><code><strong>unknown</strong> <em>cmdName ?arg arg …?</em></code></p></div>
6681 <div class="paragraph"><p>This command doesn’t actually exist as part of Tcl, but Tcl will
6682 invoke it if it does exist.</p></div>
6684 is not a defined command, then Tcl checks for the existence of
6687 error.</p></div>
6688 <div class="paragraph"><p>If the <a href="#_unknown"><strong><code>unknown</code></strong></a> command exists, then it is invoked with
6689 arguments consisting of the fully-substituted name and arguments
6690 for the original non-existent command.</p></div>
6691 <div class="paragraph"><p>The <a href="#_unknown"><strong><code>unknown</code></strong></a> command typically does things like searching
6692 through library directories for a command procedure with the name
6693 <code><em>cmdName</em></code>, or expanding abbreviated command names to full-length,
6694 or automatically executing unknown commands as UNIX sub-processes.</p></div>
6695 <div class="paragraph"><p>In some cases (such as expanding abbreviations) <a href="#_unknown"><strong><code>unknown</code></strong></a> will
6696 change the original command slightly and then (re-)execute it.
6697 The result of the <a href="#_unknown"><strong><code>unknown</code></strong></a> command is used as the result for
6698 the original non-existent command.</p></div>
6699 </div>
6702 <div class="paragraph"><p><code><strong>unset ?-nocomplain? ?--?</strong> <em>?name name …?</em></code></p></div>
6704 Each <code><em>name</em></code> is a variable name, specified in any of the
6705 ways acceptable to the <a href="#_set"><strong><code>set</code></strong></a> command.</p></div>
6706 <div class="paragraph"><p>If a <code><em>name</em></code> refers to an element of an array, then that
6707 element is removed without affecting the rest of the array.</p></div>
6708 <div class="paragraph"><p>If a <code><em>name</em></code> consists of an array name with no parenthesized
6709 index, then the entire array is deleted.</p></div>
6710 <div class="paragraph"><p>The <a href="#_unset"><strong><code>unset</code></strong></a> command returns an empty string as result.</p></div>
6711 <div class="paragraph"><p>An error occurs if any of the variables doesn’t exist, unless <em>-nocomplain</em>
6712 is specified. The <em>--</em> argument may be specified to stop option processing
6713 in case the variable name may be <em>-nocomplain</em>.</p></div>
6714 </div>
6717 <div class="paragraph"><p><code><strong>upcall</strong> <em>command ?args …?</em></code></p></div>
6718 <div class="paragraph"><p>May be used from within a proc defined as <a href="#_local"><strong><code>local</code></strong></a> <a href="#_proc"><strong><code>proc</code></strong></a> in order to call
6719 the previous, hidden version of the same command.</p></div>
6720 <div class="paragraph"><p>If there is no previous definition of the command, an error is returned.</p></div>
6721 </div>
6724 <div class="paragraph"><p><code><strong>uplevel</strong> <em>?level? command ?command …?</em></code></p></div>
6725 <div class="paragraph"><p>All of the <code><em>command</em></code> arguments are concatenated as if they had
6726 been passed to <a href="#_concat"><strong><code>concat</code></strong></a>; the result is then evaluated in the
6727 variable context indicated by <code><em>level</em></code>. <a href="#_uplevel"><strong><code>uplevel</code></strong></a> returns
6728 the result of that evaluation. If <code><em>level</em></code> is an integer, then
6729 it gives a distance (up the procedure calling stack) to move before
6730 executing the command. If <code><em>level</em></code> consists of <code>#</code> followed by
6731 a number then the number gives an absolute level number. If <code><em>level</em></code>
6732 is omitted then it defaults to <code>1</code>. <code><em>level</em></code> cannot be
6733 defaulted if the first <code><em>command</em></code> argument starts with a digit or <code>#</code>.</p></div>
6735 from top-level, and that it called <em>b</em>, and that <em>b</em> called <em>c</em>.
6736 Suppose that <em>c</em> invokes the <a href="#_uplevel"><strong><code>uplevel</code></strong></a> command. If <code><em>level</em></code>
6737 is <code>1</code> or <code>#2</code> or omitted, then the command will be executed
6738 in the variable context of <em>b</em>. If <code><em>level</em></code> is <code>2</code> or <code>#1</code>
6739 then the command will be executed in the variable context of <em>a</em>.</p></div>
6740 <div class="paragraph"><p>If <code><em>level</em></code> is <em>3</em> or <code>#0</code> then the command will be executed
6741 at top-level (only global variables will be visible).
6742 The <a href="#_uplevel"><strong><code>uplevel</code></strong></a> command causes the invoking procedure to disappear
6743 from the procedure calling stack while the command is being executed.
6744 In the above example, suppose <em>c</em> invokes the command</p></div>
6747 <pre><code>uplevel 1 {set x 43; d}</code></pre>
6748 </div></div>
6749 <div class="paragraph"><p>where <em>d</em> is another Tcl procedure. The <a href="#_set"><strong><code>set</code></strong></a> command will
6750 modify the variable <em>x</em> in <em>b’s context, and 'd</em> will execute
6751 at level 3, as if called from <em>b</em>. If it in turn executes
6752 the command</p></div>
6755 <pre><code>uplevel {set x 42}</code></pre>
6756 </div></div>
6757 <div class="paragraph"><p>then the <a href="#_set"><strong><code>set</code></strong></a> command will modify the same variable <em>x</em> in <em>b’s
6758 context: the procedure 'c</em> does not appear to be on the call stack
6759 when <em>d</em> is executing. The command <a href="#_info"><strong><code>info</code></strong></a> <code>level</code> may
6760 be used to obtain the level of the current procedure.</p></div>
6761 <div class="paragraph"><p><a href="#_uplevel"><strong><code>uplevel</code></strong></a> makes it possible to implement new control
6762 constructs as Tcl procedures (for example, <a href="#_uplevel"><strong><code>uplevel</code></strong></a> could
6763 be used to implement the <a href="#_while"><strong><code>while</code></strong></a> construct as a Tcl procedure).</p></div>
6764 </div>
6767 <div class="paragraph"><p><code><strong>upvar</strong> <em>?level? otherVar myVar ?otherVar myVar …?</em></code></p></div>
6769 procedure to refer to variables in an enclosing procedure call or
6770 to global variables.</p></div>
6771 <div class="paragraph"><p><code><em>level</em></code> may have any of the forms permitted for the <a href="#_uplevel"><strong><code>uplevel</code></strong></a>
6772 command, and may be omitted if the first letter of the first <code><em>otherVar</em></code>
6773 isn’t <code>#</code> or a digit (it defaults to <em>1</em>).</p></div>
6774 <div class="paragraph"><p>For each <code><em>otherVar</em></code> argument, <a href="#_upvar"><strong><code>upvar</code></strong></a> makes the variable
6775 by that name in the procedure frame given by <code><em>level</em></code> (or at
6776 global level, if <code><em>level</em></code> is <code>#0</code>) accessible
6777 in the current procedure by the name given in the corresponding
6778 <code><em>myVar</em></code> argument.</p></div>
6779 <div class="paragraph"><p>The variable named by <code><em>otherVar</em></code> need not exist at the time of the
6780 call; it will be created the first time <code><em>myVar</em></code> is referenced, just like
6781 an ordinary variable.</p></div>
6782 <div class="paragraph"><p><a href="#_upvar"><strong><code>upvar</code></strong></a> may only be invoked from within procedures.</p></div>
6783 <div class="paragraph"><p><a href="#_upvar"><strong><code>upvar</code></strong></a> returns an empty string.</p></div>
6784 <div class="paragraph"><p>The <a href="#_upvar"><strong><code>upvar</code></strong></a> command simplifies the implementation of call-by-name
6785 procedure calling and also makes it easier to build new control constructs
6786 as Tcl procedures.
6787 For example, consider the following procedure:</p></div>
6790 <pre><code>proc add2 name {
6791 upvar $name x
6792 set x [expr $x+2]
6793 }</code></pre>
6794 </div></div>
6795 <div class="paragraph"><p><em>add2</em> is invoked with an argument giving the name of a variable,
6796 and it adds two to the value of that variable.
6797 Although <em>add2</em> could have been implemented using <a href="#_uplevel"><strong><code>uplevel</code></strong></a>
6798 instead of <a href="#_upvar"><strong><code>upvar</code></strong></a>, <a href="#_upvar"><strong><code>upvar</code></strong></a> makes it simpler for <em>add2</em>
6799 to access the variable in the caller’s procedure frame.</p></div>
6800 </div>
6804 <div class="paragraph"><p>The <code><em>while</em></code> command evaluates <code><em>test</em></code> as an expression
6805 (in the same way that <a href="#_expr"><strong><code>expr</code></strong></a> evaluates its argument).
6806 The value of the expression must be numeric; if it is non-zero
6807 then <code><em>body</em></code> is executed by passing it to the Tcl interpreter.</p></div>
6808 <div class="paragraph"><p>Once <code><em>body</em></code> has been executed then <code><em>test</em></code> is evaluated
6809 again, and the process repeats until eventually <code><em>test</em></code>
6810 evaluates to a zero numeric value. <a href="#_continue"><strong><code>continue</code></strong></a>
6811 commands may be executed inside <code><em>body</em></code> to terminate the current
6813 commands may be executed inside <code><em>body</em></code> to cause immediate
6814 termination of the <a href="#_while"><strong><code>while</code></strong></a> command.</p></div>
6815 <div class="paragraph"><p>The <a href="#_while"><strong><code>while</code></strong></a> command always returns an empty string.</p></div>
6816 </div>
6817 </div>
6818 </div>
6823 what options were selected when Jim Tcl was built.</p></div>
6828 <code><strong>os.fork</strong></code>
6829 </dt>
6830 <dd>
6831 <p>
6832 Invokes <em>fork(2)</em> and returns the result.
6833 </p>
6834 </dd>
6836 <code><strong>os.wait -nohang</strong> <em>pid</em></code>
6837 </dt>
6838 <dd>
6839 <p>
6840 Invokes waitpid(2), with WNOHANG if <code>-nohang</code> is specified.
6841 Returns a list of 3 elements.
6842 </p>
6845 <pre><code>{0 none 0} if -nohang is specified, and the process is still alive.</code></pre>
6846 </div></div>
6849 <pre><code>{-1 error <error-description>} if the process does not exist or has already been waited for.</code></pre>
6850 </div></div>
6853 <pre><code>{<pid> exit <exit-status>} if the process exited normally.</code></pre>
6854 </div></div>
6857 <pre><code>{<pid> signal <signal-number>} if the process terminated on a signal.</code></pre>
6858 </div></div>
6861 <pre><code>{<pid> other 0} otherwise (core dump, stopped, continued, etc.)</code></pre>
6862 </div></div>
6863 </dd>
6865 <code><strong>os.gethostname</strong></code>
6866 </dt>
6867 <dd>
6868 <p>
6869 Invokes <em>gethostname(3)</em> and returns the result.
6870 </p>
6871 </dd>
6873 <code><strong>os.getids</strong></code>
6874 </dt>
6875 <dd>
6876 <p>
6877 Returns the various user/group ids for the current process.
6878 </p>
6881 <pre><code>jim> os.getids
6882 uid 1000 euid 1000 gid 100 egid 100</code></pre>
6883 </div></div>
6884 </dd>
6886 <code><strong>os.uptime</strong></code>
6887 </dt>
6888 <dd>
6889 <p>
6890 Returns the number of seconds since system boot. See description of <em>uptime</em> in <em>sysinfo(2)</em>.
6891 </p>
6892 </dd>
6893 </dl></div>
6894 </div>
6895 </div>
6896 </div>
6901 <div class="paragraph"><p>See <a href="#_open"><strong><code>open</code></strong></a> and <a href="#_socket"><strong><code>socket</code></strong></a> for commands which return an I/O handle.</p></div>
6906 <code>$handle <strong>accept</strong> ?addrvar?</code>
6907 </dt>
6908 <dd>
6909 <p>
6910 Server socket only: Accept a connection and return stream.
6911 If <code><em>addrvar</em></code> is specified, the address of the connected client is stored
6912 in the named variable in the form <em>addr:port</em>. See <a href="#_socket"><strong><code>socket</code></strong></a> for details.
6913 </p>
6914 </dd>
6916 <code>$handle <strong>buffering none|line|full</strong></code>
6917 </dt>
6918 <dd>
6919 <p>
6920 Sets the buffering mode of the stream.
6921 </p>
6922 </dd>
6924 <code>$handle <strong>close</strong> ?r(ead)|w(rite)?</code>
6925 </dt>
6926 <dd>
6927 <p>
6928 Closes the stream.
6929 The two-argument form is a "half-close" on a socket. See the <code>shutdown(2)</code> man page.
6930 </p>
6931 </dd>
6933 <code>$handle <strong>copyto</strong> <em>tofd ?size?</em></code>
6934 </dt>
6935 <dd>
6936 <p>
6937 Copy bytes to the file descriptor <code><em>tofd</em></code>. If <code><em>size</em></code> is specified, at most
6938 that many bytes will be copied. Otherwise copying continues until the end
6939 of the input file. Returns the number of bytes actually copied.
6940 </p>
6941 </dd>
6943 <code>$handle <strong>eof</strong></code>
6944 </dt>
6945 <dd>
6946 <p>
6947 Returns 1 if stream is at eof
6948 </p>
6949 </dd>
6951 <code>$handle <strong>filename</strong></code>
6952 </dt>
6953 <dd>
6954 <p>
6955 Returns the original filename associated with the handle.
6956 Handles returned by <a href="#_socket"><strong><code>socket</code></strong></a> give the socket type instead of a filename.
6957 </p>
6958 </dd>
6960 <code>$handle <strong>flush</strong></code>
6961 </dt>
6962 <dd>
6963 <p>
6964 Flush the stream
6965 </p>
6966 </dd>
6968 <code>$handle <strong>gets</strong> <em>?var?</em></code>
6969 </dt>
6970 <dd>
6971 <p>
6972 Read one line and return it or store it in the var
6973 </p>
6974 </dd>
6976 <code>$handle <strong>isatty</strong></code>
6977 </dt>
6978 <dd>
6979 <p>
6980 Returns 1 if the stream is a tty device.
6981 </p>
6982 </dd>
6984 <code>$handle <strong>ndelay ?0|1?</strong></code>
6985 </dt>
6986 <dd>
6987 <p>
6988 Set O_NDELAY (if arg). Returns current/new setting.
6989 Note that in general ANSI I/O interacts badly with non-blocking I/O.
6990 Use with care.
6991 </p>
6992 </dd>
6994 <code>$handle <strong>puts ?-nonewline?</strong> <em>str</em></code>
6995 </dt>
6996 <dd>
6997 <p>
6998 Write the string, with newline unless -nonewline
6999 </p>
7000 </dd>
7002 <code>$handle <strong>read ?-nonewline?</strong> <em>?len?</em></code>
7003 </dt>
7004 <dd>
7005 <p>
7006 Read and return bytes from the stream. To eof if no len.
7007 </p>
7008 </dd>
7010 <code>$handle <strong>recvfrom</strong> <em>maxlen ?addrvar?</em></code>
7011 </dt>
7012 <dd>
7013 <p>
7014 Receives a message from the handle via recvfrom(2) and returns it.
7015 At most <code><em>maxlen</em></code> bytes are read.
7016 If <code><em>addrvar</em></code> is specified, the sending address of the message is stored in
7017 the named variable in the form <em>addr:port</em>. See <a href="#_socket"><strong><code>socket</code></strong></a> for details.
7018 </p>
7019 </dd>
7021 <code>$handle <strong>seek</strong> <em>offset</em> <strong>?start|current|end?</strong></code>
7022 </dt>
7023 <dd>
7024 <p>
7025 Seeks in the stream (default <em>current</em>)
7026 </p>
7027 </dd>
7029 <code>$handle <strong>sendto</strong> <em>str ?addr:?port</em></code>
7030 </dt>
7031 <dd>
7032 <p>
7033 Sends the string, <code><em>str</em></code>, to the given address via the socket using sendto(2).
7034 This is intended for udp/dgram sockets and may give an error or behave in unintended
7035 ways for other handle types.
7036 Returns the number of bytes written.
7037 </p>
7038 </dd>
7040 <code>$handle <strong>sync</strong></code>
7041 </dt>
7042 <dd>
7043 <p>
7044 Flush the stream, then fsync(2) to commit any changes to storage.
7045 Only available on platforms that support fsync(2).
7046 </p>
7047 </dd>
7049 <code>$handle <strong>tell</strong></code>
7050 </dt>
7051 <dd>
7052 <p>
7053 Returns the current seek position
7054 </p>
7055 </dd>
7057 <code>$handle <strong>ssl</strong> <strong>?-server cert priv?</strong></code>
7058 </dt>
7059 <dd>
7060 <p>
7061 Initiates a SSL/TLS session and returns a new stream
7062 </p>
7063 </dd>
7065 <code>$handle <strong>verify</strong></code>
7066 </dt>
7067 <dd>
7068 <p>
7069 Verifies the certificate of a SSL/TLS stream peer
7070 </p>
7071 </dd>
7073 <code><strong>load_ssl_certs</strong> <em>dir</em></code>
7074 </dt>
7075 <dd>
7076 <p>
7077 Loads SSL/TLS CA certificates for use during verification
7078 </p>
7079 </dd>
7080 </dl></div>
7081 </div>
7086 <code><strong>fconfigure</strong> <em>handle</em> <strong>?-blocking 0|1? ?-buffering noneline|full? ?-translation</strong> <em>mode</em>?</code>
7087 </dt>
7088 <dd>
7089 <p>
7090 For compatibility with Tcl, a limited form of the <a href="#_fconfigure"><strong><code>fconfigure</code></strong></a>
7091 command is supported.
7092 </p>
7094 <li>
7095 <p>
7096 <a href="#_fconfigure"><strong><code>fconfigure</code></strong></a> <code>... -blocking</code> maps to <a href="#_aio"><strong><code>aio</code></strong></a> <code>ndelay</code>
7097 </p>
7098 </li>
7099 <li>
7100 <p>
7101 <a href="#_fconfigure"><strong><code>fconfigure</code></strong></a> <code>... -buffering</code> maps to <a href="#_aio"><strong><code>aio</code></strong></a> <code>buffering</code>
7102 </p>
7103 </li>
7104 <li>
7105 <p>
7106 <a href="#_fconfigure"><strong><code>fconfigure</code></strong></a> <code>... -translation</code> is accepted but ignored
7107 </p>
7108 </li>
7109 </ul></div>
7110 </dd>
7111 </dl></div>
7112 </div>
7115 <div class="paragraph"><p>The following commands allow a script to be invoked when the given condition occurs.
7116 If no script is given, returns the current script. If the given script is the empty, the
7117 handler is removed.</p></div>
7120 <code>$handle <strong>readable</strong> <em>?readable-script?</em></code>
7121 </dt>
7122 <dd>
7123 <p>
7124 Sets or returns the script for when the socket is readable.
7125 </p>
7126 </dd>
7128 <code>$handle <strong>writable</strong> <em>?writable-script?</em></code>
7129 </dt>
7130 <dd>
7131 <p>
7132 Sets or returns the script for when the socket is writable.
7133 </p>
7134 </dd>
7136 <code>$handle <strong>onexception</strong> <em>?exception-script?</em></code>
7137 </dt>
7138 <dd>
7139 <p>
7140 Sets or returns the script for when oob data received.
7141 </p>
7142 </dd>
7143 </dl></div>
7144 <div class="paragraph"><p>For compatibility with <em>Tcl</em>, these may be prefixed with <code>fileevent</code>. e.g.</p></div>
7148 </dt>
7149 <dd>
7150 <p>
7151 <code>fileevent $handle <strong>readable</strong> <em>...</em></code>
7152 </p>
7153 </dd>
7154 </dl></div>
7155 <div class="paragraph"><p>Time-based execution is also available via the eventloop API.</p></div>
7158 <code><strong>after</strong> <em>ms</em></code>
7159 </dt>
7160 <dd>
7161 <p>
7162 Sleeps for the given number of milliseconds. No events are
7163 processed during this time.
7164 </p>
7165 </dd>
7167 <code><strong>after</strong> <em>ms</em>|<strong>idle</strong> <em>script ?script ...?</em></code>
7168 </dt>
7169 <dd>
7170 <p>
7171 The scripts are concatenated and executed after the given
7172 number of milliseconds have elapsed. If <em>idle</em> is specified,
7173 the script will run the next time the event loop is processed
7174 with <a href="#cmd_2"><strong><code>vwait</code></strong></a> or <a href="#cmd_2"><strong><code>update</code></strong></a>. The script is only run once and
7175 then removed. Returns an event id.
7176 </p>
7177 </dd>
7179 <code><strong>after cancel</strong> <em>id|command</em></code>
7180 </dt>
7181 <dd>
7182 <p>
7183 Cancels an <a href="#cmd_2"><strong><code>after</code></strong></a> event with the given event id or matching
7184 command (script). Returns the number of milliseconds
7185 remaining until the event would have fired. Returns the
7186 empty string if no matching event is found.
7187 </p>
7188 </dd>
7190 <code><strong>after info</strong> <em>?id?</em></code>
7191 </dt>
7192 <dd>
7193 <p>
7194 If <code><em>id</em></code> is not given, returns a list of current <a href="#cmd_2"><strong><code>after</code></strong></a>
7195 events. If <code><em>id</em></code> is given, returns a list containing the
7196 associated script and either <em>timer</em> or <em>idle</em> to indicated
7197 the type of the event. An error occurs if <code><em>id</em></code> does not
7198 match an event.
7199 </p>
7200 </dd>
7202 <code><strong>vwait</strong> <em>variable</em></code>
7203 </dt>
7204 <dd>
7205 <p>
7206 A call to <a href="#cmd_2"><strong><code>vwait</code></strong></a> is enters the eventloop. <a href="#cmd_2"><strong><code>vwait</code></strong></a> processes
7207 events until the named (global) variable changes or all
7208 event handlers are removed. The variable need not exist
7209 beforehand. If there are no event handlers defined, <a href="#cmd_2"><strong><code>vwait</code></strong></a>
7210 returns immediately.
7211 </p>
7212 </dd>
7214 <code><strong>update ?idletasks?</strong></code>
7215 </dt>
7216 <dd>
7217 <p>
7218 A call to <a href="#cmd_2"><strong><code>update</code></strong></a> enters the eventloop to process expired events, but
7219 no new events. If <em>idletasks</em> is specified, only expired time events are handled,
7220 not file events.
7221 Returns once handlers have been run for all expired events.
7222 </p>
7223 </dd>
7224 </dl></div>
7225 <div class="paragraph"><p>Scripts are executed at the global scope. If an error occurs during a handler script,
7226 an attempt is made to call (the user-defined command) <code>bgerror</code> with the details of the error.
7227 If the <code>bgerror</code> command does not exist, the error message details are printed to stderr instead.</p></div>
7228 <div class="paragraph"><p>If a file event handler script generates an error, the handler is automatically removed
7229 to prevent infinite errors. (A time event handler is always removed after execution).</p></div>
7232 <code><strong>bgerror</strong> <em>msg</em></code>
7233 </dt>
7234 <dd>
7235 <p>
7236 Called when an event handler script generates an error. Note that the normal command resolution
7237 rules are used for bgerror. First the name is resolved in the current namespace, then in the
7238 global scope.
7239 </p>
7240 </dd>
7241 </dl></div>
7242 </div>
7248 <code><strong>socket unix</strong> <em>path</em></code>
7249 </dt>
7250 <dd>
7251 <p>
7252 A unix domain socket client.
7253 </p>
7254 </dd>
7256 <code><strong>socket unix.server</strong> <em>path</em></code>
7257 </dt>
7258 <dd>
7259 <p>
7260 A unix domain socket server.
7261 </p>
7262 </dd>
7264 <code><strong>socket ?-ipv6? stream</strong> <em>addr:port</em></code>
7265 </dt>
7266 <dd>
7267 <p>
7268 A TCP socket client. (See the forms for <code><em>addr</em></code> below)
7269 </p>
7270 </dd>
7272 <code><strong>socket ?-ipv6? stream.server</strong> <em>?addr:?port</em></code>
7273 </dt>
7274 <dd>
7275 <p>
7276 A TCP socket server (<code><em>addr</em></code> defaults to <code>0.0.0.0</code> for IPv4 or <code>[::]</code> for IPv6).
7277 </p>
7278 </dd>
7280 <code><strong>socket ?-ipv6? dgram</strong> ?<em>addr:port</em>?</code>
7281 </dt>
7282 <dd>
7283 <p>
7284 A UDP socket client. If the address is not specified,
7285 the client socket will be unbound and <em>sendto</em> must be used
7286 to indicated the destination.
7287 </p>
7288 </dd>
7290 <code><strong>socket ?-ipv6? dgram.server</strong> <em>addr:port</em></code>
7291 </dt>
7292 <dd>
7293 <p>
7294 A UDP socket server.
7295 </p>
7296 </dd>
7298 <code><strong>socket pipe</strong></code>
7299 </dt>
7300 <dd>
7301 <p>
7302 A pipe. Note that unlike all other socket types, this command returns
7303 a list of two channels: {read write}
7304 </p>
7305 </dd>
7307 <code><strong>socket pair</strong></code>
7308 </dt>
7309 <dd>
7310 <p>
7311 A socketpair (see socketpair(2)). Like <a href="#_socket"><strong><code>socket</code></strong></a> <code>pipe</code>, this command returns
7312 a list of two channels: {s1 s2}. These channels are both readable and writable.
7313 </p>
7314 </dd>
7315 </dl></div>
7316 <div class="paragraph"><p>This command creates a socket connected (client) or bound (server) to the given
7317 address.</p></div>
7318 <div class="paragraph"><p>The returned value is channel and may generally be used with the various file I/O
7319 commands (gets, puts, read, etc.), either as object-based syntax or Tcl-compatible syntax.</p></div>
7322 <pre><code>set f [socket stream www.google.com:80]
7323 aio.sockstream1
7325 $f gets
7326 HTTP/1.0 302 Found
7327 $f close</code></pre>
7328 </div></div>
7329 <div class="paragraph"><p>Server sockets, however support only <em>accept</em>, which is most useful in conjunction with
7330 the EVENTLOOP API.</p></div>
7333 <pre><code>set f [socket stream.server 80]
7334 $f readable {
7335 set client [$f accept]
7336 $client gets $buf
7337 ...
7339 $client close
7340 }
7341 vwait done</code></pre>
7342 </div></div>
7343 <div class="paragraph"><p>The address, <code><em>addr</em></code>, can be given in one of the following forms:</p></div>
7345 <li>
7346 <p>
7347 For IPv4 socket types, an IPv4 address such as 192.168.1.1
7348 </p>
7349 </li>
7350 <li>
7351 <p>
7352 For IPv6 socket types, an IPv6 address such as [fe80::1234] or [::]
7353 </p>
7354 </li>
7355 <li>
7356 <p>
7357 A hostname
7358 </p>
7359 </li>
7360 </ol></div>
7361 <div class="paragraph"><p>Note that on many systems, listening on an IPv6 address such as [::] will
7362 also accept requests via IPv4.</p></div>
7363 <div class="paragraph"><p>Where a hostname is specified, the <code><em>first</em></code> returned address is used
7364 which matches the socket type is used.</p></div>
7365 <div class="paragraph"><p>The special type <em>pipe</em> isn’t really a socket.</p></div>
7368 <pre><code>lassign [socket pipe] r w</code></pre>
7369 </div></div>
7372 <pre><code># Must close $w after exec
7373 exec ps >@$w &
7374 $w close</code></pre>
7375 </div></div>
7378 <pre><code>$r readable ...</code></pre>
7379 </div></div>
7380 </div>
7383 <div class="paragraph"><p><code><strong>syslog</strong> <em>?options? ?priority? message</em></code></p></div>
7385 priority. Valid priorities are:</p></div>
7388 <pre><code>emerg, alert, crit, err, error, warning, notice, info, debug</code></pre>
7389 </div></div>
7391 priority of info is used.</p></div>
7392 <div class="paragraph"><p>By default, facility user is used and the value of global tcl variable
7393 argv0 is used as ident string. However, any of the following options
7394 may be specified before priority to control these parameters:</p></div>
7397 <code><strong>-facility</strong> <em>value</em></code>
7398 </dt>
7399 <dd>
7400 <p>
7401 Use specified facility instead of user. The following
7402 values for facility are recognized:
7403 </p>
7406 <pre><code>authpriv, cron, daemon, kernel, lpr, mail, news, syslog, user,
7407 uucp, local0-local7</code></pre>
7408 </div></div>
7409 </dd>
7411 <code><strong>-ident</strong> <em>string</em></code>
7412 </dt>
7413 <dd>
7414 <p>
7415 Use given string instead of argv0 variable for ident string.
7416 </p>
7417 </dd>
7419 <code><strong>-options</strong> <em>integer</em></code>
7420 </dt>
7421 <dd>
7422 <p>
7423 Set syslog options such as <code>LOG_CONS</code>, <code>LOG_NDELAY</code>. You should
7424 use numeric values of those from your system syslog.h file,
7425 because I haven’t got time to implement yet another hash
7426 table.
7427 </p>
7428 </dd>
7429 </dl></div>
7430 </div>
7433 <div class="paragraph"><p>The optional <em>pack</em> extension provides commands to encode and decode binary strings.</p></div>
7436 <code><strong>pack</strong> <em>varName value</em> <strong>-intle|-intbe|-floatle|-floatbe|-str</strong> <em>bitwidth ?bitoffset?</em></code>
7437 </dt>
7438 <dd>
7439 <p>
7440 Packs the binary representation of <code><em>value</em></code> into the variable
7441 <code><em>varName</em></code>. The value is packed according to the given type
7442 (integer/floating point/string, big-endian/little-endian), width and bit offset.
7443 The variable is created if necessary (like <a href="#_append"><strong><code>append</code></strong></a>).
7444 The variable is expanded if necessary.
7445 </p>
7446 </dd>
7448 <code><strong>unpack</strong> <em>binvalue</em> <strong>-intbe|-intle|-uintbe|-uintle|-floatbe|-floatle|-str</strong> <em>bitpos bitwidth</em></code>
7449 </dt>
7450 <dd>
7451 <p>
7452 Unpacks bits from <code><em>binvalue</em></code> at bit position <code><em>bitpos</em></code> and with <code><em>bitwidth</em></code>.
7453 Interprets the value according to the type (integer/floating point/string, big-endian/little-endian
7454 and signed/unsigned) and returns it. For integer types, <code><em>bitwidth</em></code>
7455 may be up to the size of a Jim Tcl integer (typically 64 bits). For floating point types,
7456 <code><em>bitwidth</em></code> may be 32 bits (for single precision numbers) or 64 bits (for double precision).
7457 For the string type, both the width and the offset must be on a byte boundary (multiple of 8). Attempting to
7458 access outside the length of the value will return 0 for integer types, 0.0 for floating point types
7459 or the empty string for the string type.
7460 </p>
7461 </dd>
7462 </dl></div>
7463 </div>
7466 <div class="paragraph"><p>The optional, pure-Tcl <em>binary</em> extension provides the Tcl-compatible <a href="#_binary"><strong><code>binary</code></strong></a> <code>scan</code> and <a href="#_binary"><strong><code>binary</code></strong></a> <code>format</code>
7467 commands based on the low-level <a href="#cmd_3"><strong><code>pack</code></strong></a> and <a href="#cmd_3"><strong><code>unpack</code></strong></a> commands.</p></div>
7468 <div class="paragraph"><p>See the Tcl documentation at: <a href="http://www.tcl.tk/man/tcl8.5/TclCmd/binary.htm">http://www.tcl.tk/man/tcl8.5/TclCmd/binary.htm</a></p></div>
7469 <div class="paragraph"><p>Note that <em>binary format</em> with f/r/R specifiers (single-precision float) uses the value of Infinity
7470 in case of overflow.</p></div>
7471 </div>
7474 <div class="paragraph"><p>The optional, pure-Tcl <em>oo</em> extension provides object-oriented (OO) support for Jim Tcl.</p></div>
7475 <div class="paragraph"><p>See the online documentation (<a href="http://jim.tcl.tk/index.html/doc/www/www/documentation/oo/">http://jim.tcl.tk/index.html/doc/www/www/documentation/oo/</a>) for more details.</p></div>
7478 <code><strong>class</strong> <em>classname ?baseclasses? classvars</em></code>
7479 </dt>
7480 <dd>
7481 <p>
7482 Create a new class, <code><em>classname</em></code>, with the given dictionary
7483 (<code><em>classvars</em></code>) as class variables. These are the initial variables
7484 which all newly created objects of this class are initialised with.
7485 If a list of baseclasses is given, methods and instance variables
7486 are inherited.
7487 </p>
7488 </dd>
7490 <code><strong>super</strong> <em>method ?args ...?</em></code>
7491 </dt>
7492 <dd>
7493 <p>
7494 From within a method, invokes the given method on the base class.
7495 Note that this will only call the last baseclass given.
7496 </p>
7497 </dd>
7498 </dl></div>
7499 </div>
7502 <div class="paragraph"><p>The optional, pure-Tcl <em>tree</em> extension implements an OO, general purpose tree structure
7503 similar to that provided by tcllib ::struct::tree (<a href="http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/struct/struct_tree.html">http://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/struct/struct_tree.html</a>)</p></div>
7504 <div class="paragraph"><p>A tree is a collection of nodes, where each node (except the root node) has a single parent
7505 and zero or more child nodes (ordered), as well as zero or more attribute/value pairs.</p></div>
7508 <code><strong>tree</strong></code>
7509 </dt>
7510 <dd>
7511 <p>
7513 All operations on the tree are invoked through this object.
7514 </p>
7515 </dd>
7517 <code>$tree <strong>destroy</strong></code>
7518 </dt>
7519 <dd>
7520 <p>
7521 Destroy the tree and all it’s nodes. (Note that the tree will also
7522 be automatically garbage collected once it goes out of scope).
7523 </p>
7524 </dd>
7526 <code>$tree <strong>set</strong> <em>nodename key value</em></code>
7527 </dt>
7528 <dd>
7529 <p>
7530 Set the value for the given attribute key.
7531 </p>
7532 </dd>
7534 <code>$tree <strong>lappend</strong> <em>nodename key value ...</em></code>
7535 </dt>
7536 <dd>
7537 <p>
7538 Append to the (list) value(s) for the given attribute key, or set if not yet set.
7539 </p>
7540 </dd>
7542 <code>$tree <strong>keyexists</strong> <em>nodename key</em></code>
7543 </dt>
7544 <dd>
7545 <p>
7546 Returns 1 if the given attribute key exists.
7547 </p>
7548 </dd>
7550 <code>$tree <strong>get</strong> <em>nodename key</em></code>
7551 </dt>
7552 <dd>
7553 <p>
7554 Returns the value associated with the given attribute key.
7555 </p>
7556 </dd>
7558 <code>$tree <strong>getall</strong> <em>nodename</em></code>
7559 </dt>
7560 <dd>
7561 <p>
7562 Returns the entire attribute dictionary associated with the given key.
7563 </p>
7564 </dd>
7566 <code>$tree <strong>depth</strong> <em>nodename</em></code>
7567 </dt>
7568 <dd>
7569 <p>
7571 </p>
7572 </dd>
7574 <code>$tree <strong>parent</strong> <em>nodename</em></code>
7575 </dt>
7576 <dd>
7577 <p>
7579 </p>
7580 </dd>
7582 <code>$tree <strong>numchildren</strong> <em>nodename</em></code>
7583 </dt>
7584 <dd>
7585 <p>
7586 Returns the number of child nodes.
7587 </p>
7588 </dd>
7590 <code>$tree <strong>children</strong> <em>nodename</em></code>
7591 </dt>
7592 <dd>
7593 <p>
7594 Returns a list of the child nodes.
7595 </p>
7596 </dd>
7598 <code>$tree <strong>next</strong> <em>nodename</em></code>
7599 </dt>
7600 <dd>
7601 <p>
7603 </p>
7604 </dd>
7606 <code>$tree <strong>insert</strong> <em>nodename ?index?</em></code>
7607 </dt>
7608 <dd>
7609 <p>
7610 Add a new child node to the given node. The index is a list index
7611 such as <code>3</code> or <code>end-2</code>. The default index is <code>end</code>.
7612 Returns the name of the newly added node.
7613 </p>
7614 </dd>
7616 <code>$tree <strong>walk</strong> <em>nodename</em> <strong>dfs|bfs</strong> {<em>actionvar nodevar</em>} <em>script</em></code>
7617 </dt>
7618 <dd>
7619 <p>
7620 Walks the tree starting from the given node, either breadth first (<code>bfs</code>)
7621 depth first (<code>dfs</code>).
7622 The value <code>"enter"</code> or <code>"exit"</code> is stored in variable <code><em>actionvar</em></code>.
7623 The name of each node is stored in <code><em>nodevar</em></code>.
7624 The script is evaluated twice for each node, on entry and exit.
7625 </p>
7626 </dd>
7628 <code>$tree <strong>dump</strong></code>
7629 </dt>
7630 <dd>
7631 <p>
7632 Dumps the tree contents to stdout
7633 </p>
7634 </dd>
7635 </dl></div>
7636 </div>
7639 <div class="paragraph"><p>The optional tclprefix extension provides the Tcl8.6-compatible <em>tcl::prefix</em> command
7640 (<a href="http://www.tcl.tk/man/tcl8.6/TclCmd/prefix.htm">http://www.tcl.tk/man/tcl8.6/TclCmd/prefix.htm</a>) for matching strings against a table
7641 of possible values (typically commands or options).</p></div>
7644 <code><strong>tcl::prefix all</strong> <em>table string</em></code>
7645 </dt>
7646 <dd>
7647 <p>
7648 Returns a list of all elements in <code><em>table</em></code> that begin with the prefix <code><em>string</em></code>.
7649 </p>
7650 </dd>
7652 <code><strong>tcl::prefix longest</strong> <em>table string</em></code>
7653 </dt>
7654 <dd>
7655 <p>
7656 Returns the longest common prefix of all elements in <code><em>table</em></code> that begin with the prefix <code><em>string</em></code>.
7657 </p>
7658 </dd>
7660 <code><strong>tcl::prefix match</strong> <em>?options? table string</em></code>
7661 </dt>
7662 <dd>
7663 <p>
7664 If <code><em>string</em></code> equals one element in <code><em>table</em></code> or is a prefix to
7665 exactly one element, the matched element is returned. If not, the
7666 result depends on the <code>-error</code> option.
7667 </p>
7669 <li>
7670 <p>
7671 <code><strong>-exact</strong></code> Accept only exact matches.
7672 </p>
7673 </li>
7674 <li>
7675 <p>
7676 <code><strong>-message</strong> <em>string</em></code> Use <code><em>string</em></code> in the error message at a mismatch. Default is "option".
7677 </p>
7678 </li>
7679 <li>
7680 <p>
7681 <code><strong>-error</strong> <em>options</em></code> The options are used when no match is found. If <code><em>options</em></code> is
7682 empty, no error is generated and an empty string is returned.
7683 Otherwise the options are used as return options when
7684 generating the error message. The default corresponds to
7685 setting <code>-level 0</code>.
7686 </p>
7687 </li>
7688 </ul></div>
7689 </dd>
7690 </dl></div>
7691 </div>
7694 <div class="paragraph"><p>The optional history extension provides script access to the command line editing
7695 and history support available in <em>jimsh</em>. See <em>examples/jtclsh.tcl</em> for an example.
7696 Note: if line editing support is not available, <a href="#_history"><strong><code>history</code></strong></a> <code>getline</code> acts like <a href="#_gets"><strong><code>gets</code></strong></a> and
7697 the remaining subcommands do nothing.</p></div>
7700 <code><strong>history load</strong> <em>filename</em></code>
7701 </dt>
7702 <dd>
7703 <p>
7704 Load history from a (text) file. If the file does not exist or is not readable,
7705 it is ignored.
7706 </p>
7707 </dd>
7709 <code><strong>history getline</strong> <em>prompt ?varname?</em></code>
7710 </dt>
7711 <dd>
7712 <p>
7713 Displays the given prompt and allows a line to be entered. Similarly to <a href="#_gets"><strong><code>gets</code></strong></a>,
7714 if <code><em>varname</em></code> is given, it receives the line and the length of the line is returned,
7715 or -1 on EOF. If <code><em>varname</em></code> is not given, the line is returned directly.
7716 </p>
7717 </dd>
7719 <code><strong>history add</strong> <em>line</em></code>
7720 </dt>
7721 <dd>
7722 <p>
7723 Adds the given line to the history buffer.
7724 </p>
7725 </dd>
7727 <code><strong>history save</strong> <em>filename</em></code>
7728 </dt>
7729 <dd>
7730 <p>
7731 Saves the current history buffer to the given file.
7732 </p>
7733 </dd>
7735 <code><strong>history show</strong></code>
7736 </dt>
7737 <dd>
7738 <p>
7739 Displays the current history buffer to standard output.
7740 </p>
7741 </dd>
7742 </dl></div>
7743 </div>
7746 <div class="paragraph"><p>Provides namespace-related functions. See also: <a href="http://www.tcl.tk/man/tcl8.6/TclCmd/namespace.htm">http://www.tcl.tk/man/tcl8.6/TclCmd/namespace.htm</a></p></div>
7749 <code><strong>namespace code</strong> <em>script</em></code>
7750 </dt>
7751 <dd>
7752 <p>
7753 Captures the current namespace context for later execution of
7754 the script <code><em>script</em></code>. It returns a new script in which script has
7755 been wrapped in a <code><strong>namespace inscope</strong></code> command.
7756 </p>
7757 </dd>
7759 <code><strong>namespace current</strong></code>
7760 </dt>
7761 <dd>
7762 <p>
7763 Returns the fully-qualified name for the current namespace.
7764 </p>
7765 </dd>
7767 <code><strong>namespace delete</strong> <em>?namespace …?</em></code>
7768 </dt>
7769 <dd>
7770 <p>
7771 Deletes all commands and variables with the given namespace prefixes.
7772 </p>
7773 </dd>
7775 <code><strong>namespace eval</strong> <em>namespace arg ?arg…?</em></code>
7776 </dt>
7777 <dd>
7778 <p>
7779 Activates a namespace called <code><em>namespace</em></code> and evaluates some code in that context.
7780 </p>
7781 </dd>
7783 <code><strong>namespace origin</strong> <em>command</em></code>
7784 </dt>
7785 <dd>
7786 <p>
7787 Returns the fully-qualified name of the original command to which the imported command <code><em>command</em></code> refers.
7788 </p>
7789 </dd>
7791 <code><strong>namespace parent</strong> ?namespace?</code>
7792 </dt>
7793 <dd>
7794 <p>
7795 Returns the fully-qualified name of the parent namespace for namespace <code><em>namespace</em></code>, if given, otherwise
7796 for the current namespace.
7797 </p>
7798 </dd>
7800 <code><strong>namespace qualifiers</strong> <em>string</em></code>
7801 </dt>
7802 <dd>
7803 <p>
7804 Returns any leading namespace qualifiers for <code><em>string</em></code>
7805 </p>
7806 </dd>
7808 <code><strong>namespace tail</strong> <em>string</em></code>
7809 </dt>
7810 <dd>
7811 <p>
7812 Returns the simple name at the end of a qualified string.
7813 </p>
7814 </dd>
7816 <code><strong>namespace upvar</strong> <em>namespace ?arg…?</em></code>
7817 </dt>
7818 <dd>
7819 <p>
7820 This command arranges for zero or more local variables in the current procedure to refer to variables in <code><em>namespace</em></code>
7821 </p>
7822 </dd>
7824 <code><strong>namespace which</strong> <em>?-command|-variable? name</em></code>
7825 </dt>
7826 <dd>
7827 <p>
7828 Looks up <code><em>name</em></code> as either a command (the default) or variable and returns its fully-qualified name.
7829 </p>
7830 </dd>
7831 </dl></div>
7832 </div>
7833 </div>
7834 </div>
7839 by the Tcl library.</p></div>
7842 <code><strong>env</strong></code>
7843 </dt>
7844 <dd>
7845 <p>
7846 This variable is set by Jim as an array
7847 whose elements are the environment variables for the process.
7848 Reading an element will return the value of the corresponding
7849 environment variable.
7850 This array is initialised at startup from the <a href="#_env"><strong><code>env</code></strong></a> command.
7851 It may be modified and will affect the environment passed to
7853 </p>
7854 </dd>
7856 <code><strong>platform_tcl</strong></code>
7857 </dt>
7858 <dd>
7859 <p>
7860 This variable is set by Jim as an array containing information
7861 about the platform on which Jim was built. Currently this includes
7862 <em>os</em> and <em>platform</em>.
7863 </p>
7864 </dd>
7866 <code><strong>auto_path</strong></code>
7867 </dt>
7868 <dd>
7869 <p>
7870 This variable contains a list of paths to search for packages.
7871 It defaults to a location based on where jim is installed
7872 (e.g. <code>/usr/local/lib/jim</code>), but may be changed by <code>jimsh</code>
7873 or the embedding application. Note that <code>jimsh</code> will consider
7874 the environment variable <code>$JIMLIB</code> to be a list of colon-separated
7875 list of paths to add to <code><strong>auto_path</strong></code>.
7876 </p>
7877 </dd>
7879 <code><strong>errorCode</strong></code>
7880 </dt>
7881 <dd>
7882 <p>
7883 This variable holds the value of the -errorcode return
7884 option set by the most recent error that occurred in this
7885 interpreter. This list value represents additional information
7886 about the error in a form that is easy to process with
7887 programs. The first element of the list identifies a general
7888 class of errors, and determines the format of the rest of
7889 the list. The following formats for -errorcode return options
7890 are used by the Tcl core; individual applications may define
7891 additional formats. Currently only <a href="#_exec"><strong><code>exec</code></strong></a> sets this variable.
7892 Otherwise it will be <code>NONE</code>.
7893 </p>
7894 </dd>
7895 </dl></div>
7899 <code><strong>tcl_interactive</strong></code>
7900 </dt>
7901 <dd>
7902 <p>
7903 This variable is set to 1 if jimsh is started in interactive mode
7904 or 0 otherwise.
7905 </p>
7906 </dd>
7908 <code><strong>tcl_platform</strong></code>
7909 </dt>
7910 <dd>
7911 <p>
7912 This variable is set by Jim as an array containing information
7913 about the platform upon which Jim was built. The following is an
7914 example of the contents of this array.
7915 </p>
7918 <pre><code>tcl_platform(byteOrder) = littleEndian
7919 tcl_platform(engine) = Jim
7920 tcl_platform(os) = Darwin
7921 tcl_platform(platform) = unix
7922 tcl_platform(pointerSize) = 8
7923 tcl_platform(threaded) = 0
7924 tcl_platform(wordSize) = 8
7925 tcl_platform(pathSeparator) = :</code></pre>
7926 </div></div>
7927 </dd>
7929 <code><strong>argv0</strong></code>
7930 </dt>
7931 <dd>
7932 <p>
7933 If jimsh is invoked to run a script, this variable contains the name
7934 of the script.
7935 </p>
7936 </dd>
7938 <code><strong>argv</strong></code>
7939 </dt>
7940 <dd>
7941 <p>
7942 If jimsh is invoked to run a script, this variable contains a list
7943 of any arguments supplied to the script.
7944 </p>
7945 </dd>
7947 <code><strong>argc</strong></code>
7948 </dt>
7949 <dd>
7950 <p>
7951 If jimsh is invoked to run a script, this variable contains the number
7952 of arguments supplied to the script.
7953 </p>
7954 </dd>
7956 <code><strong>jim::argv0</strong></code>
7957 </dt>
7958 <dd>
7959 <p>
7960 The value of argv[0] when jimsh was invoked.
7961 </p>
7962 </dd>
7963 </dl></div>
7964 </div>
7965 </div>
7972 <li>
7973 <p>
7974 <code>platform_tcl()</code> settings are now automatically determined
7975 </p>
7976 </li>
7977 <li>
7978 <p>
7979 Add aio <code>$handle filename</code>
7980 </p>
7981 </li>
7982 <li>
7983 <p>
7985 </p>
7986 </li>
7987 <li>
7988 <p>
7989 The <em>bio</em> extension is gone. Now <a href="#_aio"><strong><code>aio</code></strong></a> supports <em>copyto</em>.
7990 </p>
7991 </li>
7992 <li>
7993 <p>
7995 </p>
7996 </li>
7997 <li>
7998 <p>
7999 Add the pure-Tcl <em>oo</em> extension
8000 </p>
8001 </li>
8002 <li>
8003 <p>
8004 The <a href="#_exec"><strong><code>exec</code></strong></a> command now only uses vfork(), not fork()
8005 </p>
8006 </li>
8007 <li>
8008 <p>
8009 Unit test framework is less verbose and more Tcl-compatible
8010 </p>
8011 </li>
8012 <li>
8013 <p>
8014 Optional UTF-8 support
8015 </p>
8016 </li>
8017 <li>
8018 <p>
8019 Optional built-in regexp engine for better Tcl compatibility and UTF-8 support
8020 </p>
8021 </li>
8022 <li>
8023 <p>
8024 Command line editing in interactive mode, e.g. <em>jimsh</em>
8025 </p>
8026 </li>
8027 </ol></div>
8028 </div>
8032 <li>
8033 <p>
8034 <a href="#_source"><strong><code>source</code></strong></a> now checks that a script is complete (.i.e. not missing a brace)
8035 </p>
8036 </li>
8037 <li>
8038 <p>
8039 <em>info complete</em> now uses the real parser and so is 100% accurate
8040 </p>
8041 </li>
8042 <li>
8043 <p>
8044 Better access to live stack frames with <em>info frame</em>, <a href="#_stacktrace"><strong><code>stacktrace</code></strong></a> and <a href="#_stackdump"><strong><code>stackdump</code></strong></a>
8045 </p>
8046 </li>
8047 <li>
8048 <p>
8049 <a href="#_tailcall"><strong><code>tailcall</code></strong></a> no longer loses stack trace information
8050 </p>
8051 </li>
8052 <li>
8053 <p>
8054 Add <a href="#_alias"><strong><code>alias</code></strong></a> and <a href="#_curry"><strong><code>curry</code></strong></a>
8055 </p>
8056 </li>
8057 <li>
8058 <p>
8059 <a href="#_lambda"><strong><code>lambda</code></strong></a>, <a href="#_alias"><strong><code>alias</code></strong></a> and <a href="#_curry"><strong><code>curry</code></strong></a> are implemented via <a href="#_tailcall"><strong><code>tailcall</code></strong></a> for efficiency
8060 </p>
8061 </li>
8062 <li>
8063 <p>
8064 <a href="#_local"><strong><code>local</code></strong></a> allows procedures to be deleted automatically at the end of the current procedure
8065 </p>
8066 </li>
8067 <li>
8068 <p>
8069 udp sockets are now supported for both clients and servers.
8070 </p>
8071 </li>
8072 <li>
8073 <p>
8074 vfork-based exec is now working correctly
8075 </p>
8076 </li>
8077 <li>
8078 <p>
8079 Add <em>file tempfile</em>
8080 </p>
8081 </li>
8082 <li>
8083 <p>
8084 Add <em>socket pipe</em>
8085 </p>
8086 </li>
8087 <li>
8088 <p>
8089 Enhance <em>try … on … finally</em> to be more Tcl 8.6 compatible
8090 </p>
8091 </li>
8092 <li>
8093 <p>
8094 It is now possible to <a href="#_return"><strong><code>return</code></strong></a> from within <a href="#_try"><strong><code>try</code></strong></a>
8095 </p>
8096 </li>
8097 <li>
8098 <p>
8099 IPv6 support is now included
8100 </p>
8101 </li>
8102 <li>
8103 <p>
8104 Add <em>string is</em>
8105 </p>
8106 </li>
8107 <li>
8108 <p>
8109 Event handlers works better if an error occurs. eof handler has been removed.
8110 </p>
8111 </li>
8112 <li>
8113 <p>
8114 <a href="#_exec"><strong><code>exec</code></strong></a> now sets $::errorCode, and catch sets opts(-errorcode) for exit status
8115 </p>
8116 </li>
8117 <li>
8118 <p>
8120 </p>
8121 </li>
8122 <li>
8123 <p>
8124 <a href="#_pid"><strong><code>pid</code></strong></a> can now return pids of a command pipeline
8125 </p>
8126 </li>
8127 <li>
8128 <p>
8129 Add <em>info references</em>
8130 </p>
8131 </li>
8132 <li>
8133 <p>
8134 Add support for <em>after <code>'ms</em></code><em>, 'after idle</em>, <em>after info</em>, <a href="#cmd_2"><strong><code>update</code></strong></a>
8135 </p>
8136 </li>
8137 <li>
8138 <p>
8140 </p>
8141 </li>
8142 <li>
8143 <p>
8144 Add <em>dict keys</em>
8145 </p>
8146 </li>
8147 <li>
8148 <p>
8149 Add support for <em>lsort -index</em>
8150 </p>
8151 </li>
8152 </ol></div>
8153 </div>
8157 <li>
8158 <p>
8159 Add support to <a href="#_exec"><strong><code>exec</code></strong></a> for <em>>&</em>, <em>>>&</em>, <em>|&</em>, <em>2>@1</em>
8160 </p>
8161 </li>
8162 <li>
8163 <p>
8164 Fix <a href="#_exec"><strong><code>exec</code></strong></a> error messages when special token (e.g. <em>></em>) is the last token
8165 </p>
8166 </li>
8167 <li>
8168 <p>
8170 </p>
8171 </li>
8172 <li>
8173 <p>
8175 </p>
8176 </li>
8177 <li>
8178 <p>
8179 Add support for <a href="#_return"><strong><code>return</code></strong></a>, <a href="#_break"><strong><code>break</code></strong></a>, <a href="#_continue"><strong><code>continue</code></strong></a> in subst
8180 </p>
8181 </li>
8182 <li>
8183 <p>
8185 </p>
8186 </li>
8187 <li>
8188 <p>
8189 Add support for functions in <a href="#_expr"><strong><code>expr</code></strong></a> (e.g. int(), abs()), and also <em>in</em>, <em>ni</em> list operations
8190 </p>
8191 </li>
8192 <li>
8193 <p>
8194 The variable name argument to <a href="#_regsub"><strong><code>regsub</code></strong></a> is now optional
8195 </p>
8196 </li>
8197 <li>
8198 <p>
8199 Add support for <em>unset -nocomplain</em>
8200 </p>
8201 </li>
8202 <li>
8203 <p>
8204 Add support for list commands: <a href="#_lassign"><strong><code>lassign</code></strong></a>, <a href="#_lrepeat"><strong><code>lrepeat</code></strong></a>
8205 </p>
8206 </li>
8207 <li>
8208 <p>
8209 Fully-functional <a href="#_lsearch"><strong><code>lsearch</code></strong></a> is now implemented
8210 </p>
8211 </li>
8212 <li>
8213 <p>
8214 Add <em>info nameofexecutable</em> and <em>info returncodes</em>
8215 </p>
8216 </li>
8217 <li>
8218 <p>
8219 Allow <a href="#_catch"><strong><code>catch</code></strong></a> to determine what return codes are caught
8220 </p>
8221 </li>
8222 <li>
8223 <p>
8224 Allow <a href="#_incr"><strong><code>incr</code></strong></a> to increment an unset variable by first setting to 0
8225 </p>
8226 </li>
8227 <li>
8228 <p>
8229 Allow <em>args</em> and optional arguments to the left or required arguments in <a href="#_proc"><strong><code>proc</code></strong></a>
8230 </p>
8231 </li>
8232 <li>
8233 <p>
8234 Add <em>file copy</em>
8235 </p>
8236 </li>
8237 <li>
8238 <p>
8239 Add <em>try … finally</em> command
8240 </p>
8241 </li>
8242 </ol></div>
8243 </div>
8244 </div>
8245 </div>
8251 <pre><code>Copyright 2005 Salvatore Sanfilippo <antirez@invece.org>
8252 Copyright 2005 Clemens Hintze <c.hintze@gmx.net>
8253 Copyright 2005 patthoyts - Pat Thoyts <patthoyts@users.sf.net>
8254 Copyright 2008 oharboe - Oyvind Harboe - oyvind.harboe@zylin.com
8255 Copyright 2008 Andrew Lunn <andrew@lunn.ch>
8256 Copyright 2008 Duane Ellis <openocd@duaneellis.com>
8257 Copyright 2008 Uwe Klein <uklein@klein-messgeraete.de>
8258 Copyright 2009 Steve Bennett <steveb@workware.net.au></code></pre>
8259 </div></div>
8262 <pre><code>Redistribution and use in source and binary forms, with or without
8263 modification, are permitted provided that the following conditions
8264 are met:
8265 1. Redistributions of source code must retain the above copyright
8266 notice, this list of conditions and the following disclaimer.
8267 2. Redistributions in binary form must reproduce the above
8268 copyright notice, this list of conditions and the following
8269 disclaimer in the documentation and/or other materials
8270 provided with the distribution.</code></pre>
8271 </div></div>
8274 <pre><code>THIS SOFTWARE IS PROVIDED BY THE JIM TCL PROJECT ``AS IS'' AND ANY
8275 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
8276 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
8277 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
8278 JIM TCL PROJECT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
8279 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
8280 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
8281 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
8282 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
8283 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
8284 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
8285 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</code></pre>
8286 </div></div>
8289 <pre><code>The views and conclusions contained in the software and documentation
8290 are those of the authors and should not be interpreted as representing
8291 official policies, either expressed or implied, of the Jim Tcl Project.</code></pre>
8292 </div></div>
8293 </div>
8294 </div>
8295 </div>
8299 Last updated 2016-01-25 09:25:06 AEST
8300 </div>
8301 </div>
8302 </body>
8303 </html>