tcl/doc/while.n

   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$
   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 while {$x<10} {
  49         puts "x is $x"
  50         incr x
  51 }
  52 .CE
  53
  54 .SH KEYWORDS
  55 boolean value, loop, test, while