blib/lib/Dist/Zilla/Plugin/PkgVersion.pm

filter: Statementstmt 97.6% 123 / 126 Branchbran 85.5% 65 / 76 Conditioncond 70.0% 14 / 20 MC/DCmcdc 45.4% 5 / 11 Subroutinesub 100% 11 / 11 Podpod 0.0% 0 / 4 totaltotal 87.9% 218 / 248 CC 49 SCAR 29.2
CC
49
Cov
91%
munge_perl
31.2
__ANON__
7.3
BUILD
6.1
CRAP 18.5
« blib/lib/Dist/Zilla/Util/AuthorDeps.pm ↑ Summary blib/lib/Dist/Zilla/Role/PluginBundle/Easy.pm »
1 package Dist::Zilla::Plugin::PkgVersion 6.040;
2 # ABSTRACT: add a $VERSION to your packages
3  
4 10 ▶use Moose;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 10 with(
6 'Dist::Zilla::Role::FileMunger',
7 'Dist::Zilla::Role::FileFinderUser' => {
8 default_finders => [ ':InstallModules', ':ExecFiles' ],
9 },
10 'Dist::Zilla::Role::PPI',
11 );
12  
13 10 ▶use Dist::Zilla::Pragmas;
Subroutine BEGIN: called CC=1 SCAR=0.0
14  
15 10 ▶use namespace::autoclean;
Subroutine BEGIN: called CC=1 SCAR=0.0
16  
17 #pod =head1 SYNOPSIS
18 #pod
19 #pod in dist.ini
20 #pod
21 #pod [PkgVersion]
22 #pod
23 #pod =head1 DESCRIPTION
24 #pod
25 #pod This plugin will add lines like the following to each package in each Perl
26 #pod module or program (more or less) within the distribution:
27 #pod
28 #pod $MyModule::VERSION = '0.001';
29 #pod
30 #pod or
31 #pod
32 #pod { our $VERSION = '0.001'; }
33 #pod
34 #pod ...where 0.001 is the version of the dist, and MyModule is the name of the
35 #pod package being given a version. (In other words, it always uses fully-qualified
36 #pod names to assign versions.)
37 #pod
38 #pod It will skip any package declaration that includes a newline between the
39 #pod C<package> keyword and the package name, like:
40 #pod
41 #pod package
42 #pod Foo::Bar;
43 #pod
44 #pod This sort of declaration is also ignored by the CPAN toolchain, and is
45 #pod typically used when doing monkey patching or other tricky things.
46 #pod
47 #pod =attr die_on_existing_version
48 #pod
49 #pod If true, then when PkgVersion sees an existing C<$VERSION> assignment, it will
50 #pod throw an exception rather than skip the file. This attribute defaults to
51 #pod false.
52 #pod
53 #pod =attr die_on_line_insertion
54 #pod
55 #pod By default, PkgVersion looks for a blank line after each C<package> statement.
56 #pod If it finds one, it inserts the C<$VERSION> assignment on that line. If it
57 #pod doesn't, it will insert a new line, which means the shipped copy of the module
58 #pod will have different line numbers (off by one) than the source. If
59 #pod C<die_on_line_insertion> is true, PkgVersion will raise an exception rather
60 #pod than insert a new line.
61 #pod
62 #pod =attr use_package
63 #pod
64 #pod This option, if true, will not insert an assignment to C<$VERSION> but will
65 #pod replace the existing C<package> declaration with one that includes a version
66 #pod like:
67 #pod
68 #pod package Module::Name 0.001;
69 #pod
70 #pod =attr use_our
71 #pod
72 #pod The idea here was to insert C<< { our $VERSION = '0.001'; } >> instead of C<<
73 #pod $Module::Name::VERSION = '0.001'; >>. It turns out that this causes problems
74 #pod with some analyzers. Use of this feature is deprecated.
75 #pod
76 #pod Something else will replace it in the future.
77 #pod
78 #pod =attr use_begin
79 #pod
80 #pod If true, the version assignment is wrapped in a BEGIN block. This may help in
81 #pod rare cases, such as when DynaLoader has to be called at BEGIN time, and
82 #pod requires VERSION. This option should be needed rarely.
83 #pod
84 #pod Also note that assigning to C<$VERSION> before the module has finished
85 #pod compiling can lead to confused behavior with attempts to determine whether a
86 #pod module was successfully loaded on perl v5.8.
87 #pod
88 #pod =attr finder
89 #pod
90 #pod =for stopwords FileFinder
91 #pod
92 #pod This is the name of a L<FileFinder|Dist::Zilla::Role::FileFinder> for finding
93 #pod modules to edit. The default value is C<:InstallModules> and C<:ExecFiles>;
94 #pod this option can be used more than once.
95 #pod
96 #pod Other predefined finders are listed in
97 #pod L<Dist::Zilla::Role::FileFinderUser/default_finders>.
98 #pod You can define your own with the
99 #pod L<[FileFinder::ByName]|Dist::Zilla::Plugin::FileFinder::ByName> and
100 #pod L<[FileFinder::Filter]|Dist::Zilla::Plugin::FileFinder::Filter> plugins.
101 #pod
102 #pod =cut
103  
104 23 ▶sub BUILD {
Subroutine BUILD: called CC=5 SCAR=18.1
Pod undocumented
105 23 my ($self) = @_;
106 23 ▶ $self->log("use_our option to PkgVersion is deprecated and will be removed")
Branch: 1 branch
BranchTrueFalseTotal
if $self->use_our 3 20 23
107 if $self->use_our;
108  
109 23 ▶ if ($self->use_package && ($self->use_our || $self->use_begin)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->use_package and $self->use_our || $self->use_begin) 0 23 23
Condition50%3/6
$self->use_package and $self->use_our || $self->use_begin
!ll&&!rl&&r
2120
$self->use_our or $self->use_begin
l!l&&r!l&&!r
002
MC/DC0%0/3
$self->use_package and $self->use_our || $self->use_begin
$self->use_package $self->use_our $self->use_begin
Truth table50%2/4
A and B or C
A= $self->use_packageB= $self->use_ourC= $self->use_begin
ABCresult
0XX0
1000
11X1
1011
110 0 $self->log_fatal("use_package and (use_our or use_begin) are not compatible");
111 }
112 }
113  
114 23 ▶sub munge_files {
Subroutine munge_files: called CC=2 SCAR=6.9
Pod undocumented
115 23 my ($self) = @_;
116  
117 23 $self->munge_file($_) for @{ $self->found_files };
118 }
119  
120 57 ▶sub munge_file {
Subroutine munge_file: called CC=3 SCAR=11.4
Pod undocumented
121 57 my ($self, $file) = @_;
122  
123 57 ▶ if ($file->is_bytes) {
Branch: 1 branch
BranchTrueFalseTotal
if ($file->is_bytes) 1 56 57
124 1 $self->log_debug($file->name . " has 'bytes' encoding, skipping...");
125 1 return;
126 }
127  
128 56 ▶ if ($file->name =~ /\.pod$/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($file->name =~ /\.pod$/u) 0 56 56
129 0 $self->log_debug($file->name . " is a pod file, skipping...");
130 0 return;
131 }
132  
133 56 return $self->munge_perl($file);
134 }
135  
136 10 has die_on_existing_version => (
137 is => 'ro',
138 isa => 'Bool',
139 default => 0,
140 );
141  
142 10 has die_on_line_insertion => (
143 is => 'ro',
144 isa => 'Bool',
145 default => 0,
146 );
147  
148 10 has use_package => (
149 is => 'ro',
150 isa => 'Bool',
151 default => 0,
152 );
153  
154 10 has use_our => (
155 is => 'ro',
156 isa => 'Bool',
157 default => 0,
158 );
159  
160 10 has use_begin => (
161 is => 'ro',
162 isa => 'Bool',
163 default => 0,
164 );
165  
166 45 ▶sub _version_assignment {
Subroutine _version_assignment: called CC=4 SCAR=13.9
167 45 my ($self, $package, $version) = @_;
168  
169 # the \x20 hack is here so that when we scan *this* document we don't find
170 # an assignment to version; it shouldn't be needed, but it's been annoying
171 # enough in the past that I'm keeping it here until tests are better
172 45 ▶ my $perl = $self->use_our
Branch: 1 branch
BranchTrueFalseTotal
$self->use_our ? : 7 38 45
173 ? "our \$VERSION\x20=\x20'$version';"
174 : "\$$package\::VERSION\x20=\x20'$version';";
175  
176 return
177 45 ▶ $self->use_begin ? "BEGIN { $perl }"
Branch: 2 branches
BranchTrueFalseTotal
$self->use_begin ? : 7 38 45
$self->use_our ? : 5 33 38
178 : $self->use_our ? "{ $perl }"
179 : $perl;
180 }
181  
182 # PPI does not understand the perl v5.38 class syntax. It turns a class
183 # block into one opaque PPI::Statement, and any package statements after it
184 # in the file are swallowed into that statement too. We can't version the
185 # class, but we can say so instead of silently shipping unversioned code.
186 # This spots the `class NAME` shape without misfiring on `class->method`.
187 56 ▶sub _class_declarations ($self, $document) {
Subroutine _class_declarations: called CC=2 SCAR=7.0
188 450 ▶ my $stmts = $document->find(sub {
Subroutine __ANON__: called CC=7 SCAR=19.9
189 450 my ($doc, $elem) = @_;
190 450 ▶ return unless ref $elem eq 'PPI::Statement';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $elem eq "PPI::Statement" 406 44 450
191 44 my ($kw, $name) = $elem->schildren;
192 44 ▶ return unless $kw && $kw->isa('PPI::Token::Word') && $kw->content eq 'class';
Branch: 1 branch
BranchTrueFalseTotal
unless $kw and $kw->isa("PPI::Token::Word") and $kw->content eq "class" 43 1 44
Condition83%5/6
$kw and $kw->isa("PPI::Token::Word") and $kw->content eq "class"
!ll&&!rl&&r
3851
$kw and $kw->isa("PPI::Token::Word")
!ll&&!rl&&r
0386
MC/DC66%2/3
$kw and $kw->isa("PPI::Token::Word") and $kw->content eq "class"
$kw $kw->isa("PPI::Token::Word") $kw->content eq "class"
Truth table75%3/4
A and B and C
A= $kwB= $kw->isa("PPI::Token::Word")C= $kw->content eq "class"
ABCresult
0XX0
10X0
1100
1111
193 1 ▶ return unless $name && $name->isa('PPI::Token::Word');
Branch: 1 branch
BranchTrueFalseTotal
unless $name and $name->isa("PPI::Token::Word") 0 1 1
Condition33%1/3
$name and $name->isa("PPI::Token::Word")
!ll&&!rl&&r
001
MC/DC0%0/2
$name and $name->isa("PPI::Token::Word")
$name $name->isa("PPI::Token::Word")
Truth table33%1/3
A and B
A= $nameB= $name->isa("PPI::Token::Word")
ABresult
0X0
100
111
194 1 return 1;
195 56 });
196  
197 56 ▶ return map {; ($_->schildren)[1]->content } @{ $stmts || [] };
Condition100%2/2
$stmts || []
l!l
155
MC/DC100%1/1
$stmts || []
$stmts
Truth table100%2/2
A
A= $stmts
Aresult
11
00
198 }
199  
200 56 ▶sub munge_perl {
Subroutine munge_perl: called CC=31 SCAR=34.4
Pod undocumented
201 56 my ($self, $file) = @_;
202  
203 56 my $version = $self->zilla->version;
204  
205 56 require version;
206 56 ▶ Carp::croak("invalid characters in version")
Branch: 1 branch
BranchTrueFalseTotal
unless version::is_lax($version) 0 56 56
207 unless version::is_lax($version);
208  
209 56 my $document = $self->ppi_document_for_file($file);
210  
211 56 for my $class ($self->_class_declarations($document)) {
212 1 $self->log([
213 '%s declares class %s, which will not get a version: PPI cannot parse class syntax yet',
214 $file->name,
215 $class,
216 ]);
217 }
218  
219 56 my $package_stmts = $document->find('PPI::Statement::Package');
220 56 ▶ unless ($package_stmts) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($package_stmts) 5 51 56
221 5 $self->log_debug([ 'skipping %s: no package statement found', $file->name ]);
222 5 return;
223 }
224  
225 51 ▶ if ($self->document_assigns_to_variable($document, '$VERSION')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->document_assigns_to_variable($document, "\$VERSION")) 6 45 51
226 6 ▶ if ($self->die_on_existing_version) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->die_on_existing_version) 1 5 6
227 1 $self->log_fatal([ 'existing assignment to $VERSION in %s', $file->name ]);
228 }
229  
230 5 $self->log([ 'skipping %s: assigns to $VERSION', $file->name ]);
231 5 return;
232 }
233  
234 45 my %seen_pkg;
235  
236 45 my $munged = 0;
237 45 STATEMENT: for my $stmt (@$package_stmts) {
238 54 my $package = $stmt->namespace;
239 54 ▶ if ($seen_pkg{ $package }++) {
Branch: 1 branch
BranchTrueFalseTotal
if ($seen_pkg{$package}++) 1 53 54
240 1 $self->log([ 'skipping package re-declaration for %s', $package ]);
241 1 next;
242 }
243  
244 53 ▶ if ($stmt->content =~ /package\s*(?:#.*)?\n\s*\Q$package/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($stmt->content =~ /package\s*(?:#.*)?\n\s*\Q$package\E/u) 2 51 53
245 2 $self->log([ 'skipping private package %s in %s', $package, $file->name ]);
246 2 next;
247 }
248  
249 51 ▶ $self->log("non-ASCII package name is likely to cause problems")
Branch: 1 branch
BranchTrueFalseTotal
if $package =~ /\P{ASCII}/u 0 51 51
250 if $package =~ /\P{ASCII}/;
251  
252 51 ▶ $self->log("non-ASCII version is likely to cause problems")
Branch: 1 branch
BranchTrueFalseTotal
if $version =~ /\P{ASCII}/u 0 51 51
253 if $version =~ /\P{ASCII}/;
254  
255 51 ▶ if ($self->use_package) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->use_package) 12 39 51
256 12 ▶ my $version_token = $version =~ m/\.\d+\./
Branch: 1 branch
BranchTrueFalseTotal
$version =~ /\.\d+\./u ? : 6 6 12
257 ? PPI::Token::Number::Version->new(version->parse($version)->normal)
258 : PPI::Token::Number->new($version)
259 ;
260  
261 12 ▶ if (my ($block) = grep {; $_->isa('PPI::Structure::Block') } $stmt->schildren) {
Branch: 1 branch
BranchTrueFalseTotal
if (my($block) = grep({$_->isa("PPI::Structure::Block");} $stmt->schildren)) 4 8 12
262 # Okay, we've encountered `package NAME BLOCK` and want to turn it into
263 # `package NAME VERSION BLOCK` but, to quote the PPI documentation,
264 # "we're on our own here".
265 #
266 # This will also preclude us from adding "# TRIAL" because where would
267 # it go? Look, a block package should (in my opinion) not be the only
268 # or top-level package in a file, so the TRIAL comment can be
269 # elsewhere. -- rjbs, 2021-06-12
270 #
271 # First off, let's make sure we do not already have a version. If the
272 # "version" has a "{" in it, it's just the block, and we're good.
273 # Otherwise, it's going to be a real version and we need to skip.
274 4 ▶ if ($stmt->version !~ /\{/) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($stmt->version =~ /\{/u) 2 2 4
275 2 $self->log([
276 "skipping package %s with version %s declared",
277 $stmt->namespace,
278 $stmt->version,
279 ]);
280 2 next STATEMENT;
281 }
282  
283 # Okay, there's a block (which we have in $block) but no version. So,
284 # we stick a Number / Number::Version in front of the block, then a
285 # space between them.
286 2 $block->insert_before( $version_token );
287 2 $block->insert_before( PPI::Token::Whitespace->new(q{ }) );
288 2 $munged = 1;
289 2 next STATEMENT;
290 }
291  
292 # Now, it's not got a block, but does it already have a version?
293 8 ▶ if (length $stmt->version) {
Branch: 1 branch
BranchTrueFalseTotal
if (length $stmt->version) 2 6 8
294 2 $self->log([
295 "skipping package %s with version %s declared",
296 $stmt->namespace,
297 $stmt->version,
298 ]);
299 2 next STATEMENT;
300 }
301  
302 # Oh, good! It's just a normal `package NAME` and we are going to add
303 # VERSION to it. This is stupid, but gets the job done.
304 6 my $perl = sprintf 'package %s %s;', $package, $version_token->content;
305 6 ▶ $perl .= ' # TRIAL' if $self->zilla->is_trial;
Branch: 1 branch
BranchTrueFalseTotal
if $self->zilla->is_trial 0 6 6
306  
307 6 my $newstmt = PPI::Token::Unknown->new($perl);
308 6 ▶ Carp::carp("error inserting version in " . $file->name)
Branch: 1 branch
BranchTrueFalseTotal
unless $stmt->parent->__replace_child($stmt, $newstmt) 0 6 6
309 unless $stmt->parent->__replace_child($stmt, $newstmt);
310 6 $munged = 1;
311 6 next STATEMENT;
312 }
313  
314 # the \x20 hack is here so that when we scan *this* document we don't find
315 # an assignment to version; it shouldn't be needed, but it's been annoying
316 # enough in the past that I'm keeping it here until tests are better
317 39 my $perl = $self->_version_assignment($package, $version);
318 39 ▶ $self->zilla->is_trial
Branch: 1 branch
BranchTrueFalseTotal
$self->zilla->is_trial and $perl .= ' # TRIAL' 7 32 39
319 and $perl .= ' # TRIAL';
320  
321 39 my $clean_version = $version =~ tr/_//dr;
322 39 ▶ if ($version ne $clean_version) {
Branch: 1 branch
BranchTrueFalseTotal
if ($version ne $clean_version) 6 33 39
323 6 $perl .= "\n" . $self->_version_assignment($package, $clean_version);
324 }
325  
326 $self->log_debug([
327 39 'adding $VERSION assignment to %s in %s',
328 $package,
329 $file->name,
330 ]);
331  
332 39 my $blank;
333  
334 {
335 39 my $curr = $stmt;
336 39 while (1) {
337 # avoid bogus locations due to insert_after
338 45 ▶ $document->flush_locations if $munged;
Branch: 1 branch
BranchTrueFalseTotal
if $munged 4 41 45
339 45 my $curr_line_number = $curr->line_number + 1;
340 808 ▶ my $find = $document->find(sub {
Subroutine __ANON__: called CC=2 SCAR=6.9
341 808 my $line = $_[1]->line_number;
342 808 ▶ return $line > $curr_line_number ? undef : $line == $curr_line_number;
Branch: 1 branch
BranchTrueFalseTotal
$line > $curr_line_number ? : 167 641 808
343 45 });
344  
345 45 ▶ last unless $find and @$find == 1;
Branch: 1 branch
BranchTrueFalseTotal
unless $find and @$find == 1 10 35 45
Condition100%3/3
$find and @$find == 1
!ll&&!rl&&r
1935
MC/DC100%2/2
$find and @$find == 1
$find @$find == 1
Truth table100%3/3
A and B
A= $findB= @$find == 1
ABresult
0X0
100
111
346  
347 35 ▶ if ($find->[0]->isa('PPI::Token::Comment')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($find->[0]->isa("PPI::Token::Comment")) 6 29 35
348 6 $curr = $find->[0];
349 6 next;
350 }
351  
352 29 ▶ if ("$find->[0]" =~ /\A\s*\z/) {
Branch: 1 branch
BranchTrueFalseTotal
if ("$find->[0]" =~ /\A\s*\z/u) 28 1 29
353 28 $blank = $find->[0];
354 }
355  
356 29 last;
357 }
358 }
359  
360 39 ▶ $perl = $blank ? "$perl\n" : "\n$perl";
Branch: 1 branch
BranchTrueFalseTotal
$blank ? : 28 11 39
361  
362 # Why can't I use PPI::Token::Unknown? -- rjbs, 2014-01-11
363 39 my $bogus_token = PPI::Token::Comment->new($perl);
364  
365 39 ▶ if ($blank) {
Branch: 1 branch
BranchTrueFalseTotal
if ($blank) { } 28 11 39
366 28 ▶ Carp::carp("error inserting version in " . $file->name)
Branch: 1 branch
BranchTrueFalseTotal
unless $blank->insert_after($bogus_token) 0 28 28
367 unless $blank->insert_after($bogus_token);
368 28 $blank->delete;
369 } else {
370 11 ▶ my $method = $self->die_on_line_insertion ? 'log_fatal' : 'log';
Branch: 1 branch
BranchTrueFalseTotal
$self->die_on_line_insertion ? : 0 11 11
371 11 $self->$method([
372 'no blank line for $VERSION after package %s statement in %s line %s',
373 $stmt->namespace,
374 $file->name,
375 $stmt->line_number,
376 ]);
377  
378 11 ▶ Carp::carp("error inserting version in " . $file->name)
Branch: 1 branch
BranchTrueFalseTotal
unless $stmt->insert_after($bogus_token) 0 11 11
379 unless $stmt->insert_after($bogus_token);
380 }
381  
382 39 $munged = 1;
383 }
384  
385 # the document is no longer correct; it must be reparsed before it can be
386 # used again, so we can't just save_ppi_document_to_file
387 # Maybe we want a way to clear the cache for the old form, though...
388 # -- rjbs, 2016-04-24
389 45 ▶ $file->content($document->serialize) if $munged;
Branch: 1 branch
BranchTrueFalseTotal
if $munged 41 4 45
390 45 return;
391 }
392  
393 10 __PACKAGE__->meta->make_immutable;
394 10 1;
395  
396 #pod =head1 SEE ALSO
397 #pod
398 #pod Core Dist::Zilla plugins:
399 #pod L<PodVersion|Dist::Zilla::Plugin::PodVersion>,
400 #pod L<AutoVersion|Dist::Zilla::Plugin::AutoVersion>,
401 #pod L<NextRelease|Dist::Zilla::Plugin::NextRelease>.
402 #pod
403 #pod Other Dist::Zilla plugins:
404 #pod L<OurPkgVersion|Dist::Zilla::Plugin::OurPkgVersion> inserts version
405 #pod numbers using C<our $VERSION = '...';> and without changing line numbers
406 #pod
407 #pod =cut
408  
409 __END__
« blib/lib/Dist/Zilla/Util/AuthorDeps.pm ↑ Summary blib/lib/Dist/Zilla/Role/PluginBundle/Easy.pm »