This is 1.17

[perl/modules/Test-Valgrind.git] / lib / Test / Valgrind / Tool.pm

diff --git a/lib/Test/Valgrind/Tool.pm b/lib/Test/Valgrind/Tool.pm
index 54598a596d84c0b6f6138ae653791e37254c0b85..c7dd55c03cdff6f500aebd956305f8175817c92b 100644 (file)
--- a/lib/Test/Valgrind/Tool.pm
+++ b/lib/Test/Valgrind/Tool.pm
@@ -9,11 +9,11 @@ Test::Valgrind::Tool - Base class for Test::Valgrind tools.
 
 =head1 VERSION
 
-Version 1.02
+Version 1.17
 
 =cut
 
-our $VERSION = '1.02';
+our $VERSION = '1.17';
 
 =head1 DESCRIPTION
 
@@ -24,12 +24,16 @@ They are expected to function both in suppressions generation and in analysis mo
 
 =cut
 
-use base qw/Test::Valgrind::Component Test::Valgrind::Carp/;
+use Test::Valgrind::Util;
+
+use base qw<Test::Valgrind::Component Test::Valgrind::Carp>;
 
 =head1 METHODS
 
 =head2 C<requires_version>
 
+    my $required_version = $tvt->requires_version;
+
 The minimum C<valgrind> version needed to run this tool.
 Defaults to C<3.1.0>.
 
@@ -37,7 +41,9 @@ Defaults to C<3.1.0>.
 
 sub requires_version { '3.1.0' }
 
-=head2 C<< new tool => $tool >>
+=head2 C<new>
+
+    my $tvt = Test::Valgrind::Tool->new(tool => $tool);
 
 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.
 The class represented by C<$tool> must inherit this class.
@@ -51,10 +57,10 @@ sub new {
  my %args = @_;
 
  if ($class eq __PACKAGE__) {
-  my $tool = delete $args{tool} || 'memcheck';
-  $tool =~ s/[^\w:]//g;
-  $tool = __PACKAGE__ . "::$tool" if $tool !~ /::/;
-  $class->_croak("Couldn't load tool $tool: $@") unless eval "require $tool; 1";
+  my ($tool, $msg) = Test::Valgrind::Util::validate_subclass(
+   delete $args{tool} || 'memcheck',
+  );
+  $class->_croak($msg) unless defined $tool;
   return $tool->new(%args);
  }
 
@@ -63,6 +69,8 @@ sub new {
 
 =head2 C<new_trainer>
 
+    my $tvt_train = Test::Valgrind::Tool->new_trainer;
+
 Creates a new tool object suitable for generating suppressions.
 
 Defaults to return C<undef>, which skips suppression generation.
@@ -71,7 +79,9 @@ Defaults to return C<undef>, which skips suppression generation.
 
 sub new_trainer { }
 
-=head2 C<parser_class $session>
+=head2 C<parser_class>
+
+    my $parser_class = $tvt->parser_class($session);
 
 Returns the class from which the parser for this tool output will be instanciated.
 
@@ -81,7 +91,9 @@ This method must be implemented when subclassing.
 
 sub parser_class;
 
-=head2 C<report_class $session>
+=head2 C<report_class>
+
+    my $report_class = $tvt->report_class($session);
 
 Returns the class in which suppression reports generated by this tool will be blessed.
 
@@ -91,7 +103,9 @@ This method must be implemented when subclassing.
 
 sub report_class;
 
-=head2 C<args $session>
+=head2 C<args>
+
+    my @args = $tvt->args($session);
 
 Returns the list of tool-specific arguments that are to be passed to C<valgrind>.
 All the suppression arguments are already handled by the session.
@@ -102,7 +116,9 @@ Defaults to the empty list.
 
 sub args { }
 
-=head2 C<suppressions_tag $session>
+=head2 C<suppressions_tag>
+
+    my $tag = $tvt->suppressions_tag($session);
 
 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.
 
@@ -112,15 +128,19 @@ This method must be implemented when subclassing.
 
 sub suppressions_tag;
 
-=head2 C<start $session>
+=head2 C<start>
+
+    $tvt->start($session);
 
 Called when the C<$session> starts.
 
 Defaults to set L<Test::Valgrind::Component/started>.
 
-=head2 C<filter $session, $report>
+=head2 C<filter>
 
-The <$session> calls this method after receiving a report from the parser and before letting the command filter it.
+    my $filtered_report = $tvt->filter($session, $report);
+
+The C<$session> calls this method after receiving a report from the parser and before letting the command filter it.
 You can either return a mangled C<$report> (which does not need to be a clone of the original) or C<undef> if you want the action to ignore it completely.
 
 Defaults to the identity function.
@@ -129,7 +149,9 @@ Defaults to the identity function.
 
 sub filter { $_[2] }
 
-=head2 C<finish $session>
+=head2 C<finish>
+
+    $tvt->finish($session);
 
 Called when the C<$session> finishes.
 
@@ -158,7 +180,7 @@ You can find documentation for this module with the perldoc command.
 
 =head1 COPYRIGHT & LICENSE
 
-Copyright 2009 Vincent Pit, all rights reserved.
+Copyright 2009,2010,2011,2013,2015 Vincent Pit, all rights reserved.
 
 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.