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:
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.
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 anundef
.['alpha', 'alpha', undef, 'alpha', 'beta', undef]
Does not qualify, as the sub-list starting with
beta
ends with anundef
.['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:
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];
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.