Lines Matching full:pod
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
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
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
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
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
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
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
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
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
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
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
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
423 #pod =method meta_spec_version
424 #pod
425 #pod This method returns the version part of the C<meta_spec> entry in the distmeta
426 #pod structure. It is equivalent to:
427 #pod
428 #pod $meta->meta_spec->{version};
429 #pod
430 #pod =cut
437 #pod =method effective_prereqs
438 #pod
439 #pod my $prereqs = $meta->effective_prereqs;
440 #pod
441 #pod my $prereqs = $meta->effective_prereqs( \@feature_identifiers );
442 #pod
443 #pod This method returns a L<CPAN::Meta::Prereqs> object describing all the
444 #pod prereqs for the distribution. If an arrayref of feature identifiers is given,
445 #pod the prereqs for the identified features are merged together with the
446 #pod distribution's core prereqs before the CPAN::Meta::Prereqs object is returned.
447 #pod
448 #pod =cut
463 #pod =method should_index_file
464 #pod
465 #pod ... if $meta->should_index_file( $filename );
466 #pod
467 #pod This method returns true if the given file should be indexed. It decides this
468 #pod by checking the C<file> and C<directory> keys in the C<no_index> property of
469 #pod the distmeta structure. Note that neither the version format nor
470 #pod C<release_status> are considered.
471 #pod
472 #pod C<$filename> should be given in unix format.
473 #pod
474 #pod =cut
491 #pod =method should_index_package
492 #pod
493 #pod ... if $meta->should_index_package( $package );
494 #pod
495 #pod This method returns true if the given package should be indexed. It decides
496 #pod this by checking the C<package> and C<namespace> keys in the C<no_index>
497 #pod property of the distmeta structure. Note that neither the version format nor
498 #pod C<release_status> are considered.
499 #pod
500 #pod =cut
516 #pod =method features
517 #pod
518 #pod my @feature_objects = $meta->features;
519 #pod
520 #pod This method returns a list of L<CPAN::Meta::Feature> objects, one for each
521 #pod optional feature described by the distribution's metadata.
522 #pod
523 #pod =cut
535 #pod =method feature
536 #pod
537 #pod my $feature_object = $meta->feature( $identifier );
538 #pod
539 #pod This method returns a L<CPAN::Meta::Feature> object for the optional feature
540 #pod with the given identifier. If no feature with that identifier exists, an
541 #pod exception will be raised.
542 #pod
543 #pod =cut
554 #pod =method as_struct
555 #pod
556 #pod my $copy = $meta->as_struct( \%options );
557 #pod
558 #pod This method returns a deep copy of the object's metadata as an unblessed hash
559 #pod reference. It takes an optional hashref of options. If the hashref contains
560 #pod a C<version> argument, the copied metadata will be converted to the version
561 #pod of the specification and returned. For example:
562 #pod
563 #pod my $old_spec = $meta->as_struct( {version => "1.4"} );
564 #pod
565 #pod =cut
577 #pod =method as_string
578 #pod
579 #pod my $string = $meta->as_string( \%options );
580 #pod
581 #pod This method returns a serialized copy of the object's metadata as a character
582 #pod string. (The strings are B<not> UTF-8 encoded.) It takes an optional hashref
583 #pod of options. If the hashref contains a C<version> argument, the copied metadata
584 #pod will be converted to the version of the specification and returned. For
585 #pod example:
586 #pod
587 #pod my $string = $meta->as_string( {version => "1.4"} );
588 #pod
589 #pod For C<version> greater than or equal to 2, the string will be serialized as
590 #pod JSON. For C<version> less than 2, the string will be serialized as YAML. In
591 #pod both cases, the same rules are followed as in the C<save()> method for choosing
592 #pod a serialization backend.
593 #pod
594 #pod The serialized structure will include a C<x_serialization_backend> entry giving
595 #pod the package and version used to serialize. Any existing key in the given
596 #pod C<$meta> object will be clobbered.
597 #pod
598 #pod =cut
643 =pod
976 =for Pod::Coverage TO_JSON abstract author authors custom custom_keys description dynamic_config