1 | '\" |
---|
2 | '\" Copyright (c) 1993 The Regents of the University of California. |
---|
3 | '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. |
---|
4 | '\" |
---|
5 | '\" See the file "license.terms" for information on usage and redistribution |
---|
6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
7 | '\" |
---|
8 | '\" RCS: @(#) $Id: while.n,v 1.5 2004/10/27 14:43:54 dkf Exp $ |
---|
9 | '\" |
---|
10 | .so man.macros |
---|
11 | .TH while n "" Tcl "Tcl Built-In Commands" |
---|
12 | .BS |
---|
13 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
14 | .SH NAME |
---|
15 | while \- Execute script repeatedly as long as a condition is met |
---|
16 | .SH SYNOPSIS |
---|
17 | \fBwhile \fItest body\fR |
---|
18 | .BE |
---|
19 | |
---|
20 | .SH DESCRIPTION |
---|
21 | .PP |
---|
22 | The \fBwhile\fR command evaluates \fItest\fR as an expression |
---|
23 | (in the same way that \fBexpr\fR evaluates its argument). |
---|
24 | The value of the expression must a proper boolean |
---|
25 | value; if it is a true value |
---|
26 | then \fIbody\fR is executed by passing it to the Tcl interpreter. |
---|
27 | Once \fIbody\fR has been executed then \fItest\fR is evaluated |
---|
28 | again, and the process repeats until eventually \fItest\fR |
---|
29 | evaluates to a false boolean value. \fBContinue\fR |
---|
30 | commands may be executed inside \fIbody\fR to terminate the current |
---|
31 | iteration of the loop, and \fBbreak\fR |
---|
32 | commands may be executed inside \fIbody\fR to cause immediate |
---|
33 | termination of the \fBwhile\fR command. The \fBwhile\fR command |
---|
34 | always returns an empty string. |
---|
35 | .PP |
---|
36 | Note: \fItest\fR should almost always be enclosed in braces. If not, |
---|
37 | variable substitutions will be made before the \fBwhile\fR |
---|
38 | command starts executing, which means that variable changes |
---|
39 | made by the loop body will not be considered in the expression. |
---|
40 | This is likely to result in an infinite loop. If \fItest\fR is |
---|
41 | enclosed in braces, variable substitutions are delayed until the |
---|
42 | expression is evaluated (before |
---|
43 | each loop iteration), so changes in the variables will be visible. |
---|
44 | For an example, try the following script with and without the braces |
---|
45 | around \fB$x<10\fR: |
---|
46 | .CS |
---|
47 | set x 0 |
---|
48 | \fBwhile\fR {$x<10} { |
---|
49 | puts "x is $x" |
---|
50 | incr x |
---|
51 | } |
---|
52 | .CE |
---|
53 | .SH EXAMPLE |
---|
54 | Read lines from a channel until we get to the end of the stream, and |
---|
55 | print them out with a line-number prepended: |
---|
56 | .CS |
---|
57 | set lineCount 0 |
---|
58 | \fBwhile\fR {[gets $chan line] >= 0} { |
---|
59 | puts "[incr lineCount]: $line" |
---|
60 | } |
---|
61 | .CE |
---|
62 | |
---|
63 | .SH "SEE ALSO" |
---|
64 | break(n), continue(n), for(n), foreach(n) |
---|
65 | |
---|
66 | .SH KEYWORDS |
---|
67 | boolean value, loop, test, while |
---|