support control of colorization report belogning to the read-only var…

…iables $CLASS, $METHOD, and $METHOD_REF
pkg-perl-tools · Feb 10, 2024 · 2b90c9a · 2b90c9a
1 parent 10695a7
commit 2b90c9a
Show file tree

Hide file tree

Showing 8 changed files with 198 additions and 114 deletions.
diff --git a/Changes b/Changes
@@ -1,5 +1,8 @@
 Changelog for Test-Expander
 
+2.5.0 2024-02-10
+    - Support control of colorization report belogning to the read-only variables $CLASS, $METHOD, and $METHOD_REF.
+
 2.4.0 2024-02-07
     - Report unset and unexported read-only variables $CLASS, $METHOD, and $METHOD_REF.
 

diff --git a/META.json b/META.json
@@ -63,11 +63,11 @@
    "provides" : {
       "Test::Expander" : {
          "file" : "lib/Test/Expander.pm",
-         "version" : "2.4.0"
+         "version" : "2.5.0"
       },
       "Test::Expander::Constants" : {
          "file" : "lib/Test/Expander/Constants.pm",
-         "version" : "2.4.0"
+         "version" : "2.5.0"
       }
    },
    "release_status" : "stable",
@@ -81,5 +81,5 @@
          "web" : "https://github.com/jsf116/Test-Expander"
       }
    },
-   "version" : "2.4.0"
+   "version" : "2.5.0"
 }
diff --git a/META.yml b/META.yml
@@ -18,10 +18,10 @@ no_index:
 provides:
   Test::Expander:
     file: lib/Test/Expander.pm
-    version: '2.4.0'
+    version: '2.5.0'
   Test::Expander::Constants:
     file: lib/Test/Expander/Constants.pm
-    version: '2.4.0'
+    version: '2.5.0'
 requires:
   B: '0'
   Const::Fast: '0'
@@ -44,4 +44,4 @@ requires:
 resources:
   bugtracker: https://github.com/jsf116/Test-Expander
   repository: git://github.com/jsf116/Test-Expander.git
-version: '2.4.0'
+version: '2.5.0'
diff --git a/Readme.md b/Readme.md
@@ -8,6 +8,15 @@
     # creates neither a temporary directory, nor a temporary file:
     use Test::Expander;
 
+    # Tries to automatically determine, which class / module and method / subroutine are to be tested.
+    # The determined (and hence exported) values are displayed in green,
+    # the undetermined (and hence unexported) ones in red:
+    use Test::Expander -color => { exported => 'green', unexported => 'red' };
+
+    # Tries to automatically determine, which class / module and method / subroutine are to be tested.
+    # Both determined and undetermined values are displayed uncolorized:
+    use Test::Expander -color => { exported => undef, unexported => undef };
+
     # Tries to automatically determine, which class / module and method / subroutine are to be tested,
     # creates both a temporary directory and a temporary file preventing their removal after execution:
     use Test::Expander -tempdir => { CLEANUP => 0 }, -tempfile => { UNLINK => 0 };
@@ -253,6 +262,21 @@ The following options are accepted:
     - **-builtins** - overrides builtins in the name space of class / module to be tested.
     The expected value is a hash reference, where keys are the names of builtins and
     the values are code references overriding default behavior.
