NAME

Devel::Git::MultiBisect::Auxiliary - Helper functions for Devel::Git::MultiBisect

SYNOPSIS

    use Devel::Git::MultiBisect::Auxiliary qw(
        clean_outputfile
        hexdigest_one_file
        validate_list_sequence
    );

DESCRIPTION

This package exports, on demand only, subroutines used within publicly available methods in Devel::Git::MultiBisect.

SUBROUTINES

clean_outputfile()

• Purpose

  When we redirect the output of a test harness program such as prove to a file, we typically get at the end a line matching this pattern:

      m/^Files=\d+,\sTests=\d+/

  This line also contains measurements of the time it took for a particular file to be run. These timings vary from one run to the next, which makes the content of otherwise identical files different, which in turn makes their md5_hex digests different. So we simply rewrite the test output file to remove this line.

• Arguments

      $outputfile = clean_outputfile($outputfile);

  A string holding the path to a file holding TAP output.

• Return Value

  A string holding the path to a file holding TAP output.

• Comment

  The return value is provided for the purpose of chaining function calls; the file itself is changed in place.

hexdigest_one_file()

• Purpose

  To compare multiple files for same or different content, we need a convenient, short datum. We will use the md5_hex value provided by the Digest::MD5 module which is part of the Perl 5 core distribution.

• Arguments

      $md5_hex = hexdigest_one_file($outputfile);

  A string holding the path to a file holding TAP output.

• Return Value

  A string holding the md5_hex digest for that file.

• Comment

  The file provided as argument should be run through clean_outputfile() before being passed to this function.

validate_list_sequence()

• Purpose

  Determine whether a given list consists of one or more sub-lists, each of which conforms to the following properties:

  1. The sub-list consists of one or more elements, the first and last of which are defined and identical. Elements between the first and last (if any) are either identical to the first and last or are undefined.

  2. The sole defined value in any sub-list is not found in any other sub-list.

  Examples:

  • ['alpha', 'alpha', undef, 'alpha', undef, 'beta']

    Does not qualify, as the sub-list terminating with beta starts with an undef.

  • ['alpha', 'alpha', undef, 'alpha', 'beta', undef]

    Does not qualify, as the sub-list starting with beta ends with an undef.

  • ['alpha', 'alpha', undef, 'alpha', 'beta', undef, 'beta', 'alpha', 'alpha']

    Does not qualify, as alpha occurs in both the first and third sub-lists.

    Qualifies.

  • ['alpha', 'alpha', undef, 'alpha', 'beta', undef, 'beta']

    Qualifies.

• Arguments

      my $vls = validate_list_sequence( [
          'alpha', 'alpha', undef, 'alpha', 'beta', undef, 'beta'
      ] );

  Reference to an array holding scalars.

• Return Value

  Array reference consisting of either 1 or 3 elements. If the list qualifies, the array holds just one element which is a Perl-true value. If the list qualifies, the array hold 3 elements as follows:

  • Element 0

    Perl-false value, indicating that the list does not qualify.

  • Element 1

    Index of the array element at which the first non-conforming value was observed.

  • Element 2

    String holding explanation for failure to qualify.

  Examples:

  1. Qualifying list:

         use Data::Dumper; $Data::Dumper::Indent = 0;
         my $vls;
     
         my $good =
             ['alpha', 'alpha', undef, 'alpha', 'beta', undef, 'beta', 'gamma'];
         $vls = validate_list_sequence($good);
         print Dumper($vls);
     
         #####
     
         $VAR1 = [1];

  2. Non-qualifying list:

         my $bad =
             ['alpha', 'alpha', undef, 'alpha', 'beta', undef, 'beta', 'alpha', 'alpha'];
         $vls = validate_list_sequence($bad);
         print Dumper($vls);
     
         #####
     
             $VAR1 = [0,7,'alpha previously observed']