diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/CPAN::Meta.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/CPAN::Meta.3pm | 460 |
1 files changed, 460 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/CPAN::Meta.3pm b/upstream/mageia-cauldron/man3pm/CPAN::Meta.3pm new file mode 100644 index 00000000..135f1a00 --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/CPAN::Meta.3pm @@ -0,0 +1,460 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "CPAN::Meta 3pm" +.TH CPAN::Meta 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CPAN::Meta \- the distribution metadata for a CPAN dist +.SH VERSION +.IX Header "VERSION" +version 2.150010 +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 5 +\& use v5.10; +\& use strict; +\& use warnings; +\& use CPAN::Meta; +\& use Module::Load; +\& +\& my $meta = CPAN::Meta\->load_file(\*(AqMETA.json\*(Aq); +\& +\& printf "testing requirements for %s version %s\en", +\& $meta\->name, +\& $meta\->version; +\& +\& my $prereqs = $meta\->effective_prereqs; +\& +\& for my $phase ( qw/configure runtime build test/ ) { +\& say "Requirements for $phase:"; +\& my $reqs = $prereqs\->requirements_for($phase, "requires"); +\& for my $module ( sort $reqs\->required_modules ) { +\& my $status; +\& if ( eval { load $module unless $module eq \*(Aqperl\*(Aq; 1 } ) { +\& my $version = $module eq \*(Aqperl\*(Aq ? $] : $module\->VERSION; +\& $status = $reqs\->accepts_module($module, $version) +\& ? "$version ok" : "$version not ok"; +\& } else { +\& $status = "missing" +\& }; +\& say " $module ($status)"; +\& } +\& } +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Software distributions released to the CPAN include a \fIMETA.json\fR or, for +older distributions, \fIMETA.yml\fR, which describes the distribution, its +contents, and the requirements for building and installing the distribution. +The data structure stored in the \fIMETA.json\fR file is described in +CPAN::Meta::Spec. +.PP +CPAN::Meta provides a simple class to represent this distribution metadata (or +\&\fIdistmeta\fR), along with some helpful methods for interrogating that data. +.PP +The documentation below is only for the methods of the CPAN::Meta object. For +information on the meaning of individual fields, consult the spec. +.SH METHODS +.IX Header "METHODS" +.SS new +.IX Subsection "new" +.Vb 1 +\& my $meta = CPAN::Meta\->new($distmeta_struct, \e%options); +.Ve +.PP +Returns a valid CPAN::Meta object or dies if the supplied metadata hash +reference fails to validate. Older-format metadata will be up-converted to +version 2 if they validate against the original stated specification. +.PP +It takes an optional hashref of options. Valid options include: +.IP \(bu 4 +lazy_validation \-\- if true, new will attempt to convert the given metadata +to version 2 before attempting to validate it. This means than any +fixable errors will be handled by CPAN::Meta::Converter before validation. +(Note that this might result in invalid optional data being silently +dropped.) The default is false. +.SS create +.IX Subsection "create" +.Vb 1 +\& my $meta = CPAN::Meta\->create($distmeta_struct, \e%options); +.Ve +.PP +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 +will be generated if not provided. This means the metadata structure is +assumed to otherwise follow the latest CPAN::Meta::Spec. +.SS load_file +.IX Subsection "load_file" +.Vb 1 +\& my $meta = CPAN::Meta\->load_file($distmeta_file, \e%options); +.Ve +.PP +Given a pathname to a file containing metadata, this deserializes the file +according to its file suffix and constructs a new \f(CW\*(C`CPAN::Meta\*(C'\fR object, just +like \f(CWnew()\fR. It will die if the deserialized version fails to validate +against its stated specification version. +.PP +It takes the same options as \f(CWnew()\fR but \f(CW\*(C`lazy_validation\*(C'\fR defaults to +true. +.SS load_yaml_string +.IX Subsection "load_yaml_string" +.Vb 1 +\& my $meta = CPAN::Meta\->load_yaml_string($yaml, \e%options); +.Ve +.PP +This method returns a new CPAN::Meta object using the first document in the +given YAML string. In other respects it is identical to \f(CWload_file()\fR. +.SS load_json_string +.IX Subsection "load_json_string" +.Vb 1 +\& my $meta = CPAN::Meta\->load_json_string($json, \e%options); +.Ve +.PP +This method returns a new CPAN::Meta object using the structure represented by +the given JSON string. In other respects it is identical to \f(CWload_file()\fR. +.SS load_string +.IX Subsection "load_string" +.Vb 1 +\& my $meta = CPAN::Meta\->load_string($string, \e%options); +.Ve +.PP +If you don't know if a string contains YAML or JSON, this method will use +Parse::CPAN::Meta to guess. In other respects it is identical to +\&\f(CWload_file()\fR. +.SS save +.IX Subsection "save" +.Vb 1 +\& $meta\->save($distmeta_file, \e%options); +.Ve +.PP +Serializes the object as JSON and writes it to the given file. The only valid +option is \f(CW\*(C`version\*(C'\fR, which defaults to '2'. On Perl 5.8.1 or later, the file +is saved with UTF\-8 encoding. +.PP +For \f(CW\*(C`version\*(C'\fR 2 (or higher), the filename should end in '.json'. JSON::PP +is the default JSON backend. Using another JSON backend requires JSON 2.5 or +later and you must set the \f(CW$ENV{PERL_JSON_BACKEND}\fR to a supported alternate +backend like JSON::XS. +.PP +For \f(CW\*(C`version\*(C'\fR less than 2, the filename should end in '.yml'. +CPAN::Meta::Converter is used to generate an older metadata structure, which +is serialized to YAML. CPAN::Meta::YAML is the default YAML backend. You may +set the \f(CW$ENV{PERL_YAML_BACKEND}\fR to a supported alternative backend, though +this is not recommended due to subtle incompatibilities between YAML parsers on +CPAN. +.SS meta_spec_version +.IX Subsection "meta_spec_version" +This method returns the version part of the \f(CW\*(C`meta_spec\*(C'\fR entry in the distmeta +structure. It is equivalent to: +.PP +.Vb 1 +\& $meta\->meta_spec\->{version}; +.Ve +.SS effective_prereqs +.IX Subsection "effective_prereqs" +.Vb 1 +\& my $prereqs = $meta\->effective_prereqs; +\& +\& my $prereqs = $meta\->effective_prereqs( \e@feature_identifiers ); +.Ve +.PP +This method returns a CPAN::Meta::Prereqs object describing all the +prereqs for the distribution. If an arrayref of feature identifiers is given, +the prereqs for the identified features are merged together with the +distribution's core prereqs before the CPAN::Meta::Prereqs object is returned. +.SS should_index_file +.IX Subsection "should_index_file" +.Vb 1 +\& ... if $meta\->should_index_file( $filename ); +.Ve +.PP +This method returns true if the given file should be indexed. It decides this +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 +the distmeta structure. Note that neither the version format nor +\&\f(CW\*(C`release_status\*(C'\fR are considered. +.PP +\&\f(CW$filename\fR should be given in unix format. +.SS should_index_package +.IX Subsection "should_index_package" +.Vb 1 +\& ... if $meta\->should_index_package( $package ); +.Ve +.PP +This method returns true if the given package should be indexed. It decides +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 +property of the distmeta structure. Note that neither the version format nor +\&\f(CW\*(C`release_status\*(C'\fR are considered. +.SS features +.IX Subsection "features" +.Vb 1 +\& my @feature_objects = $meta\->features; +.Ve +.PP +This method returns a list of CPAN::Meta::Feature objects, one for each +optional feature described by the distribution's metadata. +.SS feature +.IX Subsection "feature" +.Vb 1 +\& my $feature_object = $meta\->feature( $identifier ); +.Ve +.PP +This method returns a CPAN::Meta::Feature object for the optional feature +with the given identifier. If no feature with that identifier exists, an +exception will be raised. +.SS as_struct +.IX Subsection "as_struct" +.Vb 1 +\& my $copy = $meta\->as_struct( \e%options ); +.Ve +.PP +This method returns a deep copy of the object's metadata as an unblessed hash +reference. It takes an optional hashref of options. If the hashref contains +a \f(CW\*(C`version\*(C'\fR argument, the copied metadata will be converted to the version +of the specification and returned. For example: +.PP +.Vb 1 +\& my $old_spec = $meta\->as_struct( {version => "1.4"} ); +.Ve +.SS as_string +.IX Subsection "as_string" +.Vb 1 +\& my $string = $meta\->as_string( \e%options ); +.Ve +.PP +This method returns a serialized copy of the object's metadata as a character +string. (The strings are \fBnot\fR UTF\-8 encoded.) It takes an optional hashref +of options. If the hashref contains a \f(CW\*(C`version\*(C'\fR argument, the copied metadata +will be converted to the version of the specification and returned. For +example: +.PP +.Vb 1 +\& my $string = $meta\->as_string( {version => "1.4"} ); +.Ve +.PP +For \f(CW\*(C`version\*(C'\fR greater than or equal to 2, the string will be serialized as +JSON. For \f(CW\*(C`version\*(C'\fR less than 2, the string will be serialized as YAML. In +both cases, the same rules are followed as in the \f(CWsave()\fR method for choosing +a serialization backend. +.PP +The serialized structure will include a \f(CW\*(C`x_serialization_backend\*(C'\fR entry giving +the package and version used to serialize. Any existing key in the given +\&\f(CW$meta\fR object will be clobbered. +.SH "STRING DATA" +.IX Header "STRING DATA" +The following methods return a single value, which is the value for the +corresponding entry in the distmeta structure. Values should be either undef +or strings. +.IP \(bu 4 +abstract +.IP \(bu 4 +description +.IP \(bu 4 +dynamic_config +.IP \(bu 4 +generated_by +.IP \(bu 4 +name +.IP \(bu 4 +release_status +.IP \(bu 4 +version +.SH "LIST DATA" +.IX Header "LIST DATA" +These methods return lists of string values, which might be represented in the +distmeta structure as arrayrefs or scalars: +.IP \(bu 4 +authors +.IP \(bu 4 +keywords +.IP \(bu 4 +licenses +.PP +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 +\&\f(CW\*(C`license\*(C'\fR, respectively, to match the field name in the distmeta structure. +.SH "MAP DATA" +.IX Header "MAP DATA" +These readers return hashrefs of arbitrary unblessed data structures, each +described more fully in the specification: +.IP \(bu 4 +meta_spec +.IP \(bu 4 +resources +.IP \(bu 4 +provides +.IP \(bu 4 +no_index +.IP \(bu 4 +prereqs +.IP \(bu 4 +optional_features +.SH "CUSTOM DATA" +.IX Header "CUSTOM DATA" +A list of custom keys are available from the \f(CW\*(C`custom_keys\*(C'\fR method and +particular keys may be retrieved with the \f(CW\*(C`custom\*(C'\fR method. +.PP +.Vb 1 +\& say $meta\->custom($_) for $meta\->custom_keys; +.Ve +.PP +If a custom key refers to a data structure, a deep clone is returned. +.SH BUGS +.IX Header "BUGS" +Please report any bugs or feature using the CPAN Request Tracker. +Bugs can be submitted through the web interface at +<http://rt.cpan.org/Dist/Display.html?Queue=CPAN\-Meta> +.PP +When submitting a bug or request, please include a test-file or a patch to an +existing test-file that illustrates the bug or desired feature. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +.IP \(bu 4 +CPAN::Meta::Converter +.IP \(bu 4 +CPAN::Meta::Validator +.SH SUPPORT +.IX Header "SUPPORT" +.SS "Bugs / Feature Requests" +.IX Subsection "Bugs / Feature Requests" +Please report any bugs or feature requests through the issue tracker +at <https://github.com/Perl\-Toolchain\-Gang/CPAN\-Meta/issues>. +You will be notified automatically of any progress on your issue. +.SS "Source Code" +.IX Subsection "Source Code" +This is open source software. The code repository is available for +public review and contribution under the terms of the license. +.PP +<https://github.com/Perl\-Toolchain\-Gang/CPAN\-Meta> +.PP +.Vb 1 +\& git clone https://github.com/Perl\-Toolchain\-Gang/CPAN\-Meta.git +.Ve +.SH AUTHORS +.IX Header "AUTHORS" +.IP \(bu 4 +David Golden <dagolden@cpan.org> +.IP \(bu 4 +Ricardo Signes <rjbs@cpan.org> +.IP \(bu 4 +Adam Kennedy <adamk@cpan.org> +.SH CONTRIBUTORS +.IX Header "CONTRIBUTORS" +.IP \(bu 4 +Ansgar Burchardt <ansgar@cpan.org> +.IP \(bu 4 +Avar Arnfjord Bjarmason <avar@cpan.org> +.IP \(bu 4 +Benjamin Noggle <agwind@users.noreply.github.com> +.IP \(bu 4 +Christopher J. Madsen <cjm@cpan.org> +.IP \(bu 4 +Chuck Adams <cja987@gmail.com> +.IP \(bu 4 +Cory G Watson <gphat@cpan.org> +.IP \(bu 4 +Damyan Ivanov <dam@cpan.org> +.IP \(bu 4 +David Golden <xdg@xdg.me> +.IP \(bu 4 +Eric Wilhelm <ewilhelm@cpan.org> +.IP \(bu 4 +Graham Knop <haarg@haarg.org> +.IP \(bu 4 +Gregor Hermann <gregoa@debian.org> +.IP \(bu 4 +Karen Etheridge <ether@cpan.org> +.IP \(bu 4 +Kenichi Ishigaki <ishigaki@cpan.org> +.IP \(bu 4 +Kent Fredric <kentfredric@gmail.com> +.IP \(bu 4 +Ken Williams <kwilliams@cpan.org> +.IP \(bu 4 +Lars Dieckow <daxim@cpan.org> +.IP \(bu 4 +Leon Timmermans <leont@cpan.org> +.IP \(bu 4 +majensen <maj@fortinbras.us> +.IP \(bu 4 +Mark Fowler <markf@cpan.org> +.IP \(bu 4 +Matt S Trout <mst@shadowcat.co.uk> +.IP \(bu 4 +Michael G. Schwern <mschwern@cpan.org> +.IP \(bu 4 +Mohammad S Anwar <mohammad.anwar@yahoo.com> +.IP \(bu 4 +mohawk2 <mohawk2@users.noreply.github.com> +.IP \(bu 4 +moznion <moznion@gmail.com> +.IP \(bu 4 +Niko Tyni <ntyni@debian.org> +.IP \(bu 4 +Olaf Alders <olaf@wundersolutions.com> +.IP \(bu 4 +Olivier Mengué <dolmen@cpan.org> +.IP \(bu 4 +Randy Sims <randys@thepierianspring.org> +.IP \(bu 4 +Tomohiro Hosaka <bokutin@bokut.in> +.SH "COPYRIGHT AND LICENSE" +.IX Header "COPYRIGHT AND LICENSE" +This software is copyright (c) 2010 by David Golden, Ricardo Signes, Adam Kennedy and Contributors. +.PP +This is free software; you can redistribute it and/or modify it under +the same terms as the Perl 5 programming language system itself. |