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 =head1 NAME
  12
  13 Acme::Study::Perl - empirical studies about how perl behaves
  14
  15 =cut
  16
  17 use version; our $VERSION = qv('0.0.2');
  18
  19 =head1 SYNOPSIS
  20
  21     use Acme::Study::Perl qw(studyperl);
  22     studyperl("your expression goes here", "optional comment");
  23
  24 =head1 DESCRIPTION
  25
  26 This module provides nothing that you cannot do yourself. Its focus
  27 is the test suite. If cpantesters deliver what they promise, this
  28 module's test suite can be used to study the behaviour of perl on
  29 multiple platforms.
  30
  31 The single function C<studyperl> only does some trivial formatting
  32 which will help deciphering the output of the testsuite.
  33
  34 =head1 EXPORT
  35
  36 =head1 FUNCTIONS
  37
  38 =head2 (void) studyperl ($expr, $comment)
  39
  40 Evals the expression and sends with the diag() command from Test::More
  41 a terse Data::Dumper representation for STDERR.
  42
  43 So far we have defined four characters as hash keys per study:
  44
  45   # comment
  46   < input
  47   > output
  48   @ error ($@)
  49
  50 We have configured Data::Dumpe to write one line and sort the keys
  51
  52 =cut
  53
  54 sub studyperl {
  55     my($expr, $comment) = @_;
  56     my $out = eval $expr;
  57     my $err = $@;
  58     my @err = $err ? ('@' => $err) : ();
  59     my @comment = $comment ? ("#" => $comment) : ();
  60     our $Test;
  61     $Test ||= Test::Builder->new;
  62     $Test->diag(Data::Dumper->new([{"<"=>$expr, ">"=>$out, @comment, @err}])
  63                 ->Sortkeys(1)->Indent(0)->Useqq(1)->Terse(1)->Dump);
  64     return;
  65 }
  66
  67 =head1 AUTHOR
  68
  69 Andreas König, C<< <andreas.koenig.7os6VVqR at franz.ak.mind.de> >>
  70
  71 =head1 BUGS
  72
  73 Please report any bugs or feature requests through the web interface
  74 at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Acme-Study-Perl>.
  75 I will be notified, and then you'll automatically be notified of
  76 progress on your bug as I make changes.
  77
  78 =head1 SUPPORT
  79
  80 You can find documentation for this module with the perldoc command.
  81
  82     perldoc Acme::Study::Perl
  83
  84 You can also look for information at:
  85
  86 =over 4
  87
  88 =item * RT: CPAN's request tracker
  89
  90 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Acme-Study-Perl>
  91
  92 =item * AnnoCPAN: Annotated CPAN documentation
  93
  94 L<http://annocpan.org/dist/Acme-Study-Perl>
  95
  96 =item * CPAN Ratings
  97
  98 L<http://cpanratings.perl.org/d/Acme-Study-Perl>
  99
 100 =item * Search CPAN
 101
 102 L<http://search.cpan.org/dist/Acme-Study-Perl>
 103
 104 =back
 105
 106
 107 =head1 ACKNOWLEDGEMENTS
 108
 109 Thanks to RJBS for Module::Starter.
 110
 111 =head1 COPYRIGHT & LICENSE
 112
 113 Copyright 2008 Andreas König.
 114
 115 This program is free software; you can redistribute it and/or modify it
 116 under the same terms as Perl itself.
 117
 118
 119 =cut
 120
 121 1; # End of Acme::Study::Perl