Return to Tcl.man CVS log

Up to [Research Unix] / researchv10no / cmd / worm / scsi / tcl

Annotation of researchv10no/cmd/worm/scsi/tcl/Tcl.man, revision 1.1

1.1     ! root        1: '\" Copyright 1989 Regents of the University of California
        !             2: '\" Permission to use, copy, modify, and distribute this
        !             3: '\" documentation for any purpose and without fee is hereby
        !             4: '\" granted, provided that this notice appears in all copies.
        !             5: '\" The University of California makes no representations about
        !             6: '\" the suitability of this material for any purpose.  It is
        !             7: '\" provided "as is" without express or implied warranty.
        !             8: '\" 
        !             9: '\" $Header: /sprite/src/lib/tcl/RCS/Tcl.man,v 1.29 90/04/18 17:19:18 ouster Exp $ SPRITE (Berkeley)
        !            10: '
        !            11: .so \*(]ltmac.sprite
        !            12: .de UL
        !            13: \\$1\l'|0\(ul'\\$2
        !            14: ..
        !            15: .HS Tcl tcl
        !            16: .BS
        !            17: .SH NAME
        !            18: Tcl \- overview of tool command language facilities
        !            19: .BE
        !            20: 
        !            21: .SH INTRODUCTION
        !            22: .PP
        !            23: Tcl stands for ``tool command language'' and is pronounced ``tickle.''
        !            24: It is actually two things:
        !            25: a language and a library.
        !            26: First, Tcl is a simple textual language,
        !            27: intended primarily for issuing commands to interactive programs such
        !            28: as text editors, debuggers, illustrators, and shells.  It has
        !            29: a simple syntax and is also programmable, so
        !            30: Tcl users can write command procedures to provide more powerful
        !            31: commands than those in the built-in set.
        !            32: .PP
        !            33: Second, Tcl is a library package that can be embedded in application
        !            34: programs.  The Tcl library consists of a parser for the Tcl
        !            35: language, routines to implement the Tcl built-in commands, and
        !            36: procedures that allow each application to extend Tcl with additional
        !            37: commands specific to that application.  The application program
        !            38: generates Tcl commands and passes them to the Tcl parser for
        !            39: execution.  Commands may be generated
        !            40: by reading characters from an input
        !            41: source, or by associating command strings with elements of the
        !            42: application's user interface, such as menu entries, buttons, or
        !            43: keystrokes.
        !            44: When the Tcl library receives commands it parses them
        !            45: into component fields and executes built-in commands directly.
        !            46: For commands implemented by the
        !            47: application, Tcl calls back to the application to execute the
        !            48: commands.  In many cases commands will invoke recursive invocations
        !            49: of the Tcl interpreter by passing in additional strings to execute
        !            50: (procedures, looping commands, and conditional commands all work
        !            51: in this way).
        !            52: .PP
        !            53: An application program gains three advantages by using Tcl for
        !            54: its command language.  First, Tcl provides a standard syntax:  once
        !            55: users know Tcl, they will be able to issue commands easily
        !            56: to any Tcl-based application.  Second, Tcl provides programmability.
        !            57: All a Tcl application needs to do is to implement a few
        !            58: application-specific low-level commands.  Tcl provides many utility
        !            59: commands plus a general programming interface for building up
        !            60: complex command procedures.  By using Tcl, applications need not
        !            61: re-implement these features.  Third, Tcl will eventually provide
        !            62: a mechanism for communicating between applications:  it will be
        !            63: possible to send Tcl commands from one application to another.
        !            64: The common Tcl language framework will make it easier for applications
        !            65: to communicate with one another.  The communication features are not
        !            66: implemented in the current version of Tcl.
        !            67: .PP
        !            68: This manual page focusses primarily on the Tcl language.  It describes
        !            69: the language syntax and the built-in commands that will be available in
        !            70: any application based on Tcl.  The individual library
        !            71: procedures are described in more detail in separate manual pages, one
        !            72: per procedure.
        !            73: 
        !            74: .SH "INTERPRETERS"
        !            75: .PP
        !            76: The central data structure in Tcl is an interpreter (C type
        !            77: ``Tcl_Interp'').  An interpreter consists of a set of command
        !            78: bindings, a set of variable values, and a few other miscellaneous
        !            79: pieces of state.  Each Tcl command is interpreted in the context
        !            80: of a particular interpreter.
        !            81: Some Tcl-based applications will maintain
        !            82: multiple interpreters simultaneously, each associated with a
        !            83: different widget or portion of the application.
        !            84: Interpreters are relatively lightweight structures.  They can
        !            85: be created and deleted quickly, so application programmers should feel free to
        !            86: use multiple interpreters if that simplifies the application.
        !            87: Eventually Tcl will provide a mechanism for sending Tcl commands
        !            88: and results back and forth between interpreters, even if the
        !            89: interpreters are managed by different processes.
        !            90: 
        !            91: .SH "DATA TYPES"
        !            92: .PP
        !            93: Tcl supports only one type of data:  strings.  All commands,
        !            94: all arguments to commands, all command results, and all variable values
        !            95: are strings.
        !            96: Where commands require numeric arguments or return numeric results,
        !            97: the arguments and results are passed as strings.
        !            98: Many commands expect their string arguments to have certain formats,
        !            99: but this interpretation is
        !           100: up to the individual commands.  For example, arguments often contain
        !           101: Tcl command strings, which may get executed as part of the commands.
        !           102: The easiest way to understand the Tcl interpreter is to remember that
        !           103: everything is just an operation on a string.  In many cases Tcl constructs
        !           104: will look similar to more structured constructs from other languages.
        !           105: However, the Tcl constructs
        !           106: are not structured at all;  they are just strings of characters, and this
        !           107: gives them a different behavior than the structures they may look like.
        !           108: .PP
        !           109: Although the exact interpretation of a Tcl string depends on who is
        !           110: doing the interpretation, there are three common forms that strings
        !           111: take:  commands, expressions, and lists.  The major sections below
        !           112: discuss these three forms in more detail.
        !           113: 
        !           114: .SH "BASIC COMMAND SYNTAX"
        !           115: .PP
        !           116: The Tcl language has syntactic similarities to both the Unix shells
        !           117: and Lisp.  However, the interpretation of commands is different
        !           118: in Tcl than in either of those other two systems.
        !           119: A Tcl command string consists of one or more commands separated
        !           120: by newline characters or semi-colons.
        !           121: Each command consists of a collection of fields separated by
        !           122: white space (spaces or tabs).
        !           123: The first field must be the name of a command, and the
        !           124: additional fields, if any, are arguments that will be passed to
        !           125: that command.  For example, the command
        !           126: .DS
        !           127: \fBset a 22\fR
        !           128: .DE
        !           129: has three fields:  the first, \fBset\fR, is the name of a Tcl command, and
        !           130: the last two, \fBa\fR and \fB22\fR, will be passed as arguments to
        !           131: the \fBset\fR command.  The command name may refer either to a built-in
        !           132: Tcl command, an application-specific command bound in with the library
        !           133: procedure \fBTcl_CreateCommand\fR, or a command procedure defined with the
        !           134: \fBproc\fR built-in command.
        !           135: Arguments are passed literally as
        !           136: text strings.  Individual commands may interpret those strings in any
        !           137: fashion they wish.  The \fBset\fR command, for example, will treat its
        !           138: first argument as the name of a variable and its second argument as a
        !           139: string value to assign to that variable.  For other commands arguments
        !           140: may be interpreted as integers, lists, file names, or Tcl commands.
        !           141: .PP
        !           142: Command names may be abbreviated as long as the abbreviation is unique.
        !           143: However, it's probably a bad idea to use abbreviations in command scripts
        !           144: and other forms that will be re-used over time:  changes to the command
        !           145: set may cause abbreviations to become ambiguous, resulting in scripts
        !           146: that no longer work.  Abbreviations are intended primarily for
        !           147: commands that are typed interactively, invoked once, and discarded.
        !           148: Also, command abbreviations are disallowed if the global variable
        !           149: \fBnoAbbrev\fR has the value \fB1\fR.
        !           150: 
        !           151: .SH "COMMENTS"
        !           152: .PP
        !           153: If the first non-blank character in a command is \fB#\fR, then everything
        !           154: from the \fB#\fR up through the next newline character is treated as
        !           155: a comment and ignored.
        !           156: 
        !           157: .SH "GROUPING ARGUMENTS WITH DOUBLE-QUOTES"
        !           158: .VS
        !           159: .PP
        !           160: Normally each argument field ends at the next white space, but
        !           161: double-quotes may be used to create arguments with embedded
        !           162: space.  If an argument
        !           163: field begins with a double-quote, then the argument isn't
        !           164: terminated by white space (including newlines) or a semi-colon
        !           165: (see below for information on semi-colons);  instead it ends at the next
        !           166: double-quote character.  The double-quotes are not included
        !           167: in the resulting argument.  For example, the
        !           168: command
        !           169: .DS
        !           170: \fBset a "This is a single argument"\fR
        !           171: .DE
        !           172: will pass two arguments to \fBset\fR:  \fBa\fR and
        !           173: \fBThis is a single argument\fR.  Within double-quotes, command
        !           174: substitutions, variable substitutions, and backslash substitutions
        !           175: still occur, as described below.  If the first character of a
        !           176: command field is not a quote, then quotes receive no special
        !           177: interpretation in the parsing of that field.
        !           178: 
        !           179: .SH "GROUPING ARGUMENTS WITH BRACES"
        !           180: .PP
        !           181: Curly braces may also be used for grouping arguments.  They are
        !           182: similar to quotes except for two differences.  First, they nest;
        !           183: this makes them easier to use for complicated arguments like nested Tcl
        !           184: command strings.  Second, the substitutions described below for
        !           185: commands, variables, and backslashes do \fInot\fR occur in arguments
        !           186: enclosed in braces, so braces can be used to prevent substitutions
        !           187: where they are undesirable.
        !           188: If an argument field
        !           189: begins with a left brace, then the argument ends at the matching
        !           190: right brace.  Tcl will strip off the outermost layer of braces
        !           191: and pass the information between the braces to the command without
        !           192: any further modification.  For example, in the command
        !           193: .VE
        !           194: .DS
        !           195: \fBset a {xyz a {b c d}}\fR
        !           196: .DE
        !           197: the \fBset\fR command will receive two arguments: \fBa\fR
        !           198: and \fBxyz a {b c d}\fR.
        !           199: .PP
        !           200: When braces or quotes are in effect, the matching brace
        !           201: or quote need not be on
        !           202: the same line as the starting quote or brace;  in this case
        !           203: the newline will be
        !           204: included in the argument field along with any other characters up to the
        !           205: matching brace or quote.  For example, the \fBeval\fR command
        !           206: takes one
        !           207: argument, which is a command string;  \fBeval\fR invokes the Tcl
        !           208: interpreter to execute the command string.  The command
        !           209: .DS
        !           210: \fBeval {
        !           211:        set a 22
        !           212:        set b 33
        !           213: }\fR
        !           214: .DE
        !           215: will assign the value \fB22\fR to \fBa\fR and \fB33\fR to \fBb\fR.
        !           216: .PP
        !           217: If the first character of a command field is not a left
        !           218: brace, then neither left nor right
        !           219: braces in the field will be treated specially (except as part of
        !           220: variable substitution;  see below).
        !           221: 
        !           222: .SH "COMMAND SUBSTITUTION WITH BRACKETS"
        !           223: .PP
        !           224: If an open bracket occurs in a field of a command, then
        !           225: command substitution occurs (except for fields enclosed in
        !           226: braces).  All of the text up to the matching
        !           227: close bracket is treated as a Tcl command and executed immediately.
        !           228: Then the result of that command is substituted for the bracketed
        !           229: text.  For example, consider the command
        !           230: .DS
        !           231: \fBset a [set b]\fR
        !           232: .DE
        !           233: When the \fBset\fR command has only a single argument, it is the
        !           234: name of a variable and \fBset\fR returns the contents of that
        !           235: variable.  In this case, if variable \fBb\fR has the value \fBfoo\fR,
        !           236: then the command above is equivalent to the command
        !           237: .DS
        !           238: \fBset a foo\fR
        !           239: .DE
        !           240: Brackets can be used in more complex ways.  For example, if the
        !           241: variable \fBb\fR has the value \fBfoo\fR and the variable \fBc\fR
        !           242: has the value \fBgorp\fR, then the command
        !           243: .DS
        !           244: \fBset a xyz[set b].[set c]\fR
        !           245: .DE
        !           246: is equivalent to the command
        !           247: .DS
        !           248: \fBset a xyzfoo.gorp\fR
        !           249: .DE
        !           250: A bracketed command need not be all on one line:  newlines within
        !           251: brackets are treated as argument separators, not command separators.
        !           252: If a field is enclosed in braces then the brackets and the characters
        !           253: between them are not interpreted specially;  they are passed through
        !           254: to the argument verbatim.
        !           255: 
        !           256: .SH "VARIABLE SUBSTITUTION WITH $"
        !           257: .PP
        !           258: The dollar sign (\fB$\fR) may be used as a special shorthand form
        !           259: for substituting variables.  If \fB$\fR appears in an argument that
        !           260: isn't enclosed in braces
        !           261: then variable substitution will occur.  The characters after
        !           262: the \fB$\fR, up to the first character that isn't a number, letter, or
        !           263: underscore, are taken as a variable name and the string value of that
        !           264: variable is substituted for the name.  Or, if the dollar sign is followed
        !           265: by an open curly brace then the variable name consists of all the characters
        !           266: up to the next close curly brace.  For example, if variable \fBfoo\fR
        !           267: has the value \fBtest\fR, then the command
        !           268: .DS C
        !           269: \fBset a $foo.c\fR
        !           270: .DE
        !           271: is equivalent to the command
        !           272: .DS C
        !           273: \fBset a test.c\fR
        !           274: .DE
        !           275: and the command
        !           276: .DS C
        !           277: \fBset a abc${foo}bar\fR
        !           278: .DE
        !           279: is equivalent to the command
        !           280: .DS C
        !           281: \fBset a abctestbar\fR
        !           282: .DE
        !           283: Variable substitution does not occur in arguments that are enclosed
        !           284: in braces:  the
        !           285: dollar sign and variable name are passed through to the argument verbatim.
        !           286: .PP
        !           287: The dollar sign abbreviation is simply a shorthand form.  \fB$a\fR is
        !           288: completely equivalent to \fB[set a]\fR;  it is provided as a convenience
        !           289: to reduce typing.
        !           290: 
        !           291: .VS
        !           292: .SH "SEPARATING COMMANDS WITH SEMI-COLONS"
        !           293: .PP
        !           294: Normally, each command occupies one line (the command is terminated by
        !           295: a newline character).  However, semi-colon (``;'') is treated
        !           296: as a command separator character;  multiple commands may be placed
        !           297: on one line by separating them with a semi-colon.  Semi-colons are
        !           298: not treated as command separators if they appear within curly braces
        !           299: or double-quotes.
        !           300: .VE
        !           301: 
        !           302: .SH "BACKSLASH SUBSTITUTION"
        !           303: .PP
        !           304: Backslashes may be used to insert non-printing characters into
        !           305: command fields and also to insert special characters like
        !           306: braces and brackets into fields
        !           307: without them being interpreted specially as described above.
        !           308: The backslash sequences understood by the Tcl interpreter are
        !           309: listed below.  In each case, the backslash
        !           310: sequence is replaced by the given character:
        !           311: .TP 20
        !           312: \fB\eb\fR
        !           313: Backspace (0x8).
        !           314: .TP 20
        !           315: \fB\ee\fR
        !           316: Escape (0x1b).
        !           317: .TP 20
        !           318: \fB\en\fR
        !           319: Newline (0xa).
        !           320: .TP 20
        !           321: \fB\er\fR
        !           322: .VS
        !           323: Carriage-return (0xd).
        !           324: .VE
        !           325: .TP 20
        !           326: \fB\et\fR
        !           327: Tab (0x9).
        !           328: .TP 20
        !           329: \fB\e{\fR
        !           330: Left brace (``{'').
        !           331: .TP 20
        !           332: \fB\e}\fR
        !           333: Right brace (``}'').
        !           334: .TP 20
        !           335: \fB\e[\fR
        !           336: Open bracket (``['').
        !           337: .TP 20
        !           338: \fB\e]\fR
        !           339: Close bracket (``]'').
        !           340: .TP 20
        !           341: \fB\e$\fR
        !           342: Dollar sign (``$'').
        !           343: .TP 20
        !           344: \fB\e<space>\fR
        !           345: Space (`` ''): doesn't terminate argument.
        !           346: .br
        !           347: .VS
        !           348: .TP 20
        !           349: \fB\e;\fR
        !           350: Semi-colon: doesn't terminate command.
        !           351: .TP 20
        !           352: \fB\e"\fR
        !           353: Double-quote.
        !           354: .TP 20
        !           355: \fB\e<newline>\fR
        !           356: Nothing:  this effectively joins two lines together
        !           357: into a single line.  This backslash feature is only provided
        !           358: when parsing Tcl commands;  it is not supported by the
        !           359: Tcl_Backslash procedure.
        !           360: .VE
        !           361: .TP 20
        !           362: \fB\e\e\fR
        !           363: Backslash (``\e'').
        !           364: .TP 20
        !           365: \fB\eC\fIx\fR
        !           366: Control-\fIx\fR (\fIx\fR AND octal 037), for any ASCII \fIx\fR except \fBM\fR
        !           367: (see below).
        !           368: .TP 20
        !           369: \fB\eM\fIx\fR
        !           370: Meta-\fIx\fR (\fIx\fR OR octal 200), for any ASCII \fIx\fR.
        !           371: .TP 20
        !           372: \fB\eCM\fIx\fR
        !           373: Control-meta-\fIx\fR ((\fIx\fR AND octal 037) OR octal 0200), for
        !           374: any ASCII \fIx\fR.
        !           375: .TP 20
        !           376: \fB\e\fIddd\fR
        !           377: The digits \fIddd\fR (one, two, or three of them) give the octal value of
        !           378: the character.
        !           379: .PP
        !           380: For example, in the command
        !           381: .DS
        !           382: \fBset a \e{x\e[\e\0yz\e141\fR
        !           383: .DE
        !           384: the second argument to \fBset\fR will be ``\fB{x[\0yza\fR''.
        !           385: .PP
        !           386: If a backslash is followed by something other than one of the options
        !           387: described above, then the backslash is transmitted to the argument
        !           388: field without any special processing, and the Tcl scanner continues
        !           389: normal processing with the next character.  For example, in the
        !           390: command
        !           391: .DS
        !           392: \fBset \e*a \e\e\e{foo\fR
        !           393: .DE
        !           394: The first argument to \fBset\fR will be \fB\e*a\fR and the second
        !           395: argument will be \fB\e{foo\fR.
        !           396: .PP
        !           397: If an argument is enclosed in braces, then backslash sequences inside
        !           398: the argument are parsed but no substitution occurs:  the backslash
        !           399: sequence is passed through to the argument as is, without making
        !           400: any special interpretation of the characters in the backslash sequence.
        !           401: In particular, backslashed braces are not counted in locating the
        !           402: matching right brace that terminates the argument.
        !           403: For example, in the
        !           404: command
        !           405: .DS
        !           406: \fBset a {\e{abc}\fR
        !           407: .DE
        !           408: the second argument to \fBset\fR will be \fB\e{abc\fR.
        !           409: .PP
        !           410: This backslash mechanism is not sufficient to generate absolutely
        !           411: any argument structure;  it only covers the
        !           412: most common cases.  To produce particularly complicated arguments
        !           413: it is probably easiest to use the \fBformat\fR command along with
        !           414: command substitution.
        !           415: 
        !           416: .SH "COMMAND SUMMARY"
        !           417: .IP [1]
        !           418: A command is just a string.
        !           419: .IP [2]
        !           420: Within a string commands are separated by newlines or semi-colons
        !           421: (unless the newline or semi-colon is within braces or brackets
        !           422: or is backslashed).
        !           423: .IP [3]
        !           424: A command consists of fields.  The first field is the name of the command,
        !           425: and may be abbreviated.
        !           426: The other fields are strings that are passed to that command as arguments.
        !           427: .IP [4]
        !           428: Fields are normally separated by white space.
        !           429: .IP [5]
        !           430: Double-quotes allow white space and semi-colons to appear within
        !           431: a single argument.
        !           432: Command substitution, variable substitution, and backslash substitution
        !           433: still occur inside quotes.
        !           434: .IP [6]
        !           435: Braces defer interpretation of special characters.
        !           436: If a field begins with a left brace, then it consists of everything
        !           437: between the left brace and the matching right brace. The
        !           438: braces themselves are not included in the argument.
        !           439: No further processing is done on the information between the braces.
        !           440: .IP [7]
        !           441: If a field doesn't begin with a brace then backslash,
        !           442: variable, and command substitution are done on the field.  Only a
        !           443: single level of processing is done:  the results of one substitution
        !           444: are not scanned again for further substitutions or any other
        !           445: special treatment.  Substitution can
        !           446: occur on any field of a command, including the command name
        !           447: as well as the arguments.
        !           448: .IP [8]
        !           449: If the first non-blank character of a command is a \fB#\fR, everything
        !           450: from the \fB#\fR up through the next newline is treated as a comment
        !           451: and ignored.
        !           452: 
        !           453: .SH "EXPRESSIONS"
        !           454: .PP
        !           455: The second major interpretation applied to strings in Tcl is
        !           456: as expressions.  Several commands, such as \fBexpr\fR, \fBfor\fR,
        !           457: and \fBif\fR, treat some of their arguments as expressions and
        !           458: call the Tcl expression processor (\fBTcl_Expr\fR) to evaluate them.
        !           459: A Tcl expression has C-like syntax and evaluates to an integer
        !           460: result.  Expressions
        !           461: may contain integer values, variable names in \fB$\fR notation
        !           462: (the variables' values must be integer strings),
        !           463: commands (embedded in brackets) that produce integer string results,
        !           464: parentheses for grouping, and operators.  Numeric values, whether they
        !           465: are passed directly or through variable or command substitution, may
        !           466: be specified either in decimal (the normal case), in octal (if the
        !           467: first character of the value is \fB0\fR), or in hexadecimal (if the first
        !           468: two characters of the value are \fB0x\fR).
        !           469: The valid operators are listed
        !           470: below, grouped in decreasing order of precedence:
        !           471: .TP 20
        !           472: \fB\-\0\0~\0\0!\fR
        !           473: Unary minus, bit-wise NOT, logical NOT.
        !           474: .TP 20
        !           475: \fB*\0\0/\0\0%\fR
        !           476: Multiply, divide, remainder.
        !           477: .TP 20
        !           478: \fB+\0\0\-\fR
        !           479: Add and subtract.
        !           480: .TP 20
        !           481: \fB<<\0\0>>\fR
        !           482: Left and right shift.
        !           483: .TP 20
        !           484: \fB<\0\0>\0\0<=\0\0>=\fR
        !           485: Boolean less, greater, less than or equal, and greater than or equal.
        !           486: Each operator produces 1 if the condition is true, 0 otherwise.
        !           487: .TP 20
        !           488: \fB==\0\0!=\fR
        !           489: Boolean equal and not equal.  Each operator produces a zero/one result.
        !           490: .TP 20
        !           491: \fB&\fR
        !           492: Bit-wise AND.
        !           493: .TP 20
        !           494: \fB^\fR
        !           495: Bit-wise exclusive OR.
        !           496: .TP 20
        !           497: \fB|\fR
        !           498: Bit-wise OR.
        !           499: .TP 20
        !           500: \fB&&\fR
        !           501: Logical AND.  Produces a 1 result if both operands are non-zero, 0 otherwise.
        !           502: .TP 20
        !           503: \fB||\fR
        !           504: Logical OR.  Produces a 0 result if both operands are zero, 1 otherwise.
        !           505: .TP 20
        !           506: \fIx\fB?\fIy\fB:\fIz\fR
        !           507: .VS
        !           508: If-then-else, as in C.  If \fIx
        !           509: evaluates to non-zero, then the result is the value of \fIy\fR.
        !           510: Otherwise the result is the value of \fIz\fR.
        !           511: .VE
        !           512: .PP
        !           513: See the C manual for more details on the results
        !           514: produced by each operator.
        !           515: All of the binary operators group left-to-right within the same
        !           516: precedence level.  For example, the expression
        !           517: .DS
        !           518: \fB(4*2) < 7\fR
        !           519: .DE
        !           520: evaluates to 0.  Evaluating the expression string
        !           521: .DS
        !           522: \fB($a + 3) < [set b]\fR
        !           523: .DE
        !           524: will cause the values of the variables \fBa\fR and \fBb\fR to be
        !           525: examined;  the result will be 1
        !           526: if \fBb\fR is greater than a by at least 3;  otherwise the result
        !           527: will be 0.
        !           528: .PP
        !           529: In general it is safest to enclose an expression in braces when
        !           530: entering it in a command:  otherwise, if the expression contains
        !           531: any white space then the Tcl interpreter will split it
        !           532: among several arguments.  For example, the command
        !           533: .DS C
        !           534: \fBexpr $a + $b\fR
        !           535: .DE
        !           536: results in three arguments being passed to \fBexpr\fR:  \fB$a\fR,
        !           537: \fB+\fR, and \fB$b\fR.  In addition, if the expression isn't in braces
        !           538: then the Tcl interpreter will perform variable and command substitution
        !           539: immediately (it will happen in the command parser rather than in
        !           540: the expression parser).  In many cases the expression is being
        !           541: passed to a command that will evaluate the expression later (or
        !           542: even many times if, for example, the expression is to be used to
        !           543: decide when to exit a loop).  Usually the desired goal is to re-do
        !           544: the variable or command substitutions each time the expression is
        !           545: evaluated, rather than once and for all at the beginning.  For example,
        !           546: the command
        !           547: .DS C
        !           548: \fBfor {set i 1} $i<=10 {set i [expr $i+1]} {...}\fR
        !           549: .DE
        !           550: is probably intended to iterate over all values of \fBi\fR from 1 to 10.
        !           551: After each iteration of the body of the loop, \fBfor\fR will pass
        !           552: its second argument to the expression evaluator to see whether or not
        !           553: to continue processing.  Unfortunately, in this case the value of \fBi\fR
        !           554: in the second argument will be substituted once and for all when the
        !           555: \fBfor\fR command is parsed.  If \fBi\fR was 0 before the \fBfor\fR
        !           556: command was invoked then \fBfor\fR's second argument will be \fB0<=10\fR
        !           557: which will always evaluate to 1, even though \fBi\fR's value eventually
        !           558: becomes greater than 10.  In the above case the loop will never
        !           559: terminate.  By placing the expression in braces, the
        !           560: substitution of \fBi\fR's
        !           561: value will be delayed;  it will be re-done each time the expression is
        !           562: evaluated, which is probably the desired result.
        !           563: 
        !           564: .SH LISTS
        !           565: .PP
        !           566: The third major way that strings are interpreted in Tcl is as lists.
        !           567: A list is just a string with a list-like structure
        !           568: consisting of fields separated by white space.  For example, the
        !           569: string
        !           570: .DS
        !           571: \fBAl Sue Anne John\fR
        !           572: .DE
        !           573: is a list with four elements or fields.
        !           574: Lists have the same basic structure as command strings, except
        !           575: that a newline character in a list is treated as a field separator
        !           576: just like space or tab.  Conventions for braces
        !           577: and backslashes are the same for lists as for commands.  For example,
        !           578: the string
        !           579: .DS
        !           580: \fBa b\e c {d e {f g h}}\fR
        !           581: .DE
        !           582: is a list with three elements:  \fBa\fR, \fBb c\fR, and \fBd e {f g h}\fR.
        !           583: Whenever an element
        !           584: is extracted from a list, the same rules about backslashes and
        !           585: braces are applied as for commands.  Thus in the example above
        !           586: when the third element is extracted from the list, the result is
        !           587: .DS
        !           588: \fBd e {f g h}\fR
        !           589: .DE
        !           590: (when the field was extracted, all that happened was to strip off
        !           591: the outermost layer of braces).  Command substitution is never
        !           592: made on a list (at least, not by the list-processing commands;  the
        !           593: list can always be passed to the Tcl interpreter for evaluation).
        !           594: .PP
        !           595: The Tcl commands \fBconcat\fR, \fBforeach\fR, \fBindex\fR,
        !           596: \fBlength\fR, \fBlist\fR, and \fBrange\fR allow you to build lists,
        !           597: extract elements from them, search them, and perform other list-related
        !           598: functions.
        !           599: 
        !           600: .SH "COMMAND RESULTS"
        !           601: .PP
        !           602: Each command produces two results:  a code and a string.  The
        !           603: code indicates whether the command completed successfully or not,
        !           604: and the string gives additional information.  The valid codes are
        !           605: defined in tcl.h, and are:
        !           606: .RS
        !           607: .TP 20
        !           608: \fBTCL_OK\fR
        !           609: This is the normal return code, and indicates that the command completed
        !           610: succesfully.  The string gives the command's return value.
        !           611: .TP 20
        !           612: \fBTCL_ERROR\fR
        !           613: Indicates that an error occurred;  the string gives a message describing
        !           614: the error.
        !           615: .VS
        !           616: The variable \fBerrorInfo\fR will contain additional information
        !           617: describing which commands and procedures were being executed when the
        !           618: error occurred.
        !           619: .VE
        !           620: .TP 20
        !           621: \fBTCL_RETURN\fR
        !           622: Indicates that the \fBreturn\fR command has been invoked, and that the
        !           623: .VS
        !           624: current procedure (or top-level command or \fBsource\fR command)
        !           625: should return immediately.  The
        !           626: string gives the return value for the procedure or command.
        !           627: .VE
        !           628: .TP 20
        !           629: \fBTCL_BREAK\fR
        !           630: Indicates that the \fBbreak\fR command has been invoked, so the
        !           631: innermost loop should abort immediately.  The string should always
        !           632: be empty.
        !           633: .TP 20
        !           634: \fBTCL_CONTINUE\fR
        !           635: Indicates that the \fBcontinue\fR command has been invoked, so the
        !           636: innermost loop should go on to the next iteration.  The string
        !           637: should always be empty.
        !           638: .RE
        !           639: Tcl programmers do not normally need to think about return codes,
        !           640: since TCL_OK is almost always returned.  If anything else is returned
        !           641: by a command, then the Tcl interpreter immediately stops processing
        !           642: commands and returns to its caller.  If there are several nested
        !           643: invocations of the Tcl interpreter in progress, then each nested
        !           644: command will usually return the error to its caller, until eventually
        !           645: the error is reported to the top-level application code.  The
        !           646: application will then display the error message for the user.
        !           647: .PP
        !           648: In a few cases, some commands will handle certain ``error'' conditions
        !           649: themselves and not return them upwards.  For example, the \fBfor\fR
        !           650: command checks for the TCL_BREAK code;  if it occurs, then \fBfor\fR
        !           651: stops executing the body of the loop and returns TCL_OK to its
        !           652: caller.  The \fBfor\fR command also handles TCL_CONTINUE codes and the
        !           653: procedure interpreter handles TCL_RETURN codes.  The \fBcatch\fR
        !           654: command allows Tcl programs to catch errors and handle them without
        !           655: aborting command interpretation any further.
        !           656: 
        !           657: .SH PROCEDURES
        !           658: .PP
        !           659: Tcl allows you to extend the command interface by defining
        !           660: procedures.  A Tcl procedure can be invoked just like any other Tcl
        !           661: command (it has a name and it receives one or more arguments).
        !           662: The only difference is that its body isn't a piece of C code linked
        !           663: into the program;  it is a string containing one or more other
        !           664: Tcl commands.  See the \fBproc\fR command for information on
        !           665: how to define procedures and what happens when they are invoked.
        !           666: 
        !           667: .SH VARIABLES
        !           668: .PP
        !           669: Tcl allows the definition of variables and the use of their values
        !           670: either through \fB$\fR-style variable substitution, the \fBset\fR
        !           671: command, or a few other mechanisms.  Variables need not be declared:
        !           672: a new variable will automatically be created each time a new variable
        !           673: name is used.  Variables may be either global or local.  If a variable
        !           674: name is used when a procedure isn't being executed, then it
        !           675: automatically refers to a global variable.  Variable names used
        !           676: within a procedure normally refer to local variables associated with that
        !           677: invocation of the procedure.  Local variables are deleted whenever
        !           678: a procedure exits.  The \fBglobal\fR command may be used to request
        !           679: that a name refer to a global variable for the duration of the current
        !           680: procedure (this is somewhat analogous to \fBextern\fR in C).
        !           681: 
        !           682: .SH "BUILT-IN COMMANDS"
        !           683: .PP
        !           684: The Tcl library provides the following built-in commands, which will
        !           685: be available in any application using Tcl.  In addition to these
        !           686: built-in commands, there may be additional commands defined by each
        !           687: application, plus commands defined as Tcl procedures.  In the command syntax
        !           688: descriptions below, optional arguments are indicated by enclosing their
        !           689: names in brackets;  apologies in advance for the confusion between this
        !           690: descriptive use of brackets and the use of brackets to invoke
        !           691: command substitution.
        !           692: Words in boldface are literals that you type verbatim to Tcl.
        !           693: Words in italics are meta-symbols;  they act as names to refer to
        !           694: a class of values that you can type.
        !           695: .TP
        !           696: \fBbreak\fR
        !           697: This command may be invoked only inside the body of a loop command
        !           698: such as \fBfor\fR or \fBforeach\fR.  It returns a TCL_BREAK code
        !           699: to signal the innermost containing loop command to return immediately.
        !           700: .TP
        !           701: \fBcase\fI string \fR[\fBin\fR] \fIpatList body patList body \fR...
        !           702: .VS
        !           703: Match \fIstring\fR against each of the \fIpatList\fR arguments
        !           704: in order.  If one matches, then evaluate the following \fIbody\fR argument
        !           705: by passing it recursively to the Tcl interpreter, and return the result
        !           706: of that evaluation.  Each \fIpatList\fR argument consists of a single
        !           707: pattern or list of patterns.  Each pattern may contain any of the wild-cards
        !           708: described under \fBstring match\fR.  If a \fIpatList\fR
        !           709: argument is \fBdefault\fR, the corresponding body will be evaluated
        !           710: if no \fIpatList\fR matches \fIstring\fR.  If no \fIpatList\fR argument
        !           711: matches \fIstring\fR and no default is given, then the \fBcase\fR
        !           712: command returns an empty string.  For example,
        !           713: .RS
        !           714: .DS
        !           715: \fBcase abc in {a b} {format 1} default {format 2} a* {format 3}
        !           716: .DE
        !           717: will return \fB3\fR, 
        !           718: .DS
        !           719: \fBcase a in {a b} {format 1} default {format 2} a* {format 3}
        !           720: .DE
        !           721: will return \fB1\fR, and
        !           722: .DS
        !           723: \fBcase xyz {a b} {format 1} default {format 2} a* {format 3}
        !           724: .DE
        !           725: will return \fB2\fR.
        !           726: .RE
        !           727: .VE
        !           728: .TP
        !           729: \fBcatch\fI command \fR[\fIvarName\fR]
        !           730: The \fBcatch\fR command may be used to prevent errors from aborting
        !           731: command interpretation.  \fBCatch\fR calls the Tcl interpreter recursively
        !           732: to execute \fIcommand\fR, and always returns a TCL_OK code, regardless of
        !           733: any errors that might occur while executing \fIcommand\fR.  The return
        !           734: value from \fBcatch\fR is a decimal string giving the
        !           735: code returned by the Tcl interpreter after executing \fIcommand\fR.
        !           736: This will be \fB0\fR (TCL_OK) if there were no errors in \fIcommand\fR; otherwise
        !           737: it will have a non-zero value corresponding to one of the exceptional
        !           738: return codes (see tcl.h for the definitions of code values).  If the
        !           739: \fIvarName\fR argument is given, then it gives the name of a variable;
        !           740: \fBcatch\fR will set the value of the variable to the string returned
        !           741: from \fIcommand\fR (either a result or an error message).
        !           742: .TP
        !           743: \fBconcat\fI arg \fR[\fIarg ...\fR]
        !           744: This command treats each argument as a list and concatenates them
        !           745: into a single list.  It permits any number of arguments.  For example,
        !           746: the command
        !           747: .RS
        !           748: .DS
        !           749: \fBconcat a b {c d e} {f {g h}}\fR
        !           750: .DE
        !           751: will return
        !           752: .DS
        !           753: \fBa b c d e f {g h}\fR
        !           754: .DE
        !           755: as its result.
        !           756: .RE
        !           757: .TP
        !           758: \fBcontinue\fR
        !           759: This command may be invoked only inside the body of a loop command
        !           760: such as \fBfor\fR or \fBforeach\fR.  It returns a  TCL_CONTINUE code
        !           761: to signal the innermost containing loop command to skip the
        !           762: remainder of the loop's body
        !           763: but continue with the next iteration of the loop.
        !           764: .TP
        !           765: \fBerror \fImessage\fR [\fIinfo\fR]
        !           766: Returns a TCL_ERROR code, which causes command interpretation to be
        !           767: unwound.  \fIMessage\fR is a string that is returned to the application
        !           768: to indicate what went wrong.
        !           769: .VS
        !           770: If the \fIinfo\fR argument is
        !           771: provided, it is used to initialize the global variable \fBerrorInfo\fR.
        !           772: \fBErrorInfo\fR is used to accumulate a stack trace of what
        !           773: was in progress when an error occurred;  as nested commands unwind,
        !           774: the Tcl interpreter adds information to \fBerrorInfo\fR.  If the
        !           775: \fIinfo\fR argument is present, it is used to initialize the
        !           776: \fBerrorInfo\fR variable, and the first increment of unwind information
        !           777: will not be added by the Tcl interpreter.  In other
        !           778: words, the command containing the \fBerror\fR command will not appear
        !           779: in the \fBerrorInfo\fR variable;  in its place will be \fIinfo\fR.
        !           780: This feature is most useful in conjunction with the \fBcatch\fR command:
        !           781: if a caught error cannot be handled successfully, \fIinfo\fR can be used
        !           782: to return a stack trace reflecting the original point of occurrence
        !           783: of the error:
        !           784: .RS
        !           785: .DS
        !           786: \fBcatch {...} errMsg
        !           787: set savedInfo $errorInfo
        !           788: \&...
        !           789: error $errMsg $savedInfo\fR
        !           790: .DE
        !           791: .RE
        !           792: .TP
        !           793: \fBeval \fIarg1 \fR[\fIarg2 ...\fR]
        !           794: \fBEval\fR takes one or more arguments, which together comprise a Tcl
        !           795: command (or collection of Tcl commands separated by newlines in the
        !           796: usual way).  \fBEval\fR concatenates all its arguments in the same
        !           797: fashion as the \fBconcat\fR command, passes the concatenated string to the
        !           798: Tcl interpreter recursively, and returns the result of that
        !           799: evaluation (or any error generated by it).
        !           800: .VE
        !           801: .TP
        !           802: \fBexec \fIcommand arg1 \fR[\fIarg2 ...\fR] [\fB< \fIinput\fR]
        !           803: The \fBexec\fR command treats its \fIcommand\fR argument as the name of
        !           804: a program to execute.  \fBExec\fR
        !           805: .VS
        !           806: performs tilde-substitution on
        !           807: \fIcommand\fR, if appropriate, then searches the directories in
        !           808: .VE
        !           809: the PATH environment variable to find
        !           810: an executable file by the name \fIcommand\fR,
        !           811: then executes the file, passing it an argument list consisting of
        !           812: \fIcommand\fR plus all of the \fIarg\fRs.  If an argument \fB<\fR appears
        !           813: anywhere among the arguments to \fBexec\fR, then neither it or the
        !           814: following argument is passed to \fIcommand\fR.  Instead, the following
        !           815: argument (\fIinput\fR) consists of input to the command;  \fBexec\fR
        !           816: will create a pipe and use it to pass \fIinput\fR to \fIcommand\fR
        !           817: as standard input.  \fBExec\fR also creates a pipe to receive \fIcommand\fR's
        !           818: output (both standard output and standard error).  The information
        !           819: received over this pipe is returned as the result of the \fBexec\fR
        !           820: command.  The \fBexec\fR command also looks at the return status
        !           821: returned by \fIcommand\fR.  Normally this should be zero;  if it is then
        !           822: \fBexec\fR returns normally.  If \fIcommand\fR returns a non-zero status,
        !           823: then \fBexec\fR will return that code;  it should be one of the ones
        !           824: defined in the section ``COMMAND RESULTS'' above.  If an out-of range
        !           825: code is returned by the command, it will cause command unwinding just
        !           826: as if TCL_ERROR had been returned; at the outermost level of command
        !           827: interpretation, the Tcl interpreter will turn the code into TCL_ERROR,
        !           828: with an appropriate error message.
        !           829: .TP
        !           830: \fBexpr \fIarg\fR
        !           831: Calls the expression processor to evaluate \fIarg\fR, and returns
        !           832: the result as a decimal string.
        !           833: .TP
        !           834: \fBfile \fIname\fR \fIoption\fR
        !           835: Operate on a file or a file name.  \fIName\fR is the name of a file;
        !           836: .VS
        !           837: if it starts with a tilde, then tilde substitution is done before
        !           838: executing the command (see the manual entry for \fBTcl_TildeSubst\fR
        !           839: for details).
        !           840: .VE
        !           841: \fIOption\fR indicates what to do with the file name.  Any unique
        !           842: abbreviation for \fIoption\fR is acceptable.  The valid options are:
        !           843: .RS
        !           844: .TP
        !           845: \fBfile \fIname \fBdirname\fR
        !           846: Return all of the characters in \fIname\fR up to but not including
        !           847: the last slash character.  If there are no slashes in \fIname\fR
        !           848: then return ``.''.  If the last slash in \fIname\fR is its first
        !           849: character, then return ``/''.
        !           850: .TP
        !           851: \fBfile \fIname \fBexecutable\fR
        !           852: Return \fB1\fR if file \fIname\fR is executable by
        !           853: the current user, \fB0\fR otherwise.
        !           854: .TP
        !           855: \fBfile \fIname \fBexists\fR
        !           856: Return \fB1\fR if file \fIname\fR exists and the current user has
        !           857: search privileges for the directories leading to it, \fB0\fR otherwise.
        !           858: .TP
        !           859: \fBfile \fIname \fBextension\fR
        !           860: Return all of the characters in \fIname\fR after and including the
        !           861: last dot in \fIname\fR.  If there is no dot in \fIname\fR then return
        !           862: the empty string.
        !           863: .TP
        !           864: \fBfile \fIname \fBisdirectory\fR
        !           865: Return \fB1\fR if file \fIname\fR is a directory,
        !           866: \fB0\fR otherwise.
        !           867: .TP
        !           868: \fBfile \fIname \fBisfile\fR
        !           869: Return \fB1\fR if file \fIname\fR is a regular file,
        !           870: \fB0\fR otherwise.
        !           871: .TP
        !           872: \fBfile \fIname \fBowned\fR
        !           873: Return \fB1\fR if file \fIname\fR is owned by the current user,
        !           874: \fB0\fR otherwise.
        !           875: .TP
        !           876: \fBfile \fIname \fBreadable\fR
        !           877: Return \fB1\fR if file \fIname\fR is readable by
        !           878: the current user, \fB0\fR otherwise.
        !           879: .TP
        !           880: \fBfile \fIname \fBrootname\fR
        !           881: Return all of the characters in \fIname\fR up to but not including
        !           882: the last ``.'' character in the name.  If \fIname\fR doesn't contain
        !           883: a dot, then return \fIname\fR.
        !           884: .TP
        !           885: \fBfile \fIname \fBtail\fR
        !           886: Return all of the characters in \fIname\fR after the last slash.
        !           887: If \fIname\fR contains no slashes then return \fIname\fR.
        !           888: .TP
        !           889: \fBfile \fIname \fBwritable\fR
        !           890: Return \fB1\fR if file \fIname\fR is writable by
        !           891: the current user, \fB0\fR otherwise.
        !           892: .RE
        !           893: .IP
        !           894: The \fBfile\fR commands that return 0/1 results are often used in
        !           895: conditional or looping commands, for example:
        !           896: .RS
        !           897: .DS
        !           898: \fBif {![file foo exists]} then {error {bad file name}} else {...}\fR
        !           899: .DE
        !           900: .RE
        !           901: .TP
        !           902: \fBfor \fIstart test next body\fR
        !           903: \fBFor\fR is a looping command, similar in structure to the C
        !           904: \fBfor\fR statement.  The \fIstart\fR, \fInext\fR, and
        !           905: \fIbody\fR arguments must be Tcl command strings, and \fItest\fR
        !           906: is an expression string.
        !           907: The \fBfor\fR command first invokes the Tcl interpreter to
        !           908: execute \fIstart\fR.  Then it repeatedly evaluates \fItest\fR as
        !           909: an expression;  if the result is non-zero it invokes the Tcl
        !           910: interpreter on \fIbody\fR, then invokes the Tcl interpreter on \fInext\fR,
        !           911: then repeats the loop.  The command terminates when \fItest\fR evaluates
        !           912: to 0.  If a \fBcontinue\fR command is invoked within \fIbody\fR then
        !           913: any remaining commands in the current execution of \fIbody\fR are skipped;
        !           914: processing continues by invoking the Tcl interpreter on \fInext\fR, then
        !           915: evaluating \fItest\fR, and so on.  If a \fBbreak\fR command is invoked
        !           916: within \fIbody\fR
        !           917: .VS
        !           918: or \fInext\fR,
        !           919: .VE
        !           920: then the \fBfor\fR command will
        !           921: return immediately.
        !           922: The operation of \fBbreak\fR and \fBcontinue\fR are similar to the
        !           923: corresponding statements in C.
        !           924: \fBFor\fR returns an empty string.
        !           925: .TP
        !           926: \fBforeach \fIvarname list body\fR
        !           927: In this command, \fIvarname\fR is the name of a variable, \fIlist\fR
        !           928: is a list of values to assign to \fIvarname\fR, and \fIbody\fR is a
        !           929: collection of Tcl commands.  For each field in \fIlist\fR (in order
        !           930: from left to right), \fBforeach\fR assigns the contents of the
        !           931: field to \fIvarname\fR (as if the \fBindex\fR command had been used
        !           932: to extract the field), then calls the Tcl interpreter to execute
        !           933: \fIbody\fR.  The \fBbreak\fR and \fBcontinue\fR statements may be
        !           934: invoked inside \fIbody\fR, with the same effect as in the \fBfor\fR
        !           935: command.  \fBForeach\fR an empty string.
        !           936: .TP
        !           937: \fBformat \fIformatString \fR[\fIarg arg ...\fR]
        !           938: This command generates a formatted string in the same way as the
        !           939: C \fBsprintf\fR procedure (it uses \fBsprintf\fR in its
        !           940: implementation).  \fIFormatString\fR indicates how to format
        !           941: the result, using \fB%\fR fields as in \fBsprintf\fR, and the additional
        !           942: arguments, if any, provide values to be substituted into the result.
        !           943: All of the \fBsprintf\fR options are valid;  see the \fBsprintf\fR
        !           944: man page for details.  Each \fIarg\fR must match the expected type
        !           945: from the \fB%\fR field in \fIformatString\fR;  the \fBformat\fR command
        !           946: converts each argument to the correct type (floating, integer, etc.)
        !           947: before passing it to \fBsprintf\fR for formatting.
        !           948: The only unusual conversion is for \fB%c\fR;  in this case the argument
        !           949: must be a decimal string, which will then be converted to the corresponding
        !           950: ASCII character value.
        !           951: \fBFormat\fR does backslash substitution on its \fIformatString\fR
        !           952: argument, so backslash sequences in \fIformatString\fR will be handled
        !           953: correctly even if the argument is in braces.
        !           954: The return value from \fBformat\fR
        !           955: is the formatted string.
        !           956: .TP
        !           957: \fBglob \fIfilename\fR [\fIfilename ...\fR]
        !           958: .VS
        !           959: This command performs filename globbing, using csh rules.  The returned
        !           960: value from \fBglob\fR is the list of expanded filenames.
        !           961: .VE
        !           962: .TP
        !           963: \fBglobal \fIvarname \fR[\fIvarname ...\fR]
        !           964: This command is ignored unless a Tcl procedure is being interpreted.
        !           965: If so, then it declares the given \fIvarname\fR's to be global variables
        !           966: rather than local ones.  For the duration of the current procedure
        !           967: (and only while executing in the current procedure), any reference to
        !           968: any of the \fIvarname\fRs will be bound to a global variable instead
        !           969: of a local one.
        !           970: .TP
        !           971: \fBhistory \fR[\fIoption \fR[\fIarg arg ...\fR]
        !           972: .VS
        !           973: Note:  this command may not be available in all Tcl-based applications.
        !           974: Typically, only those that receive command input in a typescript
        !           975: form will support history.
        !           976: The \fBhistory\fR command performs one of several operations related to
        !           977: recently-executed commands recorded in a history list.  Each of
        !           978: these recorded commands is referred to as an ``event''.  When
        !           979: specifying an event to the \fBhistory\fR command, the following
        !           980: forms may be used:
        !           981: .RS
        !           982: .IP [1]
        !           983: A number:  if positive, it refers to the event with
        !           984: that number (all events are numbered starting at 1).  If the number
        !           985: is negative, it selects an event relative to the current event
        !           986: (\fB-1\fR refers to the previous event, \fB-2\fR to the one before that, and
        !           987: so on).
        !           988: .IP [2]
        !           989: A string:  selects the most recent event that matches the string.
        !           990: An event is considered to match the string either if the string is
        !           991: the same as the first characters of the event, or if the string
        !           992: matches the event in the sense of the \fBstring match\fR command.
        !           993: .LP
        !           994: The \fBhistory\fR command can take any of the following forms:
        !           995: .TP
        !           996: \fBhistory\fR
        !           997: Re-execute the most recent command in the history list and return
        !           998: its result.  This command has the same effect as \fBhistory redo -1\fR.
        !           999: .TP
        !          1000: \fBhistory add\fI command \fR[\fBexec\fR]
        !          1001: Add the \fIcommand\fR argument to the history list as a new event.  If
        !          1002: \fBexec\fR is specified (or abbreviated) then the command is also
        !          1003: executed and its result is returned.  If \fBexec\fR isn't specified
        !          1004: then an empty string is returned as result.
        !          1005: .TP
        !          1006: \fBhistory change\fI newValue\fR [\fIevent\fR]
        !          1007: Replace the value recorded for an event with \fInewValue\fR.  \fIEvent\fR
        !          1008: specifies the event to replace, and
        !          1009: defaults to the \fIcurrent\fR event (not event \fB-1\fR).  This command
        !          1010: is intended for use in commands that implement new forms of history
        !          1011: substitution and wish to replace the current event (which invokes the
        !          1012: substitution) with the command created through substitution.  The return
        !          1013: value is an empty string.
        !          1014: .TP
        !          1015: \fBhistory event\fR [\fIevent\fR]
        !          1016: Returns the value of the event given by \fIevent\fR.  \fIEvent\fR
        !          1017: defaults to \fB-1\fR.  This command causes history revision to occur:
        !          1018: see below for details.
        !          1019: .TP
        !          1020: \fBhistory info \fR[\fIcount\fR]
        !          1021: Returns a formatted string (intended for humans to read) giving
        !          1022: the event number and contents for each of the events in the history
        !          1023: list except the current event.  If \fIcount\fR is specified
        !          1024: then only the most recent \fIcount\fR events are returned.
        !          1025: .TP
        !          1026: \fBhistory keep \fIcount\fR
        !          1027: This command may be used to change the size of the history list to
        !          1028: \fIcount\fR events.  Initially, 20 events are retained in the history
        !          1029: list.  This command returns an empty string.
        !          1030: .TP
        !          1031: \fBhistory nextid\fR
        !          1032: Returns the number of the next event to be recorded
        !          1033: in the history list.  It is useful for things like printing the
        !          1034: event number in command-line prompts.
        !          1035: .TP
        !          1036: \fBhistory redo \fR[\fIevent\fR]
        !          1037: Re-execute the command indicated by \fIevent\fR and return its result.
        !          1038: \fIEvent\fR defaults to \fB-1\fR.  This command results in history
        !          1039: revision:  see below for details.
        !          1040: .TP
        !          1041: \fBhistory substitute \fIold new \fR[\fIevent\fR]
        !          1042: Retrieve the command given by \fIevent\fR
        !          1043: (\fB-1\fR by default), replace any occurences of \fIold\fR by
        !          1044: \fInew\fR in the command (only simple character equality is supported;
        !          1045: no wild cards), execute the resulting command, and return the result
        !          1046: of that execution.  This command results in history
        !          1047: revision:  see below for details.
        !          1048: .TP
        !          1049: \fBhistory words \fIselector\fR [\fIevent\fR]
        !          1050: Retrieve from the command given by \fIevent\fR (\fB-1\fR by default)
        !          1051: the words given by \fIselector\fR, and return those words in a string
        !          1052: separated by spaces.  The \fBselector\fR argument has three forms.
        !          1053: If it is a single number then it selects the word given by that
        !          1054: number (\fB0\fR for the command name, \fB1\fR for its first argument,
        !          1055: and so on).  If it consists of two numbers separated by a dash,
        !          1056: then it selects all the arguments between those two.  Otherwise
        !          1057: \fBseletor\fR is treated as a pattern;  all words matching that
        !          1058: pattern (in the sense of \fBstring match\fR) are returned.  In
        !          1059: the numeric forms \fB$\fR may be used
        !          1060: to select the last word of a command.
        !          1061: For example, suppose the most recent command in the history list is
        !          1062: .RS
        !          1063: .DS
        !          1064: \fBformat  {%s is %d years old} Alice [expr $ageInMonths/12]\fR
        !          1065: .DE
        !          1066: Below are some history commands and the results they would produce:
        !          1067: .DS
        !          1068: .ta 4c
        !          1069: .fi
        !          1070: .UL Command "  "
        !          1071: .UL Result
        !          1072: .nf
        !          1073: 
        !          1074: \fBhistory words $     [expr $ageInMonths*12]\fR
        !          1075: \fBhistory words 1-2   {%s is %d years  old} Alice\fR
        !          1076: \fBhistory words *a*o* {%s is %d years old} [expr $ageInMonths*12]\fR
        !          1077: .DE
        !          1078: \fBHistory words\fR results in history revision:  see below for details.
        !          1079: .RE
        !          1080: The history options \fBredo\fR, \fBsubstitute\fR, and \fBwords\fR result
        !          1081: in ``history revision''.  If a history command with one of these options
        !          1082: can be traced directly to the current history event (e.g. the current
        !          1083: event invoked the history command directly or through command
        !          1084: substitution), then the current event is modified to eliminate the
        !          1085: history command and replace it with the result of the history
        !          1086: substitution.  For example, suppose that the most recent command in
        !          1087: the history list is
        !          1088: .DS
        !          1089: \fBset a [expr $b+2]\fR
        !          1090: .DE
        !          1091: and suppose that the next command invoked is one of the ones on
        !          1092: the left side of the table below.  The command actually recorded in
        !          1093: the history event will be the corresponding one on the right side
        !          1094: of the table.
        !          1095: .ne 1.5c
        !          1096: .DS
        !          1097: .ta 4c
        !          1098: .fi
        !          1099: .UL "Command Typed" "  "
        !          1100: .UL "Command Recorded"
        !          1101: .nf
        !          1102: 
        !          1103: \fBhistory     set a [expr $b+2]\fR
        !          1104: \fBhistory s a b       set b [expr $b+2]\fR
        !          1105: \fBset c [history w 2] set c [expr $b+2]\fR
        !          1106: .DE
        !          1107: History revision only occurs for history commands that can be directly
        !          1108: traced to the current event.  For example, the command
        !          1109: \fBeval history\fR will not result in history revision, because
        !          1110: the history command is invoked indirectly by \fBeval\fR.  If history
        !          1111: revision is desired in cases like this, it can be achieved by
        !          1112: requesting it explicitly with \fBhistory change\fR.
        !          1113: .RE
        !          1114: .VE
        !          1115: .TP
        !          1116: \fBif \fItest \fR[\fBthen\fR] \fItrueBody \fR[[\fBelse\fR] \fIfalseBody\fR]
        !          1117: The \fIif\fR command evaluates \fItest\fR as an expression (in the
        !          1118: same way that \fBexpr\fR evaluates its argument).  If the
        !          1119: result is non-zero then \fItrueBody\fR is called by passing it to the
        !          1120: Tcl interpreter.  Otherwise \fIfalseBody\fR is executed by passing it to
        !          1121: the Tcl interpreter.  The \fBthen\fR and \fBelse\fR arguments are optional
        !          1122: ``noise words'' to make the command easier to read.  \fIFalseBody\fR is
        !          1123: also optional;  if it isn't specified then the command does nothing if
        !          1124: \fItest\fR evaluates to zero.  The return value from \fBif\fR is
        !          1125: the value of the last command executed in \fItrueBody\fR or
        !          1126: \fIfalseBody\fR, or the empty string if \fItest\fR evaluates to zero and
        !          1127: \fIfalseBody\fR isn't specified.
        !          1128: .TP
        !          1129: \fBindex \fIvalue index \fR[\fBchars\fR]
        !          1130: Extract an element from a list or a character from a string.  If the
        !          1131: \fBchars\fR keyword isn't specified, then \fBindex\fR treats \fIvalue\fR
        !          1132: as a list and returns the \fIindex\fR'th field from it.  In extracting
        !          1133: the field, \fIindex\fR observes the same rules concerning braces
        !          1134: and backslashes as the Tcl command interpreter;  however, variable
        !          1135: substitution and command substitution do not occur.  If \fIindex\fR is
        !          1136: greater than or equal to the number of elements in \fIvalue\fR, then the empty
        !          1137: string is returned.  If the \fBchars\fR keyword is specified (or any
        !          1138: abbreviation of it), then \fIvalue\fR is treated as a string and the
        !          1139: command returns the \fIindex\fR'th character from it (or the empty string
        !          1140: if there aren't at least \fIindex\fR+1 characters in the string).
        !          1141: Index 0 refers to the first element or character of \fIvalue\fR.
        !          1142: .TP
        !          1143: \fBinfo \fIoption \fR[\fIarg arg ...\fR]
        !          1144: Provide information about various internals to the Tcl interpreter.
        !          1145: The legal \fIoption\fR's (which may be abbreviated) are:
        !          1146: .RS
        !          1147: .TP
        !          1148: \fBinfo args \fIprocname\fR
        !          1149: Returns a list containing the names of the arguments to procedure
        !          1150: \fIprocname\fR, in order.  \fIProcname\fR must be the name of a
        !          1151: Tcl command procedure.
        !          1152: .TP
        !          1153: \fBinfo body \fIprocname\fR
        !          1154: Returns the body of procedure \fIprocname\fR.  \fIProcname\fR must be
        !          1155: the name of a Tcl command procedure.
        !          1156: .TP
        !          1157: \fBinfo commands \fR[\fIpattern\fR]
        !          1158: .VS
        !          1159: If \fIpattern\fR isn't specified, returns a list of names of all the
        !          1160: Tcl commands, including both the built-in commands written in C and
        !          1161: the command procedures defined using the \fBproc\fR command.
        !          1162: If \fIpattern\fR is specified, only those names matching \fIpattern\fR
        !          1163: are returned.  Matching is determined using the same rules as for
        !          1164: \fBstring match\fR.
        !          1165: .VE
        !          1166: .TP
        !          1167: \fBinfo cmdcount\fR
        !          1168: Returns a count of the total number of commands that have been invoked
        !          1169: in this interpreter.
        !          1170: .TP
        !          1171: \fBinfo default \fIprocname arg varname\fR
        !          1172: \fIProcname\fR must be the name of a Tcl command procedure and \fIarg\fR
        !          1173: must be the name of an argument to that procedure.  If \fIarg\fR
        !          1174: doesn't have a default value then the command returns \fB0\fR.
        !          1175: Otherwise it returns \fB1\fR and places the default value of \fIarg\fR
        !          1176: into variable \fIvarname\fR.
        !          1177: .TP
        !          1178: \fBinfo exists \fIvarName\fR
        !          1179: Returns \fB1\fR if the variable named \fIvarName\fR exists in the
        !          1180: current context (either as a global or local variable), returns \fB0\fR
        !          1181: otherwise.
        !          1182: .TP
        !          1183: \fBinfo globals \fR[\fIpattern\fR]
        !          1184: .VS
        !          1185: If \fIpattern\fR isn't specified, returns a list of all the names
        !          1186: of currently-defined global variables.
        !          1187: If \fIpattern\fR is specified, only those names matching \fIpattern\fR
        !          1188: are returned.  Matching is determined using the same rules as for
        !          1189: \fBstring match\fR.
        !          1190: .TP
        !          1191: \fBinfo level\fR [\fInumber\fR]
        !          1192: If \fInumber\fR is not specified, this command returns a number
        !          1193: giving the stack level of the invoking procedure, or 0 if the
        !          1194: command is invoked at top-level.  If \fInumber\fR is specified,
        !          1195: then the result is a list consisting of the name and arguments for the
        !          1196: procedure call at level \fInumber\fR on the stack.  If \fInumber\fR
        !          1197: is positive then it selects a particular stack level (1 refers
        !          1198: to the top-most active procedure, 2 to the procedure it called, and
        !          1199: so on);  otherwise it gives a level relative to the current level
        !          1200: (0 refers to the current procedure, -1 to its caller, and so on).
        !          1201: See the \fBuplevel\fR command for more information on what stack
        !          1202: levels mean.
        !          1203: .TP
        !          1204: \fBinfo locals \fR[\fIpattern\fR]
        !          1205: If \fIpattern\fR isn't specified, returns a list of all the names
        !          1206: of currently-defined local variables, including arguments to the
        !          1207: current procedure, if any.
        !          1208: If \fIpattern\fR is specified, only those names matching \fIpattern\fR
        !          1209: are returned.  Matching is determined using the same rules as for
        !          1210: \fBstring match\fR.
        !          1211: .TP
        !          1212: \fBinfo procs \fR[\fIpattern\fR]
        !          1213: If \fIpattern\fR isn't specified, returns a list of all the
        !          1214: names of Tcl command procedures.
        !          1215: If \fIpattern\fR is specified, only those names matching \fIpattern\fR
        !          1216: are returned.  Matching is determined using the same rules as for
        !          1217: \fBstring match\fR.
        !          1218: .TP
        !          1219: \fBinfo tclversion\fR
        !          1220: Returns the version number for this version of Tcl in the form \fIx.y\fR,
        !          1221: where changes to \fIx\fR represent major changes with probable
        !          1222: incompatibilities and changes to \fIy\fR represent small enhancements and
        !          1223: bug fixes that retain backward compatibility.
        !          1224: .VE
        !          1225: .TP
        !          1226: \fBinfo vars\fR
        !          1227: Returns a list of all the names of currently-visible variables, including
        !          1228: both locals and currently-visible globals.
        !          1229: .RE
        !          1230: .TP
        !          1231: \fBlength \fIvalue\fR [\fBchars\fR]
        !          1232: If \fBchars\fR isn't specified, treats \fIvalue\fR as a list
        !          1233: and returns the number of elements in the list.  If \fBchars\fR
        !          1234: is specified (or any abbreviation of it), then \fBlength\fR
        !          1235: treats \fIvalue\fR as a string and returns the number of characters
        !          1236: in it (not including the terminating null character).
        !          1237: .TP
        !          1238: \fBlist \fIarg1 \fR[\fIarg2 ...\fR]
        !          1239: This command returns a list comprised of all the \fIarg\fRs.  Braces
        !          1240: and backslashes get added as necessary, so that the \fBindex\fR command
        !          1241: may be used on the result to re-extract the original arguments, and also
        !          1242: so that \fBeval\fR may be used to execute the resulting list, with
        !          1243: \fIarg1\fR comprising the command's name and the other \fIarg\fRs comprising
        !          1244: its arguments.  \fBList\fR produces slightly different results than
        !          1245: \fBconcat\fR:  \fBconcat\fR removes one level of grouping before forming
        !          1246: the list, while \fBlist\fR works directly from the original arguments.
        !          1247: For example, the command
        !          1248: .RS
        !          1249: .DS
        !          1250: \fBlist a b {c d e} {f {g h}}
        !          1251: .DE
        !          1252: will return
        !          1253: .DS
        !          1254: \fBa b {c d e} {f {g h}}
        !          1255: .DE
        !          1256: while \fBconcat\fR with the same arguments will return
        !          1257: .DS
        !          1258: \fBa b c d e f {g h}\fR
        !          1259: .DE
        !          1260: .RE
        !          1261: .TP
        !          1262: \fBprint \fIstring \fR[\fIfile \fR[\fBappend\fR]]
        !          1263: .VS
        !          1264: Print the \fIstring\fR argument.  If no \fIfile\fR is specified then
        !          1265: \fIstring\fR is output to the standard output file.  If \fIfile\fR is
        !          1266: specified, then \fIstring\fR is output to that file.  If the \fBappend\fR
        !          1267: option is given, then \fIstring\fR is appended to \fIfile\fR;  otherwise
        !          1268: any existing contents of \fIfile\fR are discarded before \fIstring\fR
        !          1269: is written to the file.
        !          1270: .VE
        !          1271: .TP
        !          1272: \fBproc \fIname args body\fR
        !          1273: The \fBproc\fR command creates a new Tcl command procedure,
        !          1274: \fIname\fR, replacing
        !          1275: any existing command there may have been by that name.  Whenever the
        !          1276: new command is invoked, the contents of \fIbody\fR will be executed
        !          1277: by the Tcl interpreter.  \fIArgs\fR specifies the formal arguments to the
        !          1278: procedure.  It consists of a list, possibly empty, each of whose
        !          1279: elements specifies
        !          1280: one argument.  Each argument specifier is also a list with either
        !          1281: one or two fields.  If there is only a single field in the specifier,
        !          1282: then it is the name of the argument;  if there are two fields, then
        !          1283: the first is the argument name and the second is its default value.
        !          1284: braces and backslashes may be used in the usual way to specify
        !          1285: complex default values.
        !          1286: .IP
        !          1287: When \fIname\fR is invoked, a local variable
        !          1288: will be created for each of the formal arguments to the procedure;  its
        !          1289: value will be the value of corresponding argument in the invoking command
        !          1290: or the argument's default value.
        !          1291: Arguments with default values need not be
        !          1292: specified in a procedure invocation.  However, there must be enough
        !          1293: actual arguments for all the
        !          1294: formal arguments that don't have defaults, and there must not be any extra
        !          1295: actual arguments.  There is one special case to permit procedures with
        !          1296: variable numbers of arguments.  If the last formal argument has the name
        !          1297: \fBargs\fR, then a call to the procedure may contain more actual arguments
        !          1298: than the procedure has formals.  In this case, all of the actual arguments
        !          1299: starting at the one that would be assigned to \fBargs\fR are combined into
        !          1300: a list (as if the \fBlist\fR command had been used);  this combined value
        !          1301: is assigned to the local variable \fBargs\fR.
        !          1302: .IP
        !          1303: When \fIbody\fR is being executed, variable names normally refer to
        !          1304: local variables, which are created automatically when referenced and
        !          1305: deleted when the procedure returns.  One local variable is automatically
        !          1306: created for each of the procedure's arguments.
        !          1307: Global variables can only be accessed by invoking
        !          1308: the \fBglobal\fR command.
        !          1309: .IP
        !          1310: The \fBproc\fR command returns the null string.  When a procedure is
        !          1311: invoked, the procedure's return value is the value specified in a
        !          1312: \fBreturn\fR command.  If the procedure doesn't execute an explicit
        !          1313: \fBreturn\fR, then its return value is the value of the last command
        !          1314: executed in the procedure's body.
        !          1315: If an error occurs while executing the procedure
        !          1316: body, then the procedure-as-a-whole will return that same error.
        !          1317: .TP
        !          1318: \fBrange \fIvalue first last \fR[\fBchars\fR]
        !          1319: Return a range of fields or characters from \fIvalue\fR.  If the
        !          1320: \fBchars\fR keyword isn't specified, then \fIvalue\fR must be
        !          1321: a list and \fBrange\fR will return a new list consisting of elements
        !          1322: \fIfirst\fR through \fIlast\fR, inclusive.  The
        !          1323: special keyword \fBend\fR may be specified for \fIlast\fR; in
        !          1324: this case all the elements of \fIvalue\fR starting at \fIfirst\fR
        !          1325: are returned.  If the \fBchars\fR keyword, or any abbreviation of
        !          1326: it, is specified, then \fBrange\fR treats \fIvalue\fR as a character
        !          1327: string and returns characters \fIfirst\fR through \fIlast\fR of
        !          1328: it, inclusive.  Once again, the \fBend\fR keyword may be used for
        !          1329: \fIlast\fR.  In both cases if a \fIlast\fR value is specified greater
        !          1330: than the size of \fIvalue\fR it is equivalent to specifying \fBend\fR;
        !          1331: if \fIlast\fR is less than \fIfirst\fR then an empty string is returned.
        !          1332: Note: ``\fBrange \fIvalue first first\fR'' does not always produce the
        !          1333: same results as ``\fBindex \fIvalue first\fR'' (although it often does
        !          1334: for simple fields that aren't enclosed in braces);  it does, however,
        !          1335: produce exactly the same results as ``\fBlist [index \fIvalue first\fB]\fR''
        !          1336: .TP
        !          1337: \fBrename \fIoldName newName\fR
        !          1338: .VS
        !          1339: Rename the command that used to be called \fIoldName\fR so that it
        !          1340: is now called \fInewName\fR.  If \fInewName\fR is an empty string
        !          1341: (e.g. {}) then \fIoldName\fR is deleted.  The \fBrename\fR command
        !          1342: returns an empty string as result.
        !          1343: .VE
        !          1344: .TP
        !          1345: \fBreturn \fR[\fIvalue\fR]
        !          1346: Return immediately from the current procedure
        !          1347: .VS
        !          1348: (or top-level command or \fBsource\fR command),
        !          1349: .VE
        !          1350: with \fIvalue\fR as the return value.  If \fIvalue\fR is not specified,
        !          1351: an empty string will be returned as result.
        !          1352: .VE
        !          1353: .TP
        !          1354: \fBscan \fIstring format varname1 \fR[\fIvarname2 ...\fR]
        !          1355: This command parses fields from an input string in the same fashion
        !          1356: as the C \fBsscanf\fR procedure.  \fIString\fR gives the input to
        !          1357: be parsed and \fIformat\fR indicates how to parse it, using \fB%\fR
        !          1358: fields as in \fBsscanf\fR.  All of the \fBsscanf\fR options are valid;
        !          1359: see the \fBsscanf\fR man page for details.  Each \fIvarname\fR gives
        !          1360: the name of a variable;  when a field is scanned from \fIstring\fR,
        !          1361: the result is converted back into a string and assigned to the
        !          1362: corresponding \fIvarname\fR.  The only unusual conversion is for
        !          1363: \fB%c\fR;  in this case, the character value is converted to a
        !          1364: decimal string, which is then assigned to the corresponding \fIvarname\fR.
        !          1365: .VS
        !          1366: .TP
        !          1367: \fBset \fIvarname \fR[\fIvalue\fR]
        !          1368: .VS
        !          1369: If \fIvalue\fR isn't specified, then return the current value of
        !          1370: \fIvarname\fR.  If \fIvalue\fR is specified, then set
        !          1371: .VE
        !          1372: the value of \fIvarname\fR to \fIvalue\fR, creating a new variable
        !          1373: if one doesn't already exist.  If no procedure is active, then
        !          1374: \fIvarname\fR refers to a global variable.  If a procedure is
        !          1375: active, then \fIvarname\fR refers to a parameter or local variable
        !          1376: of the procedure, unless the \fIglobal\fR command has been invoked
        !          1377: to declare \fIvarname\fR to be global.
        !          1378: .VE
        !          1379: .TP
        !          1380: \fBsource \fIfileName\fR
        !          1381: Read file \fIfileName\fR and pass the contents to the Tcl interpreter
        !          1382: as a sequence of commands to execute in the normal fashion.  The return
        !          1383: value of \fBsource\fR is the return value of the last command executed
        !          1384: from the file.  If an error occurs in executing the contents of the
        !          1385: file, then the \fBsource\fR command will return that error.
        !          1386: .VS
        !          1387: If a \fBreturn\fR command is invoked from within the file, the remainder of
        !          1388: the file will be skipped and the \fBsource\fR command will return
        !          1389: normally with the result from the \fBreturn\fR command.
        !          1390: If \fIfileName\fR starts with a tilde, then it is tilde-substituted
        !          1391: as described in the \fBTcl_TildeSubst\fR manual entry.
        !          1392: .VE
        !          1393: .TP
        !          1394: \fBstring \fIoption a b\fR
        !          1395: Perform a string operation on the two operands \fIa\fR and \fIb\fR,
        !          1396: based on \fIoption\fR.  The possible options are:
        !          1397: .RS
        !          1398: .TP
        !          1399: \fBstring compare \fIa b\fR
        !          1400: Perform a character-by-character comparison of strings \fIa\fR and
        !          1401: \fIb\fR, in the same way as the C \fBstrcmp\fR procedure.  Return
        !          1402: -1, 0, or 1, depending on whether \fIa\fR is lexicographically
        !          1403: less than, equal to, or greater than \fIb\fR.
        !          1404: .TP
        !          1405: \fBstring first \fIa b\fR
        !          1406: Search \fIb\fR for a sequence of characters that exactly match
        !          1407: the characters in \fIa\fR.  If found, return the index of the
        !          1408: first character in the first such match within \fIb\fR.  If not
        !          1409: found, return -1.
        !          1410: .TP
        !          1411: \fBstring last \fIa b\fR
        !          1412: Search \fIb\fR for a sequence of characters that exactly match
        !          1413: the characters in \fIa\fR.  If found, return the index of the
        !          1414: first character in the last such match within \fIb\fR.  If there
        !          1415: is no match, then return -1.
        !          1416: .br
        !          1417: .VS
        !          1418: .TP
        !          1419: \fBstring match \fIpattern\fR \fIstring\fR
        !          1420: See if \fIpattern\fR matches \fIstring\fR;  return 1 if it does, 0
        !          1421: if it doesn't.  Matching is done in a fashion similar to that
        !          1422: used by the C-shell.  For the two strings to match, their contents
        !          1423: must be identical except that the following special sequences
        !          1424: may appear in \fIpattern\fR:
        !          1425: .RS
        !          1426: .IP \fB*\fR 10
        !          1427: Matches any sequence of characters in \fIstring\fR,
        !          1428: including a null string.
        !          1429: .IP \fB?\fR 10
        !          1430: Matches any single character in \fIstring\fR.
        !          1431: .IP \fB[\fIchars\fB]\fR 10
        !          1432: Matches any character in the set given by \fIchars\fR.  If a sequence
        !          1433: of the form
        !          1434: \fIx\fB\-\fIy\fR appears in \fIchars\fR, then any character
        !          1435: between \fIx\fR and \fIy\fR, inclusive, will match.
        !          1436: .IP\fB\e\fIx\fR 10
        !          1437: Matches the single character \fIx\fR.  This provides a way of
        !          1438: avoiding the special interpretation of the characters
        !          1439: \fB*?[]\e\fR in \fIpattern\fR.
        !          1440: .RE
        !          1441: .RE
        !          1442: .VE
        !          1443: .IP
        !          1444: Unique abbreviations for \fIoption\fR are acceptable.
        !          1445: .TP
        !          1446: \fBtime \fIcommand\fR [\fIcount\fR]
        !          1447: This command will call the Tcl interpreter \fIcount\fR
        !          1448: times to execute \fIcommand\fR (or once if \fIcount\fR isn't
        !          1449: specified).  It will then return a string of the form
        !          1450: .RS
        !          1451: .DS
        !          1452: \fB503 microseconds per iteration\fR
        !          1453: .DE
        !          1454: which indicates the average amount of time required per iteration,
        !          1455: in microseconds.
        !          1456: Time is measured in elapsed time, not CPU time.
        !          1457: .RE
        !          1458: .TP
        !          1459: \fBuplevel \fR[\fIlevel\fR]\fI command \fR[\fIcommand ...\fR]
        !          1460: .VS
        !          1461: All of the \fIcommand\fR arguments are concatenated as if they had
        !          1462: been passed to \fBconcat\fR;  the result is then evaluated in the
        !          1463: variable context indicated by \fIlevel\fR.  \fBUplevel\fR returns
        !          1464: the result of that evaluation.  If \fIlevel\fR is an integer, then
        !          1465: it gives a distance (up the procedure calling stack) to move before
        !          1466: executing the command.  If \fIlevel\fR consists of \fB#\fR followed by
        !          1467: a number then the number gives an absolute level number.  If \fIlevel\fR
        !          1468: is omitted then it defaults to \fB1\fR.  \fILevel\fR cannot be
        !          1469: defaulted if the first \fIcommand\fR argument starts with a digit or \fB#\fR.
        !          1470: For example, suppose that procedure \fBa\fR was invoked
        !          1471: from top-level, and that it called \fBb\fR, and that \fBb\fR called \fBc\fR.
        !          1472: Suppose that \fBc\fR invokes the \fBuplevel\fR command.  If \fIlevel\fR
        !          1473: is \fB1\fR or \fB#2\fR  or omitted, then the command will be executed
        !          1474: in the variable context of \fBb\fR.  If \fIlevel\fR is \fB2\fR or \fB#1\fR
        !          1475: then the command will be executed in the variable context of \fBa\fR.
        !          1476: If \fIlevel\fR is \fB3\fR or \fB#0\fR then the command will be executed
        !          1477: at top-level (only global variables will be visible).
        !          1478: The \fBuplevel\fR command causes the invoking procedure to disappear
        !          1479: from the procedure calling stack while the command is being executed.
        !          1480: In the above example, suppose \fBc\fR invokes the command
        !          1481: .RS
        !          1482: .DS
        !          1483: \fBuplevel 1 {set x 43; d}
        !          1484: .DE
        !          1485: where \fBc\fR is another Tcl procedure.  The \fBset\fR command will
        !          1486: modify the variable \fBx\fR in \fBb\fR's context, and \fBd\fR will execute
        !          1487: at level 3, as if called from \fBb\fR.  If it in turn executes
        !          1488: the command
        !          1489: .DS
        !          1490: \fBuplevel {set x 42}
        !          1491: .DE
        !          1492: then the \fBset\fR command will modify the same variable \fBx\fR in \fBb\fR's
        !          1493: context:  the procedure \fBc\fR does not appear to be on the call stack
        !          1494: when \fBd\fR is executing.  The command ``\fBinfo level\fR'' may
        !          1495: be used to obtain the level of the current procedure.
        !          1496: \fBUplevel\fR makes it possible to implement new control
        !          1497: constructs as Tcl procedures (for example, \fBuplevel\fR could
        !          1498: be used to implement the \fBwhile\fR construct as a Tcl procedure).
        !          1499: .VE
        !          1500: .RE
        !          1501: 
        !          1502: .VS
        !          1503: .SH "BUILT-IN VARIABLES"
        !          1504: .PP
        !          1505: The following global variables are created and managed automatically
        !          1506: by the Tcl library.  These variables should normally be treated as
        !          1507: read-only by application-specific code and by users.
        !          1508: .TP
        !          1509: \fBerrorInfo\fR
        !          1510: After an error has occurred, this string will contain two or more lines
        !          1511: identifying the Tcl commands and procedures that were being executed
        !          1512: when the most recent error occurred.
        !          1513: .TP
        !          1514: \fBnoAbbrev\fR
        !          1515: If this variable has the value \fB1\fR then abbreviations are disallowed
        !          1516: for command names.  If the variable doesn't exist or has a value other
        !          1517: than \fB1\fR then abbreviations are permitted.
        !          1518: .VE
        !          1519: 
        !          1520: .SH AUTHOR
        !          1521: John Ousterhout, University of California at Berkeley ([email protected])

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.