foreach: Introduce `IN ZIP_LISTS` mode

2 files changed, 33 insertions, 0 deletions

diff --git a/Help/command/foreach.rst b/Help/command/foreach.rst
index ecbfed3..dbd2fac 100644
--- a/Help/command/foreach.rst
+++ b/Help/command/foreach.rst
@@ -82,3 +82,31 @@ yields
   -- X=6
   -- X=7
   -- X=8
+
+
+.. code-block:: cmake
+
+  foreach(<loop_var> IN ZIP_LISTS <lists>)
+
+In this variant, ``<lists>`` is a whitespace or semicolon
+separated list of list-valued variables. The ``foreach``
+command iterates over each list simultaneously and set the
+``loop_var_N`` variables to the current item from the
+corresponding list. If some list is shorter than others,
+the corresponding iteration variable is not defined.
+
+.. code-block:: cmake
+
+  list(APPEND English one two three four)
+  list(APPEND Bahasa satu dua tiga)
+  foreach(X IN ZIP_LISTS English Bahasa)
+      message(STATUS "X_0=${X_0}, X_1=${X_1}")
+  endforeach()
+
+yields
+::
+
+  -- X_0=one, X_1=satu
+  -- X_0=two, X_1=dua
+  -- X_0=three, X_1=tiga
+  -- X_0=four, X_1=
diff --git a/Help/release/dev/foreach-ZIP_LISTS.rst b/Help/release/dev/foreach-ZIP_LISTS.rst
new file mode 100644
index 0000000..d45d9b9
--- /dev/null
+++ b/Help/release/dev/foreach-ZIP_LISTS.rst
@@ -0,0 +1,5 @@
+foreach-ZIP_LISTS
+-----------------
+
+* The :command:`foreach` learned a new option ``ZIP_LISTS`` to iterate
+  over multiple lists simultaneously.