Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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.