Debian Codegraph @

upstream/debian-unstable/man3/CPAN::Meta.3perl

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