CPAN/Meta.pm

filter: Statementstmt 97.5% 198 / 203 Branchbran 65.7% 46 / 70 Conditioncond 73.6% 14 / 19 MC/DCmcdc 50.0% 5 / 10 Subroutinesub 100% 41 / 41 Podpod 75.0% 15 / 20 totaltotal 87.8% 319 / 363 CC 52 SCAR 13.2
CC
52
Cov
88%
save
7.3
should_index_file
7.0
as_string
6.1
CRAP 3.7
« CPAN/Meta/Merge.pm ↑ Summary CPAN/Meta/History.pm »
1 22 ▶use 5.008001;
Subroutine BEGIN: called CC=1 SCAR=0.0
2 22 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 22 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 package CPAN::Meta;
5  
6 22 our $VERSION = '2.150015';
7  
8 #pod =head1 SYNOPSIS
9 #pod
10 #pod use v5.10;
11 #pod use strict;
12 #pod use warnings;
13 #pod use CPAN::Meta;
14 #pod use Module::Load;
15 #pod
16 #pod my $meta = CPAN::Meta->load_file('META.json');
17 #pod
18 #pod printf "testing requirements for %s version %s\n",
19 #pod $meta->name,
20 #pod $meta->version;
21 #pod
22 #pod my $prereqs = $meta->effective_prereqs;
23 #pod
24 #pod for my $phase ( qw/configure runtime build test/ ) {
25 #pod say "Requirements for $phase:";
26 #pod my $reqs = $prereqs->requirements_for($phase, "requires");
27 #pod for my $module ( sort $reqs->required_modules ) {
28 #pod my $status;
29 #pod if ( eval { load $module unless $module eq 'perl'; 1 } ) {
30 #pod my $version = $module eq 'perl' ? $] : $module->VERSION;
31 #pod $status = $reqs->accepts_module($module, $version)
32 #pod ? "$version ok" : "$version not ok";
33 #pod } else {
34 #pod $status = "missing"
35 #pod };
36 #pod say " $module ($status)";
37 #pod }
38 #pod }
39 #pod
40 #pod =head1 DESCRIPTION
41 #pod
42 #pod Software distributions released to the CPAN include a F<META.json> or, for
43 #pod older distributions, F<META.yml>, which describes the distribution, its
44 #pod contents, and the requirements for building and installing the distribution.
45 #pod The data structure stored in the F<META.json> file is described in
46 #pod L<CPAN::Meta::Spec>.
47 #pod
48 #pod CPAN::Meta provides a simple class to represent this distribution metadata (or
49 #pod I<distmeta>), along with some helpful methods for interrogating that data.
50 #pod
51 #pod The documentation below is only for the methods of the CPAN::Meta object. For
52 #pod information on the meaning of individual fields, consult the spec.
53 #pod
54 #pod =cut
55  
56 22 ▶use Carp qw(carp croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
57 22 ▶use CPAN::Meta::Feature;
Subroutine BEGIN: called CC=1 SCAR=0.0
58 22 ▶use CPAN::Meta::Prereqs;
Subroutine BEGIN: called CC=1 SCAR=0.0
59 22 ▶use CPAN::Meta::Converter;
Subroutine BEGIN: called CC=1 SCAR=0.0
60 22 ▶use CPAN::Meta::Validator;
Subroutine BEGIN: called CC=1 SCAR=0.0
61 22 ▶use Parse::CPAN::Meta 1.4414 ();
Subroutine BEGIN: called CC=1 SCAR=0.0
62  
63 22 ▶BEGIN { *_dclone = \&CPAN::Meta::Converter::_dclone }
Subroutine BEGIN: called CC=1 SCAR=0.0
64  
65 #pod =head1 STRING DATA
66 #pod
67 #pod The following methods return a single value, which is the value for the
68 #pod corresponding entry in the distmeta structure. Values should be either undef
69 #pod or strings.
70 #pod
71 #pod =for :list
72 #pod * abstract
73 #pod * description
74 #pod * dynamic_config
75 #pod * generated_by
76 #pod * name
77 #pod * release_status
78 #pod * version
79 #pod
80 #pod =cut
81  
82 22 ▶BEGIN {
Subroutine BEGIN: called CC=2 SCAR=6.9
83 22 my @STRING_READERS = qw(
84 abstract
85 description
86 dynamic_config
87 generated_by
88 name
89 release_status
90 version
91 );
92  
93 22 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
94 22 for my $attr (@STRING_READERS) {
95 154 ▶ *$attr = sub { $_[0]{ $attr } };
Subroutine __ANON__: called CC=1 SCAR=0.0
96 }
97 }
98  
99 #pod =head1 LIST DATA
100 #pod
101 #pod These methods return lists of string values, which might be represented in the
102 #pod distmeta structure as arrayrefs or scalars:
103 #pod
104 #pod =for :list
105 #pod * authors
106 #pod * keywords
107 #pod * licenses
108 #pod
109 #pod The C<authors> and C<licenses> methods may also be called as C<author> and
110 #pod C<license>, respectively, to match the field name in the distmeta structure.
111 #pod
112 #pod =cut
113  
114 22 ▶BEGIN {
Subroutine BEGIN: called CC=2 SCAR=7.1
115 22 my @LIST_READERS = qw(
116 author
117 keywords
118 license
119 );
120  
121 22 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
122 22 for my $attr (@LIST_READERS) {
123 6 ▶ *$attr = sub {
Subroutine __ANON__: called CC=3 SCAR=12.0
124 6 my $value = $_[0]{ $attr };
125 6 ▶ croak "$attr must be called in list context"
Branch: 1 branch
BranchTrueFalseTotal
unless wantarray 0 6 6
126 unless wantarray;
127 6 ▶ return @{ _dclone($value) } if ref $value;
Branch: 1 branch
BranchTrueFalseTotal
if ref $value 6 0 6
128 0 return $value;
129 66 };
130 }
131 }
132  
133 2 ▶sub authors { $_[0]->author }
Subroutine authors: called CC=1 SCAR=0.0
Pod undocumented
134 1 ▶sub licenses { $_[0]->license }
Subroutine licenses: called CC=1 SCAR=0.0
Pod undocumented
135  
136 #pod =head1 MAP DATA
137 #pod
138 #pod These readers return hashrefs of arbitrary unblessed data structures, each
139 #pod described more fully in the specification:
140 #pod
141 #pod =for :list
142 #pod * meta_spec
143 #pod * resources
144 #pod * provides
145 #pod * no_index
146 #pod * prereqs
147 #pod * optional_features
148 #pod
149 #pod =cut
150  
151 22 ▶BEGIN {
Subroutine BEGIN: called CC=2 SCAR=6.9
152 22 my @MAP_READERS = qw(
153 meta-spec
154 resources
155 provides
156 no_index
157  
158 prereqs
159 optional_features
160 );
161  
162 22 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
163 22 for my $attr (@MAP_READERS) {
164 132 (my $subname = $attr) =~ s/-/_/;
165 30 ▶ *$subname = sub {
Subroutine __ANON__: called CC=2 SCAR=6.9
166 30 my $value = $_[0]{ $attr };
167 30 ▶ return _dclone($value) if $value;
Branch: 1 branch
BranchTrueFalseTotal
if $value 26 4 30
168 4 return {};
169 132 };
170 }
171 }
172  
173 #pod =head1 CUSTOM DATA
174 #pod
175 #pod A list of custom keys are available from the C<custom_keys> method and
176 #pod particular keys may be retrieved with the C<custom> method.
177 #pod
178 #pod say $meta->custom($_) for $meta->custom_keys;
179 #pod
180 #pod If a custom key refers to a data structure, a deep clone is returned.
181 #pod
182 #pod =cut
183  
184 1 ▶sub custom_keys {
Subroutine custom_keys: called CC=1 SCAR=0.0
Pod undocumented
185 1 return grep { /^x_/i } keys %{$_[0]};
186 }
187  
188 3 ▶sub custom {
Subroutine custom: called CC=2 SCAR=6.9
Pod undocumented
189 3 my ($self, $attr) = @_;
190 3 my $value = $self->{$attr};
191 3 ▶ return _dclone($value) if ref $value;
Branch: 1 branch
BranchTrueFalseTotal
if ref $value 2 1 3
192 1 return $value;
193 }
194  
195 #pod =method new
196 #pod
197 #pod my $meta = CPAN::Meta->new($distmeta_struct, \%options);
198 #pod
199 #pod Returns a valid CPAN::Meta object or dies if the supplied metadata hash
200 #pod reference fails to validate. Older-format metadata will be up-converted to
201 #pod version 2 if they validate against the original stated specification.
202 #pod
203 #pod It takes an optional hashref of options. Valid options include:
204 #pod
205 #pod =over
206 #pod
207 #pod =item *
208 #pod
209 #pod lazy_validation -- if true, new will attempt to convert the given metadata
210 #pod to version 2 before attempting to validate it. This means than any
211 #pod fixable errors will be handled by CPAN::Meta::Converter before validation.
212 #pod (Note that this might result in invalid optional data being silently
213 #pod dropped.) The default is false.
214 #pod
215 #pod =back
216 #pod
217 #pod =cut
218  
219 76 ▶sub _new {
Subroutine _new: called CC=5 SCAR=16.9
220 76 my ($class, $struct, $options) = @_;
221 76 my $self;
222  
223 76 ▶ if ( $options->{lazy_validation} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($options->{'lazy_validation'}) { } 70 6 76
224 # try to convert to a valid structure; if succeeds, then return it
225 70 my $cmc = CPAN::Meta::Converter->new( $struct );
226 70 $self = $cmc->convert( version => 2 ); # valid or dies
227 70 return bless $self, $class;
228 }
229 else {
230 # validate original struct
231 6 my $cmv = CPAN::Meta::Validator->new( $struct );
232 6 ▶ unless ( $cmv->is_valid) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($cmv->is_valid) 0 6 6
233 0 die "Invalid metadata structure. Errors: "
234 . join(", ", $cmv->errors) . "\n";
235 }
236 }
237  
238 # up-convert older spec versions
239 6 ▶ my $version = $struct->{'meta-spec'}{version} || '1.0';
Condition50%1/2
$struct->{'meta-spec'}{'version'} || '1.0'
l!l
60
MC/DC0%0/1
$struct->{'meta-spec'}{'version'} || '1.0'
$struct->{'meta-spec'}{'version'}
Truth table50%1/2
A
A= $struct->{'meta-spec'}{'version'}
Aresult
11
00
240 6 ▶ if ( $version == 2 ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($version == 2) { } 6 0 6
241 6 $self = $struct;
242 }
243 else {
244 0 my $cmc = CPAN::Meta::Converter->new( $struct );
245 0 $self = $cmc->convert( version => 2 );
246 }
247  
248 6 return bless $self, $class;
249 }
250  
251 11 ▶sub new {
Subroutine new: called CC=2 SCAR=7.0
Pod documented
252 11 my ($class, $struct, $options) = @_;
253 11 my $self = eval { $class->_new($struct, $options) };
254 11 ▶ croak($@) if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 11 11
255 11 return $self;
256 }
257  
258 #pod =method create
259 #pod
260 #pod my $meta = CPAN::Meta->create($distmeta_struct, \%options);
261 #pod
262 #pod This is same as C<new()>, except that C<generated_by> and C<meta-spec> fields
263 #pod will be generated if not provided. This means the metadata structure is
264 #pod assumed to otherwise follow the latest L<CPAN::Meta::Spec>.
265 #pod
266 #pod =cut
267  
268 1 ▶sub create {
Subroutine create: called CC=5 SCAR=17.3
Pod documented
269 1 my ($class, $struct, $options) = @_;
270 1 ▶ my $version = __PACKAGE__->VERSION || 2;
Condition50%1/2
__PACKAGE__->VERSION || 2
l!l
10
MC/DC0%0/1
__PACKAGE__->VERSION || 2
__PACKAGE__->VERSION
Truth table50%1/2
A
A= __PACKAGE__->VERSION
Aresult
11
00
271 1 ▶ $struct->{generated_by} ||= __PACKAGE__ . " version $version" ;
Condition50%1/2
$struct->{"generated_by"} ||= 'CPAN::Meta' . " version $version"
l!l
10
MC/DC0%0/1
$struct->{"generated_by"} ||= 'CPAN::Meta' . " version $version"
$struct->{"generated_by"}
Truth table50%1/2
A
A= $struct->{"generated_by"}
Aresult
11
00
272 1 ▶ $struct->{'meta-spec'}{version} ||= int($version);
Condition33%1/3
$struct->{"meta-spec"}{"version"} ||= int $version
l!l&&r!l&&!r
100
MC/DC0%0/2
$struct->{"meta-spec"}{"version"} ||= int $version
$struct->{"meta-spec"}{"version"} int $version
Truth table33%1/3
A ||= B
A= $struct->{"meta-spec"}{"version"}B= int $version
ABresult
1X1
011
000
273 1 my $self = eval { $class->_new($struct, $options) };
274 1 ▶ croak ($@) if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 1 1
275 1 return $self;
276 }
277  
278 #pod =method load_file
279 #pod
280 #pod my $meta = CPAN::Meta->load_file($distmeta_file, \%options);
281 #pod
282 #pod Given a pathname to a file containing metadata, this deserializes the file
283 #pod according to its file suffix and constructs a new C<CPAN::Meta> object, just
284 #pod like C<new()>. It will die if the deserialized version fails to validate
285 #pod against its stated specification version.
286 #pod
287 #pod It takes the same options as C<new()> but C<lazy_validation> defaults to
288 #pod true.
289 #pod
290 #pod =cut
291  
292 22 ▶sub load_file {
Subroutine load_file: called CC=4 SCAR=14.2
Pod documented
293 22 my ($class, $file, $options) = @_;
294 22 ▶ $options->{lazy_validation} = 1 unless exists $options->{lazy_validation};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $options->{"lazy_validation"} 22 0 22
295  
296 22 ▶ croak "load_file() requires a valid, readable filename"
Branch: 1 branch
BranchTrueFalseTotal
unless -r $file 0 22 22
297 unless -r $file;
298  
299 22 my $self;
300 22 eval {
301 22 my $struct = Parse::CPAN::Meta->load_file( $file );
302 22 $self = $class->_new($struct, $options);
303 };
304 22 ▶ croak($@) if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 22 22
305 22 return $self;
306 }
307  
308 #pod =method load_yaml_string
309 #pod
310 #pod my $meta = CPAN::Meta->load_yaml_string($yaml, \%options);
311 #pod
312 #pod This method returns a new CPAN::Meta object using the first document in the
313 #pod given YAML string. In other respects it is identical to C<load_file()>.
314 #pod
315 #pod =cut
316  
317 14 ▶sub load_yaml_string {
Subroutine load_yaml_string: called CC=3 SCAR=11.1
Pod documented
318 14 my ($class, $yaml, $options) = @_;
319 14 ▶ $options->{lazy_validation} = 1 unless exists $options->{lazy_validation};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $options->{"lazy_validation"} 14 0 14
320  
321 14 my $self;
322 14 eval {
323 14 my ($struct) = Parse::CPAN::Meta->load_yaml_string( $yaml );
324 14 $self = $class->_new($struct, $options);
325 };
326 14 ▶ croak($@) if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 14 14
327 14 return $self;
328 }
329  
330 #pod =method load_json_string
331 #pod
332 #pod my $meta = CPAN::Meta->load_json_string($json, \%options);
333 #pod
334 #pod This method returns a new CPAN::Meta object using the structure represented by
335 #pod the given JSON string. In other respects it is identical to C<load_file()>.
336 #pod
337 #pod =cut
338  
339 27 ▶sub load_json_string {
Subroutine load_json_string: called CC=3 SCAR=11.1
Pod documented
340 27 my ($class, $json, $options) = @_;
341 27 ▶ $options->{lazy_validation} = 1 unless exists $options->{lazy_validation};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $options->{"lazy_validation"} 27 0 27
342  
343 27 my $self;
344 27 eval {
345 27 my $struct = Parse::CPAN::Meta->load_json_string( $json );
346 27 $self = $class->_new($struct, $options);
347 };
348 27 ▶ croak($@) if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 27 27
349 27 return $self;
350 }
351  
352 #pod =method load_string
353 #pod
354 #pod my $meta = CPAN::Meta->load_string($string, \%options);
355 #pod
356 #pod If you don't know if a string contains YAML or JSON, this method will use
357 #pod L<Parse::CPAN::Meta> to guess. In other respects it is identical to
358 #pod C<load_file()>.
359 #pod
360 #pod =cut
361  
362 1 ▶sub load_string {
Subroutine load_string: called CC=3 SCAR=11.1
Pod documented
363 1 my ($class, $string, $options) = @_;
364 1 ▶ $options->{lazy_validation} = 1 unless exists $options->{lazy_validation};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $options->{"lazy_validation"} 1 0 1
365  
366 1 my $self;
367 1 eval {
368 1 my $struct = Parse::CPAN::Meta->load_string( $string );
369 1 $self = $class->_new($struct, $options);
370 };
371 1 ▶ croak($@) if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 1 1
372 1 return $self;
373 }
374  
375 #pod =method save
376 #pod
377 #pod $meta->save($distmeta_file, \%options);
378 #pod
379 #pod Serializes the object as JSON and writes it to the given file. The only valid
380 #pod option is C<version>, which defaults to '2'. On Perl 5.8.1 or later, the file
381 #pod is saved with UTF-8 encoding.
382 #pod
383 #pod For C<version> 2 (or higher), the filename should end in '.json'. L<JSON::PP>
384 #pod is the default JSON backend. Using another JSON backend requires L<JSON> 2.5 or
385 #pod later and you must set the C<$ENV{PERL_JSON_BACKEND}> to a supported alternate
386 #pod backend like L<JSON::XS>.
387 #pod
388 #pod For C<version> less than 2, the filename should end in '.yml'.
389 #pod L<CPAN::Meta::Converter> is used to generate an older metadata structure, which
390 #pod is serialized to YAML. CPAN::Meta::YAML is the default YAML backend. You may
391 #pod set the C<$ENV{PERL_YAML_BACKEND}> to a supported alternative backend, though
392 #pod this is not recommended due to subtle incompatibilities between YAML parsers on
393 #pod CPAN.
394 #pod
395 #pod =cut
396  
397 2 ▶sub save {
Subroutine save: called CC=7 SCAR=19.8
Pod documented
398 2 my ($self, $file, $options) = @_;
399  
400 2 ▶ my $version = $options->{version} || '2';
Condition100%2/2
$options->{'version'} || '2'
l!l
11
MC/DC100%1/1
$options->{'version'} || '2'
$options->{'version'}
Truth table100%2/2
A
A= $options->{'version'}
Aresult
11
00
401  
402 2 ▶ if ( $version ge '2' ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($version ge '2') { } 1 1 2
403 1 ▶ carp "'$file' should end in '.json'"
Branch: 1 branch
BranchTrueFalseTotal
unless $file =~ /\.json$/ 0 1 1
404 unless $file =~ m{\.json$};
405 }
406 else {
407 1 ▶ carp "'$file' should end in '.yml'"
Branch: 1 branch
BranchTrueFalseTotal
unless $file =~ /\.yml$/ 0 1 1
408 unless $file =~ m{\.yml$};
409 }
410  
411 2 my $data = $self->as_string( $options );
412 2 ▶ open my $fh, '>:encoding(UTF-8)', $file
Branch: 1 branch
BranchTrueFalseTotal
open my $fh, ">:encoding(UTF-8)", $file or die "Error opening '${file}' for writing: $!\n" 2 0 2
413 or die "Error opening '$file' for writing: $!\n";
414  
415 2 print {$fh} $data;
416 2 ▶ close $fh
Branch: 1 branch
BranchTrueFalseTotal
close $fh or die "Error closing '${file}': $!\n" 2 0 2
417 or die "Error closing '$file': $!\n";
418  
419 2 return 1;
420 }
421  
422 #pod =method meta_spec_version
423 #pod
424 #pod This method returns the version part of the C<meta_spec> entry in the distmeta
425 #pod structure. It is equivalent to:
426 #pod
427 #pod $meta->meta_spec->{version};
428 #pod
429 #pod =cut
430  
431 6 ▶sub meta_spec_version {
Subroutine meta_spec_version: called CC=1 SCAR=0.0
Pod documented
432 6 my ($self) = @_;
433 6 return $self->meta_spec->{version};
434 }
435  
436 #pod =method effective_prereqs
437 #pod
438 #pod my $prereqs = $meta->effective_prereqs;
439 #pod
440 #pod my $prereqs = $meta->effective_prereqs( \@feature_identifiers );
441 #pod
442 #pod This method returns a L<CPAN::Meta::Prereqs> object describing all the
443 #pod prereqs for the distribution. If an arrayref of feature identifiers is given,
444 #pod the prereqs for the identified features are merged together with the
445 #pod distribution's core prereqs before the CPAN::Meta::Prereqs object is returned.
446 #pod
447 #pod =cut
448  
449 2 ▶sub effective_prereqs {
Subroutine effective_prereqs: called CC=3 SCAR=11.0
Pod documented
450 2 my ($self, $features) = @_;
451 2 ▶ $features ||= [];
Condition100%2/2
$features ||= []
l!l
11
MC/DC100%1/1
$features ||= []
$features
Truth table100%2/2
A
A= $features
Aresult
11
00
452  
453 2 my $prereq = CPAN::Meta::Prereqs->new($self->prereqs);
454  
455 2 ▶ return $prereq unless @$features;
Branch: 1 branch
BranchTrueFalseTotal
unless @$features 1 1 2
456  
457 1 my @other = map {; $self->feature($_)->prereqs } @$features;
458  
459 1 return $prereq->with_merged_prereqs(\@other);
460 }
461  
462 #pod =method should_index_file
463 #pod
464 #pod ... if $meta->should_index_file( $filename );
465 #pod
466 #pod This method returns true if the given file should be indexed. It decides this
467 #pod by checking the C<file> and C<directory> keys in the C<no_index> property of
468 #pod the distmeta structure. Note that neither the version format nor
469 #pod C<release_status> are considered.
470 #pod
471 #pod C<$filename> should be given in unix format.
472 #pod
473 #pod =cut
474  
475 4 ▶sub should_index_file {
Subroutine should_index_file: called CC=7 SCAR=19.5
Pod documented
476 4 my ($self, $filename) = @_;
477  
478 4 ▶ for my $no_index_file (@{ $self->no_index->{file} || [] }) {
Condition100%2/2
$self->no_index->{'file'} || []
l!l
31
MC/DC100%1/1
$self->no_index->{'file'} || []
$self->no_index->{'file'}
Truth table100%2/2
A
A= $self->no_index->{'file'}
Aresult
11
00
479 3 ▶ return if $filename eq $no_index_file;
Branch: 1 branch
BranchTrueFalseTotal
if $filename eq $no_index_file 1 2 3
480 }
481  
482 3 for my $no_index_dir (@{ $self->no_index->{directory} }) {
483 2 ▶ $no_index_dir =~ s{$}{/} unless $no_index_dir =~ m{/\z};
Branch: 1 branch
BranchTrueFalseTotal
unless $no_index_dir =~ m[/\z] 2 0 2
484 2 ▶ return if index($filename, $no_index_dir) == 0;
Branch: 1 branch
BranchTrueFalseTotal
if index($filename, $no_index_dir) == 0 1 1 2
485 }
486  
487 2 return 1;
488 }
489  
490 #pod =method should_index_package
491 #pod
492 #pod ... if $meta->should_index_package( $package );
493 #pod
494 #pod This method returns true if the given package should be indexed. It decides
495 #pod this by checking the C<package> and C<namespace> keys in the C<no_index>
496 #pod property of the distmeta structure. Note that neither the version format nor
497 #pod C<release_status> are considered.
498 #pod
499 #pod =cut
500  
501 4 ▶sub should_index_package {
Subroutine should_index_package: called CC=6 SCAR=17.9
Pod documented
502 4 my ($self, $package) = @_;
503  
504 4 ▶ for my $no_index_pkg (@{ $self->no_index->{package} || [] }) {
Condition100%2/2
$self->no_index->{'package'} || []
l!l
31
MC/DC100%1/1
$self->no_index->{'package'} || []
$self->no_index->{'package'}
Truth table100%2/2
A
A= $self->no_index->{'package'}
Aresult
11
00
505 3 ▶ return if $package eq $no_index_pkg;
Branch: 1 branch
BranchTrueFalseTotal
if $package eq $no_index_pkg 1 2 3
506 }
507  
508 3 for my $no_index_ns (@{ $self->no_index->{namespace} }) {
509 2 ▶ return if index($package, "${no_index_ns}::") == 0;
Branch: 1 branch
BranchTrueFalseTotal
if index($package, "${no_index_ns}::") == 0 1 1 2
510 }
511  
512 2 return 1;
513 }
514  
515 #pod =method features
516 #pod
517 #pod my @feature_objects = $meta->features;
518 #pod
519 #pod This method returns a list of L<CPAN::Meta::Feature> objects, one for each
520 #pod optional feature described by the distribution's metadata.
521 #pod
522 #pod =cut
523  
524 1 ▶sub features {
Subroutine features: called CC=1 SCAR=0.0
Pod documented
525 1 my ($self) = @_;
526  
527 1 my $opt_f = $self->optional_features;
528 1 my @features = map {; CPAN::Meta::Feature->new($_ => $opt_f->{ $_ }) }
529 keys %$opt_f;
530  
531 1 return @features;
532 }
533  
534 #pod =method feature
535 #pod
536 #pod my $feature_object = $meta->feature( $identifier );
537 #pod
538 #pod This method returns a L<CPAN::Meta::Feature> object for the optional feature
539 #pod with the given identifier. If no feature with that identifier exists, an
540 #pod exception will be raised.
541 #pod
542 #pod =cut
543  
544 2 ▶sub feature {
Subroutine feature: called CC=2 SCAR=7.1
Pod documented
545 2 my ($self, $ident) = @_;
546  
547 croak "no feature named $ident"
548 2 ▶ unless my $f = $self->optional_features->{ $ident };
Branch: 1 branch
BranchTrueFalseTotal
unless my $f = $self->optional_features->{$ident} 0 2 2
549  
550 2 return CPAN::Meta::Feature->new($ident, $f);
551 }
552  
553 #pod =method as_struct
554 #pod
555 #pod my $copy = $meta->as_struct( \%options );
556 #pod
557 #pod This method returns a deep copy of the object's metadata as an unblessed hash
558 #pod reference. It takes an optional hashref of options. If the hashref contains
559 #pod a C<version> argument, the copied metadata will be converted to the version
560 #pod of the specification and returned. For example:
561 #pod
562 #pod my $old_spec = $meta->as_struct( {version => "1.4"} );
563 #pod
564 #pod =cut
565  
566 32 ▶sub as_struct {
Subroutine as_struct: called CC=2 SCAR=6.9
Pod documented
567 32 my ($self, $options) = @_;
568 32 my $struct = _dclone($self);
569 32 ▶ if ( $options->{version} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($options->{"version"}) 1 31 32
570 1 my $cmc = CPAN::Meta::Converter->new( $struct );
571 1 $struct = $cmc->convert( version => $options->{version} );
572 }
573 32 return $struct;
574 }
575  
576 #pod =method as_string
577 #pod
578 #pod my $string = $meta->as_string( \%options );
579 #pod
580 #pod This method returns a serialized copy of the object's metadata as a character
581 #pod string. (The strings are B<not> UTF-8 encoded.) It takes an optional hashref
582 #pod of options. If the hashref contains a C<version> argument, the copied metadata
583 #pod will be converted to the version of the specification and returned. For
584 #pod example:
585 #pod
586 #pod my $string = $meta->as_string( {version => "1.4"} );
587 #pod
588 #pod For C<version> greater than or equal to 2, the string will be serialized as
589 #pod JSON. For C<version> less than 2, the string will be serialized as YAML. In
590 #pod both cases, the same rules are followed as in the C<save()> method for choosing
591 #pod a serialization backend.
592 #pod
593 #pod The serialized structure will include a C<x_serialization_backend> entry giving
594 #pod the package and version used to serialize. Any existing key in the given
595 #pod C<$meta> object will be clobbered.
596 #pod
597 #pod =cut
598  
599 5 ▶sub as_string {
Subroutine as_string: called CC=6 SCAR=18.0
Pod documented
600 5 my ($self, $options) = @_;
601  
602 5 ▶ my $version = $options->{version} || '2';
Condition100%2/2
$options->{'version'} || '2'
l!l
32
MC/DC100%1/1
$options->{'version'} || '2'
$options->{'version'}
Truth table100%2/2
A
A= $options->{'version'}
Aresult
11
00
603  
604 5 my $struct;
605 5 ▶ if ( $self->meta_spec_version ne $version ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->meta_spec_version ne $version) { } 2 3 5
606 2 my $cmc = CPAN::Meta::Converter->new( $self->as_struct );
607 2 $struct = $cmc->convert( version => $version );
608 }
609 else {
610 3 $struct = $self->as_struct;
611 }
612  
613 5 my ($data, $backend);
614 5 ▶ if ( $version ge '2' ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($version ge '2') { } 3 2 5
615 3 $backend = Parse::CPAN::Meta->json_backend();
616 3 local $struct->{x_serialization_backend} = sprintf '%s version %s',
617 $backend, $backend->VERSION;
618 3 $data = $backend->new->pretty->canonical->encode($struct);
619 }
620 else {
621 2 $backend = Parse::CPAN::Meta->yaml_backend();
622 2 local $struct->{x_serialization_backend} = sprintf '%s version %s',
623 $backend, $backend->VERSION;
624 22 ▶ $data = eval { no strict 'refs'; &{"$backend\::Dump"}($struct) };
Subroutine BEGIN: called CC=1 SCAR=0.0
625 2 ▶ if ( $@ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 2 2
626 0 ▶ croak $backend->can('errstr') ? $backend->errstr : $@
Branch: 1 branch
BranchTrueFalseTotal
$backend->can('errstr') ? : 0 0 0
627 }
628 }
629  
630 5 return $data;
631 }
632  
633 # Used by JSON::PP, etc. for "convert_blessed"
634 32 ▶sub TO_JSON {
Subroutine TO_JSON: called CC=1 SCAR=0.0
Pod undocumented
635 32 return { %{ $_[0] } };
636 }
637  
638 22 1;
639  
640 # ABSTRACT: the distribution metadata for a CPAN dist
641  
642 =pod
643  
644 =encoding UTF-8
645  
646 =head1 NAME
647  
648 CPAN::Meta - the distribution metadata for a CPAN dist
649  
650 =head1 VERSION
651  
652 version 2.150015
653  
654 =head1 SYNOPSIS
655  
656 use v5.10;
657 use strict;
658 use warnings;
659 use CPAN::Meta;
660 use Module::Load;
661  
662 my $meta = CPAN::Meta->load_file('META.json');
663  
664 printf "testing requirements for %s version %s\n",
665 $meta->name,
666 $meta->version;
667  
668 my $prereqs = $meta->effective_prereqs;
669  
670 for my $phase ( qw/configure runtime build test/ ) {
671 say "Requirements for $phase:";
672 my $reqs = $prereqs->requirements_for($phase, "requires");
673 for my $module ( sort $reqs->required_modules ) {
674 my $status;
675 if ( eval { load $module unless $module eq 'perl'; 1 } ) {
676 my $version = $module eq 'perl' ? $] : $module->VERSION;
677 $status = $reqs->accepts_module($module, $version)
678 ? "$version ok" : "$version not ok";
679 } else {
680 $status = "missing"
681 };
682 say " $module ($status)";
683 }
684 }
685  
686 =head1 DESCRIPTION
687  
688 Software distributions released to the CPAN include a F<META.json> or, for
689 older distributions, F<META.yml>, which describes the distribution, its
690 contents, and the requirements for building and installing the distribution.
691 The data structure stored in the F<META.json> file is described in
692 L<CPAN::Meta::Spec>.
693  
694 CPAN::Meta provides a simple class to represent this distribution metadata (or
695 I<distmeta>), along with some helpful methods for interrogating that data.
696  
697 The documentation below is only for the methods of the CPAN::Meta object. For
698 information on the meaning of individual fields, consult the spec.
699  
700 =head1 METHODS
701  
702 =head2 new
703  
704 my $meta = CPAN::Meta->new($distmeta_struct, \%options);
705  
706 Returns a valid CPAN::Meta object or dies if the supplied metadata hash
707 reference fails to validate. Older-format metadata will be up-converted to
708 version 2 if they validate against the original stated specification.
709  
710 It takes an optional hashref of options. Valid options include:
711  
712 =over
713  
714 =item *
715  
716 lazy_validation -- if true, new will attempt to convert the given metadata
717 to version 2 before attempting to validate it. This means than any
718 fixable errors will be handled by CPAN::Meta::Converter before validation.
719 (Note that this might result in invalid optional data being silently
720 dropped.) The default is false.
721  
722 =back
723  
724 =head2 create
725  
726 my $meta = CPAN::Meta->create($distmeta_struct, \%options);
727  
728 This is same as C<new()>, except that C<generated_by> and C<meta-spec> fields
729 will be generated if not provided. This means the metadata structure is
730 assumed to otherwise follow the latest L<CPAN::Meta::Spec>.
731  
732 =head2 load_file
733  
734 my $meta = CPAN::Meta->load_file($distmeta_file, \%options);
735  
736 Given a pathname to a file containing metadata, this deserializes the file
737 according to its file suffix and constructs a new C<CPAN::Meta> object, just
738 like C<new()>. It will die if the deserialized version fails to validate
739 against its stated specification version.
740  
741 It takes the same options as C<new()> but C<lazy_validation> defaults to
742 true.
743  
744 =head2 load_yaml_string
745  
746 my $meta = CPAN::Meta->load_yaml_string($yaml, \%options);
747  
748 This method returns a new CPAN::Meta object using the first document in the
749 given YAML string. In other respects it is identical to C<load_file()>.
750  
751 =head2 load_json_string
752  
753 my $meta = CPAN::Meta->load_json_string($json, \%options);
754  
755 This method returns a new CPAN::Meta object using the structure represented by
756 the given JSON string. In other respects it is identical to C<load_file()>.
757  
758 =head2 load_string
759  
760 my $meta = CPAN::Meta->load_string($string, \%options);
761  
762 If you don't know if a string contains YAML or JSON, this method will use
763 L<Parse::CPAN::Meta> to guess. In other respects it is identical to
764 C<load_file()>.
765  
766 =head2 save
767  
768 $meta->save($distmeta_file, \%options);
769  
770 Serializes the object as JSON and writes it to the given file. The only valid
771 option is C<version>, which defaults to '2'. On Perl 5.8.1 or later, the file
772 is saved with UTF-8 encoding.
773  
774 For C<version> 2 (or higher), the filename should end in '.json'. L<JSON::PP>
775 is the default JSON backend. Using another JSON backend requires L<JSON> 2.5 or
776 later and you must set the C<$ENV{PERL_JSON_BACKEND}> to a supported alternate
777 backend like L<JSON::XS>.
778  
779 For C<version> less than 2, the filename should end in '.yml'.
780 L<CPAN::Meta::Converter> is used to generate an older metadata structure, which
781 is serialized to YAML. CPAN::Meta::YAML is the default YAML backend. You may
782 set the C<$ENV{PERL_YAML_BACKEND}> to a supported alternative backend, though
783 this is not recommended due to subtle incompatibilities between YAML parsers on
784 CPAN.
785  
786 =head2 meta_spec_version
787  
788 This method returns the version part of the C<meta_spec> entry in the distmeta
789 structure. It is equivalent to:
790  
791 $meta->meta_spec->{version};
792  
793 =head2 effective_prereqs
794  
795 my $prereqs = $meta->effective_prereqs;
796  
797 my $prereqs = $meta->effective_prereqs( \@feature_identifiers );
798  
799 This method returns a L<CPAN::Meta::Prereqs> object describing all the
800 prereqs for the distribution. If an arrayref of feature identifiers is given,
801 the prereqs for the identified features are merged together with the
802 distribution's core prereqs before the CPAN::Meta::Prereqs object is returned.
803  
804 =head2 should_index_file
805  
806 ... if $meta->should_index_file( $filename );
807  
808 This method returns true if the given file should be indexed. It decides this
809 by checking the C<file> and C<directory> keys in the C<no_index> property of
810 the distmeta structure. Note that neither the version format nor
811 C<release_status> are considered.
812  
813 C<$filename> should be given in unix format.
814  
815 =head2 should_index_package
816  
817 ... if $meta->should_index_package( $package );
818  
819 This method returns true if the given package should be indexed. It decides
820 this by checking the C<package> and C<namespace> keys in the C<no_index>
821 property of the distmeta structure. Note that neither the version format nor
822 C<release_status> are considered.
823  
824 =head2 features
825  
826 my @feature_objects = $meta->features;
827  
828 This method returns a list of L<CPAN::Meta::Feature> objects, one for each
829 optional feature described by the distribution's metadata.
830  
831 =head2 feature
832  
833 my $feature_object = $meta->feature( $identifier );
834  
835 This method returns a L<CPAN::Meta::Feature> object for the optional feature
836 with the given identifier. If no feature with that identifier exists, an
837 exception will be raised.
838  
839 =head2 as_struct
840  
841 my $copy = $meta->as_struct( \%options );
842  
843 This method returns a deep copy of the object's metadata as an unblessed hash
844 reference. It takes an optional hashref of options. If the hashref contains
845 a C<version> argument, the copied metadata will be converted to the version
846 of the specification and returned. For example:
847  
848 my $old_spec = $meta->as_struct( {version => "1.4"} );
849  
850 =head2 as_string
851  
852 my $string = $meta->as_string( \%options );
853  
854 This method returns a serialized copy of the object's metadata as a character
855 string. (The strings are B<not> UTF-8 encoded.) It takes an optional hashref
856 of options. If the hashref contains a C<version> argument, the copied metadata
857 will be converted to the version of the specification and returned. For
858 example:
859  
860 my $string = $meta->as_string( {version => "1.4"} );
861  
862 For C<version> greater than or equal to 2, the string will be serialized as
863 JSON. For C<version> less than 2, the string will be serialized as YAML. In
864 both cases, the same rules are followed as in the C<save()> method for choosing
865 a serialization backend.
866  
867 The serialized structure will include a C<x_serialization_backend> entry giving
868 the package and version used to serialize. Any existing key in the given
869 C<$meta> object will be clobbered.
870  
871 =head1 STRING DATA
872  
873 The following methods return a single value, which is the value for the
874 corresponding entry in the distmeta structure. Values should be either undef
875 or strings.
876  
877 =over 4
878  
879 =item *
880  
881 abstract
882  
883 =item *
884  
885 description
886  
887 =item *
888  
889 dynamic_config
890  
891 =item *
892  
893 generated_by
894  
895 =item *
896  
897 name
898  
899 =item *
900  
901 release_status
902  
903 =item *
904  
905 version
906  
907 =back
908  
909 =head1 LIST DATA
910  
911 These methods return lists of string values, which might be represented in the
912 distmeta structure as arrayrefs or scalars:
913  
914 =over 4
915  
916 =item *
917  
918 authors
919  
920 =item *
921  
922 keywords
923  
924 =item *
925  
926 licenses
927  
928 =back
929  
930 The C<authors> and C<licenses> methods may also be called as C<author> and
931 C<license>, respectively, to match the field name in the distmeta structure.
932  
933 =head1 MAP DATA
934  
935 These readers return hashrefs of arbitrary unblessed data structures, each
936 described more fully in the specification:
937  
938 =over 4
939  
940 =item *
941  
942 meta_spec
943  
944 =item *
945  
946 resources
947  
948 =item *
949  
950 provides
951  
952 =item *
953  
954 no_index
955  
956 =item *
957  
958 prereqs
959  
960 =item *
961  
962 optional_features
963  
964 =back
965  
966 =head1 CUSTOM DATA
967  
968 A list of custom keys are available from the C<custom_keys> method and
969 particular keys may be retrieved with the C<custom> method.
970  
971 say $meta->custom($_) for $meta->custom_keys;
972  
973 If a custom key refers to a data structure, a deep clone is returned.
974  
975 =for Pod::Coverage TO_JSON abstract author authors custom custom_keys description dynamic_config
976 generated_by keywords license licenses meta_spec name no_index
977 optional_features prereqs provides release_status resources version
978  
979 =head1 BUGS
980  
981 Please report any bugs or feature using the CPAN Request Tracker.
982 Bugs can be submitted through the web interface at
983 L<http://rt.cpan.org/Dist/Display.html?Queue=CPAN-Meta>
984  
985 When submitting a bug or request, please include a test-file or a patch to an
986 existing test-file that illustrates the bug or desired feature.
987  
988 =head1 SEE ALSO
989  
990 =over 4
991  
992 =item *
993  
994 L<CPAN::Meta::Converter>
995  
996 =item *
997  
998 L<CPAN::Meta::Validator>
999  
1000 =back
1001  
1002 =for :stopwords cpan testmatrix url bugtracker rt cpants kwalitee diff irc mailto metadata placeholders metacpan
1003  
1004 =head1 SUPPORT
1005  
1006 =head2 Bugs / Feature Requests
1007  
1008 Please report any bugs or feature requests through the issue tracker
1009 at L<https://github.com/Perl-Toolchain-Gang/CPAN-Meta/issues>.
1010 You will be notified automatically of any progress on your issue.
1011  
1012 =head2 Source Code
1013  
1014 This is open source software. The code repository is available for
1015 public review and contribution under the terms of the license.
1016  
1017 L<https://github.com/Perl-Toolchain-Gang/CPAN-Meta>
1018  
1019 git clone https://github.com/Perl-Toolchain-Gang/CPAN-Meta.git
1020  
1021 =head1 AUTHORS
1022  
1023 =over 4
1024  
1025 =item *
1026  
1027 David Golden <dagolden@cpan.org>
1028  
1029 =item *
1030  
1031 Ricardo Signes <cpan@semiotic.systems>
1032  
1033 =item *
1034  
1035 Adam Kennedy <adamk@cpan.org>
1036  
1037 =back
1038  
1039 =head1 CONTRIBUTORS
1040  
1041 =for stopwords Ansgar Burchardt Avar Arnfjord Bjarmason Benjamin Noggle Christopher J. Madsen Chuck Adams Cory G Watson Damyan Ivanov Dan Book Eric Wilhelm Graham Knop Gregor Hermann James E Keenan Karen Etheridge Kenichi Ishigaki Kent Fredric Ken Williams Lars Dieckow Leon Timmermans majensen Mark Fowler Matt S Trout Michael G. Schwern Mohammad Anwar mohawk2 moznion Niko Tyni Olaf Alders Olivier Mengué Philippe Bruhat (BooK) Randy Sims Ricardo Signes Tomohiro Hosaka
1042  
1043 =over 4
1044  
1045 =item *
1046  
1047 Ansgar Burchardt <ansgar@cpan.org>
1048  
1049 =item *
1050  
1051 Avar Arnfjord Bjarmason <avar@cpan.org>
1052  
1053 =item *
1054  
1055 Benjamin Noggle <agwind@users.noreply.github.com>
1056  
1057 =item *
1058  
1059 Christopher J. Madsen <cjm@cpan.org>
1060  
1061 =item *
1062  
1063 Chuck Adams <cja987@gmail.com>
1064  
1065 =item *
1066  
1067 Cory G Watson <gphat@cpan.org>
1068  
1069 =item *
1070  
1071 Damyan Ivanov <dam@cpan.org>
1072  
1073 =item *
1074  
1075 Dan Book <grinnz@gmail.com>
1076  
1077 =item *
1078  
1079 Eric Wilhelm <ewilhelm@cpan.org>
1080  
1081 =item *
1082  
1083 Graham Knop <haarg@haarg.org>
1084  
1085 =item *
1086  
1087 Gregor Hermann <gregoa@debian.org>
1088  
1089 =item *
1090  
1091 James E Keenan <jkeenan@cpan.org>
1092  
1093 =item *
1094  
1095 Karen Etheridge <ether@cpan.org>
1096  
1097 =item *
1098  
1099 Kenichi Ishigaki <ishigaki@cpan.org>
1100  
1101 =item *
1102  
1103 Kent Fredric <kentfredric@gmail.com>
1104  
1105 =item *
1106  
1107 Ken Williams <kwilliams@cpan.org>
1108  
1109 =item *
1110  
1111 Lars Dieckow <daxim@cpan.org>
1112  
1113 =item *
1114  
1115 Leon Timmermans <leont@cpan.org>
1116  
1117 =item *
1118  
1119 majensen <maj@fortinbras.us>
1120  
1121 =item *
1122  
1123 Mark Fowler <markf@cpan.org>
1124  
1125 =item *
1126  
1127 Matt S Trout <mst@shadowcat.co.uk>
1128  
1129 =item *
1130  
1131 Michael G. Schwern <mschwern@cpan.org>
1132  
1133 =item *
1134  
1135 Mohammad S Anwar <mohammad.anwar@yahoo.com>
1136  
1137 =item *
1138  
1139 mohawk2 <mohawk2@users.noreply.github.com>
1140  
1141 =item *
1142  
1143 moznion <moznion@gmail.com>
1144  
1145 =item *
1146  
1147 Niko Tyni <ntyni@debian.org>
1148  
1149 =item *
1150  
1151 Olaf Alders <olaf@wundersolutions.com>
1152  
1153 =item *
1154  
1155 Olivier Mengué <dolmen@cpan.org>
1156  
1157 =item *
1158  
1159 Philippe Bruhat (BooK) <book@cpan.org>
1160  
1161 =item *
1162  
1163 Randy Sims <randys@thepierianspring.org>
1164  
1165 =item *
1166  
1167 Ricardo Signes <rjbs@semiotic.systems>
1168  
1169 =item *
1170  
1171 Tomohiro Hosaka <bokutin@bokut.in>
1172  
1173 =back
1174  
1175 =head1 COPYRIGHT AND LICENSE
1176  
1177 This software is copyright (c) 2010 by David Golden, Ricardo Signes, Adam Kennedy and Contributors.
1178  
1179 This is free software; you can redistribute it and/or modify it under
1180 the same terms as the Perl 5 programming language system itself.
1181  
1182 =cut
1183  
1184 __END__
« CPAN/Meta/Merge.pm ↑ Summary CPAN/Meta/History.pm »