+    - **-color** - controls colorization of read-only variables **$CLASS**, **$METHOD**, and **$METHOD\_REF**
+    in the test notification header.
+    The expected value is a hash reference, the only supported keys are **exported** and **unexported**:
+        - **exported**
+
+            Contains either a string describing the foreground color, in which these variables are displayed
+            if they are being exported, or **undef** in no colorization is required in such case.
+
+            Defaults to **'cyan'**.
+
+        - **unexported**
+
+            The same as above, but for the case if these variables remains undefined and unexported.
+
+            Defaults to **'magenta'**.
     - **-lib** - prepends directory list used by the Perl interpreter for search of modules to be loaded
     (i.e. the **@INC** array) with values supplied in form of array reference.
     Each element of this array is evaluated using [string eval](https://perldoc.perl.org/functions/eval) so that

diff --git a/lib/Test/Expander.pm b/lib/Test/Expander.pm
@@ -2,7 +2,7 @@
 package Test::Expander;
 
 # The versioning is conform with https://semver.org
-our $VERSION = '2.4.0';                                     ## no critic (RequireUseStrict, RequireUseWarnings)
+our $VERSION = '2.5.0';                                     ## no critic (RequireUseStrict, RequireUseWarnings)
 
 use strict;
 use warnings
@@ -16,7 +16,7 @@ use Getopt::Long        qw( GetOptions :config posix_default );
 use Importer;
 use Path::Tiny          qw( cwd path );
 use Scalar::Readonly    qw( readonly_on );
-use Term::ANSIColor     qw( colored );
+use Term::ANSIColor     qw( color colored );
 use Test::Builder;
 use Test2::API          qw( context );
 use Test2::API::Context qw();
@@ -26,18 +26,19 @@ use Test2::Tools::Subtest;
 
 use Test::Expander::Constants qw(
   $DIE $FALSE
-  $FMT_INVALID_DIRECTORY $FMT_INVALID_ENV_ENTRY $FMT_INVALID_VALUE $FMT_INVALID_SUBTEST_NUMBER $FMT_KEEP_ENV_VAR
-  $FMT_NEW_FAILED $FMT_NEW_SUCCEEDED $FMT_REPLACEMENT $FMT_REQUIRE_DESCRIPTION $FMT_REQUIRE_IMPLEMENTATION
-  $FMT_SEARCH_PATTERN $FMT_SET_ENV_VAR $FMT_SET_TO $FMT_SKIP_ENV_VAR $FMT_UNSET_VAR $FMT_UNKNOWN_OPTION
-  $FMT_USE_DESCRIPTION $FMT_USE_IMPLEMENTATION $MSG_BAIL_OUT $MSG_ERROR_WAS $MSG_UNEXPECTED_EXCEPTION
+  $FMT_INVALID_COLOR $FMT_INVALID_DIRECTORY $FMT_INVALID_ENV_ENTRY $FMT_INVALID_VALUE $FMT_INVALID_SUBTEST_NUMBER
+  $FMT_KEEP_ENV_VAR $FMT_NEW_FAILED $FMT_NEW_SUCCEEDED $FMT_REPLACEMENT $FMT_REQUIRE_DESCRIPTION
+  $FMT_REQUIRE_IMPLEMENTATION $FMT_SEARCH_PATTERN $FMT_SET_ENV_VAR $FMT_SET_TO $FMT_SKIP_ENV_VAR $FMT_UNSET_VAR
+  $FMT_UNKNOWN_OPTION $FMT_USE_DESCRIPTION $FMT_USE_IMPLEMENTATION $MSG_BAIL_OUT $MSG_ERROR_WAS $MSG_UNEXPECTED_EXCEPTION
   $NOTE
   $REGEX_ANY_EXTENSION $REGEX_CLASS_HIERARCHY_LEVEL $REGEX_TOP_DIR_IN_PATH $REGEX_VERSION_NUMBER
   $TRUE
-  %MOST_CONSTANTS_TO_EXPORT %REST_CONSTANTS_TO_EXPORT
+  %COLORS %MOST_CONSTANTS_TO_EXPORT %REST_CONSTANTS_TO_EXPORT
 );
 
 my $ok_orig = \&Test2::API::Context::ok;
 my ( @subtest_names, @subtest_numbers );
+my %colors = %COLORS;
 
 sub _subtest_selection {
   my $error;
@@ -192,6 +193,12 @@ sub use_ok ( $;@ ) {
   return $require_result;
 }
 
+sub _colorize {
+  my ( $value, $export_type ) = @_;
+
+  return defined( $colors{ $export_type } ) ? colored( $value, $colors{ $export_type } ) : $value;
+}
+
 sub _determine_testee {
   my ( $options, $test_file ) = @_;
 
@@ -259,15 +266,15 @@ sub _export_symbols {
   my %constants = @_;
 
   foreach my $name ( sort keys( %constants ) ) {            # Export defined constants
-    no strict qw( refs );                                   ## no critic (ProhibitProlongedStrictureOverride)
+    no strict qw( refs );
     my $value = eval( "${ \$name }" );
     if ( defined( $value ) ) {
       readonly_on( ${ __PACKAGE__ . '::' . $name =~ s/^.//r } );
       push( @EXPORT, $name );
-      $NOTE->( $FMT_SET_TO, colored( $name, 'cyan' ), $constants{ $name }->( $value, $CLASS ) );
+      $NOTE->( $FMT_SET_TO, _colorize( $name, 'exported' ), $constants{ $name }->( $value, $CLASS ) );
     }
     elsif ( $name =~ /^ \$ (?: CLASS | METHOD | METHOD_REF )$/x ) {
-      $NOTE->( $FMT_UNSET_VAR, colored( $name, 'magenta' ) ) unless defined( $value );
+      $NOTE->( $FMT_UNSET_VAR, _colorize( $name, 'unexported' ) ) unless defined( $value );
     }
   }
 
@@ -293,7 +300,7 @@ sub _new_test_message {
   return $@ ? sprintf( $FMT_NEW_FAILED, $class, _error() ) : sprintf( $FMT_NEW_SUCCEEDED, $class, $class );
 }
 
-sub _parse_options {
+sub _parse_options {                                        ## no critic (ProhibitExcessComplexity)
   my ( $exports, $test_file ) = @_;
 
   my $options = {};
@@ -316,6 +323,19 @@ sub _parse_options {
       }
       $options->{ $option_name } = $option_value;
     }
+    elsif ( $option_name eq '-color' ) {
+      while ( my ( $color_name, $color_value ) = each( %colors ) ) {
+        if ( exists( $option_value->{ $color_name } ) ) {
+          my $requested_color = $option_value->{ $color_name };
+          $DIE->( $FMT_INVALID_COLOR, $requested_color, $color_name )
+            if defined( $requested_color ) && !defined( color( $requested_color ) );
+          $colors{ $color_name } = $requested_color;
+        }
+      }
+      foreach my $color_name ( keys( %$option_value ) ) {
+        $DIE->( $FMT_UNKNOWN_OPTION, $option_name, $color_name ) unless exists( $colors{ $color_name } );
+      }
+    }
     elsif ( $option_name eq '-lib' ) {
       $DIE->( $FMT_INVALID_VALUE, $option_name, $option_value ) if ref( $option_value ) ne 'ARRAY';
       $options->{ $option_name } = $option_value;
@@ -369,16 +389,16 @@ sub _read_env_file {
       };
       $DIE->( $FMT_INVALID_ENV_ENTRY, $index, $env_file, $line, $@ =~ s/\n//gr =~ s/ at \(eval .+//ir ) if $@;
       if ( defined( $value ) ) {
-        $NOTE->( $FMT_SET_ENV_VAR, colored( $name, 'cyan' ), $value, $env_file );
+        $NOTE->( $FMT_SET_ENV_VAR, _colorize( $name, 'exported' ), $value, $env_file );
         $ENV{ $name } = $env{ $name } = $value;
       }
       else {
-        $NOTE->( $FMT_SKIP_ENV_VAR, colored( $name, 'magenta' ), $env_file );
+        $NOTE->( $FMT_SKIP_ENV_VAR, _colorize( $name, 'unexported' ), $env_file );
       }
     }
     elsif ( exists( $ENV{ $+{ name } } ) ) {
       $env{ $name } = $ENV{ $name };
-      $NOTE->( $FMT_KEEP_ENV_VAR, colored( $name, 'cyan' ), $ENV{ $name }, $env_file );
+      $NOTE->( $FMT_KEEP_ENV_VAR, _colorize( $name, 'exported' ), $ENV{ $name }, $env_file );
     }
   }
 

diff --git a/lib/Test/Expander.pod b/lib/Test/Expander.pod
@@ -10,6 +10,15 @@ B<Test::Expander> - Expansion of test functionalities that appear to be frequent
   # creates neither a temporary directory, nor a temporary file:
   use Test::Expander;
 
+  # Tries to automatically determine, which class / module and method / subroutine are to be tested.
+  # The determined (and hence exported) values are displayed in green,
+  # the undetermined (and hence unexported) ones in red:
+  use Test::Expander -color => { exported => 'green', unexported => 'red' };
+
+  # Tries to automatically determine, which class / module and method / subroutine are to be tested.
+  # Both determined and undetermined values are displayed uncolorized:
+  use Test::Expander -color => { exported => undef, unexported => undef };
+
   # Tries to automatically determine, which class / module and method / subroutine are to be tested,
   # creates both a temporary directory and a temporary file preventing their removal after execution:
   use Test::Expander -tempdir => { CLEANUP => 0 }, -tempfile => { UNLINK => 0 };
@@ -291,6 +300,29 @@ the values are code references overriding default behavior.
 
 =item
 
+B<-color> - controls colorization of read-only variables B<$CLASS>, B<$METHOD>, and B<$METHOD_REF>
+in the test notification header.
+The expected value is a hash reference, the only supported keys are B<exported> and B<unexported>:
+
+=over 2
+
+=item B<exported>
+
+Contains either a string describing the foreground color, in which these variables are displayed
+if they are being exported, or B<undef> in no colorization is required in such case.
+
+Defaults to B<'cyan'>.
+
+=item B<unexported>
+
+The same as above, but for the case if these variables remains undefined and unexported.
+
+Defaults to B<'magenta'>.
+
+=back
+
+=item
+
 B<-lib> - prepends directory list used by the Perl interpreter for search of modules to be loaded
 (i.e. the B<@INC> array) with values supplied in form of array reference.
 Each element of this array is evaluated using L<string eval|https://perldoc.perl.org/functions/eval> so that

diff --git a/lib/Test/Expander/Constants.pm b/lib/Test/Expander/Constants.pm
@@ -1,6 +1,6 @@
 package Test::Expander::Constants;
 
-our $VERSION = '2.4.0';                                     ## no critic (RequireUseStrict, RequireUseWarnings)
+our $VERSION = '2.5.0';                                     ## no critic (RequireUseStrict, RequireUseWarnings)
 
 use strict;
 use warnings
@@ -22,6 +22,7 @@ const our $EXCEPTION_PREFIX            => 'BEGIN failed--compilation aborted at
 
 const our $FALSE                       => 0;
 
+const our $FMT_INVALID_COLOR           => "Color '%s' requested for %s variables is not supported\n";
 const our $FMT_INVALID_DIRECTORY       => "Invalid directory name / expression '%s' supplied with option '-lib'%s\n";
 const our $FMT_INVALID_ENV_ENTRY       => "Erroneous line %d of '%s' containing '%s': %s\n";
 const our $FMT_INVALID_VALUE           => "Option '%s' passed along with invalid value '%s'\n";
@@ -54,6 +55,8 @@ const our $REGEX_VERSION_NUMBER        => qr/^ \d+ (?: \. \d+ )* $/x;
 
 const our $TRUE                        => 1;
 
+const our %COLORS                      => ( exported => 'cyan', unexported => 'magenta' );
+
 const our %MOST_CONSTANTS_TO_EXPORT    => (
   '$CLASS'      => sub { $_[ 0 ] },
   '$TEMP_DIR'   => sub { $_[ 0 ] },