From fa1349267a28ebbda4b190fdac750c45384898d3 Mon Sep 17 00:00:00 2001
From: Ben Boeckel <ben.boeckel@kitware.com>
Date: Wed, 7 May 2025 13:53:52 +0200
Subject: [PATCH] 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     |  8 ++++++++
 Utilities/cmredbg/.gitignore  |  2 ++
 Utilities/cmredbg/README.rst  | 21 +++++++++++++++++++++
 Utilities/cmredbg/match.cmake | 21 +++++++++++++++++++++
 Utilities/cmredbg/run.sh      | 28 ++++++++++++++++++++++++++++
 5 files changed, 80 insertions(+)
 create mode 100644 Utilities/cmredbg/.gitignore
 create mode 100644 Utilities/cmredbg/README.rst
 create mode 100644 Utilities/cmredbg/match.cmake
 create mode 100755 Utilities/cmredbg/run.sh

diff --git a/Tests/RunCMake/README.rst b/Tests/RunCMake/README.rst
index f4bcc572cd..8df700a68f 100644
--- a/Tests/RunCMake/README.rst
+++ b/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
diff --git a/Utilities/cmredbg/.gitignore b/Utilities/cmredbg/.gitignore
new file mode 100644
index 0000000000..b0c4c5e553
--- /dev/null
+++ b/Utilities/cmredbg/.gitignore
@@ -0,0 +1,2 @@
+re.txt
+content.txt
diff --git a/Utilities/cmredbg/README.rst b/Utilities/cmredbg/README.rst
new file mode 100644
index 0000000000..2bc5070686
--- /dev/null
+++ b/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.
diff --git a/Utilities/cmredbg/match.cmake b/Utilities/cmredbg/match.cmake
new file mode 100644
index 0000000000..8621251cc2
--- /dev/null
+++ b/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 ()
diff --git a/Utilities/cmredbg/run.sh b/Utilities/cmredbg/run.sh
new file mode 100755
index 0000000000..f184966e5e
--- /dev/null
+++ b/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