cmredbg: add a tool to help debug RunCMake output matching

Finding small errors in `RunCMake` outputs against the output is a
tedious task. Add a small tool that sets up a simple `tmux` window setup
to help debug them.

Tests/RunCMake/README.rst

@@ -274,3 +274,11 @@ script that will automatically perform steps 1 through 4 for you::
   cmake -DRunCMake_TEST_SUITE=<test suite name> -P Tests/RunCMake/AddRunCMakeTestSuite.cmake
 
 Be sure to run this from the top-level CMake source directory.
+
+Crafting Expected Output
+========================
+
+There is a `regex debugging`_ tool available to help craft regular expressions
+to verify output from tests. See its documentation for more.
+
+.. _`regex debugging`: ../../Utilities/cmredbg/README.rst

Utilities/cmredbg/.gitignore

@@ -0,0 +1,2 @@
+re.txt
+content.txt

Utilities/cmredbg/README.rst

@@ -0,0 +1,21 @@
+Regular expression debugging tool
+=================================
+
+A tool to help diagnose issues with ``RunCMake`` regular expressions by
+offering an editor with live results matching the haystack (``content.txt``)
+against the needle (``re.txt``).
+
+This utility makes a few assumptions, but further improvement for other
+workflows is welcome. One assumption is that it is run from this directory
+(i.e., ``./run.sh``).
+
+Requirements
+------------
+
+The tool currently assumes it is running inside of a ``tmux`` session and
+offers a split which prints the results of matching the regular expression
+against the content.
+
+The ``EDITOR`` environment variable is used to detect the preferred editor,
+defaulting to ``nano``. If the editor is detected as a Vi-alike (i.e., has
+``vi`` in its name), both files are automatically opened in separate windows.

Utilities/cmredbg/match.cmake

@@ -0,0 +1,21 @@
+cmake_minimum_required(VERSION 3.10)
+
+if (NOT EXISTS "re.txt")
+  message(FATAL_ERROR
+    "Place your regular expression in `re.txt`.")
+endif ()
+if (NOT EXISTS "content.txt")
+  message(FATAL_ERROR
+    "Place your content in `content.txt`.")
+endif ()
+
+file(READ "re.txt" needle)
+string(REGEX REPLACE "\n+$" "" needle "${needle}")
+file(READ "content.txt" haystack)
+string(REGEX REPLACE "\n+$" "" haystack "${haystack}")
+
+if (haystack MATCHES "${needle}")
+  message("Matches!")
+else ()
+  message("NO match!")
+endif ()

Utilities/cmredbg/run.sh

@@ -0,0 +1,28 @@
+#!/bin/sh
+
+set -e
+
+die () {
+    echo >&2 "$@"
+    exit 1
+}
+
+test -x "$( which tmux 2>/dev/null )" || die "\`tmux\` is required"
+test -n "$TMUX" || die "must be running within a \`tmux\` session"
+test -x "$( which watch )" || die "\`watch\` is required"
+
+editor="${EDITOR:-nano}"
+readonly editor
+
+test -x "$( which "$EDITOR" )" || die "\`$editor\` is required"
+
+tmux split-window -v -l 10 -c "$PWD" 'watch --interval 1 cmake -P match.cmake'
+tmux select-pane -l
+case "$editor" in
+    *vi*)
+        "$editor" re.txt content.txt -c 'vsp|bn'
+        ;;
+    *)
+        "$editor" re.txt content.txt
+        ;;
+esac