]> git.vpit.fr Git - perl/modules/Test-Valgrind.git/blob - lib/Test/Valgrind/Tool.pm
Make sure $version is not set when no suitable valgrind was found
[perl/modules/Test-Valgrind.git] / 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.17
13
14 =cut
15
16 our $VERSION = '1.17';
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 Test::Valgrind::Util;
28
29 use base qw<Test::Valgrind::Component Test::Valgrind::Carp>;
30
31 =head1 METHODS
32
33 =head2 C<requires_version>
34
35     my $required_version = $tvt->requires_version;
36
37 The minimum C<valgrind> version needed to run this tool.
38 Defaults to C<3.1.0>.
39
40 =cut
41
42 sub requires_version { '3.1.0' }
43
44 =head2 C<new>
45
46     my $tvt = Test::Valgrind::Tool->new(tool => $tool);
47
48 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.
49 The class represented by C<$tool> must inherit this class.
50
51 =cut
52
53 sub new {
54  my $class = shift;
55  $class = ref($class) || $class;
56
57  my %args = @_;
58
59  if ($class eq __PACKAGE__) {
60   my ($tool, $msg) = Test::Valgrind::Util::validate_subclass(
61    delete $args{tool} || 'memcheck',
62   );
63   $class->_croak($msg) unless defined $tool;
64   return $tool->new(%args);
65  }
66
67  $class->SUPER::new(@_);
68 }
69
70 =head2 C<new_trainer>
71
72     my $tvt_train = Test::Valgrind::Tool->new_trainer;
73
74 Creates a new tool object suitable for generating suppressions.
75
76 Defaults to return C<undef>, which skips suppression generation.
77
78 =cut
79
80 sub new_trainer { }
81
82 =head2 C<parser_class>
83
84     my $parser_class = $tvt->parser_class($session);
85
86 Returns the class from which the parser for this tool output will be instanciated.
87
88 This method must be implemented when subclassing.
89
90 =cut
91
92 sub parser_class;
93
94 =head2 C<report_class>
95
96     my $report_class = $tvt->report_class($session);
97
98 Returns the class in which suppression reports generated by this tool will be blessed.
99
100 This method must be implemented when subclassing.
101
102 =cut
103
104 sub report_class;
105
106 =head2 C<args>
107
108     my @args = $tvt->args($session);
109
110 Returns the list of tool-specific arguments that are to be passed to C<valgrind>.
111 All the suppression arguments are already handled by the session.
112
113 Defaults to the empty list.
114
115 =cut
116
117 sub args { }
118
119 =head2 C<suppressions_tag>
120
121     my $tag = $tvt->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>
132
133     $tvt->start($session);
134
135 Called when the C<$session> starts.
136
137 Defaults to set L<Test::Valgrind::Component/started>.
138
139 =head2 C<filter>
140
141     my $filtered_report = $tvt->filter($session, $report);
142
143 The C<$session> calls this method after receiving a report from the parser and before letting the command filter it.
144 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.
145
146 Defaults to the identity function.
147
148 =cut
149
150 sub filter { $_[2] }
151
152 =head2 C<finish>
153
154     $tvt->finish($session);
155
156 Called when the C<$session> finishes.
157
158 Defaults to clear L<Test::Valgrind::Component/started>.
159
160 =head1 SEE ALSO
161
162 L<Test::Valgrind>, L<Test::Valgrind::Component>, L<Test::Valgrind::Session>.
163
164 =head1 AUTHOR
165
166 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
167
168 You can contact me by mail or on C<irc.perl.org> (vincent).
169
170 =head1 BUGS
171
172 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>.
173 I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
174
175 =head1 SUPPORT
176
177 You can find documentation for this module with the perldoc command.
178
179     perldoc Test::Valgrind::Tool
180
181 =head1 COPYRIGHT & LICENSE
182
183 Copyright 2009,2010,2011,2013,2015 Vincent Pit, all rights reserved.
184
185 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
186
187 =cut
188
189 1; # End of Test::Valgrind::Tool