From: peter@ficc.uu.net (Peter da Silva)
Newsgroups: alt.sources
Subject: TCL documentation (part 01/02)
Message-ID: <8T323-8ficc@ficc.uu.net>
Date: 9 Mar 90 03:47:45 GMT
Distribution: alt
Organization: Xenix Support, FICC
Lines: 1595
Posted: Fri Mar  9 04:47:45 1990


Archive-name: tcl/DocPart01

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then feed it
# into a shell via "sh file" or similar.  To overwrite existing files,
# type "sh file -c".
# The tool that generated this appeared in the comp.sources.unix newsgroup;
# send mail to comp-sources-unix@uunet.uu.net if you want that tool.
# If this archive is complete, you will see the following message at the end:
#		"End of archive 1 (of 2)."
# Contents:  MANIFEST Tcl.1 tmac.sprite
# Wrapped by peter@ficc.uu.net on Thu Mar  8 21:45:27 1990
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'MANIFEST' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'MANIFEST'\"
else
echo shar: Extracting \"'MANIFEST'\" \(746 characters\)
sed "s/^X//" >'MANIFEST' <<'END_OF_FILE'
X   File Name		Archive #	Description
X----------------------------------------------------------
X MANIFEST                   1	
X Backslash.3                2	
X CreateComm.3               2	
X CreateInte.3               2	
X CreateTrac.3               2	
X DeleteComm.3               2	
X DeleteInte.3               2	
X DeleteTrac.3               2	
X Eval.3                     2	
X Expr.3                     2	
X GetVar.3                   2	
X Interp.3                   2	
X Makefile                   2	
X Merge.3                    2	
X Return.3                   2	
X SetVar.3                   2	
X SplitList.3                2	
X StringMatc.3               2	
X Tcl.1                      1	
X WatchInter.3               2	
X tmac.sprite                1	
END_OF_FILE
if test 746 -ne `wc -c <'MANIFEST'`; then
    echo shar: \"'MANIFEST'\" unpacked with wrong size!
