File Coverage

blib/lib/Surveyor/App.pm

Criterion	Covered	Total	%
statement	15	46	32.6
branch	0	12	0.0
condition			n/a
subroutine	5	9	55.5
pod	3	3	100.0
total	23	70	32.8

package Surveyor::App;
use strict;
use warnings;

our $VERSION = '0.121';

=encoding utf8

=head1 NAME

Surveyor::App - Run benchmarks from a package

=head1 SYNOPSIS

	use Surveyor::App;

=head1 DESCRIPTION

C provides a minimal framework and convention for
people to distribute benchmarks. By creating a package in a special
way, you can easily share your benchmarks with people without having
to repeat a lot of code.

First, if you want to do some setup before your benchmarks run, define
a C method. Do whatever you need there, such as setting
environment variables, changing directories, and so on. The C
method gets the command-line arguments you specified when you run
C, save for any that C used for itself.

Next, define your benchmarks in subroutines whose names start with
C. Surveyor::App will find each of those, using the part of
the name after C as the label for that test.

Last, if you want to do some setup before your benchmarks run, define
a C method. The C method gets no arguments.

Your benchmarking package doesn't have to have any particular name and
it doesn't need to subclass or C this package. See
L for an example.

=over 4

=cut

=item run( PACKAGE, ITERATIONS, @ARGS )

Find all of the subroutines that start with C in C
and run each of them C times.

Before it does that, though, call the C routine in C
as a class method. After benchmarking, call the C routine
in C as a class method.

=cut

sub run {
	my( $package, $iterations, @args ) = @_;
	$package->set_up( @args ) if $package->can( 'set_up' );

	# the key is a label, which is the stuff after bench_
	no strict 'refs';
	my %hash = map {
		(
			do { (my $s = $_) =~ s/\Abench_//; $s },
			\&{"${package}::$_"}
		)
		} get_all_bench_( $package );

	die "Did not find any bench_ subroutines in [$package]\n"
		unless keys %hash;

	require Benchmark;
	my $results = Benchmark::timethese( $iterations, \%hash );

	$package->tear_down() if $package->can( 'tear_down' );
	}

=item test( PACKAGE, @ARGS )

Find all of the subroutines that start with C in C
and run each of them once. Compare the return values of each to ensure
they are the same.

Before it does that, though, call the C routine in C
as a class method. After benchmarking, call the C routine
in C as a class method.

=cut

sub test {
	my( $package, @args ) = @_;
	my @subs = get_all_bench_( $package );
	my %results;

	$package->set_up( @args ) if $package->can( 'set_up' );
	foreach my $sub ( get_all_bench_( $package ) ) {
		my @return = $package->$sub();
		$results{$sub} = \@return;
		}
	$package->tear_down() if $package->can( 'tear_down' );

	use Test::More;

	subtest pairs => sub {
		my @subs = keys %results;
		foreach my $i ( 1 .. $#subs ) {
			my @sub_names = @subs[ $i - 1, $i ];
			my( $first, $second ) = @results{ @sub_names };
			local $" = " and ";
			is_deeply( $first, $second, "@sub_names match return values" );
			}
		};

	done_testing();
	}

=item get_all_bench_( PACKAGE )

Extract all of the subroutines starting with C in C.
If you don't define a package, it uses the package this subroutine
was compiled in (so that's probably useless).

=cut

sub get_all_bench_ {
	my( $package ) = @_;
	$package = defined $package ? $package : __PACKAGE__;

	no strict 'refs';
	my @subs =
		grep /\Abench_/,
		keys %{"${package}::"};
	}


=back

=head1 TO DO


=head1 SEE ALSO


=head1 SOURCE AVAILABILITY

This source is in a Git repository that I haven't made public
because I haven't bothered to set it up. If you want to clone
it, just ask and we'll work something out.

	https://github.com/briandfoy/surveyor-app

=head1 AUTHOR

brian d foy, C<<  >>

=head1 COPYRIGHT AND LICENSE

Copyright © 2013-2018, brian d foy . All rights reserved.

You may redistribute this under the terms of the Artistic License 2.0.

=cut

1;