File Coverage

blib/lib/Perl/PrereqScanner/Scanner/Perl5.pm
Criterion Covered Total %
statement 37 38 97.3
branch 20 22 90.9
condition 32 43 74.4
subroutine 5 5 100.0
pod 0 1 0.0
total 94 109 86.2


line stmt bran cond sub pod time code
1 2     2   12 use strict;
  2         3  
  2         51  
2 2     2   8 use warnings;
  2         4  
  2         65  
3              
4             package Perl::PrereqScanner::Scanner::Perl5 1.025;
5             # ABSTRACT: scan for core Perl 5 language indicators of required modules
6              
7 2     2   10 use Moose;
  2         3  
  2         14  
8             with 'Perl::PrereqScanner::Scanner';
9              
10             #pod =head1 DESCRIPTION
11             #pod
12             #pod This scanner will look for the following indicators:
13             #pod
14             #pod =begin :list
15             #pod
16             #pod * plain lines beginning with C<use>, C<require>, or C<no> in your perl modules and scripts, including minimum perl version
17             #pod
18             #pod * regular inheritance declared with the C<base> and C<parent> pragmata
19             #pod
20             #pod =end :list
21             #pod
22             #pod Since Perl does not allow you to supply a version requirement with a
23             #pod C<require> statement, the scanner will check the statement after the
24             #pod C<require Module> to see if it is C<< Module->VERSION( minimum_version ); >>.
25             #pod
26             #pod In order to provide a minimum version, that method call must meet the
27             #pod following requirements:
28             #pod
29             #pod =begin :list
30             #pod
31             #pod * it must be the very next statement after C<require Module>. Nothing can separate them but whitespace and comments (and one semicolon).
32             #pod
33             #pod * C<Module> must be a bareword, and match the C<require> exactly.
34             #pod
35             #pod * C<minimum_version> must be a literal number, v-string, or single-quoted string. Double quotes are not allowed.
36             #pod
37             #pod =end :list
38             #pod
39             #pod =cut
40              
41             sub scan_for_prereqs {
42 265     265 0 579 my ($self, $ppi_doc, $req) = @_;
43              
44             # regular use, require, and no
45 265   100     671 my $includes = $ppi_doc->find('Statement::Include') || [];
46 265         138346 for my $node ( @$includes ) {
47             # minimum perl version
48 171 100       3085 if ( $node->version ) {
49 1         50 $req->add_minimum(perl => $node->version);
50 1         159 next;
51             }
52              
53             # inheritance
54 170 100       3803 if (grep { $_ eq $node->module } qw{ base parent }) {
  340         3662  
55             # rt#55713: skip arguments to base or parent, focus only on inheritance
56             my @meat = grep {
57 33 100       670 $_->isa('PPI::Token::QuoteLike::Words')
  39         1093  
58             || $_->isa('PPI::Token::Quote')
59             } $node->arguments;
60              
61 33         61 my @parents = map { $self->_q_contents($_) } @meat;
  33         99  
62 33         101 $req->add_minimum($_ => 0) for @parents;
63             }
64              
65             # regular modules
66 170 100       4001 my $version = $node->module_version ? $node->module_version->content : 0;
67              
68             # rt#55851: 'require $foo;' shouldn't add any prereq
69 170 100       7882 next unless $node->module;
70              
71             # See if the next statement after require is Module->VERSION(min):
72 167 100 100     3158 $version = $self->_check_required_version($node) || 0
      100        
73             if not $version and $node->type =~ /\A(?:require|use)\z/;
74              
75 167         826 $req->add_minimum($node->module, $version);
76             }
77             }
78              
79             # For "require Module", see if the next statement is Module->VERSION(min):
80             sub _check_required_version {
81 107     107   2226 my ($self, $node) = @_;
82              
83 107         321 my $next = $node->snext_sibling;
84              
85 107 100 100     2761 return unless $next and $next->class eq 'PPI::Statement';
86              
87 34         204 my ($invocant, $op, $method, $list, $too_much) = $next->schildren;
88              
89 34 50 100     494 return unless defined $list # need enough children
      66        
      66        
      66        
      66        
      100        
      66        
      66        
      33        
90             and $op->class eq 'PPI::Token::Operator'
91             and $op->content eq '->'
92             and $method->content eq 'VERSION'
93             and (not defined $too_much # but not too many children
94             or $too_much->content eq ';')
95             and $invocant->content eq $node->module
96             and $list->class eq 'PPI::Structure::List'
97             and $list->braces eq '()'
98             and $list->schildren == 1;
99              
100 21         1184 my $exp = $list->schild(0);
101              
102 21 100 66     206 return unless $exp->class eq 'PPI::Statement::Expression'
103             and $exp->schildren == 1;
104              
105 18         227 my $arg = $exp->schild(0);
106              
107 18 100 33     221 if ($arg->isa('PPI::Token::Number')) {
    50          
108 12         24 return $arg->content;
109             } elsif ($arg->isa('PPI::Token::Quote') and $arg->can('literal')) {
110 6         22 return $arg->literal;
111             }
112              
113 0           return; # No minimum version found
114             } # end _check_required_version
115              
116             1;
117              
118             __END__
119              
120             =pod
121              
122             =encoding UTF-8
123              
124             =head1 NAME
125              
126             Perl::PrereqScanner::Scanner::Perl5 - scan for core Perl 5 language indicators of required modules
127              
128             =head1 VERSION
129              
130             version 1.025
131              
132             =head1 DESCRIPTION
133              
134             This scanner will look for the following indicators:
135              
136             =over 4
137              
138             =item *
139              
140             plain lines beginning with C<use>, C<require>, or C<no> in your perl modules and scripts, including minimum perl version
141              
142             =item *
143              
144             regular inheritance declared with the C<base> and C<parent> pragmata
145              
146             =back
147              
148             Since Perl does not allow you to supply a version requirement with a
149             C<require> statement, the scanner will check the statement after the
150             C<require Module> to see if it is C<< Module->VERSION( minimum_version ); >>.
151              
152             In order to provide a minimum version, that method call must meet the
153             following requirements:
154              
155             =over 4
156              
157             =item *
158              
159             it must be the very next statement after C<require Module>. Nothing can separate them but whitespace and comments (and one semicolon).
160              
161             =item *
162              
163             C<Module> must be a bareword, and match the C<require> exactly.
164              
165             =item *
166              
167             C<minimum_version> must be a literal number, v-string, or single-quoted string. Double quotes are not allowed.
168              
169             =back
170              
171             =head1 PERL VERSION
172              
173             This library should run on perls released even a long time ago. It should work
174             on any version of perl released in the last five years.
175              
176             Although it may work on older versions of perl, no guarantee is made that the
177             minimum required version will not be increased. The version may be increased
178             for any reason, and there is no promise that patches will be accepted to lower
179             the minimum required perl.
180              
181             =head1 AUTHORS
182              
183             =over 4
184              
185             =item *
186              
187             Jerome Quelin
188              
189             =item *
190              
191             Ricardo Signes <cpan@semiotic.systems>
192              
193             =back
194              
195             =head1 COPYRIGHT AND LICENSE
196              
197             This software is copyright (c) 2009 by Jerome Quelin.
198              
199             This is free software; you can redistribute it and/or modify it under
200             the same terms as the Perl 5 programming language system itself.
201              
202             =cut