Usenet 1994 October

home *** CD-ROM | disk | FTP | other *** search

/ Usenet 1994 October / usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso / misc / volume25 / tcl / part27 < prev next >

Wrap

Text File | 1991-11-15 | 37.6 KB | 1,056 lines

Newsgroups: comp.sources.misc From: karl@sugar.neosoft.com (Karl Lehenbauer) Subject: v25i095: tcl - tool command language, version 6.1, Part27/33 Message-ID: <1991Nov15.225555.21767@sparky.imd.sterling.com> X-Md4-Signature: d29e4a97a7aec6cca1efcb2c13436270 Date: Fri, 15 Nov 1991 22:55:55 GMT Approved: kent@sparky.imd.sterling.com Submitted-by: karl@sugar.neosoft.com (Karl Lehenbauer) Posting-number: Volume 25, Issue 95 Archive-name: tcl/part27 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 27 (of 33)." # Contents: tcl6.1/doc/Tcl.man.1 # Wrapped by karl@one on Tue Nov 12 19:44:30 1991 PATH=/bin:/usr/bin:/usr/ucb ; export PATH if test -f 'tcl6.1/doc/Tcl.man.1' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'tcl6.1/doc/Tcl.man.1'\" else echo shar: Extracting \"'tcl6.1/doc/Tcl.man.1'\" $35297 characters$ sed "s/^X//" >'tcl6.1/doc/Tcl.man.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: /user6/ouster/tcl/doc/RCS/Tcl.man,v 1.86 91/10/31 13:35:32 ouster Exp $ SPRITE (Berkeley) X' X.\" The definitions below are for supplemental macros used in Sprite X.\" manual entries. X.\" X.\" .HS name section [date [version]] X.\" Replacement for .TH in other man pages. See below for valid X.\" section names. 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.\" .DS X.\" Begin an indented unfilled display. X.\" X.\" .DE X.\" End of indented unfilled display. X.\" X' # Heading for Sprite man pages X.de HS X.if '\\$2'cmds' .TH \\$1 1 \\$3 \\$4 X.if '\\$2'lib' .TH \\$1 3 \\$3 \\$4 X.if '\\$2'tcl' .TH \\$1 3 \\$3 \\$4 X.if '\\$2'tk' .TH \\$1 3 \\$3 \\$4 X.if t .wh -1.3i ^B X.nr ^l \\n(.l X.ad b 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.. 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' # ^y = starting y location X' # ^b = 1 X.de BS X.br X.mk ^y X.nr ^b 1u X.if n .nf X.if n .ti 0 X.if n \l'\\n(.lu\(ul' X.if n .fi X.. X' # BE - end boxed text (draw box now) X.de BE X.nf X.ti 0 X.mk ^t X.ie n \l'\\n(^lu\(ul' X.el \{\ X.\" Draw four-sided box normally, but don't draw top of X.\" box if the box started on an earlier page. X.ie !\\n(^b-1 \{\ X\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' X.\} X.el \}\ X\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' X.\} X.\} X.fi X.br X.nr ^b 0 X.. X' # VS - start vertical sidebar X' # ^Y = starting y location X' # ^v = 1 (for troff; for nroff this doesn't matter) X.de VS X.mk ^Y X.ie n 'mc \s12\(br\s0 X.el .nr ^v 1u X.. X' # VE - end of vertical sidebar X.de VE X.ie n 'mc X.el \{\ X.ev 2 X.nf X.ti 0 X.mk ^t X\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' X.sp -1 X.fi X.ev X.\} X.nr ^v 0 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.ev 2 X'ti 0 X'nf X.mk ^t X.if \\n(^b \{\ X.\" Draw three-sided box if this is the box's first page, X.\" draw two sides but no top otherwise. X.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c X.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c X.\} X.if \\n(^v \{\ X.nr ^x \\n(^tu+1v-\\n(^Yu X\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c X.\} X.bp X'fi X.ev X.if \\n(^b \{\ X.mk ^y X.nr ^b 2 X.\} X.if \\n(^v \{\ X.mk ^Y X.\} X.. X' # DS - begin display X.de DS X.RS X.nf X.sp X.. X' # DE - end display X.de DE X.fi X.RE X.sp .5 X.. X.de UL X\\$1\l'|0\(ul'\\$2 X.. 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 can be used as X.VS Xa common language for communicating between applications. XInter-application communication is not built into the Tcl core Xdescribed here, but various add-on libraries, such as the Tk toolkit, Xallow applications to issue commands to each other. XThis makes it possible for applications to work together in much Xmore powerful ways than was previously possible. X.VE X.PP XThis manual page focuses 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 X.VS XCommand names should normally be typed completely (e.g. no abbreviations). XHowever, if the Tcl interpreter cannot locate a command it invokes a Xspecial command named \fBunknown\fR which attempts to find or create Xthe command. XFor example, at many sites \fBunknown\fR will search Xthrough library directories for the desired command and create it Xas a Tcl procedure if it is found. XThe \fBunknown\fR command often provides automatic completion of Xabbreviated commands, but usually only for commands that were typed Xinteractively. XIt's probably a bad idea to use abbreviations in command scripts Xand other forms that will be re-used over time: changes Xto the command set may cause abbreviations to become ambiguous, Xresulting in scripts that no longer work. X.VE 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. When comments are embedded inside nested Xcommands (e.g. fields enclosed in braces) they must have properly-matched Xbraces (this is necessary because when Tcl parses the top-level command Xit doesn't yet know that the nested field will be used as a command so Xit cannot process the nested comment character as a comment). X X.SH "GROUPING ARGUMENTS WITH DOUBLE-QUOTES" X.PP XNormally each argument field ends at the next white space, but Xdouble-quotes may be used to create arguments with embedded Xspace. If an argument Xfield begins with a double-quote, then the argument isn't Xterminated by white space (including newlines) or a semi-colon X(see below for information on semi-colons); instead it ends at the next Xdouble-quote character. The double-quotes are not included Xin the resulting argument. 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. Within double-quotes, command Xsubstitutions, variable substitutions, and backslash substitutions Xstill occur, as described below. If the first character of a Xcommand field is not a quote, then quotes receive no special Xinterpretation in the parsing of that field. X X.SH "GROUPING ARGUMENTS WITH BRACES" X.PP XCurly braces may also be used for grouping arguments. They are Xsimilar to quotes except for two differences. First, they nest; Xthis makes them easier to use for complicated arguments like nested Tcl Xcommand strings. Second, the substitutions described below for Xcommands, variables, and backslashes do \fInot\fR occur in arguments Xenclosed in braces, so braces can be used to prevent substitutions Xwhere they are undesirable. XIf an argument field Xbegins with a left brace, then the argument ends at the matching Xright brace. Tcl will strip off the outermost layer of braces Xand pass the information between the braces to the command without Xany further modification. For example, 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 or quotes are in effect, the matching brace Xor quote 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 brace or quote. 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 XIf the first character of a command field is not 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 a field of a command, then Xcommand substitution occurs (except for fields enclosed in Xbraces). 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 X.VS XA bracketed command may contain multiple commands separated by Xnewlines or semi-colons in the usual fashion. XIn this case the value of the last command is used for substitution. XFor example, the command X.DS X\fBset a x[set b 22 Xexpr $b+2]x\fR X.DE Xis equivalent to the command X.DS X\fBset a x24x\fR X.DE X.VE 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 variable values. XIf \fB$\fR appears in an argument that isn'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. X.VS XFor 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 X.PP XThere are two special forms for variable substitution. XIf the next character after the name of the variable is an Xopen parenthesis, then the variable is assumed to be an array Xname, and all of the characters between the open parenthesis Xand the next close parenthesis are taken as an index into the array. XCommand substitutions and variable substitutions are Xperformed on the information between the parentheses before it is Xused as an index. XFor example, if the variable \fBx\fR is an array with one element Xnamed \fBfirst\fR and value \fB87\fR and another element named X\fB14\fR and value \fBmore\fR, then the command X.DS C X\fBset a xyz$x(first)zyx X.DE Xis equivalent to the command X.DS C X\fBset a xyz87zyx\fR X.DE XIf the variable \fBindex\fR has the value \fB14\fR, then the command X.DS C X\fBset a xyz$x($index)zyx X.DE Xis equivalent to the command X.DS C X\fBset a xyzmorezyx X.DE XFor more information on arrays, see VARIABLES AND ARRAYS below. X.PP XThe second special form for variables occurs when Xthe dollar sign is followed by an open curly brace. XIn this case the variable name consists of all the characters Xup to the next curly brace. XArray references are not possible in this form: the name Xbetween braces is assumed to refer to a scalar variable. XFor example, if variable \fBfoo\fR has the value \fBtest\fR, Xthen 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 X.VE 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.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. Semi-colons are Xnot treated as command separators if they appear within curly braces Xor double-quotes. 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 (0x8). X.TP 20 X\fB\ef\fR XForm feed (0xc). X.TP 20 X\fB\en\fR XNewline (0xa). X.TP 20 X\fB\er\fR XCarriage-return (0xd). X.TP 20 X\fB\et\fR XTab (0x9). X.TP 20 X\fB\ev\fR XVertical tab (0xb). 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$\fR XDollar sign (``$''). X.TP 20 X\fB\e<space>\fR XSpace (`` ''): doesn't terminate argument. X.br 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 joins two lines together Xinto a single line. This backslash feature is unique in that Xit will be applied even when the sequence occurs within braces. X.TP 20 X\fB\e\e\fR XBackslash (``\e''). 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. Null characters may not be embedded in command fields; Xif \fIddd\fR is zero then the backslash sequence is ignored (i.e. it Xmaps to an empty string). 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 (except for Xbackslash-newline): 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 is probably 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] XDouble-quotes allow white space and semi-colons to appear within Xa single argument. XCommand substitution, variable substitution, and backslash substitution Xstill occur inside quotes. X.IP [6] 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 Xexcept that backslash-newline sequences are eliminated. X.IP [7] XIf a field doesn't begin with a brace 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 any 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.VS 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 one or more of their arguments as expressions Xand call the Tcl expression processors (\fBTcl_ExprLong\fR, X\fBTcl_ExprBoolean\fR, etc.) to evaluate them. XThe operators permitted in Tcl expressions are a subset of Xthe operators permitted in C expressions, and they have the Xsame meaning and precedence as the corresponding C operators. XExpressions almost always yield numeric results X(integer or floating-point values). XFor example, the expression X.DS X\fB8.2 + 6\fR X.DE Xevaluates to 14.2. XTcl expressions differ from C expressions in the way that Xoperands are specified, and in that Tcl expressions support Xnon-numeric operands and string comparisons. X.PP XA Tcl expression consists of a combination of operands, operators, Xand parentheses. XWhite space may be used between the operands and operators and Xparentheses; it is ignored by the expression processor. XWhere possible, operands are interpreted as integer values. XInteger values may be specified in decimal (the normal case), in octal (if the Xfirst character of the operand is \fB0\fR), or in hexadecimal (if the first Xtwo characters of the operand are \fB0x\fR). XIf an operand does not have one of the integer formats given Xabove, then it is treated as a floating-point number if that is Xpossible. Floating-point numbers may be specified in any of the Xways accepted by an ANSI-compliant C compiler (except that the X``f'', ``F'', ``l'', and ``L'' suffixes will not be permitted in Xmost installations). For example, all of the Xfollowing are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16. XIf no numeric interpretation is possible, then an operand is left Xas a string (and only a limited set of operators may be applied to Xit). X.PP XOperators may be specified in any of the following ways: X.IP [1] XAs an numeric value, either integer or floating-point. X.IP [2] XAs a Tcl variable, using standard \fB$\fR notation. XThe variable's value will be used as the operand. X.IP [3] XAs a string enclosed in double-quotes. XThe expression parser will perform backslash, variable, and Xcommand substitutions on the information between the quotes, Xand use the resulting value as the operand X.IP [4] XAs a string enclosed in braces. XThe characters between the open brace and matching close brace Xwill be used as the operand without any substitutions. X.IP [5] XAs a Tcl command enclosed in brackets. XThe command will be executed and its result will be used as Xthe operand. X.IP [6] XAn unquoted string consisting of any number of letters, digits, Xand underscores (but a digit may not be the first character). X.LP XWhere substitutions occur above (e.g. inside quoted strings), they Xare performed by the expression processor. XHowever, an additional layer of substitution may already have Xbeen performed by the command parser before the expression Xprocessor was called. XAs discussed below, it is usually best to enclose expressions Xin braces to prevent the command parser from performing substitutions Xon the contents. X.PP XFor some examples of simple expressions, suppose the variable X\fBa\fR has the value 3 and Xthe variable \fBb\fR has the value 6. XThen the expression on the left side of each of the lines below Xwill evaluate to the value on the right side of the line: X.DS X.ta 6c X\fB3.1 + $a 6.1 X2 + "$a.$b" 5.6 X4*[length "6 2"] 8 X{word one} < "word $a" 0\fR X.DE X.PP XThe valid operators are listed below, grouped in decreasing order Xof precedence: X.TP 20 X\fB\-\0\0~\0\0!\fR XUnary minus, bit-wise NOT, logical NOT. None of these operands Xmay be applied to string operands, and bit-wise NOT may be Xapplied only to integers. X.TP 20 X\fB*\0\0/\0\0%\fR XMultiply, divide, remainder. None of these operands may be Xapplied to string operands, and remainder may be applied only Xto integers. X.TP 20 X\fB+\0\0\-\fR XAdd and subtract. Valid for any numeric operands. X.TP 20 X\fB<<\0\0>>\fR XLeft and right shift. Valid for integer operands only. 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. XThese operators may be applied to strings as well as numeric operands, Xin which case string comparison is used. X.TP 20 X\fB==\0\0!=\fR XBoolean equal and not equal. Each operator produces a zero/one result. XValid for all operand types. X.TP 20 X\fB&\fR XBit-wise AND. Valid for integer operands only. X.TP 20 X\fB^\fR XBit-wise exclusive OR. Valid for integer operands only. X.TP 20 X\fB|\fR XBit-wise OR. Valid for integer operands only. X.TP 20 X\fB&&\fR XLogical AND. Produces a 1 result if both operands are non-zero, 0 otherwise. XValid for numeric operands only (integers or floating-point). X.TP 20 X\fB||\fR XLogical OR. Produces a 0 result if both operands are zero, 1 otherwise. XValid for numeric operands only (integers or floating-point). X.TP 20 X\fIx\fB?\fIy\fB:\fIz\fR XIf-then-else, as in C. If \fIx\fR Xevaluates to non-zero, then the result is the value of \fIy\fR. XOtherwise the result is the value of \fIz\fR. XThe \fIx\fR operand must have a numeric value. X.LP 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\fB4*2 < 7\fR X.DE Xevaluates to 0. X.PP XThe \fB&&\fP, \fB||\fP, and \fB?:\fP operators have ``lazy Xevaluation'', just as in C, Xwhich means that operands are not evaluated if they are Xnot needed to determine the outcome. For example, in X.DS X\fB$v ? [a] : [b]\fR X.DE Xonly one of \fB[a]\fR or \fB[b]\fR will actually be evaluated, Xdepending on the value of \fB$v\fP. X.PP XAll internal computations involving integers are done with the C type X\fIlong\fP, and all internal computations involving floating-point are Xdone with the C type \fIdouble\fP. XWhen converting a string to floating-point, exponent overflow is Xdetected and results in a Tcl error. XFor conversion to integer from string, detection of overflow depends Xon the behavior of some routines in the local C library, so it should Xbe regarded as unreliable. XIn any case, overflow and underflow are generally not detected Xreliably for intermediate results. X.PP XConversion among internal representations for integer, floating-point, Xand string operands is done automatically as needed. XFor arithmetic computations, integers are used until some Xfloating-point number is introduced, after which floating-point is used. XFor example, X.DS X\fB5 / 4\fR X.DE Xyields the result 1, while X.DS X\fB5 / 4.0\fR X\fB5 / ( [length "abcd" chars] + 0.0 ) X.DE Xboth yield the result 1.25. X.PP XString values may be used as operands of the comparison operators, Xalthough the expression evaluator tries to do comparisons as integer Xor floating-point when it can. XIf one of the operands of a comparison is a string and the other Xhas a numeric value, the numeric operand is converted back to Xa string using the C \fIsprintf\fP format specifier X\fB%d\fR for integers and \fB%g\fR for floating-point values. XFor example, the expressions X.DS X\fB"0x03" > "2"\fR X\fB"0y" < "0x12"\fR X.DE Xboth evaluate to 1. The first comparison is done using integer Xcomparison, and the second is done using string comparison after Xthe second operand is converted to the string ``18''. X.VE 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.ta 7c X\fBfor {set i 1} $i<=10 {incr i} {...}\fR *** WRONG *** 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. Instead, the expression should be placed in braces: X.DS C X.ta 7c X\fBfor {set i 1} {$i<=10} {incr i} {...}\fR *** RIGHT *** X.DE XThis causes the substitution of \fBi\fR's Xvalue to be delayed; it will be re-done each time the expression is Xevaluated, which is 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 and quotes 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 braces and quotes and Xbackslashes 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 and Xvariable substitution are 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, X.VS X\fBlappend\fR, \fBlindex\fR, \fBlinsert\fR, \fBlist\fR, \fBllength\fR, X\fBlrange\fR, \fBlreplace\fR, \fBlsearch\fR, and \fBlsort\fR allow Xyou to build lists, X.VE Xextract elements from them, search them, and perform other list-related Xfunctions. X X.SH "REGULAR EXPRESSIONS" X.VS X.PP XTcl provides two commands that support string matching using X\fBegrep\fR-style regular expressions: \fBregexp\fR and \fBregsub\fR. XRegular expressions are implemented using Henry Spencer's package, Xand the description of regular expressions below is copied verbatim Xfrom his manual entry. X.PP XA regular expression is zero or more \fIbranches\fR, separated by ``|''. XIt matches anything that matches one of the branches. X.PP XA branch is zero or more \fIpieces\fR, concatenated. XIt matches a match for the first, followed by a match for the second, etc. X.PP XA piece is an \fIatom\fR possibly followed by ``*'', ``+'', or ``?''. XAn atom followed by ``*'' matches a sequence of 0 or more matches of the atom. XAn atom followed by ``+'' matches a sequence of 1 or more matches of the atom. XAn atom followed by ``?'' matches a match of the atom, or the null string. X.PP XAn atom is a regular expression in parentheses (matching a match for the Xregular expression), a \fIrange\fR (see below), ``.'' X(matching any single character), ``^'' (matching the null string at the Xbeginning of the input string), ``$'' (matching the null string at the Xend of the input string), a ``\e'' followed by a single character (matching Xthat character), or a single character with no other significance X(matching that character). X.PP XA \fIrange\fR is a sequence of characters enclosed in ``[]''. XIt normally matches any single character from the sequence. XIf the sequence begins with ``^'', Xit matches any single character \fInot\fR from the rest of the sequence. XIf two characters in the sequence are separated by ``\-'', this is shorthand Xfor the full list of ASCII characters between them X(e.g. ``[0-9]'' matches any decimal digit). XTo include a literal ``]'' in the sequence, make it the first character X(following a possible ``^''). XTo include a literal ``\-'', make it the first or last character. END_OF_FILE if test 35297 -ne `wc -c <'tcl6.1/doc/Tcl.man.1'`; then echo shar: \"'tcl6.1/doc/Tcl.man.1'\" unpacked with wrong size! fi # end of 'tcl6.1/doc/Tcl.man.1' fi echo shar: End of archive 27 $of 33$. cp /dev/null ark27isdone 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.