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.

    • ['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 does not qualify, 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']

write_transitions_report()

  • Purpose

    Write data about transitions to file on disk.

  • Arguments

    $transitions_report = write_transitions_report($outputdir, $report_basename, $transitions_data);

    List of 3 arguments:

    • String holding path to output directory (typically, $self->{outputdir}).

    • String holding desired basename for transitions report file (typically, $self->{transitions_report}).

    • Hash reference which is return value of $self->inspect_transitions().

  • Return Value

    String holding full path to transitions report file.