lib/Test/Valgrind/Tool.pm

   1 package Test::Valgrind::Tool;
   2
   3 use strict;
   4 use warnings;
   5
   6 =head1 NAME
   7
   8 Test::Valgrind::Tool - Base class for Test::Valgrind tools.
   9
  10 =head1 VERSION
  11
  12 Version 1.02
  13
  14 =cut
  15
  16 our $VERSION = '1.02';
  17
  18 =head1 DESCRIPTION
  19
  20 This class is the base for L<Test::Valgrind> tools.
  21
  22 They wrap around C<valgrind> tools by parsing its output and sending reports to the parent session whenever an error occurs.
  23 They are expected to function both in suppressions generation and in analysis mode.
  24
  25 =cut
  26
  27 use base qw/Test::Valgrind::Component Test::Valgrind::Carp/;
  28
  29 =head1 METHODS
  30
  31 =head2 C<requires_version>
  32
  33 The minimum C<valgrind> version needed to run this tool.
  34 Defaults to C<3.1.0>.
  35
  36 =cut
  37
  38 sub requires_version { '3.1.0' }
  39
  40 =head2 C<< new tool => $tool >>
  41
  42 Creates a new tool object of type C<$tool> by requiring and redispatching the method call to the module named C<$tool> if it contains C<'::'> or to C<Test::Valgrind::Tool::$tool> otherwise.
  43 The class represented by C<$tool> must inherit this class.
  44
  45 =cut
  46
  47 sub new {
  48  my $class = shift;
  49  $class = ref($class) || $class;
  50
  51  my %args = @_;
  52
  53  if ($class eq __PACKAGE__) {
  54   my $tool = delete $args{tool} || 'memcheck';
  55   $tool =~ s/[^\w:]//g;
  56   $tool = __PACKAGE__ . "::$tool" if $tool !~ /::/;
  57   $class->_croak("Couldn't load tool $tool: $@") unless eval "require $tool; 1";
  58   return $tool->new(%args);
  59  }
  60
  61  $class->SUPER::new(@_);
  62 }
  63
  64 =head2 C<new_trainer>
  65
  66 Creates a new tool object suitable for generating suppressions.
  67
  68 Defaults to return C<undef>, which skips suppression generation.
  69
  70 =cut
  71
  72 sub new_trainer { }
  73
  74 =head2 C<report_class $session>
  75
  76 Wraps around either L</report_class_suppressions> or L</report_class_analysis> depending on the running mode of the C<$session>.
  77
  78 =cut
  79
  80 sub report_class {
  81  my ($self, $sess) = @_;
  82
  83  if ($sess->do_suppressions) {
  84   $self->report_class_suppressions($sess);
  85  } else {
  86   $self->report_class_analysis($sess);
  87  }
  88 }
  89
  90 =head2 C<report_class_suppressions $session>
  91
  92 Returns the class in which suppression reports generated by this tool will be blessed.
  93
  94 This method must be implemented when subclassing.
  95
  96 =cut
  97
  98 sub report_class_suppression;
  99
 100 =head2 C<report_class_analysis $session>
 101
 102 Returns the class in which error reports generated by this tool will be blessed.
 103
 104 This method must be implemented when subclassing.
 105
 106 =cut
 107
 108 sub report_class_analysis;
 109
 110 =head2 C<args $session>
 111
 112 Returns the list of tool-specific arguments that are to be passed to C<valgrind>.
 113 All the suppression arguments are already handled by the session.
 114
 115 Defaults to the empty list.
 116
 117 =cut
 118
 119 sub args { }
 120
 121 =head2 C<suppressions_tag $session>
 122
 123 Returns a identifier that will be used to pick up the right suppressions for running the tool, or C<undef> to indicate that no special suppressions are needed.
 124
 125 This method must be implemented when subclassing.
 126
 127 =cut
 128
 129 sub suppressions_tag;
 130
 131 =head2 C<start $session>
 132
 133 Called when the C<$session> starts.
 134
 135 Defaults to set L<Test::Valgrind::Component/started>.
 136
 137 =head2 C<parse $session, $fh>
 138
 139 Wraps around either L</parse_suppressions> or L</parse_analysis> depending on the running mode of the C<$session>.
 140 Croaks if the tool isn't started.
 141
 142 =cut
 143
 144 sub parse {
 145  my ($self, $sess, $fh) = @_;
 146
 147  $self->_croak('Tool isn\'t started') unless $self->started;
 148
 149  if ($sess->do_suppressions) {
 150   $self->parse_suppressions($sess, $fh);
 151  } else {
 152   $self->parse_analysis($sess, $fh);
 153  }
 154 }
 155
 156 =head2 C<parse_suppressions $sesssion, $fh>
 157
 158 Parse the suppression reports that the C<valgrind> process attached to the session C<$session> send through the filehandle C<$fh>.
 159
 160 This method must be implemented when subclassing.
 161
 162 =cut
 163
 164 sub parse_suppressions;
 165
 166 =head2 C<parse_analysis $sesssion, $fh>
 167
 168 Parse the error reports sent by the C<valgrind> process attached to the session C<$session> through the filehandle C<$fh>.
 169
 170 This method must be implemented when subclassing.
 171
 172 =cut
 173
 174 sub parse_analysis;
 175
 176 =head2 C<finish $session>
 177
 178 Called when the C<$session> finishes.
 179
 180 Defaults to clear L<Test::Valgrind::Component/started>.
 181
 182 =head1 SEE ALSO
 183
 184 L<Test::Valgrind>, L<Test::Valgrind::Component>, L<Test::Valgrind::Session>.
 185
 186 =head1 AUTHOR
 187
 188 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
 189
 190 You can contact me by mail or on C<irc.perl.org> (vincent).
 191
 192 =head1 BUGS
 193
 194 Please report any bugs or feature requests to C<bug-test-valgrind at rt.cpan.org>, or through the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Valgrind>.
 195 I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
 196
 197 =head1 SUPPORT
 198
 199 You can find documentation for this module with the perldoc command.
 200
 201     perldoc Test::Valgrind::Tool
 202
 203 =head1 COPYRIGHT & LICENSE
 204
 205 Copyright 2009 Vincent Pit, all rights reserved.
 206
 207 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
 208
 209 =cut
 210
 211 1; # End of Test::Valgrind::Tool