Add function unittest_string_var_regex() (TriBITSPub#483)

I also updated the documentation some for unittest_string_regex().

I do not run the new function unittest_string_var_regex() in this commit but
will in a later commit where I manually tested as part of work for TriBITSPub#483 to
ensure it passes and fails when it should.

tribits/core/utils/UnitTestHelpers.cmake

@@ -240,12 +240,13 @@ endfunction()
 
 # @FUNCTION: unittest_string_regex()
 #
-# Perform a series regexes of given strings and update overall test statistics.
+# Perform a series of regexes on a given string and update overall test
+# statistics.
 #
 # Usage::
 #
 #   unittest_string_regex(
-#     <inputString>
+#     "<inputString>"
 #     REGEX_STRINGS "<str0>" "<str1>" ...
 #     )
 #
@@ -279,12 +280,65 @@ function(unittest_string_regex INPUT_STRING)
 
     string(REGEX MATCH "${REGEX}" REGEX_MATCH_RESULT "${INPUT_STRING}")
 
+    message("  Searching string:")
+    message("     '${INPUT_STRING}'")
+    if (REGEX_MATCH_RESULT)
+      message("  for REGEX {${REGEX}}: [PASSED]\n")
+      math( EXPR NUMPASSED ${UNITTEST_OVERALL_NUMPASSED}+1 )
+      global_set(UNITTEST_OVERALL_NUMPASSED ${NUMPASSED})
+    else()
+      message("  for REGEX {${REGEX}}: [FAILED]\n")
+      global_set(UNITTEST_OVERALL_PASS FALSE)
+      message(WARNING "Stack trace for failed unit test")
+    endif()
+
+  endforeach()
+
+endfunction()
+
+
+# @FUNCTION: unittest_string_var_regex()
+#
+# Perform a series of regexes on a given string variable and update overall
+# test statistics.
+#
+# Usage::
+#
+#   unittest_string_var_regex(
+#     <inputStringVar>
+#     REGEX_STRINGS "<str0>" "<str1>" ...
+#     )
+#
+# If the ``"${<inputStringVar>}"`` matches all of the of the regexs
+# ``"<str0>"``, ``"<str1>"``, ..., then the test passes.  Otherwise it fails.
+#
+# This updates the global variables ``UNITTEST_OVERALL_NUMRUN``,
+# ``UNITTEST_OVERALL_NUMPASSED``, and ``UNITTEST_OVERALL_PASS`` which are used
+# by the unit test harness system to assess overall pass/fail.
+#
+function(unittest_string_var_regex  inputStringVar)
+
+  cmake_parse_arguments(PARSE_ARGV 1
+     PARSE "" "" # prefix, options, one_value_keywords
+     "REGEX_STRINGS" #multi_value_keywords
+     )
+  tribits_check_for_unparsed_arguments(PARSE)
+
+  foreach(REGEX ${PARSE_REGEX_STRINGS})
+
+    math( EXPR NUMRUN ${UNITTEST_OVERALL_NUMRUN}+1 )
+    global_set(UNITTEST_OVERALL_NUMRUN ${NUMRUN})
+
+    string(REGEX MATCH "${REGEX}" REGEX_MATCH_RESULT "${${inputStringVar}}")
+
+    message("Searching string variable value '${inputStringVar}':")
+    message("     '${${inputStringVar}}'")
     if (REGEX_MATCH_RESULT)
-      message("  Searching for REGEX {${REGEX}}:  [PASSED]\n")
+      message("  for REGEX {${REGEX}}: [PASSED]\n")
       math( EXPR NUMPASSED ${UNITTEST_OVERALL_NUMPASSED}+1 )
       global_set(UNITTEST_OVERALL_NUMPASSED ${NUMPASSED})
     else()
-      message("  Searching for REGEX {${REGEX}}:  [FAILED]\n")
+      message("  for REGEX {${REGEX}}: [FAILED]\n")
       global_set(UNITTEST_OVERALL_PASS FALSE)
       message(WARNING "Stack trace for failed unit test")
     endif()

tribits/doc/guides/UtilsMacroFunctionDocTemplate.rst

@@ -44,5 +44,6 @@
 @FUNCTION: unittest_has_substr_const() +
 @FUNCTION: unittest_not_has_substr_const() +
 @FUNCTION: unittest_string_regex() +
+@FUNCTION: unittest_string_var_regex() +
 @FUNCTION: unittest_file_regex() +
 @FUNCTION: unittest_final_result() +