NAME
       foreach - Iterate over all elements in one or more lists

SYNOPSIS
       foreach varname list body
       foreach varlist1 list1 ?varlist2 list2 ...? body


DESCRIPTION
       The  foreach  command  implements  a  loop  where the loop
       variable(s) take on values from one or more lists.  In the
       simplest case there is one loop variable, varname, and one
       list, list, that is a list of values to assign to varname.
       The  body  argument  is a Tcl script.  For each element of
       list (in order from first to last),  foreach  assigns  the
       contents  of  the  element  to  varname  as  if the lindex
       command had been used to extract the element,  then  calls
       the Tcl interpreter to execute body.

       In  the general case there can be more than one value list
       (e.g., list1 and  list2),  and  each  value  list  can  be
       associated  with  a list of loop variables (e.g., varlist1
       and varlist2).  During each  iteration  of  the  loop  the
       variables  of each varlist are assigned consecutive values
       from the corresponding list.  Values in each list are used
       in  order  from  first  to  last,  and  each value is used
       exactly once.  The total  number  of  loop  iterations  is
       large  enough  to use up all the values from all the value
       lists.  If a value list does not contain  enough  elements
       for  each  of  its loop variables in each iteration, empty
       values are used for the missing elements.

       The break and continue statements may  be  invoked  inside
       body, with the same effect as in the for command.  Foreach
       returns an empty string.

EXAMPLES
       The following loop uses i  and  j  as  loop  variables  to
       iterate over pairs of elements of a single list.

              set x {}
              foreach {i j} {a b c d e f} {
                  lappend x $j $i
              }
              # The value of x is "b a d c f e"
              # There are 3 iterations of the loop.


       The  next  loop  uses i and j to iterate over two lists in
       parallel.

              set x {}
              foreach i {a b c} j {d e f g} {
                  lappend x $i $j
              }
              # The value of x is "a d b e c f {} g"
              # There are 4 iterations of the loop.


       The two forms are combined in the following example.

              set x {}
              foreach i {a b c} {j k} {d e f g} {
                  lappend x $i $j $k
              }
              # The value of x is "a d e b f g c {} {}"
              # There are 3 iterations of the loop.


KEYWORDS
