1 package Test::Valgrind::Tool;
8 Test::Valgrind::Tool - Base class for Test::Valgrind tools.
16 our $VERSION = '1.02';
20 This class is the base for L<Test::Valgrind> tools.
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.
27 use base qw/Test::Valgrind::Carp/;
31 =head2 C<requires_version>
33 The minimum C<valgrind> version needed to run this tool.
38 sub requires_version { '3.1.0' }
40 =head2 C<< new tool => $tool >>
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.
49 $class = ref($class) || $class;
53 if ($class eq __PACKAGE__) {
54 my $tool = delete $args{tool} || 'memcheck';
56 $tool = __PACKAGE__ . "::$tool" if $tool !~ /::/;
57 $class->_croak("Couldn't load tool $tool: $@") unless eval "require $tool; 1";
58 return $tool->new(%args);
61 my $self = bless { }, $class;
63 $self->started(undef);
70 Creates a new tool object suitable for generating suppressions.
72 Defaults to return C<undef>, which skips suppression generation.
78 =head2 C<report_class $session>
80 Wraps around either L</report_class_suppressions> or L</report_class_analysis> depending on the running mode of the C<$session>.
85 my ($self, $sess) = @_;
87 if ($sess->do_suppressions) {
88 $self->report_class_suppressions($sess);
90 $self->report_class_analysis($sess);
94 =head2 C<report_class_suppressions $session>
96 Returns the class in which suppression reports generated by this tool will be blessed.
98 This method must be implemented when subclassing.
102 sub report_class_suppression;
104 =head2 C<report_class_analysis $session>
106 Returns the class in which error reports generated by this tool will be blessed.
108 This method must be implemented when subclassing.
112 sub report_class_analysis;
114 =head2 C<args $session>
116 Returns the list of tool-specific arguments that are to be passed to C<valgrind>.
117 All the suppression arguments are already handled by the session.
119 Defaults to the empty list.
125 =head2 C<suppressions_tag $session>
127 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.
129 This method must be implemented when subclassing.
133 sub suppressions_tag;
137 Specifies whether the tool is running (C<1>), stopped (C<0>) or was never started (C<undef>).
141 sub started { @_ <= 1 ? $_[0]->{started} : ($_[0]->{started} = $_[1]) }
143 =head2 C<start $session>
145 Called when the C<$session> starts.
147 Defaults to set L</started>.
154 $self->_croak('Tool already started') if $self->started;
160 =head2 C<parse $session, $fh>
162 Wraps around either L</parse_suppressions> or L</parse_analysis> depending on the running mode of the C<$session>.
163 Croaks if the tool isn't started.
168 my ($self, $sess, $fh) = @_;
170 $self->_croak('Tool isn\'t started') unless $self->started;
172 if ($sess->do_suppressions) {
173 $self->parse_suppressions($sess, $fh);
175 $self->parse_analysis($sess, $fh);
179 =head2 C<parse_suppressions $sesssion, $fh>
181 Parse the suppression reports that the C<valgrind> process attached to the session C<$session> send through the filehandle C<$fh>.
183 This method must be implemented when subclassing.
187 sub parse_suppressions;
189 =head2 C<parse_analysis $sesssion, $fh>
191 Parse the error reports sent by the C<valgrind> process attached to the session C<$session> through the filehandle C<$fh>.
193 This method must be implemented when subclassing.
199 =head2 C<finish $session>
201 Called when the C<$session> finishes.
203 Defaults to clear L</started>.
210 return unless $self->started;
218 L<Test::Valgrind>, L<Test::Valgrind::Session>.
222 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
224 You can contact me by mail or on C<irc.perl.org> (vincent).
228 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>.
229 I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
233 You can find documentation for this module with the perldoc command.
235 perldoc Test::Valgrind::Tool
237 =head1 COPYRIGHT & LICENSE
239 Copyright 2009 Vincent Pit, all rights reserved.
241 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
245 1; # End of Test::Valgrind::Tool