CPAN::Meta(3pm)

1CPAN::Meta(3)         User Contributed Perl Documentation        CPAN::Meta(3)
2
3
4

NAME

6       CPAN::Meta - the distribution metadata for a CPAN dist
7

VERSION

9       version 2.150010
10

SYNOPSIS

12           use v5.10;
13           use strict;
14           use warnings;
15           use CPAN::Meta;
16           use Module::Load;
17
18           my $meta = CPAN::Meta->load_file('META.json');
19
20           printf "testing requirements for %s version %s\n",
21           $meta->name,
22           $meta->version;
23
24           my $prereqs = $meta->effective_prereqs;
25
26           for my $phase ( qw/configure runtime build test/ ) {
27               say "Requirements for $phase:";
28               my $reqs = $prereqs->requirements_for($phase, "requires");
29               for my $module ( sort $reqs->required_modules ) {
30                   my $status;
31                   if ( eval { load $module unless $module eq 'perl'; 1 } ) {
32                       my $version = $module eq 'perl' ? $] : $module->VERSION;
33                       $status = $reqs->accepts_module($module, $version)
34                               ? "$version ok" : "$version not ok";
35                   } else {
36                       $status = "missing"
37                   };
38                   say "  $module ($status)";
39               }
40           }
41

DESCRIPTION

43       Software distributions released to the CPAN include a META.json or, for
44       older distributions, META.yml, which describes the distribution, its
45       contents, and the requirements for building and installing the
46       distribution.  The data structure stored in the META.json file is
47       described in CPAN::Meta::Spec.
48
49       CPAN::Meta provides a simple class to represent this distribution
50       metadata (or distmeta), along with some helpful methods for
51       interrogating that data.
52
53       The documentation below is only for the methods of the CPAN::Meta
54       object.  For information on the meaning of individual fields, consult
55       the spec.
56

METHODS

