FOREACH

implements a foreach iteration loop within a macro

<ITEM>  Result label to hold item
<FUNC>  Function type [INDF,INFILE,INLIST,INSIZE,INTABLE,INTF]
<IN>    Variable containing input values

A FOREACH-ENDFOR combination is used in a macro to loop through each
value in a set defined by either a List, Table, or File.

Each pass through the loop, the result <ITEM> will contain the next
member of the set.

Modifiers may be added to the end of the <FUNC> name to modify behavior.
For example, INTABLE/V for key values instead of key names.

There are no restrictions nesting FOREACH loops.

Since 2.5.0 the generic IN function has been added that can iterate over
a large number of Java objects, including:
  o java.util.Map          (includes Table, Hashtable, HashMap, ...)
  o java.util.Collection   (includes List, Vector, LinkedList, ...)
  o java.util.Iterator     (any implementation of the Iterator interface)
  o java.util.Enumeration  (any implementation of the Enumeration interface)
  o java.lang.Object[]     (any generic Java array)
  o nxm.sys.lib.Data       (the values in a Data object via Data.toVector())

Notes:
  o Using IN for a Map iterates over the keys in the Map, using IN/V
    iterates over the values in the Map.
  o The IN function only supports /REV when using an Object[].


FUNCTIONS:
  INDF      - Each element in a Midas data file
  INFILE    - Alias for INDF
  INLIST    - Each element in a comma separated list
  INSIZE    - Iterate for IN=<size>
  INTABLE   - Each key in a table or KeyVector
  INTABLE/V - Each value in a table or KeyVector
  INTF      - Each line in a text file
  INKW      - Each keyword in a Midas file with scope
  IN        - Each item in a Java object (see above)
  IN/V      - Each value in a Java Map object (see above)


EXAMPLES:
  1. Erase all files whose names are in a given data file
        foreach name INDF mydatafile
          erase name
        endfor

  2. Iterate through each item in a LIST
        foreach area INLIST "MYOPT,SP,GEO,SYS"
          configure c ^area
        endfor

  3. Iterate through each element in a FILE (0 to SIZE-1)
        foreach offset INSIZE FILE(fftdemo).size
          say "Data at ^offset is ^{FILE(fftdemo).data(offset)}"
        endfor

  4. Iterate through each KEY in a table
        foreach key INTABLE msg.data
          say "Key ^key = ^msg.data.^key"
        endfor

  5. Iterate through each KEY in a KeyVector. Produces values for layName of
     GRID, WORLD and CITIES
        plot/bg world|cities
        foreach layName INTABLE reg.PLOT.layers
          say "Layer name = ^layName"
        endfor

  6. Iterate through each VALUE (KEY=VALUE) in a table
        foreach val INTABLE/V msg.data
          say "Value = ^val"
        endfor

  7. Iterate through each line in a TEXT file
        foreach line INTF mytextfile
          say "Next Line is: ^line"
        endfor

  8. Iterate through each keyword in a Data file
        foreach kwi INKW env.hwfile /scope=tag=alias
          say "Next Key: ^kwi.name  Value: ^kwi.value"
        endfor

  9. Iterates over a Java Vector
        new java.util.Vector vect
        ...
        foreach val IN vect
          say "val = ^{val}"
        endfor


Switches:
  /REV   - process elements in reverse order (not implemented)
  /SCOPE - For INKW only.  Sets the SCOPE. See KEYWORD command.
  /SORT  - process elements in sorted order (applies only to Tables)
  /VAL   - Same as INTABLE/V or IN/V

SEE ALSO:  ENDFOR, BREAK, KEYWORD