Merge topic 'foreach-ZIP_LISTS'

d30468a2f6 foreach: Allow multiple iteration variables for `ZIP_LIST` mode
f3e51a2b1d foreach: Introduce `IN ZIP_LISTS` mode

Acked-by: Kitware Robot <[email protected]>
Merge-request: !4021

Help/command/foreach.rst

@@ -82,3 +82,46 @@ 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 setting the
+iteration variables as follows:
+
+- if the only ``loop_var`` given, then it sets a series of
+  ``loop_var_N`` variables to the current item from the
+  corresponding list;
+- if multiple variable names passed, their count should match
+  the lists variables count;
+- if any of the lists are shorter, the corresponding iteration
+  variable is not defined for the current iteration.
+
+.. code-block:: cmake
+
+  list(APPEND English one two three four)
+  list(APPEND Bahasa satu dua tiga)
+
+  foreach(num IN ZIP_LISTS English Bahasa)
+      message(STATUS "num_0=${num_0}, num_1=${num_1}")
+  endforeach()
+
+  foreach(en ba IN ZIP_LISTS English Bahasa)
+      message(STATUS "en=${en}, ba=${ba}")
+  endforeach()
+
+yields
+::
+
+  -- num_0=one, num_1=satu
+  -- num_0=two, num_1=dua
+  -- num_0=three, num_1=tiga
+  -- num_0=four, num_1=
+  -- en=one, ba=satu
+  -- en=two, ba=dua
+  -- en=three, ba=tiga
+  -- en=four, ba=

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.

Source/cmForEachCommand.cxx

@@ -3,12 +3,15 @@
 #include "cmForEachCommand.h"
 
 #include <algorithm>
+#include <cassert>
 #include <cstddef>
 // NOTE The declaration of `std::abs` has moved to `cmath` since C++17
 // See https://en.cppreference.com/w/cpp/numeric/math/abs
 // ALERT But IWYU used to lint `#include`s do not "understand"
 // conditional compilation (i.e. `#if __cplusplus >= 201703L`)
 #include <cstdlib>
+#include <iterator>
+#include <map>
 #include <utility>
 
 #include <cm/memory>
