1CPAN::Meta(3) User Contributed Perl Documentation CPAN::Meta(3)
2
6 CPAN::Meta - the distribution metadata for a CPAN dist
7
9 version 2.150010
10
12 use v5.10;
13 use strict;
14 use warnings;
15 use CPAN::Meta;
16 use Module::Load;
17 my $meta = CPAN::Meta->load_file('META.json');
19 printf "testing requirements for %s version %s\n",
21 $meta->name,
22 $meta->version;
23 my $prereqs = $meta->effective_prereqs;
25 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
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 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 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
58 new
59 my $meta = CPAN::Meta->new($distmeta_struct, \%options);
60 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 It takes an optional hashref of options. Valid options include:
67 · 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 create
75 my $meta = CPAN::Meta->create($distmeta_struct, \%options);
76 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 load_file
82 my $meta = CPAN::Meta->load_file($distmeta_file, \%options);
83 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 It takes the same options as "new()" but "lazy_validation" defaults to
90 true.
91 load_yaml_string
93 my $meta = CPAN::Meta->load_yaml_string($yaml, \%options);
94 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 load_json_string
100 my $meta = CPAN::Meta->load_json_string($json, \%options);
101 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 load_string
107 my $meta = CPAN::Meta->load_string($string, \%options);
108 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 save
114 $meta->save($distmeta_file, \%options);
115 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 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 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 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 $meta->meta_spec->{version};
137 effective_prereqs
139 my $prereqs = $meta->effective_prereqs;
140 my $prereqs = $meta->effective_prereqs( \@feature_identifiers );
142 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 should_index_file
150 ... if $meta->should_index_file( $filename );
151 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 $filename should be given in unix format.
158 should_index_package
160 ... if $meta->should_index_package( $package );
161 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 features
168 my @feature_objects = $meta->features;
169 This method returns a list of CPAN::Meta::Feature objects, one for each
171 optional feature described by the distribution's metadata.
172 feature
174 my $feature_object = $meta->feature( $identifier );
175 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 as_struct
181 my $copy = $meta->as_struct( \%options );
182 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 my $old_spec = $meta->as_struct( {version => "1.4"} );
190 as_string
192 my $string = $meta->as_string( \%options );
193 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 my $string = $meta->as_string( {version => "1.4"} );
201 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 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
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 · abstract
217 · description
219 · dynamic_config
221 · generated_by
223 · name
225 · release_status
227 · version
229
231 These methods return lists of string values, which might be represented
232 in the distmeta structure as arrayrefs or scalars:
233 · authors
235 · keywords
237 · licenses
239 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
245 These readers return hashrefs of arbitrary unblessed data structures,
246 each described more fully in the specification:
247 · meta_spec
249 · resources
251 · provides
253 · no_index
255 · prereqs
257 · optional_features
259
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 say $meta->custom($_) for $meta->custom_keys;
265 If a custom key refers to a data structure, a deep clone is returned.
267
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 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
277 · CPAN::Meta::Converter
278 · CPAN::Meta::Validator
280
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 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 <https://github.com/Perl-Toolchain-Gang/CPAN-Meta>
292 git clone https://github.com/Perl-Toolchain-Gang/CPAN-Meta.git
294
296 · David Golden <dagolden@cpan.org>
297 · Ricardo Signes <rjbs@cpan.org>
299 · Adam Kennedy <adamk@cpan.org>
301
303 · Ansgar Burchardt <ansgar@cpan.org>
304 · Avar Arnfjord Bjarmason <avar@cpan.org>
306 · Benjamin Noggle <agwind@users.noreply.github.com>
308 · Christopher J. Madsen <cjm@cpan.org>
310 · Chuck Adams <cja987@gmail.com>
312 · Cory G Watson <gphat@cpan.org>
314 · Damyan Ivanov <dam@cpan.org>
316 · David Golden <xdg@xdg.me>
318 · Eric Wilhelm <ewilhelm@cpan.org>
320 · Graham Knop <haarg@haarg.org>
322 · Gregor Hermann <gregoa@debian.org>
324 · Karen Etheridge <ether@cpan.org>
326 · Kenichi Ishigaki <ishigaki@cpan.org>
328 · Kent Fredric <kentfredric@gmail.com>
330 · Ken Williams <kwilliams@cpan.org>
332 · Lars Dieckow <daxim@cpan.org>
334 · Leon Timmermans <leont@cpan.org>
336 · majensen <maj@fortinbras.us>
338 · Mark Fowler <markf@cpan.org>
340 · Matt S Trout <mst@shadowcat.co.uk>
342 · Michael G. Schwern <mschwern@cpan.org>
344 · Mohammad S Anwar <mohammad.anwar@yahoo.com>
346 · mohawk2 <mohawk2@users.noreply.github.com>
348 · moznion <moznion@gmail.com>
350 · Niko Tyni <ntyni@debian.org>
352 · Olaf Alders <olaf@wundersolutions.com>
354 · Olivier Mengué <dolmen@cpan.org>
356 · Randy Sims <randys@thepierianspring.org>
358 · Tomohiro Hosaka <bokutin@bokut.in>
360
362 This software is copyright (c) 2010 by David Golden, Ricardo Signes,
363 Adam Kennedy and Contributors.
364 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.
367perl v5.32.0 2020-07-28 CPAN::Meta(3)