58   new
59         my $meta = CPAN::Meta->new($distmeta_struct, \%options);
60
61       Returns a valid CPAN::Meta object or dies if the supplied metadata hash
62       reference fails to validate.  Older-format metadata will be up-
63       converted to version 2 if they validate against the original stated
64       specification.
65
66       It takes an optional hashref of options. Valid options include:
67
68       •   lazy_validation -- if true, new will attempt to convert the given
69           metadata to version 2 before attempting to validate it.  This means
70           than any fixable errors will be handled by CPAN::Meta::Converter
71           before validation.  (Note that this might result in invalid
72           optional data being silently dropped.)  The default is false.
73
74   create
75         my $meta = CPAN::Meta->create($distmeta_struct, \%options);
76
77       This is same as "new()", except that "generated_by" and "meta-spec"
78       fields will be generated if not provided.  This means the metadata
79       structure is assumed to otherwise follow the latest CPAN::Meta::Spec.
80
81   load_file
82         my $meta = CPAN::Meta->load_file($distmeta_file, \%options);
83
84       Given a pathname to a file containing metadata, this deserializes the
85       file according to its file suffix and constructs a new "CPAN::Meta"
86       object, just like "new()".  It will die if the deserialized version
87       fails to validate against its stated specification version.
88
89       It takes the same options as "new()" but "lazy_validation" defaults to
90       true.
91
92   load_yaml_string
93         my $meta = CPAN::Meta->load_yaml_string($yaml, \%options);
94
95       This method returns a new CPAN::Meta object using the first document in
96       the given YAML string.  In other respects it is identical to
97       "load_file()".
98
99   load_json_string
100         my $meta = CPAN::Meta->load_json_string($json, \%options);
101
102       This method returns a new CPAN::Meta object using the structure
103       represented by the given JSON string.  In other respects it is
104       identical to "load_file()".
105
106   load_string
107         my $meta = CPAN::Meta->load_string($string, \%options);
108
109       If you don't know if a string contains YAML or JSON, this method will
110       use Parse::CPAN::Meta to guess.  In other respects it is identical to
111       "load_file()".
112
113   save
114         $meta->save($distmeta_file, \%options);
115
116       Serializes the object as JSON and writes it to the given file.  The
117       only valid option is "version", which defaults to '2'. On Perl 5.8.1 or
118       later, the file is saved with UTF-8 encoding.
119
120       For "version" 2 (or higher), the filename should end in '.json'.
121       JSON::PP is the default JSON backend. Using another JSON backend
122       requires JSON 2.5 or later and you must set the $ENV{PERL_JSON_BACKEND}
123       to a supported alternate backend like JSON::XS.
124
125       For "version" less than 2, the filename should end in '.yml'.
126       CPAN::Meta::Converter is used to generate an older metadata structure,
127       which is serialized to YAML.  CPAN::Meta::YAML is the default YAML
128       backend.  You may set the $ENV{PERL_YAML_BACKEND} to a supported
129       alternative backend, though this is not recommended due to subtle
130       incompatibilities between YAML parsers on CPAN.
131
132   meta_spec_version
133       This method returns the version part of the "meta_spec" entry in the
134       distmeta structure.  It is equivalent to:
135
136         $meta->meta_spec->{version};
137
138   effective_prereqs
139         my $prereqs = $meta->effective_prereqs;
140
141         my $prereqs = $meta->effective_prereqs( \@feature_identifiers );
142
143       This method returns a CPAN::Meta::Prereqs object describing all the
144       prereqs for the distribution.  If an arrayref of feature identifiers is
145       given, the prereqs for the identified features are merged together with
146       the distribution's core prereqs before the CPAN::Meta::Prereqs object
147       is returned.
148
149   should_index_file
150         ... if $meta->should_index_file( $filename );
151
152       This method returns true if the given file should be indexed.  It
153       decides this by checking the "file" and "directory" keys in the
154       "no_index" property of the distmeta structure. Note that neither the
155       version format nor "release_status" are considered.
156
157       $filename should be given in unix format.
158
159   should_index_package
160         ... if $meta->should_index_package( $package );
161
162       This method returns true if the given package should be indexed.  It
163       decides this by checking the "package" and "namespace" keys in the
164       "no_index" property of the distmeta structure. Note that neither the
165       version format nor "release_status" are considered.
166
167   features
168         my @feature_objects = $meta->features;
169
170       This method returns a list of CPAN::Meta::Feature objects, one for each
171       optional feature described by the distribution's metadata.
172
173   feature
174         my $feature_object = $meta->feature( $identifier );
175
176       This method returns a CPAN::Meta::Feature object for the optional
177       feature with the given identifier.  If no feature with that identifier
178       exists, an exception will be raised.
179
180   as_struct
181         my $copy = $meta->as_struct( \%options );
182
183       This method returns a deep copy of the object's metadata as an
184       unblessed hash reference.  It takes an optional hashref of options.  If
185       the hashref contains a "version" argument, the copied metadata will be
186       converted to the version of the specification and returned.  For
187       example:
188
189         my $old_spec = $meta->as_struct( {version => "1.4"} );
190
191   as_string
192         my $string = $meta->as_string( \%options );
193
194       This method returns a serialized copy of the object's metadata as a
195       character string.  (The strings are not UTF-8 encoded.)  It takes an
196       optional hashref of options.  If the hashref contains a "version"
197       argument, the copied metadata will be converted to the version of the
198       specification and returned.  For example:
199
200         my $string = $meta->as_string( {version => "1.4"} );
201
202       For "version" greater than or equal to 2, the string will be serialized
203       as JSON.  For "version" less than 2, the string will be serialized as
204       YAML.  In both cases, the same rules are followed as in the "save()"
205       method for choosing a serialization backend.
206
207       The serialized structure will include a "x_serialization_backend" entry
208       giving the package and version used to serialize.  Any existing key in
209       the given $meta object will be clobbered.
210

STRING DATA

212       The following methods return a single value, which is the value for the
213       corresponding entry in the distmeta structure.  Values should be either
214       undef or strings.
215
216       •   abstract
217
218       •   description
219
220       •   dynamic_config
221
222       •   generated_by
223
224       •   name
225
226       •   release_status
227
228       •   version
229

LIST DATA

231       These methods return lists of string values, which might be represented
232       in the distmeta structure as arrayrefs or scalars:
233
234       •   authors
235
236       •   keywords
237
238       •   licenses
239
240       The "authors" and "licenses" methods may also be called as "author" and
241       "license", respectively, to match the field name in the distmeta
242       structure.
243