@@ -29,7 +32,7 @@ namespace {
 class cmForEachFunctionBlocker : public cmFunctionBlocker
 {
 public:
-  cmForEachFunctionBlocker(cmMakefile* mf);
+  explicit cmForEachFunctionBlocker(cmMakefile* mf);
   ~cmForEachFunctionBlocker() override;
 
   cm::string_view StartCommandName() const override { return "foreach"_s; }
@@ -41,10 +44,33 @@ public:
   bool Replay(std::vector<cmListFileFunction> functions,
               cmExecutionStatus& inStatus) override;
 
+  void SetIterationVarsCount(const std::size_t varsCount)
+  {
+    this->IterationVarsCount = varsCount;
+  }
+  void SetZipLists() { this->ZipLists = true; }
+
   std::vector<std::string> Args;
 
 private:
+  struct InvokeResult
+  {
+    bool Restore;
+    bool Break;
+  };
+
+  bool ReplayItems(std::vector<cmListFileFunction> const& functions,
+                   cmExecutionStatus& inStatus);
+
+  bool ReplayZipLists(std::vector<cmListFileFunction> const& functions,
+                      cmExecutionStatus& inStatus);
+
+  InvokeResult invoke(std::vector<cmListFileFunction> const& functions,
+                      cmExecutionStatus& inStatus, cmMakefile& mf);
+
   cmMakefile* Makefile;
+  std::size_t IterationVarsCount = 0u;
+  bool ZipLists = false;
 };
 
 cmForEachFunctionBlocker::cmForEachFunctionBlocker(cmMakefile* mf)
@@ -70,70 +96,240 @@ bool cmForEachFunctionBlocker::ArgumentsMatch(cmListFileFunction const& lff,
 bool cmForEachFunctionBlocker::Replay(
   std::vector<cmListFileFunction> functions, cmExecutionStatus& inStatus)
 {
-  cmMakefile& mf = inStatus.GetMakefile();
-  // at end of for each execute recorded commands
+  return this->ZipLists ? this->ReplayZipLists(functions, inStatus)
+                        : this->ReplayItems(functions, inStatus);
+}
+
+bool cmForEachFunctionBlocker::ReplayItems(
+  std::vector<cmListFileFunction> const& functions,
+  cmExecutionStatus& inStatus)
+{
+  assert("Unexpected number of iteration variables" &&
+         this->IterationVarsCount == 1);
+
+  auto& mf = inStatus.GetMakefile();
+
+  // At end of for each execute recorded commands
   // store the old value
   std::string oldDef;
   if (mf.GetDefinition(this->Args.front())) {
     oldDef = mf.GetDefinition(this->Args.front());
   }
 
+  auto restore = false;
   for (std::string const& arg : cmMakeRange(this->Args).advance(1)) {
-    // set the variable to the loop value
+    // Set the variable to the loop value
     mf.AddDefinition(this->Args.front(), arg);
     // Invoke all the functions that were collected in the block.
-    for (cmListFileFunction const& func : functions) {
-      cmExecutionStatus status(mf);
-      mf.ExecuteCommand(func, status);
-      if (status.GetReturnInvoked()) {
-        inStatus.SetReturnInvoked();
-        // restore the variable to its prior value
-        mf.AddDefinition(this->Args.front(), oldDef);
-        return true;
-      }
-      if (status.GetBreakInvoked()) {
-        // restore the variable to its prior value
-        mf.AddDefinition(this->Args.front(), oldDef);
-        return true;
-      }
-      if (status.GetContinueInvoked()) {
-        break;
-      }
-      if (cmSystemTools::GetFatalErrorOccured()) {
-        return true;
+    auto r = this->invoke(functions, inStatus, mf);
+    restore = r.Restore;
+    if (r.Break) {
+      break;
+    }
+  }
+
+  if (restore) {
+    // restore the variable to its prior value
+    mf.AddDefinition(this->Args.front(), oldDef);
+  }
+  return true;
+}
+
+bool cmForEachFunctionBlocker::ReplayZipLists(
+  std::vector<cmListFileFunction> const& functions,
+  cmExecutionStatus& inStatus)
+{
+  assert("Unexpected number of iteration variables" &&
+         this->IterationVarsCount >= 1);
+
+  auto& mf = inStatus.GetMakefile();
+
+  // Expand the list of list-variables into a list of lists of strings
+  std::vector<std::vector<std::string>> values;
+  values.reserve(this->Args.size() - this->IterationVarsCount);
+  // Also track the longest list size
+  std::size_t maxItems = 0u;
+  for (auto const& var :
+       cmMakeRange(this->Args).advance(this->IterationVarsCount)) {
+    std::vector<std::string> items;
+    auto const& value = mf.GetSafeDefinition(var);
+    if (!value.empty()) {
+      cmExpandList(value, items, true);
+    }
+    maxItems = std::max(maxItems, items.size());
+    values.emplace_back(std::move(items));
+  }
+
+  // Form the list of iteration variables
+  std::vector<std::string> iterationVars;
+  if (this->IterationVarsCount > 1) {
+    // If multiple iteration variables has given,
+    // just copy them to the `iterationVars` list.
+    iterationVars.reserve(values.size());
+    std::copy(this->Args.begin(),
+              this->Args.begin() + this->IterationVarsCount,
+              std::back_inserter(iterationVars));
+  } else {
+    // In case of the only iteration variable,
+    // generate names as `var_name_N`,
+    // where `N` is the count of lists to zip
+    iterationVars.resize(values.size());
+    const auto iter_var_prefix = this->Args.front() + "_";
+    auto i = 0u;
+    std::generate(
+      iterationVars.begin(), iterationVars.end(),
+      [&]() -> std::string { return iter_var_prefix + std::to_string(i++); });
+  }
+  assert("Sanity check" && iterationVars.size() == values.size());
+
+  // Store old values for iteration variables
+  std::map<std::string, std::string> oldDefs;
+  for (auto i = 0u; i < values.size(); ++i) {
+    if (mf.GetDefinition(iterationVars[i])) {
+      oldDefs.emplace(iterationVars[i], mf.GetDefinition(iterationVars[i]));
+    }
+  }
+
+  // Form a vector of current positions in all lists (Ok, vectors) of values
+  std::vector<decltype(values)::value_type::iterator> positions;
+  positions.reserve(values.size());
+  std::transform(
+    values.begin(), values.end(), std::back_inserter(positions),
+    // Set the initial position to the beginning of every list
+    [](decltype(values)::value_type& list) { return list.begin(); });
+  assert("Sanity check" && positions.size() == values.size());
+
+  auto restore = false;
+  // Iterate over all the lists simulateneously
+  for (auto i = 0u; i < maxItems; ++i) {
+    // Declare iteration variables
+    for (auto j = 0u; j < values.size(); ++j) {
+      // Define (or not) the iteration variable if the current position
+      // still not at the end...
+      if (positions[j] != values[j].end()) {
+        mf.AddDefinition(iterationVars[j], *positions[j]);
+        ++positions[j];
+      } else {
+        mf.RemoveDefinition(iterationVars[j]);
       }
     }
+    // Invoke all the functions that were collected in the block.
+    auto r = this->invoke(functions, inStatus, mf);
+    restore = r.Restore;
+    if (r.Break) {
+      break;
+    }
   }
 
-  // restore the variable to its prior value
-  mf.AddDefinition(this->Args.front(), oldDef);
+  // Restore the variables to its prior value
+  if (restore) {
+    for (auto const& p : oldDefs) {
+      mf.AddDefinition(p.first, p.second);
+    }
+  }
   return true;
 }
 
-bool HandleInMode(std::vector<std::string> const& args, cmMakefile& makefile)
+auto cmForEachFunctionBlocker::invoke(
+  std::vector<cmListFileFunction> const& functions,
+  cmExecutionStatus& inStatus, cmMakefile& mf) -> InvokeResult
+{
+  InvokeResult result = { true, false };
+  // Invoke all the functions that were collected in the block.
+  for (cmListFileFunction const& func : functions) {
+    cmExecutionStatus status(mf);
+    mf.ExecuteCommand(func, status);
+    if (status.GetReturnInvoked()) {
+      inStatus.SetReturnInvoked();
+      result.Break = true;
+      break;
+    }
+    if (status.GetBreakInvoked()) {
+      result.Break = true;
+      break;
+    }
+    if (status.GetContinueInvoked()) {
+      break;
+    }
+    if (cmSystemTools::GetFatalErrorOccured()) {
+      result.Restore = false;
+      result.Break = true;
+      break;
+    }
+  }
+  return result;
+}
+
+bool HandleInMode(std::vector<std::string> const& args,
+                  std::vector<std::string>::const_iterator kwInIter,
+                  cmMakefile& makefile)
 {
+  assert("A valid iterator expected" && kwInIter != args.end());
+
   auto fb = cm::make_unique<cmForEachFunctionBlocker>(&makefile);
-  fb->Args.push_back(args.front());
+
+  // Copy iteration variable names first
+  std::copy(args.begin(), kwInIter, std::back_inserter(fb->Args));
+  // Remember the count of given iteration variable names
+  const auto varsCount = fb->Args.size();
+  fb->SetIterationVarsCount(varsCount);
 
   enum Doing
   {
     DoingNone,
     DoingLists,
-    DoingItems
+    DoingItems,
+    DoingZipLists
   };
   Doing doing = DoingNone;
-  for (std::string const& arg : cmMakeRange(args).advance(2)) {
+  // Iterate over arguments past the "IN" keyword
+  for (std::string const& arg : cmMakeRange(++kwInIter, args.end())) {
     if (arg == "LISTS") {
+      if (doing == DoingZipLists) {
+        makefile.IssueMessage(MessageType::FATAL_ERROR,
+                              "ZIP_LISTS can not be used with LISTS or ITEMS");
+        return true;
+      }
+      if (varsCount != 1u) {
+        makefile.IssueMessage(
+          MessageType::FATAL_ERROR,
+          "ITEMS or LISTS require exactly one iteration variable");
+        return true;
+      }
       doing = DoingLists;
+
     } else if (arg == "ITEMS") {
+      if (doing == DoingZipLists) {
+        makefile.IssueMessage(MessageType::FATAL_ERROR,
+                              "ZIP_LISTS can not be used with LISTS or ITEMS");
+        return true;
+      }
+      if (varsCount != 1u) {
+        makefile.IssueMessage(
+          MessageType::FATAL_ERROR,
+          "ITEMS or LISTS require exactly one iteration variable");
+        return true;
+      }
       doing = DoingItems;
+
+    } else if (arg == "ZIP_LISTS") {
+      if (doing != DoingNone) {
+        makefile.IssueMessage(MessageType::FATAL_ERROR,
+                              "ZIP_LISTS can not be used with LISTS or ITEMS");
+        return true;
+      }
+      doing = DoingZipLists;
+      fb->SetZipLists();
+
     } else if (doing == DoingLists) {
       auto const& value = makefile.GetSafeDefinition(arg);
       if (!value.empty()) {
         cmExpandList(value, fb->Args, true);
       }
-    } else if (doing == DoingItems) {
+
+    } else if (doing == DoingItems || doing == DoingZipLists) {
       fb->Args.push_back(arg);
+
     } else {
       makefile.IssueMessage(MessageType::FATAL_ERROR,
                             cmStrCat("Unknown argument:\n", "  ", arg, "\n"));
@@ -141,6 +337,18 @@ bool HandleInMode(std::vector<std::string> const& args, cmMakefile& makefile)
     }
   }
 
+  // If `ZIP_LISTS` given and variables count more than 1,
+  // make sure the given lists count matches variables...
+  if (doing == DoingZipLists && varsCount > 1u &&
+      (2u * varsCount) != fb->Args.size()) {
+    makefile.IssueMessage(
+      MessageType::FATAL_ERROR,
+      cmStrCat("Expected ", std::to_string(varsCount),
+               " list variables, but given ",
+               std::to_string(fb->Args.size() - varsCount)));
+    return true;
+  }
+
   makefile.AddFunctionBlocker(std::move(fb));
 
   return true;
@@ -155,8 +363,9 @@ bool cmForEachCommand(std::vector<std::string> const& args,
     status.SetError("called with incorrect number of arguments");
     return false;
   }
-  if (args.size() > 1 && args[1] == "IN") {
-    return HandleInMode(args, status.GetMakefile());
+  auto kwInIter = std::find(args.begin(), args.end(), "IN");
+  if (kwInIter != args.end()) {
+    return HandleInMode(args, kwInIter, status.GetMakefile());
   }
 
   // create a function blocker
@@ -216,6 +425,8 @@ bool cmForEachCommand(std::vector<std::string> const& args,
   } else {
     fb->Args = args;
   }
+
+  fb->SetIterationVarsCount(1u);
   status.GetMakefile().AddFunctionBlocker(std::move(fb));
 
   return true;

Tests/RunCMake/foreach/RunCMakeTest.cmake

@@ -2,3 +2,13 @@ include(RunCMake)
 
 run_cmake(BadRangeInFunction)
 run_cmake(foreach-all-test)
+run_cmake(foreach-ITEMS-multiple-iter-vars-test)
+run_cmake(foreach-LISTS-multiple-iter-vars-test)
+run_cmake(foreach-ZIP_LISTS-test)
+run_cmake(foreach-ITEMS-with-ZIP_LISTS-mix-test)
+run_cmake(foreach-LISTS-with-ZIP_LISTS-mix-test)
+run_cmake(foreach-ZIP_LISTS-with-ITEMS-mix-test)
+run_cmake(foreach-ZIP_LISTS-with-LISTS-mix-test)
+run_cmake(foreach-ZIP_LISTS-multiple-iter-vars-test)
+run_cmake(foreach-ZIP_LISTS-iter-vars-mismatch-test-1)
+run_cmake(foreach-ZIP_LISTS-iter-vars-mismatch-test-2)

Tests/RunCMake/foreach/foreach-ITEMS-multiple-iter-vars-test-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/foreach/foreach-ITEMS-multiple-iter-vars-test-stderr.txt

@@ -0,0 +1,4 @@
+^CMake Error at foreach-ITEMS-multiple-iter-vars-test.cmake:1 \(foreach\):
+  ITEMS or LISTS require exactly one iteration variable
+Call Stack \(most recent call first\):
+  CMakeLists.txt:3 \(include\)

Tests/RunCMake/foreach/foreach-ITEMS-multiple-iter-vars-test.cmake

@@ -0,0 +1,2 @@
+foreach(one two IN ITEMS one two)
+endforeach()

Tests/RunCMake/foreach/foreach-ITEMS-with-ZIP_LISTS-mix-test-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/foreach/foreach-ITEMS-with-ZIP_LISTS-mix-test-stderr.txt

@@ -0,0 +1,4 @@
+^CMake Error at foreach-ITEMS-with-ZIP_LISTS-mix-test.cmake:1 \(foreach\):
+  ZIP_LISTS can not be used with LISTS or ITEMS
+Call Stack \(most recent call first\):
+  CMakeLists.txt:3 \(include\)

Tests/RunCMake/foreach/foreach-ITEMS-with-ZIP_LISTS-mix-test.cmake

@@ -0,0 +1,2 @@
+foreach(i IN ITEMS one two three ZIP_LISTS blah)
+endforeach()

Tests/RunCMake/foreach/foreach-LISTS-multiple-iter-vars-test-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/foreach/foreach-LISTS-multiple-iter-vars-test-stderr.txt

@@ -0,0 +1,4 @@
+^CMake Error at foreach-LISTS-multiple-iter-vars-test.cmake:1 \(foreach\):
+  ITEMS or LISTS require exactly one iteration variable
+Call Stack \(most recent call first\):
+  CMakeLists.txt:3 \(include\)

Tests/RunCMake/foreach/foreach-LISTS-multiple-iter-vars-test.cmake

@@ -0,0 +1,2 @@
+foreach(one two IN LISTS one two)
+endforeach()

Tests/RunCMake/foreach/foreach-LISTS-with-ZIP_LISTS-mix-test-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/foreach/foreach-LISTS-with-ZIP_LISTS-mix-test-stderr.txt

@@ -0,0 +1,4 @@
+^CMake Error at foreach-LISTS-with-ZIP_LISTS-mix-test.cmake:1 \(foreach\):
+  ZIP_LISTS can not be used with LISTS or ITEMS
+Call Stack \(most recent call first\):
+  CMakeLists.txt:3 \(include\)

Tests/RunCMake/foreach/foreach-LISTS-with-ZIP_LISTS-mix-test.cmake

@@ -0,0 +1,2 @@
+foreach(i IN LISTS one two three ZIP_LISTS blah)
+endforeach()

Tests/RunCMake/foreach/foreach-ZIP_LISTS-iter-vars-mismatch-test-1-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/foreach/foreach-ZIP_LISTS-iter-vars-mismatch-test-1-stderr.txt

@@ -0,0 +1,4 @@
+^CMake Error at foreach-ZIP_LISTS-iter-vars-mismatch-test-1.cmake:1 \(foreach\):
+  Expected 3 list variables, but given 4
+Call Stack \(most recent call first\):
+  CMakeLists.txt:3 \(include\)

Tests/RunCMake/foreach/foreach-ZIP_LISTS-iter-vars-mismatch-test-1.cmake

@@ -0,0 +1,2 @@
+foreach(less than lists IN ZIP_LISTS list_1 list_2 list_3 list_4)
+endforeach()

Tests/RunCMake/foreach/foreach-ZIP_LISTS-iter-vars-mismatch-test-2-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/foreach/foreach-ZIP_LISTS-iter-vars-mismatch-test-2-stderr.txt

@@ -0,0 +1,4 @@
+^CMake Error at foreach-ZIP_LISTS-iter-vars-mismatch-test-2.cmake:1 \(foreach\):
+  Expected 3 list variables, but given 2
+Call Stack \(most recent call first\):
+  CMakeLists.txt:3 \(include\)

Tests/RunCMake/foreach/foreach-ZIP_LISTS-iter-vars-mismatch-test-2.cmake

@@ -0,0 +1,2 @@
+foreach(greater than lists IN ZIP_LISTS list_1 list_2)
+endforeach()

Tests/RunCMake/foreach/foreach-ZIP_LISTS-multiple-iter-vars-test-stdout.txt

@@ -0,0 +1,6 @@
+-- foreach\(\.\.\. IN ZIP_LISTS\):
+--   Begin output
+--   | one, satu, raz
+--   | two, dua, dva
+--   | three, tiga, tri
+--   End output

Tests/RunCMake/foreach/foreach-ZIP_LISTS-multiple-iter-vars-test.cmake

@@ -0,0 +1,42 @@
+function(foreachTest result list_var_1 list_var_2 list_var_3)
+    set(_options MUTE)
+    set(_one_value_args)
+    set(_multi_value_args)
+    cmake_parse_arguments(PARSE_ARGV 3 _arg "${_options}" "${_one_value_args}" "${_multi_value_args}")
+
+    set(_has_any_output FALSE)
+    list(APPEND CMAKE_MESSAGE_INDENT "| ")
+    foreach(first second third IN ZIP_LISTS ${list_var_1} ${list_var_2} ${list_var_3})
+        if(NOT first)
+            set(first "[undefiend]")
+        endif()
+        if(NOT second)
+            set(second "[undefiend]")
+        endif()
+        if(NOT third)
+            set(third "[undefiend]")
+        endif()
+        if(NOT _arg_MUTE)
+            message(STATUS "${first}, ${second}, ${third}")
+        endif()
+        set(_has_any_output TRUE)
+    endforeach()
+    set(${result} ${_has_any_output} PARENT_SCOPE)
+endfunction()
+
+function(foreachTestDecorated list_var_1 list_var_2 list_var_3)
+    list(APPEND CMAKE_MESSAGE_INDENT "  ")
+    message(STATUS "Begin output")
+    foreachTest(_has_any_output ${list_var_1} ${list_var_2} ${list_var_3})
+    if(NOT _has_any_output)
+        message(STATUS "--> empty-output <--")
+    endif()
+    message(STATUS "End output")
+endfunction()
+
+list(APPEND english one two three)
+list(APPEND bahasa satu dua tiga)
+list(APPEND russian raz dva tri)
+
+message(STATUS "foreach(... IN ZIP_LISTS):")
+foreachTestDecorated(english bahasa russian)

Tests/RunCMake/foreach/foreach-ZIP_LISTS-test-stdout.txt

@@ -0,0 +1,19 @@
+-- foreach\(IN ZIP_LISTS\):
+--   <<< empty lists case >>>
+--     Begin output
+--     --> empty-output <--
+--     End output
+--   <<< same lengths lists case >>>
+--     Begin output
+--     | one, satu, raz
+--     | two, dua, dva
+--     | three, tiga, tri
+--     End output
+--   <<< different lengths lists case >>>
+--     Begin output
+--     | one, satu, raz
+--     | two, dua, dva
+--     | three, tiga, tri
+--     | \[undefiend\], empat, \[undefiend\]
+--     End output
+--   <<< test variable value restored -- PASSED >>>

Tests/RunCMake/foreach/foreach-ZIP_LISTS-test.cmake

@@ -0,0 +1,68 @@
+function(foreachTest result list_var_1 list_var_2 list_var_3)
+    set(_options MUTE)
+    set(_one_value_args)
+    set(_multi_value_args)
+    cmake_parse_arguments(PARSE_ARGV 3 _arg "${_options}" "${_one_value_args}" "${_multi_value_args}")
+
+    set(_has_any_output FALSE)
+    list(APPEND CMAKE_MESSAGE_INDENT "| ")
+    foreach(num IN ZIP_LISTS ${list_var_1} ${list_var_2} ${list_var_3})
+        foreach(i RANGE 2)
+            if(NOT num_${i})
+                set(num_${i} "[undefiend]")
+            endif()
+        endforeach()
+        if(NOT _arg_MUTE)
+            message(STATUS "${num_0}, ${num_1}, ${num_2}")
+        endif()
+        set(_has_any_output TRUE)
+    endforeach()
+    set(${result} ${_has_any_output} PARENT_SCOPE)
+endfunction()
+
+function(foreachTestDecorated list_var_1 list_var_2 list_var_3)
+    list(APPEND CMAKE_MESSAGE_INDENT "  ")
+    message(STATUS "Begin output")
+    foreachTest(_has_any_output ${list_var_1} ${list_var_2} ${list_var_3})
+    if(NOT _has_any_output)
+        message(STATUS "--> empty-output <--")
+    endif()
+    message(STATUS "End output")
+endfunction()
+
+message(STATUS "foreach(IN ZIP_LISTS):")
+list(APPEND CMAKE_MESSAGE_INDENT "  ")
+
+set(english)
+set(bahasa)
+set(russian)
+
+message(STATUS "<<< empty lists case >>>")
+foreachTestDecorated(english bahasa russian)
+
+list(APPEND english one two three)
+list(APPEND bahasa satu dua tiga)
+list(APPEND russian raz dva tri)
+
+message(STATUS "<<< same lengths lists case >>>")
+foreachTestDecorated(english bahasa russian)
+
+list(APPEND bahasa empat)
+
+message(STATUS "<<< different lengths lists case >>>")
+foreachTestDecorated(english bahasa russian)
+
+set(num_0 "old-0")
+set(num_1 "old-1")
+set(num_2 "old-2")
+foreachTest(_ english bahasa russian MUTE)
+set(check PASSED)
+foreach(i RANGE 2)
+    if(NOT "${num_${i}}" STREQUAL "old-${i}")
+        message(SEND_ERROR "num_${i} value is corrupted")
+        set(check FAILED)
+    endif()
+endforeach()
+message(STATUS "<<< test variable value restored -- ${check} >>>")
+
+list(POP_BACK CMAKE_MESSAGE_INDENT)

Tests/RunCMake/foreach/foreach-ZIP_LISTS-with-ITEMS-mix-test-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/foreach/foreach-ZIP_LISTS-with-ITEMS-mix-test-stderr.txt

@@ -0,0 +1,4 @@
+^CMake Error at foreach-ZIP_LISTS-with-ITEMS-mix-test.cmake:1 \(foreach\):
+  ZIP_LISTS can not be used with LISTS or ITEMS
+Call Stack \(most recent call first\):
+  CMakeLists.txt:3 \(include\)

Tests/RunCMake/foreach/foreach-ZIP_LISTS-with-ITEMS-mix-test.cmake

@@ -0,0 +1,2 @@
+foreach(i IN ZIP_LISTS blah ITEMS blah)
+endforeach()

Tests/RunCMake/foreach/foreach-ZIP_LISTS-with-LISTS-mix-test-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/foreach/foreach-ZIP_LISTS-with-LISTS-mix-test-stderr.txt

@@ -0,0 +1,4 @@
+^CMake Error at foreach-ZIP_LISTS-with-LISTS-mix-test.cmake:1 \(foreach\):
+  ZIP_LISTS can not be used with LISTS or ITEMS
+Call Stack \(most recent call first\):
+  CMakeLists.txt:3 \(include\)

Tests/RunCMake/foreach/foreach-ZIP_LISTS-with-LISTS-mix-test.cmake

@@ -0,0 +1,2 @@
+foreach(i IN ZIP_LISTS blah LISTS blah)
+endforeach()