Usenet 1994 January/usenetsourcesnewsgroupsinfomagicjanuary1994.iso/sources/misc/volume25/tcl/part33

Text File | 1991-11-15 | 44.3 KB | 1,065 lines

Newsgroups: comp.sources.misc
From: [e-mail] (Karl Lehenbauer)
Subject:  v25i101:  tcl - tool command language, version 6.1, Part33/33
Message-ID: <[e-mail]>
X-Md4-Signature: 90584bdb2366a3c0051580e20599b9b1
Date: Fri, 15 Nov 1991 23:01:49 GMT
Approved: [e-mail]

Submitted-by: [e-mail] (Karl Lehenbauer)
Posting-number: Volume 25, Issue 101
Archive-name: tcl/part33
Environment: UNIX

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#        "End of archive 33 (of 33)."
# Contents:  tcl6.1/doc/Tcl.man.2
# Wrapped by karl@one on Tue Nov 12 19:44:34 1991
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'tcl6.1/doc/Tcl.man.2' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'tcl6.1/doc/Tcl.man.2'\"
else
echo shar: Extracting \"'tcl6.1/doc/Tcl.man.2'\" \(41756 characters\)
sed "s/^X//" >'tcl6.1/doc/Tcl.man.2' <<'END_OF_FILE'
X.PP
XIf a regular expression could match two different parts of a string,
Xit will match the one which begins earliest.
XIf both begin in the same place but match different lengths, or match
Xthe same length in different ways, life gets messier, as follows.
X.PP
XIn general, the possibilities in a list of branches are considered in
Xleft-to-right order, the possibilities for ``*'', ``+'', and ``?'' are
Xconsidered longest-first, nested constructs are considered from the
Xoutermost in, and concatenated constructs are considered leftmost-first.
XThe match that will be chosen is the one that uses the earliest
Xpossibility in the first choice that has to be made.
XIf there is more than one choice, the next will be made in the same manner
X(earliest possibility) subject to the decision on the first choice.
XAnd so forth.
X.PP
XFor example, ``(ab|a)b*c'' could match ``abc'' in one of two ways.
XThe first choice is between ``ab'' and ``a''; since ``ab'' is earlier, and does
Xlead to a successful overall match, it is chosen.
XSince the ``b'' is already spoken for,
Xthe ``b*'' must match its last possibility\(emthe empty string\(emsince
Xit must respect the earlier choice.
X.PP
XIn the particular case where no ``|''s are present and there is only one
X``*'', ``+'', or ``?'', the net effect is that the longest possible
Xmatch will be chosen.
XSo ``ab*'', presented with ``xabbbby'', will match ``abbbb''.
XNote that if ``ab*'' is tried against ``xabyabbbz'', it
Xwill match ``ab'' just after ``x'', due to the begins-earliest rule.
X(In effect, the decision on where to start the match is the first choice
Xto be made, hence subsequent choices must respect it even if this leads them
Xto less-preferred alternatives.)
X.VE
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
Xsuccessfully.  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
XIn additon, the global variable \fBerrorInfo\fR will contain
Xhuman-readable information
Xdescribing which commands and procedures were being executed when the
Xerror occurred, and the global variable \fBerrorCode\fR will contain
Xmachine-readable details about the error, if they are available.
XSee the section BUILT-IN VARIABLES below for more information.
X.VE
X.VE
X.TP 20
X\fBTCL_RETURN\fR
XIndicates that the \fBreturn\fR command has been invoked, and that the
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.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 \- SCALARS AND ARRAYS
X.VS
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.
XVariables need not be declared:  a new variable will automatically
Xbe created each time a new variable name is used.
X.PP
XTcl supports two types of variables:  scalars and arrays.
XA scalar variable has a single value, whereas an array variable
Xcan have any number of elements, each with a name (called
Xits ``index'') and a value.
XArray indexes may be arbitrary strings; they need not be numeric.
XParentheses are used refer to array elements in Tcl commands.
XFor example, the command
X.DS C
X\fBset x(first) 44\fR
X.DE
Xwill modify the element of \fBx\fR whose index is \fBfirst\fR
Xso that its new value is \fB44\fR.
XTwo-dimensional arrays can be simulated in Tcl by using indexes
Xthat contain multiple concatenated values.
XFor example, the commands
X.DS C
X\fBset a(2,3) 1\fR
X\fBset a(3,6) 2\fR
X.DE
Xset the elements of \fBa\fR whose indexes are \fB2,3\fR and \fB3,6\fR.
X.PP
XIn general, array elements may be used anywhere in Tcl that scalar
Xvariables may be used.
XIf an array is defined with a particular name, then there may
Xnot be a scalar variable with the same name.
XSimilarly, if there is a scalar variable with a particular
Xname then it is not possible to make array references to the
Xvariable.
XTo convert a scalar variable to an array or vice versa, remove
Xthe existing variable with the \fBunset\fR command.
X.PP
XThe \fBarray\fR command provides several features for dealing
Xwith arrays, such as querying the names of all the elements of
Xthe array and searching through the array one element at a time.
X.VE
X.PP
XVariables 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.
XIn the command syntax descriptions below, words in boldface are
Xliterals that you type verbatim to Tcl.
XWords in italics are meta-symbols; they serve as names for any of
Xa range of values that you can type.
XOptional arguments or groups of arguments are indicated by enclosing them
Xin question-marks.
XEllipses (``...'') indicate that any number of additional
Xarguments or groups of arguments may appear, in the same format
Xas the preceding argument(s).
X.TP
X\fBappend \fIvarName value \fR?\fIvalue value ...\fR?
X.VS
XAppend all of the \fIvalue\fR arguments to the current value
Xof variable \fIvarName\fR.  If \fIvarName\fR doesn't exist,
Xit is given a value equal to the concatenation of all the
X\fIvalue\fR arguments.
XThis command provides an efficient way to build up long
Xvariables incrementally.
XFor example, ``\fBappend a $b\fR'' is much more efficient than
X``\fBset a $a$b\fR'' if \fB$a\fR is long.
X.VE
X.TP
X\fBarray \fIoption arrayName\fR ?\fIarg arg ...\fR?
X.VS
XThis command performs one of several operations on the
Xvariable given by \fIarrayName\fR.
X\fIArrayName\fR must be the name of an existing array variable.
XThe \fIoption\fR argument determines what action is carried
Xout by the command.
XThe legal \fIoptions\fR (which may be abbreviated) are:
X.RS
X.TP
X\fBarray anymore \fIarrayName searchId\fR
XReturns 1 if there are any more elements left to be processed
Xin an array search, 0 if all elements have already been
Xreturned.
X\fISearchId\fR indicates which search on \fIarrayName\fR to
Xcheck, and must have been the return value from a previous
Xinvocation of \fBarray startsearch\fR.
XThis option is particularly useful if an array has an element
Xwith an empty name, since the return value from
X\fBarray nextelement\fR won't indicate whether the search
Xhas been completed.
X.TP
X\fBarray donesearch \fIarrayName searchId\fR
XThis command terminates an array search and destroys all the
Xstate associated with that search.  \fISearchId\fR indicates
Xwhich search on \fIarrayName\fR to destroy, and must have
Xbeen the return value from a previous invocation of
X\fBarray startsearch\fR.  Returns an empty string.
X.TP
X\fBarray names \fIarrayName\fR
XReturns a list containing the names of all of the elements in
Xthe array.
XIf there are no elements in the array then an empty string is
Xreturned.
X.TP
X\fBarray nextelement \fIarrayName searchId\fR
XReturns the name of the next element in \fIarrayName\fR, or
Xan empty string if all elements of \fIarrayName\fR have
Xalready been returned in this search.  The \fIsearchId\fR
Xargument identifies the search, and must have
Xbeen the return value of an \fBarray startsearch\fR command.
XWarning:  if elements are added to or deleted from the array,
Xthen all searches are automatically terminated just as if
X\fBarray donesearch\fR had been invoked; this will cause
X\fBarray nextelement\fR operations to fail for those searches.
X.TP
X\fBarray size \fIarrayName\fR
XReturns a decimal string giving the number of elements in the
Xarray.
X.TP
X\fBarray startsearch \fIarrayName\fR
XThis command initializes an element-by-element search through the
Xarray given by \fIarrayName\fR, such that invocations of the
X\fBarray nextelement\fR command will return the names of the
Xindividual elements in the array.
XWhen the search has been completed, the \fBarray donesearch\fR
Xcommand should be invoked.
XThe return value is a
Xsearch identifier that must be used in \fBarray nextelement\fR
Xand \fBarray donesearch\fR commands; it allows multiple
Xsearches to be underway simultaneously for the same array.
X.VE
X.RE
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 or \fBwhile\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 \fR?\fIpatList body \fR...?
X.TP
X\fBcase\fI string \fR?\fBin\fR? {\fIpatList body \fR?\fIpatList body \fR...?}
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.
X.RS
X.PP
XTwo syntaxes are provided.
XThe first uses a separate argument for each of the patterns and commands;
Xthis form is convenient if substitutions are desired on some of the
Xpatterns or commands.
X.VS
XThe second form places all of the patterns and commands together into
Xa single argument; the argument must have proper list structure, with
Xthe elements of the list being the patterns and commands.
XThe second form makes it easy to construct multi-line case commands,
Xsince the braces around the whole list make it unnecessary to include a
Xbackslash at the end of each line.
XSince the \fIpatList\fR arguments are in braces in the second form,
Xno command or variable substitutions are performed on them;  this makes
Xthe behavior of the second form different than the first form in some
Xcases.
X.PP
XBelow are some examples of \fBcase\fR commands:
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.ta .5c 1c
X\fBcase a in {
X    {a b} {format 1}
X    default {format 2}
X    a* {format 3}
X}
X.DE
Xwill return \fB1\fR, and
X.DS
X.ta .5c 1c
X\fBcase xyz {
X    {a b}
X        {format 1}
X    default
X        {format 2}
X    a*
X        {format 3}
X}
X.DE
Xwill return \fB2\fR.
X.VE
X.RE
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\fBcd \fR?\fIdirName\fR?
X.VS
XChange the current working directory to \fIdirName\fR, or to the
Xhome directory (as specified in the HOME environment variable) if
X\fIdirName\fR is not given.
XIf \fIdirName\fR starts with a tilde, then tilde-expansion is
Xdone as described for \fBTcl_TildeSubst\fR.
XReturns an empty string.
XThis command can potentially be disruptive to an application,
Xso it may be removed in some applications.
X.TP
X\fBclose \fIfileId\fR
XCloses the file given by \fIfileId\fR.
X\fIFileId\fR must be the return value from a previous invocation
Xof the \fBopen\fR command; after this command, it should not be
Xused anymore.
XIf \fIfileId\fR refers to a command pipeline instead of a file,
Xthen \fBclose\fR waits for the children to complete.
XThe normal result of this command is an empty string, but errors
Xare returned if there are problems in closing the file or waiting
Xfor children to complete.
X.VE
X.TP
X\fBconcat\fI arg \fR?\fIarg ...\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 or \fBwhile\fR.  It
Xreturns 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\fBeof \fIfileId\fR
X.VS
XReturns 1 if an end-of-file condition has occurred on \fIfileId\fR,
X0 otherwise.
X\fIFileId\fR must have been the return
Xvalue from a previous call to \fBopen\fR, or it may be \fBstdin\fR,
X\fBstdout\fR, or \fBstderr\fR to refer to one of the standard I/O
Xchannels.
X.VE
X.TP
X\fBerror \fImessage\fR ?\fIinfo\fR? ?\fIcode\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.RS
X.PP
XIf the \fIinfo\fR argument is provided and is non-empty,
Xit is used to initialize the global variable \fBerrorInfo\fR.
X\fBerrorInfo\fR is used to accumulate a stack trace of what
Xwas in progress when an error occurred; as nested commands unwind,
Xthe Tcl interpreter adds information to \fBerrorInfo\fR.  If the
X\fIinfo\fR argument is present, it is used to initialize
X\fBerrorInfo\fR and the first increment of unwind information
Xwill not be added by the Tcl interpreter.  In other
Xwords, the command containing the \fBerror\fR command will not appear
Xin \fBerrorInfo\fR; in its place will be \fIinfo\fR.
XThis feature is most useful in conjunction with the \fBcatch\fR command:
Xif a caught error cannot be handled successfully, \fIinfo\fR can be used
Xto return a stack trace reflecting the original point of occurrence
Xof the error:
X.DS
X\fBcatch {...} errMsg
Xset savedInfo $errorInfo
X\&...
Xerror $errMsg $savedInfo\fR
X.DE
X.PP
X.VS
XIf the \fIcode\fR argument is present, then its value is stored
Xin the \fBerrorCode\fR global variable.  This variable is intended
Xto hold a machine-readable description of the error in cases where
Xsuch information is available; see the section BUILT-IN VARIABLES
Xbelow for information on the proper format for the variable.
XIf the \fIcode\fR argument is not
Xpresent, then \fBerrorCode\fR is automatically reset to
X``NONE'' by the Tcl interpreter as part of processing the
Xerror generated by the command.
X.VE
X.RE
X.TP
X\fBeval \fIarg \fR?\fIarg ...\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.TP
X\fBexec \fIarg \fR?\fIarg ...\fR?
X.VS
XThis command treats its arguments as the specification
Xof one or more UNIX commands to execute as subprocesses.
XThe commands take the form of a standard shell pipeline;
X``|'' arguments separate commands in the
Xpipeline and cause standard output of the preceding command
Xto be piped into standard input of the next command.
X.RS
X.PP
XUnder normal conditions the result of the \fBexec\fR command
Xconsists of the standard output produced by the last command
Xin the pipeline.
XIf any of the commands in the pipeline exit abnormally or
Xare killed or suspended, then \fBexec\fR will return an error
Xand the error message will include the pipeline's output followed by
Xerror messages describing the abnormal terminations; the
X\fBerrorCode\fR variable will contain additional information
Xabout the last abnormal termination encountered.
XIf any of the commands writes to its standard error file,
Xthen \fBexec\fR will return an error, and the error message
Xwill include the pipeline's output, followed by messages
Xabout abnormal terminations (if any), followed by the standard error
Xoutput.
X.PP
XIf the last character of the result or error message
Xis a newline then that character is deleted from the result
Xor error message for consistency with normal
XTcl return values.
X.PP
XIf an \fIarg\fR has the value ``>'' then the
Xfollowing argument is taken as the name of a file and
Xthe standard output of the last command in the pipeline
Xis redirected to the file.  In this situation \fBexec\fR
Xwill normally return an empty string.
X.PP
XIf an \fIarg\fR has the value ``<'' then the following
Xargument is taken as the name of a file to use
Xfor standard input to the first command in the
Xpipeline.
XIf an argument has the value ``<<'' then the following
Xargument is taken as an immediate value to be passed to
Xthe first command as standard input.
XIf there is no ``<'' or ``<<'' argument then the standard
Xinput for the first command in the pipeline is taken from
Xthe application's current standard input.
X.PP
XIf the last \fIarg\fR is ``&'' then the command will be
Xexecuted in background.
XIn this case the standard output from the last command
Xin the pipeline will
Xgo to the application's standard output unless
Xredirected in the command, and error output from all
Xthe commands in the pipeline will go to the application's
Xstandard error file.
X.PP
XEach \fIarg\fR becomes one word for a command, except for
X``|'', ``<'', ``<<'', ``>'', and ``&'' arguments, and the
Xarguments that follow ``<'', ``<<'', and ``>''.
XThe first word in each command is taken as the command name;
Xtilde-substitution is performed on it, and the directories
Xin the PATH environment variable are searched for
Xan executable by the given name.
XNo ``glob'' expansion or other shell-like substitutions
Xare performed on the arguments to commands.
X.RE
X.TP
X\fBexit \fR?returnCode\fR?
XTerminate the process, returning \fIreturnCode\fR to the
Xparent as the exit status.
XIf \fIreturnCode\fR isn't specified then it defaults
Xto 0.
X.VE
X.TP
X\fBexpr \fIarg\fR
XCalls the expression processor to evaluate \fIarg\fR, and returns
Xthe result as a string.  See the section EXPRESSIONS above.
X.TP
X\fBfile \fIoption\fR \fIname\fR ?\fIarg arg ...\fR?
X.VS
XOperate on a file or a file name.  \fIName\fR is the name of a file;
Xif it starts with a tilde, then tilde substitution is done before
Xexecuting the command (see the manual entry for \fBTcl_TildeSubst\fR
Xfor details).
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 \fBatime \fIname\fR
XReturn a decimal string giving the time at which file \fIname\fR
Xwas last accessed.  The time is measured in the standard UNIX
Xfashion as seconds from a fixed starting time (often January 1, 1970).
XIf the file doesn't exist or its access time cannot be queried then an
Xerror is generated.
X.TP
X\fBfile \fBdirname \fIname\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 \fBexecutable \fIname\fR
XReturn \fB1\fR if file \fIname\fR is executable by
Xthe current user, \fB0\fR otherwise.
X.TP
X\fBfile \fBexists \fIname\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 \fBextension \fIname\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 \fBisdirectory \fIname\fR
XReturn \fB1\fR if file \fIname\fR is a directory,
X\fB0\fR otherwise.
X.TP
X\fBfile \fBisfile \fIname\fR
XReturn \fB1\fR if file \fIname\fR is a regular file,
X\fB0\fR otherwise.
X.TP
X\fBfile \fBmtime \fIname\fR
XReturn a decimal string giving the time at which file \fIname\fR
Xwas last modified.  The time is measured in the standard UNIX
Xfashion as seconds from a fixed starting time (often January 1, 1970).
XIf the file doesn't exist or its modified time cannot be queried then an
Xerror is generated.
X.TP
X\fBfile \fBowned \fIname\fR
XReturn \fB1\fR if file \fIname\fR is owned by the current user,
X\fB0\fR otherwise.
X.TP
X\fBfile \fBreadable \fIname\fR
XReturn \fB1\fR if file \fIname\fR is readable by
Xthe current user, \fB0\fR otherwise.
X.TP
X\fBfile \fBrootname \fIname\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 \fBsize \fIname\fR
XReturn a decimal string giving the size of file \fIname\fR in bytes.
XIf the file doesn't exist or its size cannot be queried then an
Xerror is generated.
X.TP
X\fBfile \fBstat  \fIname\fIvarName\fR
XInvoke the \fBstat\fR kernel call on \fIname\fR, and use the
Xvariable given by \fIvarName\fR to hold information returned from
Xthe kernel call.
X\fIVarName\fR is treated as an array variable,
Xand the following elements of that variable are set: \fBatime\fR,
X\fBctime\fR, \fBdev\fR, \fBgid\fR, \fBino\fR, \fBmode\fR, \fBmtime\fR,
X\fBnlink\fR, \fBsize\fR, \fBuid\fR.
XEach element is a decimal string with the value of the corresponding
Xfield from the \fBstat\fR return structure; see the manual entry
Xfor \fBstat\fR for details on the meanings of the values.
XThis command returns an empty string.
X.TP
X\fBfile \fBtail \fIname\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 \fBwritable \fIname\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 exists foo]} then {error {bad file name}} else {...}\fR
X.DE
X.VE
X.RE
X.TP
X\fBflush \fIfileId\fR
X.VS
XFlushes any output that has been buffered for \fIfileId\fR.
X\fIFileId\fR must have been the return
Xvalue from a previous call to \fBopen\fR, or it may be
X\fBstdout\fR or \fBstderr\fR to access one of the standard I/O streams;
Xit must refer to a file that was opened for writing.
XThis command returns an empty string.
X.VE
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 \fIstart\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
Xor \fInext\fR,
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 \fBlindex\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 \fR?\fIarg 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\fBgets \fIfileId\fR ?\fIvarName\fR?
X.VS
XReads the next line from the file given by \fIfileId\fR and discards
Xthe terminating newline character.
XIf \fIvarName\fR is specified, then the line is placed in the variable
Xby that name and the return value is a count of the number of characters
Xread (not including the newline).
XIf the end of the file is reached before reading
Xany characters then \-1 is returned and \fIvarName\fR is set to an
Xempty string.
XIf \fIvarName\fR is not specified then the return value will be
Xthe line (minus the newline character) or an empty string if
Xthe end of the file is reached before reading any characters.
XAn empty string will also be returned if a line contains no characters
Xexcept the newline, so \fBeof\fR may have to be used to determine
Xwhat really happened.
XIf the last character in the file is not a newline character, then
X\fBgets\fR behaves as if there were an additional newline character
Xat the end of the file.
X\fIFileId\fR must be \fBstdin\fR or the return value from a previous
Xcall to \fBopen\fR; it must refer to a file that was opened
Xfor reading.
X.VE
X.TP
X\fBglob \fR?\fB\-nocomplain\fR? \fIfilename\fR ?\fIfilename ...\fR?
XThis command performs filename globbing, using csh rules.  The returned
Xvalue from \fBglob\fR is the list of expanded filenames.
X.VS
XIf \fB\-nocomplain\fR is specified as the first argument then an empty
Xlist may be returned;  otherwise an error is returned if the expanded
Xlist is empty.  The \fB\-nocomplain\fR argument must be provided
Xexactly: an abbreviation will not be accepted.
X.VE
X.TP
X\fBglobal \fIvarname \fR?\fIvarname ...\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\fBhistory \fR?\fIoption\fR? ?\fIarg arg ...\fR?
XNote:  this command may not be available in all Tcl-based applications.
XTypically, only those that receive command input in a typescript
Xform will support history.
XThe \fBhistory\fR command performs one of several operations related to
Xrecently-executed commands recorded in a history list.  Each of
Xthese recorded commands is referred to as an ``event''.  When
Xspecifying an event to the \fBhistory\fR command, the following
Xforms may be used:
X.RS
X.IP [1]
XA number:  if positive, it refers to the event with
Xthat number (all events are numbered starting at 1).  If the number
Xis negative, it selects an event relative to the current event
X(\fB\-1\fR refers to the previous event, \fB\-2\fR to the one before that, and
Xso on).
X.IP [2]
XA string:  selects the most recent event that matches the string.
XAn event is considered to match the string either if the string is
Xthe same as the first characters of the event, or if the string
Xmatches the event in the sense of the \fBstring match\fR command.
X.LP
XThe \fBhistory\fR command can take any of the following forms:
X.TP
X\fBhistory\fR
XSame
X.VS
Xas \fBhistory info\fR, described below.
X.VE
X.TP
X\fBhistory add\fI command \fR?\fBexec\fR?
XAdd the \fIcommand\fR argument to the history list as a new event.  If
X\fBexec\fR is specified (or abbreviated) then the command is also
Xexecuted and its result is returned.  If \fBexec\fR isn't specified
Xthen an empty string is returned as result.
X.TP
X\fBhistory change\fI newValue\fR ?\fIevent\fR?
XReplace the value recorded for an event with \fInewValue\fR.  \fIEvent\fR
Xspecifies the event to replace, and
Xdefaults to the \fIcurrent\fR event (not event \fB\-1\fR).  This command
Xis intended for use in commands that implement new forms of history
Xsubstitution and wish to replace the current event (which invokes the
Xsubstitution) with the command created through substitution.  The return
Xvalue is an empty string.
X.TP
X\fBhistory event\fR ?\fIevent\fR?
XReturns the value of the event given by \fIevent\fR.  \fIEvent\fR
Xdefaults to \fB\-1\fR.  This command causes history revision to occur:
Xsee below for details.
X.TP
X\fBhistory info \fR?\fIcount\fR?
XReturns a formatted string (intended for humans to read) giving
Xthe event number and contents for each of the events in the history
Xlist except the current event.  If \fIcount\fR is specified
Xthen only the most recent \fIcount\fR events are returned.
X.TP
X\fBhistory keep \fIcount\fR
XThis command may be used to change the size of the history list to
X\fIcount\fR events.  Initially, 20 events are retained in the history
Xlist.  This command returns an empty string.
X.TP
X\fBhistory nextid\fR
XReturns the number of the next event to be recorded
Xin the history list.  It is useful for things like printing the
Xevent number in command-line prompts.
X.TP
X\fBhistory redo \fR?\fIevent\fR?
XRe-execute the command indicated by \fIevent\fR and return its result.
X\fIEvent\fR defaults to \fB\-1\fR.  This command results in history
Xrevision:  see below for details.
X.TP
X\fBhistory substitute \fIold new \fR?\fIevent\fR?
XRetrieve the command given by \fIevent\fR
X(\fB\-1\fR by default), replace any occurrences of \fIold\fR by
X\fInew\fR in the command (only simple character equality is supported;
Xno wild cards), execute the resulting command, and return the result
Xof that execution.  This command results in history
Xrevision:  see below for details.
X.TP
X\fBhistory words \fIselector\fR ?\fIevent\fR?
XRetrieve from the command given by \fIevent\fR (\fB\-1\fR by default)
Xthe words given by \fIselector\fR, and return those words in a string
Xseparated by spaces.  The \fBselector\fR argument has three forms.
XIf it is a single number then it selects the word given by that
Xnumber (\fB0\fR for the command name, \fB1\fR for its first argument,
Xand so on).  If it consists of two numbers separated by a dash,
Xthen it selects all the arguments between those two.  Otherwise
X\fBselector\fR is treated as a pattern; all words matching that
Xpattern (in the sense of \fBstring match\fR) are returned.  In
Xthe numeric forms \fB$\fR may be used
Xto select the last word of a command.
XFor example, suppose the most recent command in the history list is
X.RS
X.DS
X\fBformat  {%s is %d years old} Alice [expr $ageInMonths/12]\fR
X.DE
XBelow are some history commands and the results they would produce:
X.DS
X.ta 4c
X.fi
X.UL Command "    "
X.UL Result
X.nf
X
X\fBhistory words $    [expr $ageInMonths/12]\fR
X\fBhistory words 1-2    {%s is %d years  old} Alice\fR
X\fBhistory words *a*o*    {%s is %d years old} [expr $ageInMonths/12]\fR
X.DE
X\fBHistory words\fR results in history revision:  see below for details.
X.RE
XThe history options \fBevent\fR, \fBredo\fR, \fBsubstitute\fR,
Xand \fBwords\fR result in ``history revision''.
XWhen one of these options is invoked then the current event
Xis modified to eliminate the history command and replace it with
Xthe result of the history command.
XFor example, suppose that the most recent command in the history
Xlist is
X.DS
X\fBset a [expr $b+2]\fR
X.DE
Xand suppose that the next command invoked is one of the ones on
Xthe left side of the table below.  The command actually recorded in
Xthe history event will be the corresponding one on the right side
Xof the table.
X.ne 1.5c
X.DS
X.ta 4c
X.fi
X.UL "Command Typed" "    "
X.UL "Command Recorded"
X.nf
X
X\fBhistory    set a [expr $b+2]\fR
X\fBhistory s a b    set b [expr $b+2]\fR
X\fBset c [history w 2]    set c [expr $b+2]\fR
X.DE
X.VS
XHistory revision is needed because event specifiers like \fB\-1\fR
Xare only valid at a particular time:  once more events have been
Xadded to the history list a different event specifier would be
Xneeded.
XHistory revision occurs even when \fBhistory\fR is invoked
Xindirectly from the current event (e.g. a user types a command
Xthat invokes a Tcl procedure that invokes \fBhistory\fR):  the
Xtop-level command whose execution eventually resulted in a
X\fBhistory\fR command is replaced.
XIf you wish to invoke commands like \fBhistory words\fR without
Xhistory revision, you can use \fBhistory event\fR to save the
Xcurrent history event and then use \fBhistory change\fR to
Xrestore it later.
X.VE
X.VE
X.RE
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).  The value of the
Xexpression must be numeric; if it
Xis 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\fBincr \fIvarName \fR?\fIincrement\fR?
X.VS
XIncrement the value stored in the variable whose name is \fIvarName\fR.
XThe value of the variable must be integral.
XIf \fIincrement\fR is supplied then its value (which must be an
Xinteger) is added to the value of variable \fIvarName\fR;  otherwise
X1 is added to \fIvarName\fR.
XThe new value is stored as a decimal string in variable \fIvarName\fR
Xand also returned as result.
X.VE
X.TP
X\fBinfo \fIoption \fR?\fIarg 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 cmdcount\fR
XReturns a count of the total number of commands that have been invoked
Xin this interpreter.
X.TP
X\fBinfo commands \fR?\fIpattern\fR?
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.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 exists \fIvarName\fR
XReturns \fB1\fR if the variable named \fIvarName\fR exists in the
Xcurrent context (either as a global or local variable), returns \fB0\fR
Xotherwise.
X.TP
X\fBinfo globals \fR?\fIpattern\fR?
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 library\fR
X.VS
XReturns the name of the library directory in which standard Tcl
Xscripts are stored.
XIf there is no such directory defined for the current installation
Xthen an error is generated.
XSee the \fBlibrary\fR manual entry for details of the facilities
Xprovided by the Tcl script library.
XNormally each application will have its own application-specific
Xscript library in addition to the Tcl script library;  I suggest that
Xeach application set a global variable with a name like
X\fB$\fIapp\fBLibrary\fR (where \fIapp\fR is the application's name)
Xto hold the location of that application's library directory.
X.VE
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.
X.VS
XVariables defined with the \fBglobal\fR and \fBupvar\fR commands
Xwill not be returned.
X.VE
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 script\fR
X.VS
XIf a Tcl script file is currently being evaluated (i.e. there is a
Xcall to \fBTcl_EvalFile\fR active or there is an active invocation
Xof the \fBsource\fR command), then this command returns the name
Xof the innermost file being processed.  Otherwise the command returns an
Xempty string.
X.VE
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.
END_OF_FILE
if test 41756 -ne `wc -c <'tcl6.1/doc/Tcl.man.2'`; then
    echo shar: \"'tcl6.1/doc/Tcl.man.2'\" unpacked with wrong size!
fi
# end of 'tcl6.1/doc/Tcl.man.2'
fi
echo shar: End of archive 33 \(of 33\).
cp /dev/null ark33isdone
MISSING=""
for I in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 ; do
    if test ! -f ark${I}isdone ; then
    MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 33 archives.
    echo "Combining tclVar.c.1 and tclVar.c.2 to produce tclVar.c..."
    cat tcl6.1/tclVar.c.1 tcl6.1/tclVar.c.2 >tcl6.1/tclVar.c
    echo "Combining Tcl.man.1, Tcl.man.2 and Tcl.man.3 to produce Tcl.man..."
    cat tcl6.1/doc/Tcl.man.1 tcl6.1/doc/Tcl.man.2 \
        tcl6.1/doc/Tcl.man.3 >tcl6.1/doc/Tcl.man
    echo "Now cd to tcl6.1, do a 'csh ./config' and a 'make'"
    rm -f ark[1-9]isdone ark[1-9][0-9]isdone
else
    echo You still need to unpack the following archives:
    echo "        " ${MISSING}
fi
##  End of shell archive.
exit 0

exit 0 # Just in case...
--
Kent Landfield                   INTERNET: [e-mail]
Sterling Software, IMD           UUCP:     uunet!sparky!kent
Phone:    [phone]         FAX:      [phone]
Please send comp.sources.misc-related mail to [e-mail].