[PATCH v2 1/2] checkpatch: add --debug rx=1|foo option and drx_print() helper

[Jim Cromie <jim.cromie@gmail.com>]

checkpatch has ~235 heuristic s/$patt// statements which strip
code-snippets that are "OK", leaving the remainder for further
heuristics to apply further "cleanups".  Many of these have obvious
purpose, but surely some are inscrutable.

To help with maintenance of those harder "cleanup" cases, add a helper
fn: drx_print($reason), which is designed to be called from a s/// or
s///g statement (in the 'replacement' side), to "explain" itself.

You can use it to instrument the code to show its work, then validate
that explanation by experiment and exersize:

  s/$patt/drx_print("why")/e;		# maintainer's best guess
  s/$patt/drx_print("whys")/ge;		# note the 'e' modifier

To activate drx_print() output, pass "--debug rx=1" to enable all the
instrumented cleanup heuristics.  For more selectivity (in case usage
grows), pass: "--debug rx=foo" to select "foo" cleanups.

Here it is in action, on a patch which triggered enough noise that I
wanted this visibility into what it was doing.

$ scripts/checkpatch.pl --strict --debug rx=inspect ../linux.git/pt-1
drx_print: -arg-inspections-
  >> Matched (`$&`): <__builtin_constant_p(cls>
  >> Capture 1 (`$1`): <__builtin_constant_p>

Also validate --debug KEYs for clear error:

$ scripts/checkpatch.pl --strict ../linux.git/pt-1 --debug foo=1
Unknown debug key 'foo', expecting: 'values possible type attr rx'

Signed-off-by: Jim Cromie <jim.cromie@gmail.com>
---
v2 - extend --debug key=1 rather than add new option
---
 scripts/checkpatch.pl | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index e722dd6fa8ef..c174e3bef2b2 100755
--- a/scripts/checkpatch.pl
+++ b/scripts/checkpatch.pl
@@ -169,6 +169,34 @@ my $DO_WHILE_0_ADVICE = q{
    Enjoy this qualification while we work to improve our heuristics.
 };
 
+my $dbg_rx = 0;
+# call this from s/$patt/drx_print("why")/e - to see whats happening there.
+sub drx_print {
+	my ($reason) = @_;
+	return "" unless $dbg_rx;
+
+	if ($dbg_rx ne '1') {
+	    # $dbg_rx is seeking "reason"
+	    # search w/o using regex, to preserve caller s///e context.
+	    return "" if ($dbg_rx and index($reason, $dbg_rx) == -1);
+	}
+
+	# report what was matched and removed (in caller)
+	print "drx_print: $reason\n";
+	print "  >> Matched (`\$&`): <$&>\n";
+
+	# Only print captures if they exist
+	if (defined $1) {
+		print "  >> Capture 1 (`\$1`): <$1>\n";
+	}
+	if (defined $2) {
+		print "  >> Capture 2 (`\$2`): <$2>\n";
+	}
+	# The subroutine must return the replacement string.  For s/$pat//
+	# statements (our target use), this is an empty string.
+	return "";
+}
+
 sub uniq {
 	my %seen;
 	return grep { !$seen{$_}++ } @_;
@@ -451,7 +479,13 @@ my $dbg_values = 0;
 my $dbg_possible = 0;
 my $dbg_type = 0;
 my $dbg_attr = 0;
+
+my @known_keys = qw(values possible type attr rx);
+my %known_keys;
+$known_keys{$_}++ for @known_keys;
+
 for my $key (keys %debug) {
+	die "Unknown debug key '$key', expecting: '@known_keys'\n" unless $known_keys{$key};
 	## no critic
 	eval "\${dbg_$key} = '$debug{$key}';";
 	die "$@" if ($@);
-- 
2.51.0