Newsgroups: comp.sources.misc From: karl@sugar.neosoft.com (Karl Lehenbauer) Subject: v25i100: tcl - tool command language, version 6.1, Part32/33 Message-ID: <1991Nov15.230132.22421@sparky.imd.sterling.com> X-Md4-Signature: 73264eab3c3709eaf41f45e569626c29 Date: Fri, 15 Nov 1991 23:01:32 GMT Approved: kent@sparky.imd.sterling.com Submitted-by: karl@sugar.neosoft.com (Karl Lehenbauer) Posting-number: Volume 25, Issue 100 Archive-name: tcl/part32 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 'tcl6.1/doc/Tcl.man.3' <<'END_OF_FILE' X.TP X\fBinfo vars\fR ?\fIpattern\fR? XIf \fIpattern\fR isn't specified, Xreturns a list of all the names of currently-visible variables, including Xboth locals and currently-visible globals. 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.RE X.TP X\fBjoin \fIlist \fR?\fIjoinString\fR? X.VS XThe \fIlist\fR argument must be a valid Tcl list. XThis command returns the string Xformed by joining all of the elements of \fIlist\fR together with X\fIjoinString\fR separating each adjacent pair of elements. XThe \fIjoinString\fR argument defaults to a space character. X.VE X.TP X\fBlappend \fIvarName value \fR?\fIvalue value ...\fR? X.VS XTreat the variable given by \fIvarName\fR as a list and append Xeach of the \fIvalue\fR arguments to that list as a separate Xelement, with spaces between elements. XIf \fIvarName\fR doesn't exist, it is created as a list with elements Xgiven by the \fIvalue\fR arguments. X\fBLappend\fR is similar to \fBappend\fR except that the \fIvalue\fRs Xare appended as list elements rather than raw text. XThis command provides a relatively efficient way to build up Xlarge lists. For example, ``\fBlappend a $b\fR'' is much Xmore efficient than ``\fBset a [concat $a [list $b]]\fR'' when X\fB$a\fR is long. X.TP X\fBlindex \fIlist index\fR XTreats \fIlist\fR as a Tcl list and returns the \fIindex\fR'th element Xfrom it (0 refers to the first element of the list). XIn extracting the element, \fIlindex\fR observes the same rules Xconcerning braces and quotes and backslashes as the Tcl command Xinterpreter; however, variable Xsubstitution and command substitution do not occur. XIf \fIindex\fR is negative or greater than or equal to the number Xof elements in \fIvalue\fR, then an empty Xstring is returned. X.TP X\fBlinsert \fIlist index element \fR?\fIelement element ...\fR? XThis command produces a new list from \fIlist\fR by inserting all Xof the \fIelement\fR arguments just before the \fIindex\fRth Xelement of \fIlist\fR. Each \fIelement\fR argument will become Xa separate element of the new list. If \fIindex\fR is less than Xor equal to zero, then the new elements are inserted at the Xbeginning of the list. If \fIindex\fR is greater than or equal Xto the number of elements in the list, then the new elements are Xappended to the list. X.VE X.TP X\fBlist \fIarg \fR?\fIarg ...\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.br X.VS X.TP X\fBllength \fIlist\fR XTreats \fIlist\fR as a list and returns a decimal string giving Xthe number of elements in it. X.TP X\fBlrange \fIlist first last X\fIList\fR must be a valid Tcl list. This command will Xreturn a new list consisting of elements X\fIfirst\fR through \fIlast\fR, inclusive. X\fILast\fR may be \fBend\fR (or any Xabbreviation of it) to refer to the last element of the list. XIf \fIfirst\fR is less than zero, it is treated as if it were zero. XIf \fIlast\fR is greater than or equal to the number of elements Xin the list, then it is treated as if it were \fBend\fR. XIf \fIfirst\fR is greater than \fIlast\fR then an empty string Xis returned. XNote: ``\fBlrange \fIlist first first\fR'' does not always produce the Xsame result as ``\fBlindex \fIlist 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 [lindex \fIlist first\fB]\fR'' X.TP X\fBlreplace \fIlist first last \fR?\fIelement element ...\fR? XReturns a new list formed by replacing one or more elements of X\fIlist\fR with the \fIelement\fR arguments. X\fIFirst\fR gives the index in \fIlist\fR of the first element Xto be replaced. XIf \fIfirst\fR is less than zero then it refers to the first Xelement of \fIlist\fR; the element indicated by \fIfirst\fR Xmust exist in the list. X\fILast\fR gives the index in \fIlist\fR of the last element Xto be replaced; it must be greater than or equal to \fIfirst\fR. X\fILast\fR may be \fBend\fR (or any abbreviation of it) to indicate Xthat all elements between \fIfirst\fR and the end of the list should Xbe replaced. XThe \fIelement\fR arguments specify zero or more new arguments to Xbe added to the list in place of those that were deleted. XEach \fIelement\fR argument will become a separate element of Xthe list. XIf no \fIelement\fR arguments are specified, then the elements Xbetween \fIfirst\fR and \fIlast\fR are simply deleted. X.TP X\fBlsearch \fIlist pattern\fR XSearch the elements of \fIlist\fR to see if one of them matches X\fIpattern\fR. XIf so, the command returns the index of the first matching Xelement. XIf not, the command returns \fB\-1\fR. XPattern matching is done in the same way as for the \fBstring match\fR Xcommand. X.TP X\fBlsort \fIlist\fR XSort the elements of \fIlist\fR, returning a new list in sorted Xorder. XASCII sorting is used, with the result in increasing order. X.VE X.TP X\fBopen \fIfileName\fR ?\fIaccess\fR? X.VS XOpens a file and returns an identifier Xthat may be used in future invocations Xof commands like \fBread\fR, \fBwrite\fR, and \fBclose\fR. X\fIFileName\fR gives the name of the file to open; if it starts with Xa tilde then tilde substitution is performed as described for X\fBTcl_TildeSubst\fR. XIf the first character of \fIfileName\fR is ``|'' then the Xremaining characters of \fIfileName\fR are treated as a command Xpipeline to invoke, in the same style as for \fBexec\fR. XIn this case, the identifier returned by \fBopen\fR may be used Xto write to the command's input pipe or read from its output pipe. XThe \fIaccess\fR argument indicates the way in which the file X(or command pipeline) is to be accessed. XIt may have any of the following values: X.RS X.TP X\fBr\fR XOpen the file for reading only; the file must already exist. X.TP X\fBr+\fR XOpen the file for both reading and writing; the file must Xalready exist. X.TP X\fBw\fR XOpen the file for writing only. Truncate it if it exists. If it doesn't Xexist, create a new file. X.TP X\fBw+\fR XOpen the file for reading and writing. Truncate it if it exists. XIf it doesn't exist, create a new file. X.TP X\fBa\fR XOpen the file for writing only. The file must already exist, and the file Xis positioned so that new data is appended to the file. X.TP X\fBa+\fR XOpen the file for reading and writing. The file must already exist, and Xthe initial access position is set to the end of the file. X.PP X\fIAccess\fR defaults to \fBr\fR. XIf a file is opened for both reading and writing, then \fBseek\fR Xmust be invoked between a read and a write, or vice versa (this Xrestriction does not apply to command pipelines opened with \fBopen\fR). XWhen \fIfileName\fR specifies a command pipeline and a write-only access Xis used, then standard output from the pipeline is directed to the Xcurrent standard output unless overridden by the command. XWhen \fIfileName\fR specifies a command pipeline and a read-only access Xis used, then standard input from the pipeline is taken from the Xcurrent standard input unless overridden by the command. X.RE 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\fBputs \fIfileId string \fR?\fBnonewline\fR? X.VS XWrites the characters given by \fIstring\fR to the file given Xby \fIfileId\fR. X\fBPuts\fR normally outputs a newline character after \fIstring\fR, Xbut this feature may be suppressed by specifying the \fBnonewline\fR Xargument. XOutput to files is buffered internally by Tcl; the \fBflush\fR Xcommand may be used to force buffered characters to be output. 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 refer to one of the standard I/O Xchannels; it must refer to a file that was opened for Xwriting. X.TP X\fBpwd\fR X.br XReturns the path name of the current working directory. X.TP X\fBread \fIfileId\fR X.TP X\fBread \fIfileId \fBnonewline\fR X.TP X\fBread \fIfileId numBytes\fR XIn the first form, all of the remaining bytes are read from the file Xgiven by \fIfileId\fR; they are returned as the result of the command. XIf \fBnonewline\fR is specified as an additional argument, then the last Xcharacter of the file is discarded if it is a newline. XIn the third form, the extra argument specifies how many bytes to read; Xexactly this many bytes will be read and returned, unless there are fewer than X\fInumBytes\fR bytes left in the file; in this case, all the remaining Xbytes are returned. X\fIFileId\fR must be \fBstdin\fR or the return Xvalue from a previous call to \fBopen\fR; it must Xrefer to a file that was opened for reading. X.TP X\fBregexp \fR?\fB\-indices\fR? \fR?\fB\-nocase\fR? \fIexp string \fR?\fImatchVar\fR? ?\fIsubMatchVar subMatchVar ...\fR? XDetermines whether the regular expression \fIexp\fR matches part or Xall of \fIstring\fR and returns 1 if it does, 0 if it doesn't. XSee REGULAR EXPRESSIONS above for complete information on the Xsyntax of \fIexp\fR and how it is matched against \fIstring\fR. X.RS X.LP XIf the \fB\-nocase\fR switch is specified then upper-case Xcharacters in \fIstring\fR Xare treated as lower case during the matching process. XThe \fB\-nocase\fR switch must be specified before \fIexp\fR and Xmay not be abbreviated. X.LP XIf additional arguments are specified after \fIstring\fR then they Xare treated as the names of variables to use to return Xinformation about which part(s) of \fIstring\fR matched \fIexp\fR. X\fIMatchVar\fR will be set to the range of \fIstring\fR that Xmatched all of \fIexp\fR. The first \fIsubMatchVar\fR will contain Xthe characters in \fIstring\fR that matched the leftmost parenthesized Xsubexpression within \fIexp\fR, the next \fIsubMatchVar\fR will Xcontain the characters that matched the next parenthesized Xsubexpression to the right in \fIexp\fR, and so on. X.LP XNormally, \fImatchVar\fR and the \fIsubMatchVar\fRs are set to hold Xthe matching characters from \fBstring\fR. XHowever, if the \fB\-indices\fR switch is specified then each variable Xwill contain a list of two decimal strings giving the indices Xin \fIstring\fR of the first and last characters in the matching Xrange of characters. XThe \fB\-indices\fR switch must be specified before the \fIexp\fR Xargument and may not be abbreviated. X.LP XIf there are more more \fIsubMatchVar\fR's than parenthesized Xsubexpressions within \fIexp\fR, or if a particular subexpression Xin \fIexp\fR doesn't match the string (e.g. because it was in a Xportion of the expression that wasn't matched), then the corresponding X\fIsubMatchVar\fR will be set to ``\fB\-1 \-1\fR'' if \fB\-indices\fR Xhas been specified or to an empty string otherwise. X.RE X.TP X\fBregsub \fR?\fB\-all\fR? ?\fB\-nocase\fR? \fIexp string subSpec varName\fR XThis command matches the regular expression \fIexp\fR against X\fIstring\fR using the rules described in REGULAR EXPRESSIONS Xabove. XIf there is no match, then the command returns 0 and does nothing Xelse. XIf there is a match, then the command returns 1 and also copies X\fIstring\fR to the variable whose name is given by \fIvarName\fR. XWhen copying \fIstring\fR, the portion of \fIstring\fR that Xmatched \fIexp\fR is replaced with \fIsubSpec\fR. XIf \fIsubSpec\fR contains a ``&'' or ``\e0'', then it is replaced Xin the substitution with the portion of \fIstring\fR that Xmatched \fIexp\fR. XIf \fIsubSpec\fR contains a ``\e\fIn\fR'', where \fIn\fR is a digit Xbetween 1 and 9, then it is replaced in the substitution with Xthe portion of \fIstring\fR that matched the \fIn\fR-th Xparenthesized subexpression of \fIexp\fR. XAdditional backslashes may be used in \fIsubSpec\fR to prevent special Xinterpretation of ``&'' or ``\e0'' or ``\e\fIn\fR'' or Xbackslash. XThe use of backslashes in \fIsubSpec\fR tends to interact badly Xwith the Tcl parser's use of backslashes, so it's generally Xsafest to enclose \fIsubSpec\fR in braces if it includes Xbackslashes. XIf the \fB\-all\fR argument is specified, then all ranges in X\fIstring\fR that match \fIexp\fR are found and substitution is Xperformed for each of these ranges; otherwise only the first Xmatching range is found and substituted. XIf \fB\-all\fR is specified, then ``&'' and ``\e\fIn\fR'' Xsequences are handled for each substitution using the information Xfrom the corresponding match. XIf the \fB\-nocase\fR argument is specified, then upper-case Xcharacters in \fIstring\fR are converted to lower-case before Xmatching against \fIexp\fR; however, substitutions specified Xby \fIsubSpec\fR use the original unconverted form of \fIstring\fR. XThe \fB\-all\fR and \fB\-nocase\fR arguments must be specified Xexactly: no abbreviations are permitted. X.VE X.TP X\fBrename \fIoldName newName\fR 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.TP X\fBreturn \fR?\fIvalue\fR? XReturn immediately from the current procedure X(or top-level command or \fBsource\fR command), Xwith \fIvalue\fR as the return value. If \fIvalue\fR is not specified, Xan empty string will be returned as result. X.TP X\fBscan \fIstring format varname1 \fR?\fIvarname2 ...\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. For \fB%c\fR conversions a single character value is Xconverted to a decimal string, which is then assigned to the Xcorresponding \fIvarname\fR; X.VS Xno field width may be specified for this conversion. X.TP X\fBseek \fIfileId offset \fR?\fIorigin\fR? XChange the current access position for \fIfileId\fR. XThe \fIoffset\fR and \fIorigin\fR arguments specify the position at Xwhich the next read or write will occur for \fIfileId\fR. X\fIOffset\fR must be a number (which may be negative) and \fIorigin\fR Xmust be one of the following: X.RS X.TP X\fBstart\fR XThe new access position will be \fIorigin\fR bytes from the start Xof the file. X.TP X\fBcurrent\fR XThe new access position will be \fIorigin\fR bytes from the current Xaccess position; a negative \fIorigin\fR moves the access position Xbackwards in the file. X.TP X\fBend\fR XThe new access position will be \fIorigin\fR bytes from the end of Xthe file. A negative \fIorigin\fR places the access position before Xthe end-of-file, and a positive \fIorigin\fR places the access position Xafter the end-of-file. X.LP XThe \fIorigin\fR argument defaults to \fBstart\fR. 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. XThis command returns an empty string. X.RE X.VE X.TP X\fBset \fIvarname \fR?\fIvalue\fR? XReturns the value of variable \fIvarname\fR. XIf \fIvalue\fR is specified, then set Xthe value of \fIvarname\fR to \fIvalue\fR, creating a new variable Xif one doesn't already exist, and return its value. X.VS XIf \fIvarName\fR contains an open parenthesis and ends with a Xclose parenthesis, then it refers to an array element: the characters Xbefore the open parenthesis are the name of the array, and the characters Xbetween the parentheses are the index within the array. XOtherwise \fIvarName\fR refers to a scalar variable. X.VE XIf no procedure is active, then \fIvarname\fR refers to a global Xvariable. XIf a procedure is active, then \fIvarname\fR refers to a parameter Xor local variable of the procedure, unless the \fIglobal\fR command Xhas been invoked to declare \fIvarname\fR to be global. 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. 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. XIf \fIfileName\fR starts with a tilde, then it is tilde-substituted Xas described in the \fBTcl_TildeSubst\fR manual entry. X.TP X\fBsplit \fIstring \fR?\fIsplitChars\fR? XReturns a list created by splitting \fIstring\fR at each character Xthat is in the \fIsplitChars\fR argument. XEach element of the result list will consist of the Xcharacters from \fIstring\fR between instances of the Xcharacters in \fIsplitChars\fR. XEmpty list elements will be generated if \fIstring\fR contains Xadjacent characters in \fIsplitChars\fR, or if the first or last Xcharacter of \fIstring\fR is in \fIsplitChars\fR. XIf \fIsplitChars\fR is an empty string then each character of X\fIstring\fR becomes a separate element of the result list. X\fISplitChars\fR defaults to the standard white-space characters. XFor example, X.RS X.DS X\fBsplit "comp.unix.misc" .\fR X.DE Xreturns \fB"comp unix misc"\fR and X.DS X\fBsplit "Hello world" {}\fR X.DE Xreturns \fB"H e l l o { } w o r l d"\fR. X.VE X.RE X.TP X\fBstring \fIoption arg \fR?\fIarg ...?\fR XPerform one of several string operations, depending on \fIoption\fR. XThe legal \fIoption\fRs (which may be abbreviated) are: X.RS X.TP X\fBstring compare \fIstring1 string2\fR XPerform a character-by-character comparison of strings \fIstring1\fR and X\fIstring2\fR in the same way as the C \fBstrcmp\fR procedure. Return X-1, 0, or 1, depending on whether \fIstring1\fR is lexicographically Xless than, equal to, or greater than \fIstring2\fR. X.TP X\fBstring first \fIstring1 string2\fR XSearch \fIstring2\fR for a sequence of characters that exactly match Xthe characters in \fIstring1\fR. If found, return the index of the Xfirst character in the first such match within \fIstring2\fR. If not Xfound, return -1. X.br X.VS X.TP X\fBstring index \fIstring charIndex\fR XReturns the \fIcharIndex\fR'th character of the \fIstring\fR Xargument. A \fIcharIndex\fR of 0 corresponds to the first Xcharacter of the string. XIf \fIcharIndex\fR is less than 0 or greater than Xor equal to the length of the string then an empty string is Xreturned. X.VE X.TP X\fBstring last \fIstring1 string2\fR XSearch \fIstring2\fR for a sequence of characters that exactly match Xthe characters in \fIstring1\fR. If found, return the index of the Xfirst character in the last such match within \fIstring2\fR. If there Xis no match, then return \-1. X.br X.VS X.TP X\fBstring length \fIstring\fR XReturns a decimal string giving the number of characters in \fIstring\fR. X.VE 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.br X.VS X.TP X\fBstring range \fIstring first last\fR XReturns a range of consecutive characters from \fIstring\fR, starting Xwith the character whose index is \fIfirst\fR and ending with the Xcharacter whose index is \fIlast\fR. An index of 0 refers to the Xfirst character of the string. \fILast\fR may be \fBend\fR (or any Xabbreviation of it) to refer to the last character of the string. XIf \fIfirst\fR is less than zero then it is treated as if it were zero, and Xif \fIlast\fR is greater than or equal to the length of the string then Xit is treated as if it were \fBend\fR. If \fIfirst\fR is greater than X\fIlast\fR then an empty string is returned. X.TP X\fBstring tolower \fIstring\fR XReturns a value equal to \fIstring\fR except that all upper case Xletters have been converted to lower case. X.TP X\fBstring toupper \fIstring\fR XReturns a value equal to \fIstring\fR except that all lower case Xletters have been converted to upper case. X.TP X\fBstring trim \fIstring\fR ?\fIchars\fR? XReturns a value equal to \fIstring\fR except that any leading Xor trailing characters from the set given by \fIchars\fR are Xremoved. XIf \fIchars\fR is not specified then white space is removed X(spaces, tabs, newlines, and carriage returns). X.TP X\fBstring trimleft \fIstring\fR ?\fIchars\fR? XReturns a value equal to \fIstring\fR except that any Xleading characters from the set given by \fIchars\fR are Xremoved. XIf \fIchars\fR is not specified then white space is removed X(spaces, tabs, newlines, and carriage returns). X.TP X\fBstring trimright \fIstring\fR ?\fIchars\fR? XReturns a value equal to \fIstring\fR except that any Xtrailing characters from the set given by \fIchars\fR are Xremoved. XIf \fIchars\fR is not specified then white space is removed X(spaces, tabs, newlines, and carriage returns). X.RE X.TP X\fBtell \fIfileId\fR XReturns a decimal string giving the current access position in X\fIfileId\fR. 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\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\fBtrace \fIoption\fR ?\fIarg arg ...\fR? X.VS XCause Tcl commands to be executed whenever certain operations are Xinvoked. At present, only variable tracing is implemented. The Xlegal \fIoption\fR's (which may be abbreviated) are: X.RS X.TP X\fBtrace variable \fIname ops command\fR XArrange for \fIcommand\fR to be executed whenever variable \fIname\fR Xis accessed in one of the ways given by \fIops\fR. \fIName\fR may Xrefer to a normal variable, an element of an array, or to an array Xas a whole (i.e. \fIname\fR may be just the name of an array, with no Xparenthesized index). If \fIname\fR refers to a whole array, then X\fIcommand\fR is invoked whenever any element of the array is Xmanipulated. X.RS X.LP X\fIOps\fR indicates which operations are of interest, and consists of Xone or more of the following letters: X.RS X.TP X\fBr\fR XInvoke \fIcommand\fR whenever the variable is read. X.TP X\fBw\fR XInvoke \fIcommand\fR whenever the variable is written. X.TP X\fBu\fR XInvoke \fIcommand\fR whenever the variable is unset. Variables Xcan be unset explicitly with the \fBunset\fR command, or Ximplicitly when procedures return (all of their local variables Xare unset). Variables are also unset when interpreters are Xdeleted, but traces will not be invoked because there is no Xinterpreter in which to execute them. X.RE X.LP XWhen the trace triggers, three arguments are appended to X\fIcommand\fR so that the actual command is as follows: X.DS C X\fIcommand name1 name2 op\fR X.DE X\fIName1\fR and \fIname2\fR give the name(s) for the variable Xbeing accessed: if the variable is a scalar then \fIname1\fR Xgives the variable's name and \fIname2\fR is an empty string; Xif the variable is an array element then \fIname1\fR gives the Xname of the array and name2 gives the index into the array; Xif an entire array is being deleted and the trace was registered Xon the overall array, rather than a single element, then \fIname1\fR Xgives the array name and \fIname2\fR is an empty string. X\fIOp\fR indicates what operation is being performed on the Xvariable, and is one of \fBr\fR, \fBw\fR, or \fBu\fR as Xdefined above. X.LP X\fICommand\fR executes in the same context as the code that invoked Xthe traced operation: if the variable was accessed as part of a XTcl procedure, then \fIcommand\fR will have access to the same Xlocal variables as code in the procedure. This context may be Xdifferent than the context in which the trace was created. XNote that \fIname1\fR may not necessarily be the same as the name Xused to set the trace on the variable; differences can occur if Xthe access is made through a variable defined with the \fBupvar\fR Xcommand. X.LP XFor read and write traces, \fIcommand\fR can modify Xthe variable to affect the result of the traced operation. XIf \fIcommand\fR modifies the value of a variable during a Xread trace, then the value returned by the traced read operation Xwill be the value of the variable after \fIcommand\fR completes. XFor write traces, \fIcommand\fR is invoked after the variable's Xvalue has been changed; it can write a new value into the variable Xto override the original value specified in the write operation. XThe value returned by the traced write operation will be the Xvalue of the variable when \fIcommand\fR completes. XIf \fIcommand\fR returns an error during a read or write trace, Xthen the traced operation is aborted with an error. XThis mechanism can be used to implement read-only variables, Xfor example. X\fICommand\fR's result is always ignored. X.LP XWhile \fIcommand\fR is executing during a read or write trace, traces Xon the variable are temporarily disabled. XThis means that reads and writes invoked by X\fIcommand\fR will occur directly, without invoking \fIcommand\fR X(or any other traces) again. XIt is illegal to \fBunset\fR a variable while a trace Xis active for it. XIt is also illegal to \fBunset\fR an array if there are Xtraces active for any of the array's elements. X.LP XWhen an unset trace is invoked, the variable has already been Xdeleted: it will appear to be undefined with no traces. XIf an unset occurs because of a procedure return, then the Xtrace will be invoked in the variable context of the procedure Xbeing returned to: the stack frame of the returning procedure Xwill no longer exist. XTraces are not disabled during unset traces, so if an unset trace Xcommand creates a new trace and accesses the variable, the Xtrace will be invoked. X.LP XIf there are multiple traces on a variable they are invoked Xin order of creation, most-recent first. XIf one trace returns an error, then no further traces are Xinvoked for the variable. XIf an array element has a trace set, and there is also a trace Xset on the array as a whole, the trace on the overall array Xis invoked before the one on the element. X.LP XOnce created, the trace remains in effect either until the Xtrace is removed with the \fBtrace vdelete\fR command described Xbelow, until the variable is unset, or until the interpreter Xis deleted. XUnsetting an element of array will remove any traces on that Xelement, but will not remove traces on the overall array. X.LP XThis command returns an empty string. X.RE X.TP X\fBtrace vdelete \fIname ops command\fR XIf there is a trace set on variable \fIname\fR with the Xoperations and command given by \fIops\fR and \fIcommand\fR, Xthen the trace is removed, so that \fIcommand\fR will never Xagain be invoked. XReturns an empty string. X.TP X\fBtrace vinfo \fIname\fR XReturns a list containing one element for each trace Xcurrently set on variable \fIname\fR. XEach element of the list is itself a list containing two Xelements, which are the \fIops\fR and \fIcommand\fR associated Xwith the trace. XIf \fIname\fR doesn't exist or doesn't have any traces set, then Xthe result of the command will be an empty string. X.RE X.TP X\fBunknown \fIcmdName \fR?\fIarg arg ...\fR? XThis command doesn't actually exist as part of Tcl, but Tcl will Xinvoke it if it does exist. XIf the Tcl interpreter encounters a command name for which there Xis not a defined command, then Tcl checks for the existence of Xa command named \fBunknown\fR. XIf there is no such command, then the interpeter returns an Xerror. XIf the \fBunknown\fR command exists, then it is invoked with Xarguments consisting of the fully-substituted name and arguments Xfor the original non-existent command. XThe \fBunknown\fR command typically does things like searching Xthrough library directories for a command procedure with the name X\fIcmdName\fR, or expanding abbreviated command names to full-length, Xor automatically executing unknown commands as UNIX sub-processes. XIn some cases (such as expanding abbreviations) \fBunknown\fR will Xchange the original command slightly and then (re-)execute it. XThe result of the \fBunknown\fR command is used as the result for Xthe original non-existent command. X.TP X\fBunset \fIname \fR?\fIname name ...\fR? XRemove one or more variables. XEach \fIname\fR is a variable name, specified in any of the Xways acceptable to the \fBset\fR command. XIf a \fIname\fR refers to an element of an array, then that Xelement is removed without affecting the rest of the array. XIf a \fIname\fR consists of an array name with no parenthesized Xindex, then the entire array is deleted. XThe \fBunset\fR command returns an empty string as result. XAn error occurs if any of the variables doesn't exist, or if Xany of the variables has an active trace. X.VE X.TP X\fBuplevel \fR?\fIlevel\fR?\fI command \fR?\fIcommand ...\fR? XAll of the \fIcommand\fR arguments are concatenated as if they had Xbeen passed to \fBconcat\fR; the result is then evaluated in the Xvariable context indicated by \fIlevel\fR. \fBUplevel\fR returns Xthe result of that evaluation. If \fIlevel\fR is an integer, then Xit gives a distance (up the procedure calling stack) to move before Xexecuting the command. If \fIlevel\fR consists of \fB#\fR followed by Xa number then the number gives an absolute level number. If \fIlevel\fR Xis omitted then it defaults to \fB1\fR. \fILevel\fR cannot be Xdefaulted if the first \fIcommand\fR argument starts with a digit or \fB#\fR. XFor example, suppose that procedure \fBa\fR was invoked Xfrom top-level, and that it called \fBb\fR, and that \fBb\fR called \fBc\fR. XSuppose that \fBc\fR invokes the \fBuplevel\fR command. If \fIlevel\fR Xis \fB1\fR or \fB#2\fR or omitted, then the command will be executed Xin the variable context of \fBb\fR. If \fIlevel\fR is \fB2\fR or \fB#1\fR Xthen the command will be executed in the variable context of \fBa\fR. XIf \fIlevel\fR is \fB3\fR or \fB#0\fR then the command will be executed Xat top-level (only global variables will be visible). XThe \fBuplevel\fR command causes the invoking procedure to disappear Xfrom the procedure calling stack while the command is being executed. XIn the above example, suppose \fBc\fR invokes the command X.RS X.DS X\fBuplevel 1 {set x 43; d} X.DE Xwhere \fBd\fR is another Tcl procedure. The \fBset\fR command will Xmodify the variable \fBx\fR in \fBb\fR's context, and \fBd\fR will execute Xat level 3, as if called from \fBb\fR. If it in turn executes Xthe command X.DS X\fBuplevel {set x 42} X.DE Xthen the \fBset\fR command will modify the same variable \fBx\fR in \fBb\fR's Xcontext: the procedure \fBc\fR does not appear to be on the call stack Xwhen \fBd\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.RE X.TP X\fBupvar \fR?\fIlevel\fR? \fIotherVar myVar \fR?\fIotherVar myVar \fR...? X.VS XThis command arranges for one or more local variables in the current Xprocedure to refer to variables in an enclosing procedure call or Xto global variables. X\fILevel\fR may have any of the forms permitted for the \fBuplevel\fR Xcommand, and may be omitted if the first letter of the first \fIotherVar\fR Xisn't \fB#\fR or a digit (it defaults to \fB1\fR). XFor each \fIotherVar\fR argument, \fBupvar\fR makes the variable Xby that name in the procedure frame given by \fIlevel\fR (or at Xglobal level, if \fIlevel\fR is \fB#0\fR) accessible Xin the current procedure by the name given in the corresponding X\fImyVar\fR argument. XThe variable named by \fIotherVar\fR need not exist at the time of the Xcall; it will be created the first time \fImyVar\fR is referenced, just like Xan ordinary variable. X\fBUpvar\fR may only be invoked from within procedures. XNeither \fIotherVar\fR or \fImyVar\fR may refer to an element of an Xarray. X\fBUpvar\fR returns an empty string. X.RS X.LP XThe \fBupvar\fR command simplifies the implementation of call-by-name Xprocedure calling and also makes it easier to build new control constructs Xas Tcl procedures. XFor example, consider the following procedure: X.DS X.ta 1c 2c 3c X\fBproc add2 name { X upvar $name x X set x [expr $x+2] X} X.DE X\fBAdd2\fR is invoked with an argument giving the name of a variable, Xand it adds two to the value of that variable. XAlthough \fBadd2\fR could have been implemented using \fBuplevel\fR Xinstead of \fBupvar\fR, \fBupvar\fR makes it simpler for \fBadd2\fR Xto access the variable in the caller's procedure frame. X.VE X.RE X.TP X\fBwhile \fItest body X.VS XThe \fIwhile\fR command evaluates \fItest\fR as an expression X(in the same way that \fBexpr\fR evaluates its argument). XThe value of the expression must be numeric; if it is non-zero Xthen \fIbody\fR is executed by passing it to the Tcl interpreter. XOnce \fIbody\fR has been executed then \fItest\fR is evaluated Xagain, and the process repeats until eventually \fItest\fR Xevaluates to a zero numeric value. \fBContinue\fR Xcommands may be executed inside \fIbody\fR to terminate the current Xiteration of the loop, and \fBbreak\fR Xcommands may be executed inside \fIbody\fR to cause immediate Xtermination of the \fBwhile\fR command. The \fBwhile\fR command Xalways returns an empty string. X.VE X X.SH "BUILT-IN VARIABLES" X.PP XThe following global variables are created and managed automatically Xby the Tcl library. Except where noted below, these variables should Xnormally be treated as read-only by application-specific code and by users. X.TP X\fBenv\fR X.br X.VS XThis variable is maintained by Tcl as an array Xwhose elements are the environment variables for the process. XReading an element will return the value of the corresponding Xenvironment variable. XSetting an element of the array will modify the corresponding Xenvironment variable or create a new one if it doesn't already Xexist. XUnsetting an element of \fBenv\fR will remove the corresponding Xenvironment variable. XChanges to the \fBenv\fR array will affect the environment Xpassed to children by commands like \fBexec\fR. XIf the entire \fBenv\fR array is unset then Tcl will stop Xmonitoring \fBenv\fR accesses and will not update environment Xvariables. X.TP X\fBerrorCode\fR XAfter an error has occurred, this variable will be set to hold Xadditional information about the error in a form that is easy Xto process with programs. X\fBerrorCode\fR consists of a Tcl list with one or more elements. XThe first element of the list identifies a general class of Xerrors, and determines the format of the rest of the list. XThe following formats for \fBerrorCode\fR are used by the XTcl core; individual applications may define additional formats. X.RS X.TP X\fBCHILDKILLED\fI pid sigName msg\fR XThis format is used when a child process has been killed because of Xa signal. The second element of \fBerrorCode\fR will be the Xprocess's identifier (in decimal). XThe third element will be the symbolic name of the signal that caused Xthe process to terminate; it will be one of the names from the Xinclude file signal.h, such as \fBSIGPIPE\fR. XThe fourth element will be a short human-readable message Xdescribing the signal, such as ``write on pipe with no readers'' Xfor \fBSIGPIPE\fR. X.TP X\fBCHILDSTATUS\fI pid code\fR XThis format is used when a child process has exited with a non-zero Xexit status. The second element of \fBerrorCode\fR will be the Xprocess's identifier (in decimal) and the third element will be the exit Xcode returned by the process (also in decimal). X.TP X\fBCHILDSUSP\fI pid code\fR XThis format is used when a child process has been suspended because Xof a signal. XThe second element of \fBerrorCode\fR will be the process's identifier, Xin decimal. XThe third element will be the symbolic name of the signal that caused Xthe process to suspend; this will be one of the names from the Xinclude file signal.h, such as \fBSIGTTIN\fR. XThe fourth element will be a short human-readable message Xdescribing the signal, such as ``background tty read'' Xfor \fBSIGTTIN\fR. X.TP X\fBNONE\fR X.br XThis format is used for errors where no additional information is Xavailable for an error besides the message returned with the Xerror. In these cases \fBerrorCode\fR will consist of a list Xcontaining a single element whose contents are \fBNONE\fR. X.TP X\fBUNIX \fIerrName msg\fR XIf the first element of \fBerrorCode\fR is \fBUNIX\fR, then Xthe error occurred during a UNIX kernel call. XThe second element of the list will contain the symbolic name Xof the error that occurred, such as \fBENOENT\fR; this will Xbe one of the values defined in the include file errno.h. XThe third element of the list will be a human-readable Xmessage corresponding to \fIerrName\fR, such as X``no such file or directory'' for the \fBENOENT\fR case. X.PP XTo set \fBerrorCode\fR, applications should use library Xprocedures such as \fBTcl_SetErrorCode\fR and X\fBTcl_UnixError\fR, or they may invoke the \fBerror\fR command. XIf one of these methods hasn't been used, then the Tcl Xinterpreter will reset the variable to \fBNONE\fR after Xthe next error. X.RE X.VE X.TP X\fBerrorInfo\fR XAfter an error has occurred, this string will contain one or more lines Xidentifying the Tcl commands and procedures that were being executed Xwhen the most recent error occurred. XIts contents take the form of a stack trace showing the various Xnested Tcl commands that had been invoked at the time of the error. X X.SH AUTHOR XJohn Ousterhout, University of California at Berkeley (ouster@sprite.berkeley.edu) X.sp XMany people have contributed to Tcl in various ways, but the following Xpeople have made unusually large contributions: X.sp X.nf XBill Carpenter XPeter Da Silva XMark Diekhans XKarl Lehenbauer XMary Ann May-Pumphrey END_OF_FILE if test 41512 -ne `wc -c <'tcl6.1/doc/Tcl.man.3'`; then echo shar: \"'tcl6.1/doc/Tcl.man.3'\" unpacked with wrong size! fi # end of 'tcl6.1/doc/Tcl.man.3' fi echo shar: End of archive 32 \(of 33\). cp /dev/null ark32isdone 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. 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: kent@sparky.IMD.Sterling.COM Sterling Software, IMD UUCP: uunet!sparky!kent Phone: (402) 291-8300 FAX: (402) 291-4362 Please send comp.sources.misc-related mail to kent@uunet.uu.net.