fi
# end of 'MANIFEST'
fi
if test -f 'Tcl.1' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'Tcl.1'\"
else
echo shar: Extracting \"'Tcl.1'\" \(53444 characters\)
sed "s/^X//" >'Tcl.1' <<'END_OF_FILE'
X'\" Copyright 1989 Regents of the University of California
X'\" Permission to use, copy, modify, and distribute this
X'\" documentation for any purpose and without fee is hereby
X'\" granted, provided that this notice appears in all copies.
X'\" The University of California makes no representations about
X'\" the suitability of this material for any purpose.  It is
X'\" provided "as is" without express or implied warranty.
X'\" 
X'\" $Header: /sprite/src/lib/tcl/RCS/Tcl.man,v 1.19 90/01/27 14:47:40 ouster Exp $ SPRITE (Berkeley)
X'
X.so \*(]ltmac.sprite
X.HS Tcl tcl
X.BS
X.SH NAME
XTcl \- overview of tool command language facilities
X.BE
X
X.SH INTRODUCTION
X.PP
XTcl stands for ``tool command language'' and is pronounced ``tickle.''
XIt is actually two things:
Xa language and a library.
XFirst, Tcl is a simple textual language,
Xintended primarily for issuing commands to interactive programs such
Xas text editors, debuggers, illustrators, and shells.  It has
Xa simple syntax and is also programmable, so
XTcl users can write command procedures to provide more powerful
Xcommands than those in the built-in set.
X.PP
XSecond, Tcl is a library package that can be embedded in application
Xprograms.  The Tcl library consists of a parser for the Tcl
Xlanguage, routines to implement the Tcl built-in commands, and
Xprocedures that allow each application to extend Tcl with additional
Xcommands specific to that application.  The application program
Xgenerates Tcl commands and passes them to the Tcl parser for
Xexecution.  Commands may be generated
Xby reading characters from an input
Xsource, or by associating command strings with elements of the
Xapplication's user interface, such as menu entries, buttons, or
Xkeystrokes.
XWhen the Tcl library receives commands it parses them
Xinto component fields and executes built-in commands directly.
XFor commands implemented by the
Xapplication, Tcl calls back to the application to execute the
Xcommands.  In many cases commands will invoke recursive invocations
Xof the Tcl interpreter by passing in additional strings to execute
X(procedures, looping commands, and conditional commands all work
Xin this way).
X.PP
XAn application program gains three advantages by using Tcl for
Xits command language.  First, Tcl provides a standard syntax:  once
Xusers know Tcl, they will be able to issue commands easily
Xto any Tcl-based application.  Second, Tcl provides programmability.
XAll a Tcl application needs to do is to implement a few
Xapplication-specific low-level commands.  Tcl provides many utility
Xcommands plus a general programming interface for building up
Xcomplex command procedures.  By using Tcl, applications need not
Xre-implement these features.  Third, Tcl will eventually provide
Xa mechanism for communicating between applications:  it will be
Xpossible to send Tcl commands from one application to another.
XThe common Tcl language framework will make it easier for applications
Xto communicate with one another.  The communication features are not
Ximplemented in the current version of Tcl.
X.PP
XThis manual page focusses primarily on the Tcl language.  It describes
Xthe language syntax and the built-in commands that will be available in
Xany application based on Tcl.  The individual library
Xprocedures are described in more detail in separate manual pages, one
Xper procedure.
X
X.SH "INTERPRETERS"
X.PP
XThe central data structure in Tcl is an interpreter (C type
X``Tcl_Interp'').  An interpreter consists of a set of command
Xbindings, a set of variable values, and a few other miscellaneous
Xpieces of state.  Each Tcl command is interpreted in the context
Xof a particular interpreter.
XSome Tcl-based applications will maintain
Xmultiple interpreters simultaneously, each associated with a
Xdifferent widget or portion of the application.
XInterpreters are relatively lightweight structures.  They can
Xbe created and deleted quickly, so application programmers should feel free to
Xuse multiple interpreters if that simplifies the application.
XEventually Tcl will provide a mechanism for sending Tcl commands
Xand results back and forth between interpreters, even if the
Xinterpreters are managed by different processes.
X
X.SH "DATA TYPES"
X.PP
XTcl supports only one type of data:  strings.  All commands,
Xall arguments to commands, all command results, and all variable values
Xare strings.
XWhere commands require numeric arguments or return numeric results,
Xthe arguments and results are passed as strings.
XMany commands expect their string arguments to have certain formats,
Xbut this interpretation is
Xup to the individual commands.  For example, arguments often contain
XTcl command strings, which may get executed as part of the commands.
XThe easiest way to understand the Tcl interpreter is to remember that
Xeverything is just an operation on a string.  In many cases Tcl constructs
Xwill look similar to more structured constructs from other languages.
XHowever, the Tcl constructs
Xare not structured at all;  they are just strings of characters, and this
Xgives them a different behavior than the structures they may look like.
X.PP
XAlthough the exact interpretation of a Tcl string depends on who is
Xdoing the interpretation, there are three common forms that strings
Xtake:  commands, expressions, and lists.  The major sections below
Xdiscuss these three forms in more detail.
X
X.SH "BASIC COMMAND SYNTAX"
X.PP
XThe Tcl language has syntactic similarities to both the Unix shells
Xand Lisp.  However, the interpretation of commands is different
Xin Tcl than in either of those other two systems.
XA Tcl command string consists of one or more commands separated
Xby newline characters or semi-colons.
XEach command consists of a collection of fields separated by
Xwhite space (spaces or tabs).
XThe first field must be the name of a command, and the
Xadditional fields, if any, are arguments that will be passed to
Xthat command.  For example, the command
X.DS
X\fBset a 22\fR
X.DE
Xhas three fields:  the first, \fBset\fR, is the name of a Tcl command, and
Xthe last two, \fBa\fR and \fB22\fR, will be passed as arguments to
Xthe \fBset\fR command.  The command name may refer either to a built-in
XTcl command, an application-specific command bound in with the library
Xprocedure \fBTcl_CreateCommand\fR, or a command procedure defined with the
X\fBproc\fR built-in command.
XArguments are passed literally as
Xtext strings.  Individual commands may interpret those strings in any
Xfashion they wish.  The \fBset\fR command, for example, will treat its
Xfirst argument as the name of a variable and its second argument as a
Xstring value to assign to that variable.  For other commands arguments
Xmay be interpreted as integers, lists, file names, or Tcl commands.
X.PP
XCommand names may be abbreviated as long as the abbreviation is unique.
XHowever, it's probably a bad idea to use abbreviations in command scripts
Xand other forms that will be re-used over time:  changes to the command
Xset may cause abbreviations to become ambiguous, resulting in scripts
Xthat no longer work.  Abbreviations are intended primarily for
Xcommands that are typed interactively, invoked once, and discarded.
X
X.SH "COMMENTS"
X.PP
XIf the first non-blank character in a command is \fB#\fR, then everything
Xfrom the \fB#\fR up through the next newline character is treated as
Xa comment and ignored.
X
X.SH "GROUPING ARGUMENTS WITH BRACES"
X.PP
XNormally each argument field ends at the next white space, but
Xcurly braces (``{'' and ``}'') may
Xbe used to group arguments in different ways.  If an argument
Xfield begins with a left brace, then the argument isn't
Xterminated by white space;  instead it ends at the matching
Xright brace.  Tcl will strip off the outermost layer of braces
Xbefore passing the argument to the command.  This provides a simple mechanism
Xfor including white space in arguments.  For example, the
Xcommand
X.DS
X\fBset a {This is a single argument}\fR
X.DE
Xwill pass two arguments to \fBset\fR:  \fBa\fR and
X\fBThis is a single argument\fR.  In the command
X.DS
X\fBset a {xyz a {b c d}}\fR
X.DE
Xthe \fBset\fR command will receive two arguments: \fBa\fR
Xand \fBxyz a {b c d}\fR.
X.PP
XWhen braces are in effect, the matching brace need not be on
Xthe same line as the starting quote or brace;  in this case
Xthe newline will be
Xincluded in the argument field along with any other characters up to the
Xmatching quote or brace.  For example, the \fBeval\fR command
Xtakes one
Xargument, which is a command string;  \fBeval\fR invokes the Tcl
Xinterpreter to execute the command string.  The command
X.DS
X\fBeval {
X	set a 22
X	set b 33
X}\fR
X.DE
Xwill assign the value \fB22\fR to \fBa\fR and \fB33\fR to \fBb\fR.
X.PP
XWhen an argument is in braces, then command, variable,
Xand backslash
Xsubstitutions do not occur as described below;  all Tcl does is to
Xstrip off the outer layer of braces and pass the
Xcontents to the command.
X.PP
XIf the first character of a command field isn't a left
Xbrace, then neither left nor right
Xbraces in the field will be treated specially (except as part of
Xvariable substitution;  see below).
X
X.SH "COMMAND SUBSTITUTION WITH BRACKETS"
X.PP
XIf an open bracket occurs in any of the fields of a command, then
Xcommand substitution occurs.  All of the text up to the matching
Xclose bracket is treated as a Tcl command and executed immediately.
XThen the result of that command is substituted for the bracketed
Xtext.  For example, consider the command
X.DS
X\fBset a [set b]\fR
X.DE
XWhen the \fBset\fR command has only a single argument, it is the
Xname of a variable and \fBset\fR returns the contents of that
Xvariable.  In this case, if variable \fBb\fR has the value \fBfoo\fR,
Xthen the command above is equivalent to the command
X.DS
X\fBset a foo\fR
X.DE
XBrackets can be used in more complex ways.  For example, if the
Xvariable \fBb\fR has the value \fBfoo\fR and the variable \fBc\fR
Xhas the value \fBgorp\fR, then the command
X.DS
X\fBset a xyz[set b].[set c]\fR
X.DE
Xis equivalent to the command
X.DS
X\fBset a xyzfoo.gorp\fR
X.DE
XA bracketed command need not be all on one line:  newlines within
Xbrackets are treated as argument separators, not command separators.
XIf a field is enclosed in braces then the brackets and the characters
Xbetween them are not interpreted specially;  they are passed through
Xto the argument verbatim.
X
X.SH "VARIABLE SUBSTITUTION WITH $"
X.PP
XThe dollar sign (\fB$\fR) may be used as a special shorthand form
Xfor substituting variables.  If \fB$\fR appears in an argument that
Xisn't enclosed in braces
Xthen variable substitution will occur.  The characters after
Xthe \fB$\fR, up to the first character that isn't a number, letter, or
Xunderscore, are taken as a variable name and the string value of that
Xvariable is substituted for the name.  Or, if the dollar sign is followed
Xby an open curly brace then the variable name consists of all the characters
Xup to the next close curly brace.  For example, if variable \fBfoo\fR
Xhas the value \fBtest\fR, then the command
X.DS C
X\fBset a $foo.c\fR
X.DE
Xis equivalent to the command
X.DS C
X\fBset a test.c\fR
X.DE
Xand the command
X.DS C
X\fBset a abc${foo}bar\fR
X.DE
Xis equivalent to the command
X.DS C
X\fBset a abctestbar\fR
X.DE
XVariable substitution does not occur in arguments that are enclosed
Xin braces:  the
Xdollar sign and variable name are passed through to the argument verbatim.
X.PP
XThe dollar sign abbreviation is simply a shorthand form.  \fB$a\fR is
Xcompletely equivalent to \fB[set a]\fR;  it is provided as a convenience
Xto reduce typing.
X
X.VS
X.SH "SEPARATING COMMANDS WITH SEMI-COLONS"
X.PP
XNormally, each command occupies one line (the command is terminated by
Xa newline character).  However, semi-colon (``;'') is treated
Xas a command separator character;  multiple commands may be placed
Xon one line by separating them with a semi-colon.
X.VE
X
X.SH "BACKSLASH SUBSTITUTION"
X.PP
XBackslashes may be used to insert non-printing characters into
Xcommand fields and also to insert special characters like
Xbraces and brackets into fields
Xwithout them being interpreted specially as described above.
XThe backslash sequences understood by the Tcl interpreter are
Xlisted below.  In each case, the backslash
Xsequence is replaced by the given character:
X.TP 20
X\fB\eb\fR
XBackspace (octal 10).
X.TP 20
X\fB\ee\fR
XEscape (octal 33).
X.TP 20
X\fB\en\fR
XNewline (octal 15).
X.TP 20
X\fB\et\fR
XTab (octal 11).
X.TP 20
X\fB\e{\fR
XLeft brace (``{'').
X.TP 20
X\fB\e}\fR
XRight brace (``}'').
X.TP 20
X\fB\e[\fR
XOpen bracket (``['').
X.TP 20
X\fB\e]\fR
XClose bracket (``]'').
X.TP 20
X\fB\e<space>\fR
XSpace (`` ''): doesn't terminate argument.
X.br
X.VS
X.TP 20
X\fB\e;\fR
XSemi-colon: doesn't terminate command.
X.TP 20
X\fB\e"\fR
XDouble-quote.
X.TP 20
X\fB\e<newline>\fR
XNothing:  this effectively joins two lines together
Xinto a single line.  This backslash feature is only provided
Xwhen parsing Tcl commands;  it is not supported by the
XTcl_Backslash procedure.
X.VE
X.TP 20
X\fB\e\e\fR
XBackslash (``\e'').
X.TP 20
X\fB\eC\fIx\fR
XControl-\fIx\fR (\fIx\fR AND octal 037), for any ASCII \fIx\fR except \fBM\fR
X(see below).
X.TP 20
X\fB\eM\fIx\fR
XMeta-\fIx\fR (\fIx\fR OR octal 200), for any ASCII \fIx\fR.
X.TP 20
X\fB\eCM\fIx\fR
XControl-meta-\fIx\fR ((\fIx\fR AND octal 037) OR octal 0200), for
Xany ASCII \fIx\fR.
X.TP 20
X\fB\e\fIddd\fR
XThe digits \fIddd\fR (one, two, or three of them) give the octal value of
Xthe character.
X.PP
XFor example, in the command
X.DS
X\fBset a \e{x\e[\e\0yz\e141\fR
X.DE
Xthe second argument to \fBset\fR will be ``\fB{x[\0yza\fR''.
X.PP
XIf a backslash is followed by something other than one of the options
Xdescribed above, then the backslash is transmitted to the argument
Xfield without any special processing, and the Tcl scanner continues
Xnormal processing with the next character.  For example, in the
Xcommand
X.DS
X\fBset \e*a \e\e\e{foo\fR
X.DE
XThe first argument to \fBset\fR will be \fB\e*a\fR and the second
Xargument will be \fB\e{foo\fR.
X.PP
XIf an argument is enclosed in braces, then backslash sequences inside
Xthe argument are parsed but no substitution occurs:  the backslash
Xsequence is passed through to the argument as is, without making
Xany special interpretation of the characters in the backslash sequence.
XIn particular, backslashed braces are not counted in locating the
Xmatching right brace that terminates the argument.
XFor example, in the
Xcommand
X.DS
X\fBset a {\e{abc}\fR
X.DE
Xthe second argument to \fBset\fR will be \fB\e{abc\fR.
X.PP
XThis backslash mechanism is not sufficient to generate absolutely
Xany argument structure;  it only covers the
Xmost common cases.  To produce particularly complicated arguments
Xit will probably be easiest to use the \fBformat\fR command along with
Xcommand substitution.
X
X.SH "COMMAND SUMMARY"
X.IP [1]
XA command is just a string.
X.IP [2]
XWithin a string commands are separated by newlines or semi-colons
X(unless the newline or semi-colon is within braces or brackets
Xor is backslashed).
X.IP [3]
XA command consists of fields.  The first field is the name of the command,
Xand may be abbreviated.
XThe other fields are strings that are passed to that command as arguments.
X.IP [4]
XFields are normally separated by white space.
X.IP [5]
XBraces defer interpretation of special characters.
XIf a field begins with a left brace, then it consists of everything
Xbetween the left brace and the matching right brace. The
Xbraces themselves are not included in the argument.
XNo further processing is done on the information between the braces.
X.IP [6]
XDouble-quotes act the same as braces except that they cannot be nested.
X.IP [7]
XIf a field doesn't begin with a left brace or double-quote, then backslash,
Xvariable, and command substitution are done on the field.  Only a
Xsingle level of processing is done:  the results of one substitution
Xare not scanned again for further substitutions or any other
Xspecial treatment.  Substitution can
Xoccur on \fIany\fR field of a command, including the command name
Xas well as the arguments.
X.IP [8]
XIf the first non-blank character of a command is a \fB#\fR, everything
Xfrom the \fB#\fR up through the next newline is treated as a comment
Xand ignored.
X
X.SH "EXPRESSIONS"
X.PP
XThe second major interpretation applied to strings in Tcl is
Xas expressions.  Several commands, such as \fBexpr\fR, \fBfor\fR,
Xand \fBif\fR, treat some of their arguments as expressions and
Xcall the Tcl expression processor (\fBTcl_Expr\fR) to evaluate them.
XA Tcl expression has C-like syntax and evaluates to an integer
Xresult.  Expressions
Xmay contain integer values, variable names in \fB$\fR notation
X(the variables' values must be integer strings),
Xcommands (embedded in brackets) that produce integer string results,
Xparentheses for grouping, and operators.  Numeric values, whether they
Xare passed directly or through variable or command substitution, may
Xbe specified either in decimal (the normal case), in octal (if the
Xfirst character of the value is \fB0\fR), or in hexadecimal (if the first
Xtwo characters of the value are \fB0x\fR).
XThe valid operators are listed
Xbelow, grouped in decreasing order of precedence:
X.TP 20
X\fB\-\0\0~\0\0!\fR
XUnary minus, bit-wise NOT, logical NOT.
X.TP 20
X\fB*\0\0/\0\0%\fR
XMultiply, divide, remainder.
X.TP 20
X\fB+\0\0\-\fR
XAdd and subtract.
X.TP 20
X\fB<<\0\0>>\fR
XLeft and right shift.
X.TP 20
X\fB<\0\0>\0\0<=\0\0>=\fR
XBoolean less, greater, less than or equal, and greater than or equal.
XEach operator produces 1 if the condition is true, 0 otherwise.
X.TP 20
X\fB==\0\0!=\fR
XBoolean equal and not equal.  Each operator produces a zero/one result.
X.TP 20
X\fB&\fR
XBit-wise AND.
X.TP 20
X\fB^\fR
XBit-wise exclusive OR.
X.TP 20
X\fB|\fR
XBit-wise OR.
X.TP 20
X\fB&&\fR
XLogical AND.  Produces a 1 result if both operands are non-zero, 0 otherwise.
X.TP 20
X\fB||\fR
XLogical OR.  Produces a 0 result if both operands are zero, 1 otherwise.
X.PP
XSee the C manual for more details on the results
Xproduced by each operator.
XAll of the binary operators group left-to-right within the same
Xprecedence level.  For example, the expression
X.DS
X\fB(4*2) < 7\fR
X.DE
Xevaluates to 0.  Evaluating the expression string
X.DS
X\fB($a + 3) < [set b]\fR
X.DE
Xwill cause the values of the variables \fBa\fR and \fBb\fR to be
Xexamined;  the result will be 1
Xif \fBb\fR is greater than a by at least 3;  otherwise the result
Xwill be 0.
X.PP
XIn general it is safest to enclose an expression in braces when
Xentering it in a command:  otherwise, if the expression contains
Xany white space then the Tcl interpreter will split it
Xamong several arguments.  For example, the command
X.DS C
X\fBexpr $a + $b\fR
X.DE
Xresults in three arguments being passed to \fBexpr\fR:  \fB$a\fR,
X\fB+\fR, and \fB$b\fR.  In addition, if the expression isn't in braces
Xthen the Tcl interpreter will perform variable and command substitution
Ximmediately (it will happen in the command parser rather than in
Xthe expression parser).  In many cases the expression is being
Xpassed to a command that will evaluate the expression later (or
Xeven many times if, for example, the expression is to be used to
Xdecide when to exit a loop).  Usually the desired goal is to re-do
Xthe variable or command substitutions each time the expression is
Xevaluated, rather than once and for all at the beginning.  For example,
Xthe command
X.DS C
X\fBfor {set i 1} $i<=10 {set i [expr $i+1]} {...}\fR
X.DE
Xis probably intended to iterate over all values of \fBi\fR from 1 to 10.
XAfter each iteration of the body of the loop, \fBfor\fR will pass
Xits second argument to the expression evaluator to see whether or not
Xto continue processing.  Unfortunately, in this case the value of \fBi\fR
Xin the second argument will be substituted once and for all when the
X\fBfor\fR command is parsed.  If \fBi\fR was 0 before the \fBfor\fR
Xcommand was invoked then \fBfor\fR's second argument will be \fB0<=10\fR
Xwhich will always evaluate to 1, even though \fBi\fR's value eventually
Xbecomes greater than 10.  In the above case the loop will never
Xterminate.  By placing the expression in braces, the
Xsubstitution of \fBi\fR's
Xvalue will be delayed;  it will be re-done each time the expression is
Xevaluated, which is probably the desired result.
X
X.SH LISTS
X.PP
XThe third major way that strings are interpreted in Tcl is as lists.
XA list is just a string with a list-like structure
Xconsisting of fields separated by white space.  For example, the
Xstring
X.DS
X\fBAl Sue Anne John\fR
X.DE
Xis a list with four elements or fields.
XLists have the same basic structure as command strings, except
Xthat a newline character in a list is treated as a field separator
Xjust like space or tab.  Conventions for braces
Xand backslashes are the same for lists as for commands.  For example,
Xthe string
X.DS
X\fBa b\e c {d e {f g h}}\fR
X.DE
Xis a list with three elements:  \fBa\fR, \fBb c\fR, and \fBd e {f g h}\fR.
XWhenever an element
Xis extracted from a list, the same rules about backslashes and
Xbraces are applied as for commands.  Thus in the example above
Xwhen the third element is extracted from the list, the result is
X.DS
X\fBd e {f g h}\fR
X.DE
X(when the field was extracted, all that happened was to strip off
Xthe outermost layer of braces).  Command substitution is never
Xmade on a list (at least, not by the list-processing commands;  the
Xlist can always be passed to the Tcl interpreter for evaluation).
X.PP
XThe Tcl commands \fBconcat\fR, \fBforeach\fR, \fBindex\fR,
X\fBlength\fR, \fBlist\fR, and \fBrange\fR allow you to build lists,
Xextract elements from them, search them, and perform other list-related
Xfunctions.
X
X.SH "COMMAND RESULTS"
X.PP
XEach command produces two results:  a code and a string.  The
Xcode indicates whether the command completed successfully or not,
Xand the string gives additional information.  The valid codes are
Xdefined in tcl.h, and are:
X.RS
X.TP 20
X\fBTCL_OK\fR
XThis is the normal return code, and indicates that the command completed
Xsuccesfully.  The string gives the command's return value.
X.TP 20
X\fBTCL_ERROR\fR
XIndicates that an error occurred;  the string gives a message describing
Xthe error.
X.VS
XThe variable \fBerrorInfo\fR will contain additional information
Xdescribing which commands and procedures were being executed when the
Xerror occurred.
X.VE
X.TP 20
X\fBTCL_RETURN\fR
XIndicates that the \fBreturn\fR command has been invoked, and that the
X.VS
Xcurrent procedure (or top-level command or \fBsource\fR command)
Xshould return immediately.  The
Xstring gives the return value for the procedure or command.
X.VE
X.TP 20
X\fBTCL_BREAK\fR
XIndicates that the \fBbreak\fR command has been invoked, so the
Xinnermost loop should abort immediately.  The string should always
Xbe empty.
X.TP 20
X\fBTCL_CONTINUE\fR
XIndicates that the \fBcontinue\fR command has been invoked, so the
Xinnermost loop should go on to the next iteration.  The string
Xshould always be empty.
X.RE
XTcl programmers do not normally need to think about return codes,
Xsince TCL_OK is almost always returned.  If anything else is returned
Xby a command, then the Tcl interpreter immediately stops processing
Xcommands and returns to its caller.  If there are several nested
Xinvocations of the Tcl interpreter in progress, then each nested
Xcommand will usually return the error to its caller, until eventually
Xthe error is reported to the top-level application code.  The
Xapplication will then display the error message for the user.
X.PP
XIn a few cases, some commands will handle certain ``error'' conditions
Xthemselves and not return them upwards.  For example, the \fBfor\fR
Xcommand checks for the TCL_BREAK code;  if it occurs, then \fBfor\fR
Xstops executing the body of the loop and returns TCL_OK to its
Xcaller.  The \fBfor\fR command also handles TCL_CONTINUE codes and the
Xprocedure interpreter handles TCL_RETURN codes.  The \fBcatch\fR
Xcommand allows Tcl programs to catch errors and handle them without
Xaborting command interpretation any further.
X
X.SH PROCEDURES
X.PP
XTcl allows you to extend the command interface by defining
Xprocedures.  A Tcl procedure can be invoked just like any other Tcl
Xcommand (it has a name and it receives one or more arguments).
XThe only difference is that its body isn't a piece of C code linked
Xinto the program;  it is a string containing one or more other
XTcl commands.  See the \fBproc\fR command for information on
Xhow to define procedures and what happens when they are invoked.
X
X.SH VARIABLES
X.PP
XTcl allows the definition of variables and the use of their values
Xeither through \fB$\fR-style variable substitution, the \fBset\fR
Xcommand, or a few other mechanisms.  Variables need not be declared:
Xa new variable will automatically be created each time a new variable
Xname is used.  Variables may be either global or local.  If a variable
Xname is used when a procedure isn't being executed, then it
Xautomatically refers to a global variable.  Variable names used
Xwithin a procedure normally refer to local variables associated with that
Xinvocation of the procedure.  Local variables are deleted whenever
Xa procedure exits.  The \fBglobal\fR command may be used to request
Xthat a name refer to a global variable for the duration of the current
Xprocedure (this is somewhat analogous to \fBextern\fR in C).
X
X.SH "BUILT-IN COMMANDS"
X.PP
XThe Tcl library provides the following built-in commands, which will
Xbe available in any application using Tcl.  In addition to these
Xbuilt-in commands, there may be additional commands defined by each
Xapplication, plus commands defined as Tcl procedures.  In the command syntax
Xdescriptions below, optional arguments are indicated by enclosing their
Xnames in brackets;  apologies in advance for the confusion between this
Xdescriptive use of brackets and the use of brackets to invoke
Xcommand substitution.
XWords in boldface are literals that you type verbatim to Tcl.
XWords in italics are meta-symbols;  they act as names to refer to
Xa class of values that you can type.
X.TP
X\fBbreak\fR
XThis command may be invoked only inside the body of a loop command
Xsuch as \fBfor\fR or \fBforeach\fR.  It returns a TCL_BREAK code
Xto signal the innermost containing loop command to return immediately.
X.TP
X\fBcase\fI string \fR[\fBin\fR] \fIpatList body patList body \fR...
X.VS
XMatch \fIstring\fR against each of the \fIpatList\fR arguments
Xin order.  If one matches, then evaluate the following \fIbody\fR argument
Xby passing it recursively to the Tcl interpreter, and return the result
Xof that evaluation.  Each \fIpatList\fR argument consists of a single
Xpattern or list of patterns.  Each pattern may contain any of the wild-cards
Xdescribed under \fBstring match\fR.  If a \fIpatList\fR
Xargument is \fBdefault\fR, the corresponding body will be evaluated
Xif no \fIpatList\fR matches \fIstring\fR.  If no \fIpatList\fR argument
Xmatches \fIstring\fR and no default is given, then the \fBcase\fR
Xcommand returns an empty string.  For example,
X.RS
X.DS
X\fBcase abc in {a b} {format 1} default {format 2} a* {format 3}
X.DE
Xwill return \fB3\fR, 
X.DS
X\fBcase a in {a b} {format 1} default {format 2} a* {format 3}
X.DE
Xwill return \fB1\fR, and
X.DS
X\fBcase xyz {a b} {format 1} default {format 2} a* {format 3}
X.DE
Xwill return \fB2\fR.
X.RE
X.VE
X.TP
X\fBcatch\fI command \fR[\fIvarName\fR]
XThe \fBcatch\fR command may be used to prevent errors from aborting
Xcommand interpretation.  \fBCatch\fR calls the Tcl interpreter recursively
Xto execute \fIcommand\fR, and always returns a TCL_OK code, regardless of
Xany errors that might occur while executing \fIcommand\fR.  The return
Xvalue from \fBcatch\fR is a decimal string giving the
Xcode returned by the Tcl interpreter after executing \fIcommand\fR.
XThis will be \fB0\fR (TCL_OK) if there were no errors in \fIcommand\fR; otherwise
Xit will have a non-zero value corresponding to one of the exceptional
Xreturn codes (see tcl.h for the definitions of code values).  If the
X\fIvarName\fR argument is given, then it gives the name of a variable;
X\fBcatch\fR will set the value of the variable to the string returned
Xfrom \fIcommand\fR (either a result or an error message).
X.TP
X\fBconcat\fI arg arg ...\fR
XThis command treats each argument as a list and concatenates them
Xinto a single list.  It permits any number of arguments.  For example,
Xthe command
X.RS
X.DS
X\fBconcat a b {c d e} {f {g h}}\fR
X.DE
Xwill return
X.DS
X\fBa b c d e f {g h}\fR
X.DE
Xas its result.
X.RE
X.TP
X\fBcontinue\fR
XThis command may be invoked only inside the body of a loop command
Xsuch as \fBfor\fR or \fBforeach\fR.  It returns a  TCL_CONTINUE code
Xto signal the innermost containing loop command to skip the
Xremainder of the loop's body
Xbut continue with the next iteration of the loop.
X.TP
X\fBerror \fImessage\fR
XReturns a TCL_ERROR code, which causes command interpretation to be
Xunwound.  \fIMessage\fR is a string that is returned to the application
Xto indicate what went wrong.
X.VS
X.TP
X\fBeval \fIarg1 arg2 ...\fR
X\fBEval\fR takes one or more arguments, which together comprise a Tcl
Xcommand (or collection of Tcl commands separated by newlines in the
Xusual way).  \fBEval\fR concatenates all its arguments in the same
Xfashion as the \fBconcat\fR command, passes the concatenated string to the
XTcl interpreter recursively, and returns the result of that
Xevaluation (or any error generated by it).
X.VE
X.TP
X\fBexec \fIcommand arg1 arg2 ...\fR[\fB< \fIinput\fR]
XThe \fBexec\fR command treats its \fIcommand\fR argument as the name of
Xa program to execute.  It searches the directories in
Xthe PATH environment variable to find
Xan executable file by the name \fIcommand\fR,
Xthen executes the file, passing it an argument list consisting of
X\fIcommand\fR plus all of the \fIarg\fRs.  If an argument \fB<\fR appears
Xanywhere among the arguments to \fBexec\fR, then neither it or the
Xfollowing argument is passed to \fIcommand\fR.  Instead, the following
Xargument (\fIinput\fR) consists of input to the command;  \fBexec\fR
Xwill create a pipe and use it to pass \fIinput\fR to \fIcommand\fR
Xas standard input.  \fBExec\fR also creates a pipe to receive \fIcommand\fR's
Xoutput (both standard output and standard error).  The information
Xreceived over this pipe is returned as the result of the \fBexec\fR
Xcommand.  The \fBexec\fR command also looks at the return status
Xreturned by \fIcommand\fR.  Normally this should be zero;  if it is then
X\fBexec\fR returns normally.  If \fIcommand\fR returns a non-zero status,
Xthen \fBexec\fR will return that code;  it should be one of the ones
Xdefined in the section ``COMMAND RESULTS'' above.  If an out-of range
Xcode is returned by the command, it will cause command unwinding just
Xas if TCL_ERROR had been returned; at the outermost level of command
Xinterpretation, the Tcl interpreter will turn the code into TCL_ERROR,
Xwith an appropriate error message.
X.TP
X\fBexpr \fIarg\fR
XCalls the expression processor to evaluate \fIarg\fR, and returns
Xthe result as a decimal string.
X.TP
X\fBfile \fIname\fR \fIoption\fR
XOperate on a file or a file name.  \fIName\fR is the name of a file, and
X\fIoption\fR indicates what to do with the file name.  Any unique
Xabbreviation for \fIoption\fR is acceptable.  The valid options are:
X.RS
X.TP
X\fBfile \fIname \fBdirname\fR
XReturn all of the characters in \fIname\fR up to but not including
Xthe last slash character.  If there are no slashes in \fIname\fR
Xthen return ``.''.  If the last slash in \fIname\fR is its first
Xcharacter, then return ``/''.
X.TP
X\fBfile \fIname \fBexecutable\fR
XReturn \fB1\fR if file \fIname\fR is executable by
Xthe current user, \fB0\fR otherwise.
X.TP
X\fBfile \fIname \fBexists\fR
XReturn \fB1\fR if file \fIname\fR exists and the current user has
Xsearch privileges for the directories leading to it, \fB0\fR otherwise.
X.TP
X\fBfile \fIname \fBextension\fR
XReturn all of the characters in \fIname\fR after and including the
Xlast dot in \fIname\fR.  If there is no dot in \fIname\fR then return
Xthe empty string.
X.TP
X\fBfile \fIname \fBisdirectory\fR
XReturn \fB1\fR if file \fIname\fR is a directory,
X\fB0\fR otherwise.
X.TP
X\fBfile \fIname \fBisfile\fR
XReturn \fB1\fR if file \fIname\fR is a regular file,
X\fB0\fR otherwise.
X.TP
X\fBfile \fIname \fBowned\fR
XReturn \fB1\fR if file \fIname\fR is owned by the current user,
X\fB0\fR otherwise.
X.TP
X\fBfile \fIname \fBreadable\fR
XReturn \fB1\fR if file \fIname\fR is readable by
Xthe current user, \fB0\fR otherwise.
X.TP
X\fBfile \fIname \fBrootname\fR
XReturn all of the characters in \fIname\fR up to but not including
Xthe last ``.'' character in the name.  If \fIname\fR doesn't contain
Xa dot, then return \fIname\fR.
X.TP
X\fBfile \fIname \fBtail\fR
XReturn all of the characters in \fIname\fR after the last slash.
XIf \fIname\fR contains no slashes then return \fIname\fR.
X.TP
X\fBfile \fIname \fBwritable\fR
XReturn \fB1\fR if file \fIname\fR is writable by
Xthe current user, \fB0\fR otherwise.
X.RE
X.IP
XThe \fBfile\fR commands that return 0/1 results are often used in
Xconditional or looping commands, for example:
X.RS
X.DS
X\fBif {![file foo exists]} then {error {bad file name}} else {...}\fR
X.DE
X.RE
X.TP
X\fBfor \fIstart test next body\fR
X\fBFor\fR is a looping command, similar in structure to the C
X\fBfor\fR statement.  The \fIstart\fR, \fInext\fR, and
X\fIbody\fR arguments must be Tcl command strings, and \fItest\fR
Xis an expression string.
XThe \fBfor\fR command first invokes the Tcl interpreter to
Xexecute \fIfirst\fR.  Then it repeatedly evaluates \fItest\fR as
Xan expression;  if the result is non-zero it invokes the Tcl
Xinterpreter on \fIbody\fR, then invokes the Tcl interpreter on \fInext\fR,
Xthen repeats the loop.  The command terminates when \fItest\fR evaluates
Xto 0.  If a \fBcontinue\fR command is invoked within \fIbody\fR then
Xany remaining commands in the current execution of \fIbody\fR are skipped;
Xprocessing continues by invoking the Tcl interpreter on \fInext\fR, then
Xevaluating \fItest\fR, and so on.  If a \fBbreak\fR command is invoked
Xwithin \fIbody\fR
X.VS
Xor \fInext\fR,
X.VE
Xthen the \fBfor\fR command will
Xreturn immediately.
XThe operation of \fBbreak\fR and \fBcontinue\fR are similar to the
Xcorresponding statements in C.
X\fBFor\fR returns an empty string.
X.TP
X\fBforeach \fIvarname list body\fR
XIn this command, \fIvarname\fR is the name of a variable, \fIlist\fR
Xis a list of values to assign to \fIvarname\fR, and \fIbody\fR is a
Xcollection of Tcl commands.  For each field in \fIlist\fR (in order
Xfrom left to right), \fBforeach\fR assigns the contents of the
Xfield to \fIvarname\fR (as if the \fBindex\fR command had been used
Xto extract the field), then calls the Tcl interpreter to execute
X\fIbody\fR.  The \fBbreak\fR and \fBcontinue\fR statements may be
Xinvoked inside \fIbody\fR, with the same effect as in the \fBfor\fR
Xcommand.  \fBForeach\fR an empty string.
X.TP
X\fBformat \fIformatString arg arg ...\fR
XThis command generates a formatted string in the same way as the
XC \fBsprintf\fR procedure (it uses \fBsprintf\fR in its
Ximplementation).  \fIFormatString\fR indicates how to format
Xthe result, using \fB%\fR fields as in \fBsprintf\fR, and the additional
Xarguments, if any, provide values to be substituted into the result.
XAll of the \fBsprintf\fR options are valid;  see the \fBsprintf\fR
Xman page for details.  Each \fIarg\fR must match the expected type
Xfrom the \fB%\fR field in \fIformatString\fR;  the \fBformat\fR command
Xconverts each argument to the correct type (floating, integer, etc.)
Xbefore passing it to \fBsprintf\fR for formatting.
XThe only unusual conversion is for \fB%c\fR;  in this case the argument
Xmust be a decimal string, which will then be converted to the corresponding
XASCII character value.
X\fBFormat\fR does backslash substitution on its \fIformatString\fR
Xargument, so backslash sequences in \fIformatString\fR will be handled
Xcorrectly even if the argument is in braces.
XThe return value from \fBformat\fR
Xis the formatted string.
X.TP
X\fBglob \fIfilename\fR
X.VS
XThis command performs filename globbing, using csh rules.  The returned
Xvalue from \fBglob\fR is the list of expanded filenames.
X.VE
X.TP
X\fBglobal \fIvarname varname ...\fR
XThis command is ignored unless a Tcl procedure is being interpreted.
XIf so, then it declares the given \fIvarname\fR's to be global variables
Xrather than local ones.  For the duration of the current procedure
X(and only while executing in the current procedure), any reference to
Xany of the \fIvarname\fRs will be bound to a global variable instead
Xof a local one.
X.TP
X\fBif \fItest \fR[\fBthen\fR] \fItrueBody \fR[[\fBelse\fR] \fIfalseBody\fR]
XThe \fIif\fR command evaluates \fItest\fR as an expression (in the
Xsame way that \fBexpr\fR evaluates its argument).  If the
Xresult is non-zero then \fItrueBody\fR is called by passing it to the
XTcl interpreter.  Otherwise \fIfalseBody\fR is executed by passing it to
Xthe Tcl interpreter.  The \fBthen\fR and \fBelse\fR arguments are optional
X``noise words'' to make the command easier to read.  \fIFalseBody\fR is
Xalso optional;  if it isn't specified then the command does nothing if
X\fItest\fR evaluates to zero.  The return value from \fBif\fR is
Xthe value of the last command executed in \fItrueBody\fR or
X\fIfalseBody\fR, or the empty string if \fItest\fR evaluates to zero and
X\fIfalseBody\fR isn't specified.
X.TP
X\fBindex \fIvalue index \fR[\fBchars\fR]
XExtract an element from a list or a character from a string.  If the
X\fBchars\fR keyword isn't specified, then \fBindex\fR treats \fIvalue\fR
Xas a list and returns the \fIindex\fR'th field from it.  In extracting
Xthe field, \fIindex\fR observes the same rules concerning braces
Xand backslashes as the Tcl command interpreter;  however, variable
Xsubstitution and command substitution do not occur.  If \fIindex\fR is
Xgreater than or equal to the number of elements in \fIvalue\fR, then the empty
Xstring is returned.  If the \fBchars\fR keyword is specified (or any
Xabbreviation of it), then \fIvalue\fR is treated as a string and the
Xcommand returns the \fIindex\fR'th character from it (or the empty string
Xif there aren't at least \fIindex\fR+1 characters in the string).
XIndex 0 refers to the first element or character of \fIvalue\fR.
X.TP
X\fBinfo \fIoption arg arg ...\fR
XProvide information about various internals to the Tcl interpreter.
XThe legal \fIoption\fR's (which may be abbreviated) are:
X.RS
X.TP
X\fBinfo args \fIprocname\fR
XReturns a list containing the names of the arguments to procedure
X\fIprocname\fR, in order.  \fIProcname\fR must be the name of a
XTcl command procedure.
X.TP
X\fBinfo body \fIprocname\fR
XReturns the body of procedure \fIprocname\fR.  \fIProcname\fR must be
Xthe name of a Tcl command procedure.
X.TP
X\fBinfo commands \fR[\fIpattern\fR]
X.VS
XIf \fIpattern\fR isn't specified, returns a list of names of all the
XTcl commands, including both the built-in commands written in C and
Xthe command procedures defined using the \fBproc\fR command.
XIf \fIpattern\fR is specified, only those names matching \fIpattern\fR
Xare returned.  Matching is determined using the same rules as for
X\fBstring match\fR.
X.VE
X.TP
X\fBinfo cmdcount\fR
XReturns a count of the total number of commands that have been invoked
Xin this interpreter.
X.TP
X\fBinfo default \fIprocname arg varname\fR
X\fIProcname\fR must be the name of a Tcl command procedure and \fIarg\fR
Xmust be the name of an argument to that procedure.  If \fIarg\fR
Xdoesn't have a default value then the command returns \fB0\fR.
XOtherwise it returns \fB1\fR and places the default value of \fIarg\fR
Xinto variable \fIvarname\fR.
X.TP
X\fBinfo globals \fR[\fIpattern\fR]
X.VS
XIf \fIpattern\fR isn't specified, returns a list of all the names
Xof currently-defined global variables.
XIf \fIpattern\fR is specified, only those names matching \fIpattern\fR
Xare returned.  Matching is determined using the same rules as for
X\fBstring match\fR.
X.TP
X\fBinfo level\fR [\fInumber\fR]
XIf \fInumber\fR is not specified, this command returns a number
Xgiving the stack level of the invoking procedure, or 0 if the
Xcommand is invoked at top-level.  If \fInumber\fR is specified,
Xthen the result is a list consisting of the name and arguments for the
Xprocedure call at level \fInumber\fR on the stack.  If \fInumber\fR
Xis positive then it selects a particular stack level (1 refers
Xto the top-most active procedure, 2 to the procedure it called, and
Xso on);  otherwise it gives a level relative to the current level
X(0 refers to the current procedure, -1 to its caller, and so on).
XSee the \fBuplevel\fR command for more information on what stack
Xlevels mean.
X.TP
X\fBinfo locals \fR[\fIpattern\fR]
XIf \fIpattern\fR isn't specified, returns a list of all the names
Xof currently-defined local variables, including arguments to the
Xcurrent procedure, if any.
XIf \fIpattern\fR is specified, only those names matching \fIpattern\fR
Xare returned.  Matching is determined using the same rules as for
X\fBstring match\fR.
X.TP
X\fBinfo procs \fR[\fIpattern\fR]
XIf \fIpattern\fR isn't specified, returns a list of all the
Xnames of Tcl command procedures.
XIf \fIpattern\fR is specified, only those names matching \fIpattern\fR
Xare returned.  Matching is determined using the same rules as for
X\fBstring match\fR.
X.TP
X\fBinfo tclversion\fR
XReturns the version number for this version of Tcl in the form \fIx.y\fR,
Xwhere changes to \fIx\fR represent major changes with probable
Xincompatibilities and changes to \fIy\fR represent small enhancements and
Xbug fixes that retain backward compatibility.
X.VE
X.TP
X\fBinfo vars\fR
XReturns a list of all the names of currently-visible variables, including
Xboth locals and currently-visible globals.
X.RE
X.TP
X\fBlength \fIvalue\fR [\fBchars\fR]
XIf \fBchars\fR isn't specified, treats \fIvalue\fR as a list
Xand returns the number of elements in the list.  If \fBchars\fR
Xis specified (or any abbreviation of it), then \fBlength\fR
Xtreats \fIvalue\fR as a string and returns the number of characters
Xin it (not including the terminating null character).
X.TP
X\fBlist \fIarg1 arg2 ...\fR
XThis command returns a list comprised of all the \fIarg\fRs.  Braces
Xand backslashes get added as necessary, so that the \fBindex\fR command
Xmay be used on the result to re-extract the original arguments, and also
Xso that \fBeval\fR may be used to execute the resulting list, with
X\fIarg1\fR comprising the command's name and the other \fIarg\fRs comprising
Xits arguments.  \fBList\fR produces slightly different results than
X\fBconcat\fR:  \fBconcat\fR removes one level of grouping before forming
Xthe list, while \fBlist\fR works directly from the original arguments.
XFor example, the command
X.RS
X.DS
X\fBlist a b {c d e} {f {g h}}
X.DE
Xwill return
X.DS
X\fBa b {c d e} {f {g h}}
X.DE
Xwhile \fBconcat\fR with the same arguments will return
X.DS
X\fBa b c d e f {g h}\fR
X.DE
X.RE
X.TP
X\fBprint \fIstring \fR[\fIfile \fR[\fBappend\fR]]
X.VS
XPrint the \fIstring\fR argument.  If no \fIfile\fR is specified then
X\fIstring\fR is output to the standard output file.  If \fIfile\fR is
Xspecified, then \fIstring\fR is output to that file.  If the \fBappend\fR
Xoption is given, then \fIstring\fR is appended to \fIfile\fR;  otherwise
Xany existing contents of \fIfile\fR are discarded before \fIstring\fR
Xis written to the file.
X.VE
X.TP
X\fBproc \fIname args body\fR
XThe \fBproc\fR command creates a new Tcl command procedure,
X\fIname\fR, replacing
Xany existing command there may have been by that name.  Whenever the
Xnew command is invoked, the contents of \fIbody\fR will be executed
Xby the Tcl interpreter.  \fIArgs\fR specifies the formal arguments to the
Xprocedure.  It consists of a list, possibly empty, each of whose
Xelements specifies
Xone argument.  Each argument specifier is also a list with either
Xone or two fields.  If there is only a single field in the specifier,
Xthen it is the name of the argument;  if there are two fields, then
Xthe first is the argument name and the second is its default value.
Xbraces and backslashes may be used in the usual way to specify
Xcomplex default values.
X.IP
XWhen \fIname\fR is invoked, a local variable
Xwill be created for each of the formal arguments to the procedure;  its
Xvalue will be the value of corresponding argument in the invoking command
Xor the argument's default value.
XArguments with default values need not be
Xspecified in a procedure invocation.  However, there must be enough
Xactual arguments for all the
Xformal arguments that don't have defaults, and there must not be any extra
Xactual arguments.  There is one special case to permit procedures with
Xvariable numbers of arguments.  If the last formal argument has the name
X\fBargs\fR, then a call to the procedure may contain more actual arguments
Xthan the procedure has formals.  In this case, all of the actual arguments
Xstarting at the one that would be assigned to \fBargs\fR are combined into
Xa list (as if the \fBlist\fR command had been used);  this combined value
Xis assigned to the local variable \fBargs\fR.
X.IP
XWhen \fIbody\fR is being executed, variable names normally refer to
Xlocal variables, which are created automatically when referenced and
Xdeleted when the procedure returns.  One local variable is automatically
Xcreated for each of the procedure's arguments.
XGlobal variables can only be accessed by invoking
Xthe \fBglobal\fR command.
X.IP
XThe \fBproc\fR command returns the null string.  When a procedure is
Xinvoked, the procedure's return value is the value specified in a
X\fBreturn\fR command.  If the procedure doesn't execute an explicit
X\fBreturn\fR, then its return value is the value of the last command
Xexecuted in the procedure's body.
XIf an error occurs while executing the procedure
Xbody, then the procedure-as-a-whole will return that same error.
X.TP
X\fBrange \fIvalue first last \fR[\fBchars\fR]
XReturn a range of fields or characters from \fIvalue\fR.  If the
X\fBchars\fR keyword isn't specified, then \fIvalue\fR must be
Xa list and \fBrange\fR will return a new list consisting of elements
X\fIfirst\fR through \fIlast\fR, inclusive.  The
Xspecial keyword \fBend\fR may be specified for \fIlast\fR; in
Xthis case all the elements of \fIvalue\fR starting at \fIfirst\fR
Xare returned.  If the \fBchars\fR keyword, or any abbreviation of
Xit, is specified, then \fBrange\fR treats \fIvalue\fR as a character
Xstring and returns characters \fIfirst\fR through \fIlast\fR of
Xit, inclusive.  Once again, the \fBend\fR keyword may be used for
X\fIlast\fR.  In both cases if a \fIlast\fR value is specified greater
Xthan the size of \fIvalue\fR it is equivalent to specifying \fBend\fR;
Xif \fIlast\fR is less than \fIfirst\fR then an empty string is returned.
XNote: ``\fBrange \fIvalue first first\fR'' does not always produce the
Xsame results as ``\fBindex \fIvalue first\fR'' (although it often does
Xfor simple fields that aren't enclosed in braces);  it does, however,
Xproduce exactly the same results as ``\fBlist [index \fIvalue first\fB]\fR''
X.TP
X\fBrename \fIoldName newName\fR
X.VS
XRename the command that used to be called \fIoldName\fR so that it
Xis now called \fInewName\fR.  If \fInewName\fR is an empty string
X(e.g. {}) then \fIoldName\fR is deleted.  The \fBrename\fR command
Xreturns an empty string as result.
X.VE
X.TP
X\fBreturn \fR[\fIvalue\fR]
XReturn immediately from the current procedure
X.VS
X(or top-level command or \fBsource\fR command),
X.VE
Xwith \fIvalue\fR as the return value.  If \fIvalue\fR is not specified,
Xan empty string will be returned as result.
X.VE
X.TP
X\fBscan \fIstring format varname1 varname2 ...\fR
XThis command parses fields from an input string in the same fashion
Xas the C \fBsscanf\fR procedure.  \fIString\fR gives the input to
Xbe parsed and \fIformat\fR indicates how to parse it, using \fB%\fR
Xfields as in \fBsscanf\fR.  All of the \fBsscanf\fR options are valid;
Xsee the \fBsscanf\fR man page for details.  Each \fIvarname\fR gives
Xthe name of a variable;  when a field is scanned from \fIstring\fR,
Xthe result is converted back into a string and assigned to the
Xcorresponding \fIvarname\fR.  The only unusual conversion is for
X\fB%c\fR;  in this case, the character value is converted to a
Xdecimal string, which is then assigned to the corresponding \fIvarname\fR.
X.VS
X.TP
X\fBset \fIvarname \fR[\fIvalue\fR]
X.VS
XIf \fIvalue\fR isn't specified, then return the current value of
X\fIvarname\fR.  If \fIvalue\fR is specified, then set
X.VE
Xthe value of \fIvarname\fR to \fIvalue\fR, creating a new variable
Xif one doesn't already exist.  If no procedure is active, then
X\fIvarname\fR refers to a global variable.  If a procedure is
Xactive, then \fIvarname\fR refers to a parameter or local variable
Xof the procedure, unless the \fIglobal\fR command has been invoked
Xto declare \fIvarname\fR to be global.
X.VE
X.TP
X\fBsource \fIfileName\fR
XRead file \fIfileName\fR and pass the contents to the Tcl interpreter
Xas a sequence of commands to execute in the normal fashion.  The return
Xvalue of \fBsource\fR is the return value of the last command executed
Xfrom the file.  If an error occurs in executing the contents of the
Xfile, then the \fBsource\fR command will return that error.
X.VS
XIf a \fBreturn\fR command is invoked from within the file, the remainder of
Xthe file will be skipped and the \fBsource\fR command will return
Xnormally with the result from the \fBreturn\fR command.
X.VE
X.TP
X\fBstring \fIoption a b\fR
XPerform a string operation on the two operands \fIa\fR and \fIb\fR,
Xbased on \fIoption\fR.  The possible options are:
X.RS
X.TP
X\fBstring compare \fIa b\fR
XPerform a character-by-character comparison of strings \fIa\fR and
X\fIb\fR, in the same way as the C \fBstrcmp\fR procedure.  Return
X-1, 0, or 1, depending on whether \fIa\fR is lexicographically
Xless than, equal to, or greater than \fIb\fR.
X.TP
X\fBstring first \fIa b\fR
XSearch \fIb\fR for a sequence of characters that exactly match
Xthe characters in \fIa\fR.  If found, return the index of the
Xfirst character in the first such match within \fIb\fR.  If not
Xfound, return -1.
X.TP
X\fBstring last \fIa b\fR
XSearch \fIb\fR for a sequence of characters that exactly match
Xthe characters in \fIa\fR.  If found, return the index of the
Xfirst character in the last such match within \fIb\fR.  If there
Xis no match, then return -1.
X.br
X.VS
X.TP
X\fBstring match \fIpattern\fR \fIstring\fR
XSee if \fIpattern\fR matches \fIstring\fR;  return 1 if it does, 0
Xif it doesn't.  Matching is done in a fashion similar to that
Xused by the C-shell.  For the two strings to match, their contents
Xmust be identical except that the following special sequences
Xmay appear in \fIpattern\fR:
X.RS
X.IP \fB*\fR 10
XMatches any sequence of characters in \fIstring\fR,
Xincluding a null string.
X.IP \fB?\fR 10
XMatches any single character in \fIstring\fR.
X.IP \fB[\fIchars\fB]\fR 10
XMatches any character in the set given by \fIchars\fR.  If a sequence
Xof the form
X\fIx\fB\-\fIy\fR appears in \fIchars\fR, then any character
Xbetween \fIx\fR and \fIy\fR, inclusive, will match.
X.IP\fB\e\fIx\fR 10
XMatches the single character \fIx\fR.  This provides a way of
Xavoiding the special interpretation of the characters
X\fB*?[]\e\fR in \fIpattern\fR.
X.RE
X.RE
X.VE
X.IP
XUnique abbreviations for \fIoption\fR are acceptable.
X.TP
X\fBtime \fIcommand\fR [\fIcount\fR]
XThis command will call the Tcl interpreter \fIcount\fR
Xtimes to execute \fIcommand\fR (or once if \fIcount\fR isn't
Xspecified).  It will then return a string of the form
X.RS
X.DS
X\fB503 microseconds per iteration\fR
X.DE
Xwhich indicates the average amount of time required per iteration,
Xin microseconds.
XTime is measured in elapsed time, not CPU time.
X.RE
X.TP
X\fBuplevel \fIlevel command command ...\fR
X.VS
XAll of the \fIcommand\fR arguments are concatenated as if they had
Xbeen passed to \fBconcat\fR and the result is evaluated in the
Xvariable context indicated by \fIlevel\fR.  \fBUplevel\fR returns
Xthe result of that evaluation.  If \fIlevel\fR is zero,
Xthen top-level context is used (all variable names refer to global
Xvariables).  If \fIlevel\fR is a positive number, then it is treated
Xas a stack level:  1 refers to the topmost active procedure, 2 to the
Xprocedure it called, and so on.  If \fIlevel\fR is a negative number,
Xthen it is treated as a level relative to the current
Xprocedure.  For example, a \fIlevel\fR of -1 refers to the procedure
Xthat called the
Xone invoking the \fBuplevel\fR command (which is top-level if the
Xprocedure invoking \fBuplevel\fR is at level 1).
XThe \fBuplevel\fR command causes the invoking procedure to disappear
Xfrom the procedure calling stack while the command is being executed.
XFor example, suppose procedure \fBx\fR is
Xat level 3 and invokes the command
X.RS
X.DS
X\fBuplevel -1 {set a 43; c}
X.DE
Xwhere \fBc\fR is another Tcl procedure.  The \fBset\fR command will
Xmodify variable \fBa\fR in \fBx\fR's caller, and \fBc\fR will execute
Xat level 3, as if called from \fBx\fR's caller.  If it in turn executes
Xthe command
X.DS
X\fBuplevel -1 {set a 42}
X.DE
Xthen the \fBset\fR command will modify the same variable \fBa\fR in \fBx\fR's
Xcaller:  the procedure \fBx\fR does not appear to be on the call stack
Xwhen \fBc\fR is executing.  The command ``\fBinfo level\fR'' may
Xbe used to obtain the level of the current procedure.
X\fBUplevel\fR makes it possible to implement new control
Xconstructs as Tcl procedures (for example, \fBuplevel\fR could
Xbe used to implement the \fBwhile\fR construct as a Tcl procedure).
X.VE
X.RE
X
X.VS
X.SH "BUILT-IN VARIABLES"
X.PP
XThe following global variables are created and managed automatically
Xby the Tcl library.  These variables should normally be treated as
Xread-only by application-specific code and by users.
X.TP
X\fBerrorInfo\fR
XAfter an error has occurred, this string will contain two or more lines
Xidentifying the Tcl commands and procedures that were being executed
Xwhen the most recent error occurred.
X.VE
X
X.SH AUTHOR
XJohn Ousterhout, University of California at Berkeley (ouster@sprite.berkeley.edu)
END_OF_FILE
if test 53444 -ne `wc -c <'Tcl.1'`; then
    echo shar: \"'Tcl.1'\" unpacked with wrong size!
fi
# end of 'Tcl.1'
fi
if test -f 'tmac.sprite' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'tmac.sprite'\"
else
echo shar: Extracting \"'tmac.sprite'\" \(4898 characters\)
sed "s/^X//" >'tmac.sprite' <<'END_OF_FILE'
X.\" This file contains extra Ditroff macros used in Sprite man pages:
X.\"
X.\" .HS name section [date [version]]
X.\"	Replacement for .TH in other man pages.  See below for valid
X.\"	section names.
X.\"
X.\" .LG
X.\"	Increase font size;  opposite of .SM
X.\"
X.\" .AP type name in/out [indent]
X.\"	Start paragraph describing an argument to a library procedure.
X.\"	type is type of argument (int, etc.), in/out is either "in", "out",
X.\"	or "in/out" to describe whether procedure reads or modifies arg,
X.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
X.\"	needed;  use .AS below instead)
X.\"
X.\" .AS [type [name]]
X.\"	Give maximum sizes of arguments for setting tab stops.  Type and
X.\"	name are examples of largest possible arguments that will be passed
X.\"	to .AP later.  If args are omitted, default tab stops are used.
X.\"
X.\" .BS
X.\"	Start box enclosure.  From here until next .BE, everything will be
X.\"	enclosed in one large box.
X.\"
X.\" .BE
X.\"	End of box enclosure.
X.\"
X.\" .VS
X.\"	Begin vertical sidebar, for use in marking newly-changed parts
X.\"	of man pages.
X.\"
X.\" .VE
X.\"	End of vertical sidebar.
X.\"
X'	# Heading for Sprite man pages
X.de HS
X.TH "\\$1" "\\$2"
X.\" .PD
X.\" .DT
X.\" .AS
X.\" .if n .nr IN .5i
X.\" .if t .nr IN .5i
X.\" .nr LL \\n(.l
X.\" .ds ]S UNKNOWN SECTION (\\$2)
X.\" .if '\\$2'cmds'       .ds ]S User Commands
X.\" .if '\\$2'lib'        .ds ]S C Library Procedures
X.\" .if '\\$2'dev'        .ds ]S Devices
X.\" .if '\\$2'tcl'        .ds ]S Tcl Command Language Library
X.\" .if '\\$2'admin'      .ds ]S Administrative Commands
X.\" .if '\\$2'daemons'    .ds ]S Daemons
X.\" .if '\\$2'files'      .ds ]S File Formats
X.\" .ds ]H \\$1
X.\" .ds ]D \\*(]S
X.\" .ie '\\$3'' .ds ]L  Printed:\\ \\ \\*(DY
X.\" .el         .ds ]L  Modified:\\ \\ \\$3
X.\" .if t .ie '\\$4'' .ds ]W Sprite version 1.0
X.\" .if t .el         .ds ]W Sprite version \\$4
X.\" .if n .ie '\\$4'' .ds ]W Sprite v.1.0
X.\" .if n .el         .ds ]W Sprite v.\\$4
X.\" .if !"\\$3"" .ds ]L \\$3
X.\" .wh 0 }H
X.\" .if t .wh -1i }B
X.\" .if n .wh -1.167i }F
X.\" .if \\n(nl .bp 1
X.\" .em }M
X.\" .}E
X.\" .DT
X.\" .nr )I .5i
X.\" .nr )R 0
X..
X'	# Increase point size 1 tick
X.de LG
X.ps +1
X.it 1 }N
X.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
X..
X'	# Start an argument description
X.de AP
X.ie !"\\$4"" .TP \\$4
X.el \{\
X.   ie !"\\$2"" .TP \\n()Cu
X.   el          .TP 15
X.\}
X.ie !"\\$3"" \{\
X.ta \\n()Au \\n()Bu
X\&\\$1	\\fI\\$2\\fP	(\\$3)
X.\".b
X.\}
X.el \{\
X.br
X.ie !"\\$2"" \{\
X\&\\$1	\\fI\\$2\\fP
X.\}
X.el \{\
X\&\\fI\\$1\\fP
X.\}
X.\}
X.DT
X..
X'	# define tabbing values for .AP
X.de AS
X.nr )A 10n
X.if !"\\$1"" .nr )A \\w'\\$1'u+3n
X.nr )B \\n()Au+15n
X.\"
X.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
X.nr )C \\n()Bu+\\w'(in/out)'u+2n
X..
X'	# BS - start boxed text
X.de BS
X.\" .br
X.\" .mk )a
X.\" .ds )b 1
X.\" .if n .nf
X.\" .if n .ti 0
X.\" .if n \l'\\n(.lu\(ul'
X.\" .if n .fi
X..
X'	# Special macro to handle page bottom:  finish off current
X'	# box/sidebar if in box/sidebar mode, then invoked standard
X'	# page bottom macro.
X.de }B
X.if '\\*()b'1' \{\
X.ev 1
X'ti 0
X'nf
X.if t \h'-1.5n'\L'|\\n()au-1.5v'\l'\\n(.lu+3n\(ul'\L'-|\\n()au+1.5v'\l'|0u-1.5n\(ul'
X'sp -1
X.ev
X'fi
X.\}
X.if '\\*()v'2' \{\
X.if t \{\
X.ev 1
X'ti 0
X'nf
X\h'|\\n(.lu+2n'\v'-1v'\L'|\\n()bu-1v\(br'\v'-|\\n()bu+2v'\h'-|\\n(.lu+2n'
X'sp -1
X'fi
X.ev
X.\}
X.\}
X.}F
X..
X'	# What to do when the head of the page occurs during boxed text
X'	# or vertical sidebar: update starting position for box/sidebar.
X.am }H
X.mk )a
X.mk )b
X..
X'	# BE - end boxed text (draw box now)
X.de BE
X.\" .sp -1
X.\" .nf
X.\" .ti 0
X.\" .ie n \l'\\n(.lu\(ul'
X.\" .el \{
X.\" \h'-1.5n'\L'|\\n()au-1.5v'\l'\\n(.lu+3n\(ul'\L'-|\\n()au+1.5v'\l'|0u-1.5n\(ul'
X.\"   \h = move left 1.5n
X.\"   \L = draw up,   len=  )a units + 1.5v 
X.\"	\L draws a line, arg = distance. if negative, draws up.
X.\"	The position in reg. )a is used to draw the vertical lines.
X.\"	  |\\n)au = distance from current loc. to )a (negative distance)
X.\"	  -1.5v   = distance above )a since there is text at )a's location
X.\"   \l = draw right, len= cur. line length + 3n using underrule
X.\"   \L = draw down, len=  )a units + 1.5v 
X.\"   \l = draw left, back to original spot
X.\}
X.\" .fi
X.\" .br
X.\" .ds )b 0
X..
X'	# VS - start vertical sidebar
X.de VS
X.if n 'mc \s12\(br\s0
X.if t \{\
X.mk )b
X.ds )v 2
X.\}
X..
X'	# VE - end of vertical sidebar
X.de VE
X.if n 'mc
X.if t \{\
X.ev 1
X.nf
X.ti 0
X\h'|\\n(.lu+2n'\L'|\\n()bu-1v\(br'\v'-|\\n()bu+1v'\h'-|\\n(.lu+2n'
X.sp -1
X.fi
X.ev
X.\}
X.ds )v 0
X..
X.\"
X.\"  Define the string DY to be the current date
X.\"  format:  month day, year
X.\"
X.if \n(mo-0 .ds MO January
X.if \n(mo-1 .ds MO February
X.if \n(mo-2 .ds MO March
X.if \n(mo-3 .ds MO April
X.if \n(mo-4 .ds MO May
X.if \n(mo-5 .ds MO June
X.if \n(mo-6 .ds MO July
X.if \n(mo-7 .ds MO August
X.if \n(mo-8 .ds MO September
X.if \n(mo-9 .ds MO October
X.if \n(mo-10 .ds MO November
X.if \n(mo-11 .ds MO December
X.ds DY \*(MO \n(dy, 19\n(yr
X
X.de DS
X.sp
X.nf
X..
X.de DE
X.sp
X.fi
X..
END_OF_FILE
if test 4898 -ne `wc -c <'tmac.sprite'`; then
    echo shar: \"'tmac.sprite'\" unpacked with wrong size!
fi
# end of 'tmac.sprite'
fi
echo shar: End of archive 1 \(of 2\).
cp /dev/null ark1isdone
MISSING=""
for I in 1 2 ; do
    if test ! -f ark${I}isdone ; then
	MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked both archives.
    rm -f ark[1-9]isdone
else
    echo You still need to unpack the following archives:
    echo "        " ${MISSING}
fi
##  End of shell archive.
exit 0
-- 
 _--_|\  `-_-' Peter da Silva. +1 713 274 5180. <peter@ficc.uu.net>.
/      \  'U`
\_.--._/
      v


