Debian Codegraph @

upstream/opensuse-tumbleweed/man3/CPAN::Meta.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "CPAN::Meta 3pm"
61 .TH CPAN::Meta 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 CPAN::Meta \- the distribution metadata for a CPAN dist
68 .SH VERSION
69 .IX Header "VERSION"
70 version 2.150010
71 .SH SYNOPSIS
72 .IX Header "SYNOPSIS"
73 .Vb 5
74 \& use v5.10;
75 \& use strict;
76 \& use warnings;
77 \& use CPAN::Meta;
78 \& use Module::Load;
79 \&
80 \& my $meta = CPAN::Meta\->load_file(\*(AqMETA.json\*(Aq);
81 \&
82 \& printf "testing requirements for %s version %s\en",
83 \& $meta\->name,
84 \& $meta\->version;
85 \&
86 \& my $prereqs = $meta\->effective_prereqs;
87 \&
88 \& for my $phase ( qw/configure runtime build test/ ) {
89 \& say "Requirements for $phase:";
90 \& my $reqs = $prereqs\->requirements_for($phase, "requires");
91 \& for my $module ( sort $reqs\->required_modules ) {
92 \& my $status;
93 \& if ( eval { load $module unless $module eq \*(Aqperl\*(Aq; 1 } ) {
94 \& my $version = $module eq \*(Aqperl\*(Aq ? $] : $module\->VERSION;
95 \& $status = $reqs\->accepts_module($module, $version)
96 \& ? "$version ok" : "$version not ok";
97 \& } else {
98 \& $status = "missing"
99 \& };
100 \& say " $module ($status)";
101 \& }
102 \& }
103 .Ve
104 .SH DESCRIPTION
105 .IX Header "DESCRIPTION"
106 Software distributions released to the CPAN include a \fIMETA.json\fR or, for
107 older distributions, \fIMETA.yml\fR, which describes the distribution, its
108 contents, and the requirements for building and installing the distribution.
109 The data structure stored in the \fIMETA.json\fR file is described in
110 CPAN::Meta::Spec.
111 .PP
112 CPAN::Meta provides a simple class to represent this distribution metadata (or
113 \&\fIdistmeta\fR), along with some helpful methods for interrogating that data.
114 .PP
115 The documentation below is only for the methods of the CPAN::Meta object. For
116 information on the meaning of individual fields, consult the spec.
117 .SH METHODS
118 .IX Header "METHODS"
119 .SS new
120 .IX Subsection "new"
121 .Vb 1
122 \& my $meta = CPAN::Meta\->new($distmeta_struct, \e%options);
123 .Ve
124 .PP
125 Returns a valid CPAN::Meta object or dies if the supplied metadata hash
126 reference fails to validate. Older\-format metadata will be up\-converted to
127 version 2 if they validate against the original stated specification.
128 .PP
129 It takes an optional hashref of options. Valid options include:
130 .IP \(bu 4
131 lazy_validation \-\- if true, new will attempt to convert the given metadata
132 to version 2 before attempting to validate it. This means than any
133 fixable errors will be handled by CPAN::Meta::Converter before validation.
134 (Note that this might result in invalid optional data being silently
135 dropped.) The default is false.
136 .SS create
137 .IX Subsection "create"
138 .Vb 1
139 \& my $meta = CPAN::Meta\->create($distmeta_struct, \e%options);
140 .Ve
141 .PP
142 This is same as \f(CWnew()\fR, except that \f(CW\*(C`generated_by\*(C'\fR and \f(CW\*(C`meta\-spec\*(C'\fR fields
143 will be generated if not provided. This means the metadata structure is
144 assumed to otherwise follow the latest CPAN::Meta::Spec.
145 .SS load_file
146 .IX Subsection "load_file"
147 .Vb 1
148 \& my $meta = CPAN::Meta\->load_file($distmeta_file, \e%options);
149 .Ve
150 .PP
151 Given a pathname to a file containing metadata, this deserializes the file
152 according to its file suffix and constructs a new \f(CW\*(C`CPAN::Meta\*(C'\fR object, just
153 like \f(CWnew()\fR. It will die if the deserialized version fails to validate
154 against its stated specification version.
155 .PP
156 It takes the same options as \f(CWnew()\fR but \f(CW\*(C`lazy_validation\*(C'\fR defaults to
157 true.
158 .SS load_yaml_string
159 .IX Subsection "load_yaml_string"
160 .Vb 1
161 \& my $meta = CPAN::Meta\->load_yaml_string($yaml, \e%options);
162 .Ve
163 .PP
164 This method returns a new CPAN::Meta object using the first document in the
165 given YAML string. In other respects it is identical to \f(CWload_file()\fR.
166 .SS load_json_string
167 .IX Subsection "load_json_string"
168 .Vb 1
169 \& my $meta = CPAN::Meta\->load_json_string($json, \e%options);
170 .Ve
171 .PP
172 This method returns a new CPAN::Meta object using the structure represented by
173 the given JSON string. In other respects it is identical to \f(CWload_file()\fR.
174 .SS load_string
175 .IX Subsection "load_string"
176 .Vb 1
177 \& my $meta = CPAN::Meta\->load_string($string, \e%options);
178 .Ve
179 .PP
180 If you don\*(Aqt know if a string contains YAML or JSON, this method will use
181 Parse::CPAN::Meta to guess. In other respects it is identical to
182 \&\f(CWload_file()\fR.
183 .SS save
184 .IX Subsection "save"
185 .Vb 1
186 \& $meta\->save($distmeta_file, \e%options);
187 .Ve
188 .PP
189 Serializes the object as JSON and writes it to the given file. The only valid
190 option is \f(CW\*(C`version\*(C'\fR, which defaults to \*(Aq2\*(Aq. On Perl 5.8.1 or later, the file
191 is saved with UTF\-8 encoding.
192 .PP
193 For \f(CW\*(C`version\*(C'\fR 2 (or higher), the filename should end in \*(Aq.json\*(Aq. JSON::PP
194 is the default JSON backend. Using another JSON backend requires JSON 2.5 or
195 later and you must set the \f(CW$ENV{PERL_JSON_BACKEND}\fR to a supported alternate
196 backend like JSON::XS.
197 .PP
198 For \f(CW\*(C`version\*(C'\fR less than 2, the filename should end in \*(Aq.yml\*(Aq.
199 CPAN::Meta::Converter is used to generate an older metadata structure, which
200 is serialized to YAML. CPAN::Meta::YAML is the default YAML backend. You may
201 set the \f(CW$ENV{PERL_YAML_BACKEND}\fR to a supported alternative backend, though
202 this is not recommended due to subtle incompatibilities between YAML parsers on
203 CPAN.
204 .SS meta_spec_version
205 .IX Subsection "meta_spec_version"
206 This method returns the version part of the \f(CW\*(C`meta_spec\*(C'\fR entry in the distmeta
207 structure. It is equivalent to:
208 .PP
209 .Vb 1
210 \& $meta\->meta_spec\->{version};
211 .Ve
212 .SS effective_prereqs
213 .IX Subsection "effective_prereqs"
214 .Vb 1
215 \& my $prereqs = $meta\->effective_prereqs;
216 \&
217 \& my $prereqs = $meta\->effective_prereqs( \e@feature_identifiers );
218 .Ve
219 .PP
220 This method returns a CPAN::Meta::Prereqs object describing all the
221 prereqs for the distribution. If an arrayref of feature identifiers is given,
222 the prereqs for the identified features are merged together with the
223 distribution\*(Aqs core prereqs before the CPAN::Meta::Prereqs object is returned.
224 .SS should_index_file
225 .IX Subsection "should_index_file"
226 .Vb 1
227 \& ... if $meta\->should_index_file( $filename );
228 .Ve
229 .PP
230 This method returns true if the given file should be indexed. It decides this
231 by checking the \f(CW\*(C`file\*(C'\fR and \f(CW\*(C`directory\*(C'\fR keys in the \f(CW\*(C`no_index\*(C'\fR property of
232 the distmeta structure. Note that neither the version format nor
233 \&\f(CW\*(C`release_status\*(C'\fR are considered.
234 .PP
235 \&\f(CW$filename\fR should be given in unix format.
236 .SS should_index_package
237 .IX Subsection "should_index_package"
238 .Vb 1
239 \& ... if $meta\->should_index_package( $package );
240 .Ve
241 .PP
242 This method returns true if the given package should be indexed. It decides
243 this by checking the \f(CW\*(C`package\*(C'\fR and \f(CW\*(C`namespace\*(C'\fR keys in the \f(CW\*(C`no_index\*(C'\fR
244 property of the distmeta structure. Note that neither the version format nor
245 \&\f(CW\*(C`release_status\*(C'\fR are considered.
246 .SS features
247 .IX Subsection "features"
248 .Vb 1
249 \& my @feature_objects = $meta\->features;
250 .Ve
251 .PP
252 This method returns a list of CPAN::Meta::Feature objects, one for each
253 optional feature described by the distribution\*(Aqs metadata.
254 .SS feature
255 .IX Subsection "feature"
256 .Vb 1
257 \& my $feature_object = $meta\->feature( $identifier );
258 .Ve
259 .PP
260 This method returns a CPAN::Meta::Feature object for the optional feature
261 with the given identifier. If no feature with that identifier exists, an
262 exception will be raised.
263 .SS as_struct
264 .IX Subsection "as_struct"
265 .Vb 1
266 \& my $copy = $meta\->as_struct( \e%options );
267 .Ve
268 .PP
269 This method returns a deep copy of the object\*(Aqs metadata as an unblessed hash
270 reference. It takes an optional hashref of options. If the hashref contains
271 a \f(CW\*(C`version\*(C'\fR argument, the copied metadata will be converted to the version
272 of the specification and returned. For example:
273 .PP
274 .Vb 1
275 \& my $old_spec = $meta\->as_struct( {version => "1.4"} );
276 .Ve
277 .SS as_string
278 .IX Subsection "as_string"
279 .Vb 1
280 \& my $string = $meta\->as_string( \e%options );
281 .Ve
282 .PP
283 This method returns a serialized copy of the object\*(Aqs metadata as a character
284 string. (The strings are \fBnot\fR UTF\-8 encoded.) It takes an optional hashref
285 of options. If the hashref contains a \f(CW\*(C`version\*(C'\fR argument, the copied metadata
286 will be converted to the version of the specification and returned. For
287 example:
288 .PP
289 .Vb 1
290 \& my $string = $meta\->as_string( {version => "1.4"} );
291 .Ve
292 .PP
293 For \f(CW\*(C`version\*(C'\fR greater than or equal to 2, the string will be serialized as
294 JSON. For \f(CW\*(C`version\*(C'\fR less than 2, the string will be serialized as YAML. In
295 both cases, the same rules are followed as in the \f(CWsave()\fR method for choosing
296 a serialization backend.
297 .PP
298 The serialized structure will include a \f(CW\*(C`x_serialization_backend\*(C'\fR entry giving
299 the package and version used to serialize. Any existing key in the given
300 \&\f(CW$meta\fR object will be clobbered.
301 .SH "STRING DATA"
302 .IX Header "STRING DATA"
303 The following methods return a single value, which is the value for the
304 corresponding entry in the distmeta structure. Values should be either undef
305 or strings.
306 .IP \(bu 4
307 abstract
308 .IP \(bu 4
309 description
310 .IP \(bu 4
311 dynamic_config
312 .IP \(bu 4
313 generated_by
314 .IP \(bu 4
315 name
316 .IP \(bu 4
317 release_status
318 .IP \(bu 4
319 version
320 .SH "LIST DATA"
321 .IX Header "LIST DATA"
322 These methods return lists of string values, which might be represented in the
323 distmeta structure as arrayrefs or scalars:
324 .IP \(bu 4
325 authors
326 .IP \(bu 4
327 keywords
328 .IP \(bu 4
329 licenses
330 .PP
331 The \f(CW\*(C`authors\*(C'\fR and \f(CW\*(C`licenses\*(C'\fR methods may also be called as \f(CW\*(C`author\*(C'\fR and
332 \&\f(CW\*(C`license\*(C'\fR, respectively, to match the field name in the distmeta structure.
333 .SH "MAP DATA"
334 .IX Header "MAP DATA"
335 These readers return hashrefs of arbitrary unblessed data structures, each
336 described more fully in the specification:
337 .IP \(bu 4
338 meta_spec
339 .IP \(bu 4
340 resources
341 .IP \(bu 4
342 provides
343 .IP \(bu 4
344 no_index
345 .IP \(bu 4
346 prereqs
347 .IP \(bu 4
348 optional_features
349 .SH "CUSTOM DATA"
350 .IX Header "CUSTOM DATA"
351 A list of custom keys are available from the \f(CW\*(C`custom_keys\*(C'\fR method and
352 particular keys may be retrieved with the \f(CW\*(C`custom\*(C'\fR method.
353 .PP
354 .Vb 1
355 \& say $meta\->custom($_) for $meta\->custom_keys;
356 .Ve
357 .PP
358 If a custom key refers to a data structure, a deep clone is returned.
359 .SH BUGS
360 .IX Header "BUGS"
361 Please report any bugs or feature using the CPAN Request Tracker.
362 Bugs can be submitted through the web interface at
363 <http://rt.cpan.org/Dist/Display.html?Queue=CPAN\-Meta>
364 .PP
365 When submitting a bug or request, please include a test\-file or a patch to an
366 existing test\-file that illustrates the bug or desired feature.
367 .SH "SEE ALSO"
368 .IX Header "SEE ALSO"
369 .IP \(bu 4
370 CPAN::Meta::Converter
371 .IP \(bu 4
372 CPAN::Meta::Validator
373 .SH SUPPORT
374 .IX Header "SUPPORT"
375 .SS "Bugs / Feature Requests"
376 .IX Subsection "Bugs / Feature Requests"
377 Please report any bugs or feature requests through the issue tracker
378 at <https://github.com/Perl\-Toolchain\-Gang/CPAN\-Meta/issues>.
379 You will be notified automatically of any progress on your issue.
380 .SS "Source Code"
381 .IX Subsection "Source Code"
382 This is open source software. The code repository is available for
383 public review and contribution under the terms of the license.
384 .PP
385 <https://github.com/Perl\-Toolchain\-Gang/CPAN\-Meta>
386 .PP
387 .Vb 1
388 \& git clone https://github.com/Perl\-Toolchain\-Gang/CPAN\-Meta.git
389 .Ve
390 .SH AUTHORS
391 .IX Header "AUTHORS"
392 .IP \(bu 4
393 David Golden <[email protected]>
394 .IP \(bu 4
395 Ricardo Signes <[email protected]>
396 .IP \(bu 4
397 Adam Kennedy <[email protected]>
398 .SH CONTRIBUTORS
399 .IX Header "CONTRIBUTORS"
400 .IP \(bu 4
401 Ansgar Burchardt <[email protected]>
402 .IP \(bu 4
403 Avar Arnfjord Bjarmason <[email protected]>
404 .IP \(bu 4
405 Benjamin Noggle <[email protected]>
406 .IP \(bu 4
407 Christopher J. Madsen <[email protected]>
408 .IP \(bu 4
409 Chuck Adams <[email protected]>
410 .IP \(bu 4
411 Cory G Watson <[email protected]>
412 .IP \(bu 4
413 Damyan Ivanov <[email protected]>
414 .IP \(bu 4
415 David Golden <[email protected]>
416 .IP \(bu 4
417 Eric Wilhelm <[email protected]>
418 .IP \(bu 4
419 Graham Knop <[email protected]>
420 .IP \(bu 4
421 Gregor Hermann <[email protected]>
422 .IP \(bu 4
423 Karen Etheridge <[email protected]>
424 .IP \(bu 4
425 Kenichi Ishigaki <[email protected]>
426 .IP \(bu 4
427 Kent Fredric <[email protected]>
428 .IP \(bu 4
429 Ken Williams <[email protected]>
430 .IP \(bu 4
431 Lars Dieckow <[email protected]>
432 .IP \(bu 4
433 Leon Timmermans <[email protected]>
434 .IP \(bu 4
435 majensen <[email protected]>
436 .IP \(bu 4
437 Mark Fowler <[email protected]>
438 .IP \(bu 4
439 Matt S Trout <[email protected]>
440 .IP \(bu 4
441 Michael G. Schwern <[email protected]>
442 .IP \(bu 4
443 Mohammad S Anwar <[email protected]>
444 .IP \(bu 4
445 mohawk2 <[email protected]>
446 .IP \(bu 4
447 moznion <[email protected]>
448 .IP \(bu 4
449 Niko Tyni <[email protected]>
450 .IP \(bu 4
451 Olaf Alders <[email protected]>
452 .IP \(bu 4
453 Olivier MenguĂ© <[email protected]>
454 .IP \(bu 4
455 Randy Sims <[email protected]>
456 .IP \(bu 4
457 Tomohiro Hosaka <[email protected]>
458 .SH "COPYRIGHT AND LICENSE"
459 .IX Header "COPYRIGHT AND LICENSE"
460 This software is copyright (c) 2010 by David Golden, Ricardo Signes, Adam Kennedy and Contributors.
461 .PP
462 This is free software; you can redistribute it and/or modify it under
463 the same terms as the Perl 5 programming language system itself.