MAP DATA

245       These readers return hashrefs of arbitrary unblessed data structures,
246       each described more fully in the specification:
247
248       •   meta_spec
249
250       •   resources
251
252       •   provides
253
254       •   no_index
255
256       •   prereqs
257
258       •   optional_features
259

CUSTOM DATA

261       A list of custom keys are available from the "custom_keys" method and
262       particular keys may be retrieved with the "custom" method.
263
264         say $meta->custom($_) for $meta->custom_keys;
265
266       If a custom key refers to a data structure, a deep clone is returned.
267

BUGS

269       Please report any bugs or feature using the CPAN Request Tracker.  Bugs
270       can be submitted through the web interface at
271       <http://rt.cpan.org/Dist/Display.html?Queue=CPAN-Meta>
272
273       When submitting a bug or request, please include a test-file or a patch
274       to an existing test-file that illustrates the bug or desired feature.
275

SUPPORT

282   Bugs / Feature Requests
283       Please report any bugs or feature requests through the issue tracker at
284       <https://github.com/Perl-Toolchain-Gang/CPAN-Meta/issues>.  You will be
285       notified automatically of any progress on your issue.
286
287   Source Code
288       This is open source software.  The code repository is available for
289       public review and contribution under the terms of the license.
290
291       <https://github.com/Perl-Toolchain-Gang/CPAN-Meta>
292
293         git clone https://github.com/Perl-Toolchain-Gang/CPAN-Meta.git
294

AUTHORS

296       •   David Golden <dagolden@cpan.org>
297
298       •   Ricardo Signes <rjbs@cpan.org>
299
300       •   Adam Kennedy <adamk@cpan.org>
301

CONTRIBUTORS

303       •   Ansgar Burchardt <ansgar@cpan.org>
304
305       •   Avar Arnfjord Bjarmason <avar@cpan.org>
306
307       •   Benjamin Noggle <agwind@users.noreply.github.com>
308
309       •   Christopher J. Madsen <cjm@cpan.org>
310
311       •   Chuck Adams <cja987@gmail.com>
312
313       •   Cory G Watson <gphat@cpan.org>
314
315       •   Damyan Ivanov <dam@cpan.org>
316
317       •   David Golden <xdg@xdg.me>
318
319       •   Eric Wilhelm <ewilhelm@cpan.org>
320
321       •   Graham Knop <haarg@haarg.org>
322
323       •   Gregor Hermann <gregoa@debian.org>
324
325       •   Karen Etheridge <ether@cpan.org>
326
327       •   Kenichi Ishigaki <ishigaki@cpan.org>
328
329       •   Kent Fredric <kentfredric@gmail.com>
330
331       •   Ken Williams <kwilliams@cpan.org>
332
333       •   Lars Dieckow <daxim@cpan.org>
334
335       •   Leon Timmermans <leont@cpan.org>
336
337       •   majensen <maj@fortinbras.us>
338
339       •   Mark Fowler <markf@cpan.org>
340
341       •   Matt S Trout <mst@shadowcat.co.uk>
342
343       •   Michael G. Schwern <mschwern@cpan.org>
344
345       •   Mohammad S Anwar <mohammad.anwar@yahoo.com>
346
347       •   mohawk2 <mohawk2@users.noreply.github.com>
348
349       •   moznion <moznion@gmail.com>
350
351       •   Niko Tyni <ntyni@debian.org>
352
353       •   Olaf Alders <olaf@wundersolutions.com>
354
355       •   Olivier Mengué <dolmen@cpan.org>
356
357       •   Randy Sims <randys@thepierianspring.org>
358
359       •   Tomohiro Hosaka <bokutin@bokut.in>
360

COPYRIGHT AND LICENSE

362       This software is copyright (c) 2010 by David Golden, Ricardo Signes,
363       Adam Kennedy and Contributors.
364
365       This is free software; you can redistribute it and/or modify it under
366       the same terms as the Perl 5 programming language system itself.
367
368
369
370perl v5.36.0                      2022-07-22                     CPAN::Meta(3)