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