ENH: New foreach(<var> IN ...) mode

This creates a new mode of the foreach command which allows precise
iteration even over empty elements.  This mode may be safely extended
with more keyword arguments in the future.  The cost now is possibly
breaking scripts that iterate over a list of items beginning with 'IN',
but there is no other way to extend the syntax in a readable way.

1 files changed, 14 insertions, 3 deletions

diff --git a/Source/cmForEachCommand.h b/Source/cmForEachCommand.h
index 3e0371119f..ea7faa592e 100644
--- a/Source/cmForEachCommand.h
+++ b/Source/cmForEachCommand.h
@@ -94,14 +94,14 @@ public:
       "    COMMAND2(ARGS ...)\n"
       "    ...\n"
       "  endforeach(loop_var)\n"
-      "  foreach(loop_var RANGE total)\n"
-      "  foreach(loop_var RANGE start stop [step])\n"
       "All commands between foreach and the matching endforeach are recorded "
       "without being invoked.  Once the endforeach is evaluated, the "
       "recorded list of commands is invoked once for each argument listed "
       "in the original foreach command.  Before each iteration of the loop "
       "\"${loop_var}\" will be set as a variable with "
       "the current value in the list.\n"
+      "  foreach(loop_var RANGE total)\n"
+      "  foreach(loop_var RANGE start stop [step])\n"
       "Foreach can also iterate over a generated range of numbers. "
       "There are three types of this iteration:\n"
       "* When specifying single number, the range will have elements "
@@ -109,10 +109,21 @@ public:
       "* When specifying two numbers, the range will have elements from "
       "the first number to the second number.\n"
       "* The third optional number is the increment used to iterate from "
-      "the first number to the second number.";
+      "the first number to the second number."
+      "\n"
+      "  foreach(loop_var IN [LISTS [list1 [...]]]\n"
+      "                      [ITEMS [item1 [...]]])\n"
+      "Iterates over a precise list of items.  "
+      "The LISTS option names list-valued variables to be traversed, "
+      "including empty elements (an empty string is a zero-length list).  "
+      "The ITEMS option ends argument parsing and includes all arguments "
+      "following it in the iteration."
+      ;
     }
   
   cmTypeMacro(cmForEachCommand, cmCommand);
+private:
+  bool HandleInMode(std::vector<std::string> const& args);
 };