[PATCH 1/3] checkpatch: add --drx 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.
For those cases, add drx_print($reason) helper, which is designed to
be called from a s/// or s///g statement (in the 'replacement' side),
to "explain" what it is doing.

You can use it to instrument the code to "explain" itself, then
validate that explanation by experiment and exersize:

  s/$patt/drx_print("why")/e;
  s/$patt/drx_print("whys")/ge;

To activate the "debug" output, pass --drx or --drx=why to enable all
(or just matching) cleanup heuristics to validate the "whys".

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 --drx=builtins ../linux.git/pt-1
drx_print: -builtins-
  >> Matched (`$&`): <__builtin_constant_p(cls>
  >> Capture 1 (`$1`): <__builtin_constant_p>

Signed-off-by: Jim Cromie <jim.cromie@gmail.com>

fixup
---
 scripts/checkpatch.pl | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index e722dd6fa8ef..2b0275dcc5a4 100755
--- a/scripts/checkpatch.pl
+++ b/scripts/checkpatch.pl
@@ -74,6 +74,7 @@ my $allow_c99_comments = 1; # Can be overridden by --ignore C99_COMMENT_TOLERANC
 my $git_command ='export LANGUAGE=en_US.UTF-8; git';
 my $tabsize = 8;
 my ${CONFIG_} = "CONFIG_";
+my $drx; # enable s/$patt/drx_print("reason")/e; debugging
 
 my %maybe_linker_symbol; # for externs in c exceptions, when seen in *vmlinux.lds.h
 
@@ -169,6 +170,30 @@ my $DO_WHILE_0_ADVICE = q{
    Enjoy this qualification while we work to improve our heuristics.
 };
 
+# call this from s/$patt/drx_print("why")/e - to see whats happening there.
+sub drx_print {
+	my ($why) = @_;
+	return "" unless defined $drx;		# --drx or --drx=
+
+	# avoid regex test to preserve caller's match, captures
+	return "" if (defined $drx && $drx ne '' && index($why, $drx) == -1);
+
+	# report what was matched and removed
+	print "drx_print: $why\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{$_}++ } @_;
@@ -348,6 +373,7 @@ GetOptions(
 	'no-color'	=> \$color,	#keep old behaviors of -nocolor
 	'nocolor'	=> \$color,	#keep old behaviors of -nocolor
 	'kconfig-prefix=s'	=> \${CONFIG_},
+	'drx:s'		=> \$drx,
 	'h|help'	=> \$help,
 	'version'	=> \$help
 ) or $help = 2;
-- 
2.51.0