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