lib/Acme/Study/Perl.pm

   1 package Acme::Study::Perl;
   2
   3 use warnings;
   4 use strict;
   5 require Data::Dumper;
   6 use Test::Builder;
   7 use Exporter;
   8 use base 'Exporter';
   9 our @EXPORT_OK = qw(studyperl);
  10
  11 =encoding utf-8
  12
  13 =head1 NAME
  14
  15 Acme::Study::Perl - empirical studies about how perl behaves
  16
  17 =cut
  18
  19 use version; our $VERSION = qv('0.0.2');
  20
  21 =head1 SYNOPSIS
  22
  23     use Acme::Study::Perl qw(studyperl);
  24     studyperl("your expression goes here", "optional comment");
  25
  26 =head1 DESCRIPTION
  27
  28 This module provides nothing that you cannot do yourself. Its focus
  29 is the test suite. If cpantesters deliver what they promise, this
  30 module's test suite can be used to study the behaviour of perl on
  31 multiple platforms.
  32
  33 The single function C<studyperl> only does some trivial formatting
  34 which will help deciphering the output of the testsuite.
  35
  36 =head1 EXAMPLE
  37
  38 My first descriptive table overview after I first released
  39 Acme::Study::Perl was generated with the following command:
  40
  41   ctgetreports --q meta:perl -q conf:use64bitint -q conf:use64bitall --q qr:"(native big math float/int.*)" Acme-Study-Perl
  42
  43 The result showed me six perls that have a bug in their conversion of
  44 strings to numbers and 28 perls that did it right. To find out more
  45 about the parameters that might have an influence, I called
  46 ctgetreports with --solve and --ycb (example in the ctgetreports
  47 manpage).
  48
  49 The calculation provided a hint that conf:ivtype is a candidate.
  50 Looking closer helped confirm the finding that all perls with ivtype
  51 C<long long> have this bug. And only one architecture with ivtype
  52 C<long>, namely C<alpha-netbsd>. All others either provided the
  53 correct result, C<-1> because they were native 64 bit processors or
  54 the expected wrong-by-rounding result C<0>.
  55
  56 =head1 EXPORT
  57
  58 =head1 FUNCTIONS
  59
  60 =head2 (void) studyperl ($expr, $comment)
  61
  62 Evals the expression and sends with the diag() command from Test::More
  63 a terse Data::Dumper representation for STDERR.
  64
  65 So far we have defined four characters as hash keys per study:
  66
  67   # comment
  68   < input
  69   > output
  70   @ error ($@)
  71
  72 We have configured Data::Dumper to write one line and sort the keys.
  73
  74 =cut
  75
  76 sub studyperl {
  77     my($expr, $comment) = @_;
  78     my $out = eval $expr;
  79     my $err = $@;
  80     my @err = $err ? ('@' => $err) : ();
  81     my @comment = $comment ? ("#" => $comment) : ();
  82     our $Test;
  83     $Test ||= Test::Builder->new;
  84     $Test->diag(Data::Dumper->new([{"<"=>$expr, ">"=>$out, @comment, @err}])
  85                 ->Sortkeys(1)->Indent(0)->Useqq(1)->Terse(1)->Dump);
  86     return;
  87 }
  88
  89 =head1 AUTHOR
  90
  91 Andreas König, C<< <andreas.koenig.7os6VVqR at franz.ak.mind.de> >>
  92
  93 =head1 BUGS
  94
  95 Please report any bugs or feature requests through the web interface
  96 at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Acme-Study-Perl>.
  97 I will be notified, and then you'll automatically be notified of
  98 progress on your bug as I make changes.
  99
 100 =head1 SUPPORT
 101
 102 You can find documentation for this module with the perldoc command.
 103
 104     perldoc Acme::Study::Perl
 105
 106 You can also look for information at:
 107
 108 =over 4
 109
 110 =item * RT: CPAN's request tracker
 111
 112 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Acme-Study-Perl>
 113
 114 =item * AnnoCPAN: Annotated CPAN documentation
 115
 116 L<http://annocpan.org/dist/Acme-Study-Perl>
 117
 118 =item * CPAN Ratings
 119
 120 L<http://cpanratings.perl.org/d/Acme-Study-Perl>
 121
 122 =item * Search CPAN
 123
 124 L<http://search.cpan.org/dist/Acme-Study-Perl>
 125
 126 =back
 127
 128 =head1 ACKNOWLEDGEMENTS
 129
 130 Thanks to RJBS for Module::Starter.
 131
 132 =head1 COPYRIGHT & LICENSE
 133
 134 Copyright 2008 Andreas König.
 135
 136 This program is free software; you can redistribute it and/or modify it
 137 under the same terms as Perl itself.
 138
 139
 140 =cut
 141
 142 1; # End of Acme::Study::Perl