Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 349 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/Module::Metadata.3perl b/upstream/debian-unstable/man3/Module::Metadata.3perl
new file mode 100644
index 00000000..3001bf57
--- /dev/null
+++ b/upstream/debian-unstable/man3/Module::Metadata.3perl
@@ -0,0 +1,349 @@
+.\" -*- 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 "Module::Metadata 3perl"
+.TH Module::Metadata 3perl 2024-01-12 "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
+Module::Metadata \- Gather package and POD information from perl module files
+.SH VERSION
+.IX Header "VERSION"
+version 1.000037
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&  use Module::Metadata;
+\&
+\&  # information about a .pm file
+\&  my $info = Module::Metadata\->new_from_file( $file );
+\&  my $version = $info\->version;
+\&
+\&  # CPAN META \*(Aqprovides\*(Aq field for .pm files in a directory
+\&  my $provides = Module::Metadata\->provides(
+\&    dir => \*(Aqlib\*(Aq, version => 2
+\&  );
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This module provides a standard way to gather metadata about a .pm file through
+(mostly) static analysis and (some) code execution.  When determining the
+version of a module, the \f(CW$VERSION\fR assignment is \f(CW\*(C`eval\*(C'\fRed, as is traditional
+in the CPAN toolchain.
+.SH "CLASS METHODS"
+.IX Header "CLASS METHODS"
+.ie n .SS """new_from_file($filename, collect_pod => 1, decode_pod => 1)"""
+.el .SS "\f(CWnew_from_file($filename, collect_pod => 1, decode_pod => 1)\fP"
+.IX Subsection "new_from_file($filename, collect_pod => 1, decode_pod => 1)"
+Constructs a \f(CW\*(C`Module::Metadata\*(C'\fR object given the path to a file.  Returns
+undef if the filename does not exist.
+.PP
+\&\f(CW\*(C`collect_pod\*(C'\fR is a optional boolean argument that determines whether POD
+data is collected and stored for reference.  POD data is not collected by
+default.  POD headings are always collected.
+.PP
+If the file begins by an UTF\-8, UTF\-16BE or UTF\-16LE byte-order mark, then
+it is skipped before processing, and the content of the file is also decoded
+appropriately starting from perl 5.8.
+.PP
+Alternatively, if \f(CW\*(C`decode_pod\*(C'\fR is set, it will decode the collected pod
+sections according to the \f(CW\*(C`=encoding\*(C'\fR declaration.
+.ie n .SS """new_from_handle($handle, $filename, collect_pod => 1, decode_pod => 1)"""
+.el .SS "\f(CWnew_from_handle($handle, $filename, collect_pod => 1, decode_pod => 1)\fP"
+.IX Subsection "new_from_handle($handle, $filename, collect_pod => 1, decode_pod => 1)"
+This works just like \f(CW\*(C`new_from_file\*(C'\fR, except that a handle can be provided
+as the first argument.
+.PP
+Note that there is no validation to confirm that the handle is a handle or
+something that can act like one.  Passing something that isn't a handle will
+cause a exception when trying to read from it.  The \f(CW\*(C`filename\*(C'\fR argument is
+mandatory or undef will be returned.
+.PP
+You are responsible for setting the decoding layers on \f(CW$handle\fR if
+required.
+.ie n .SS """new_from_module($module, collect_pod => 1, inc => \e@dirs, decode_pod => 1)"""
+.el .SS "\f(CWnew_from_module($module, collect_pod => 1, inc => \e@dirs, decode_pod => 1)\fP"
+.IX Subsection "new_from_module($module, collect_pod => 1, inc => @dirs, decode_pod => 1)"
+Constructs a \f(CW\*(C`Module::Metadata\*(C'\fR object given a module or package name.
+Returns undef if the module cannot be found.
+.PP
+In addition to accepting the \f(CW\*(C`collect_pod\*(C'\fR and \f(CW\*(C`decode_pod\*(C'\fR arguments as
+described above, this method accepts a \f(CW\*(C`inc\*(C'\fR argument which is a reference to
+an array of directories to search for the module.  If none are given, the
+default is \f(CW@INC\fR.
+.PP
+If the file that contains the module begins by an UTF\-8, UTF\-16BE or
+UTF\-16LE byte-order mark, then it is skipped before processing, and the
+content of the file is also decoded appropriately starting from perl 5.8.
+.ie n .SS """find_module_by_name($module, \e@dirs)"""
+.el .SS "\f(CWfind_module_by_name($module, \e@dirs)\fP"
+.IX Subsection "find_module_by_name($module, @dirs)"
+Returns the path to a module given the module or package name. A list
+of directories can be passed in as an optional parameter, otherwise
+\&\f(CW@INC\fR is searched.
+.PP
+Can be called as either an object or a class method.
+.ie n .SS """find_module_dir_by_name($module, \e@dirs)"""
+.el .SS "\f(CWfind_module_dir_by_name($module, \e@dirs)\fP"
+.IX Subsection "find_module_dir_by_name($module, @dirs)"
+Returns the entry in \f(CW@dirs\fR (or \f(CW@INC\fR by default) that contains
+the module \f(CW$module\fR. A list of directories can be passed in as an
+optional parameter, otherwise \f(CW@INC\fR is searched.
+.PP
+Can be called as either an object or a class method.
+.ie n .SS "provides( %options )"
+.el .SS "\f(CWprovides( %options )\fP"
+.IX Subsection "provides( %options )"
+This is a convenience wrapper around \f(CW\*(C`package_versions_from_directory\*(C'\fR
+to generate a CPAN META \f(CW\*(C`provides\*(C'\fR data structure.  It takes key/value
+pairs.  Valid option keys include:
+.IP "version \fB(required)\fR" 4
+.IX Item "version (required)"
+Specifies which version of the CPAN::Meta::Spec should be used as
+the format of the \f(CW\*(C`provides\*(C'\fR output.  Currently only '1.4' and '2'
+are supported (and their format is identical).  This may change in
+the future as the definition of \f(CW\*(C`provides\*(C'\fR changes.
+.Sp
+The \f(CW\*(C`version\*(C'\fR option is required.  If it is omitted or if
+an unsupported version is given, then \f(CW\*(C`provides\*(C'\fR will throw an error.
+.IP dir 4
+.IX Item "dir"
+Directory to search recursively for \fI.pm\fR files.  May not be specified with
+\&\f(CW\*(C`files\*(C'\fR.
+.IP files 4
+.IX Item "files"
+Array reference of files to examine.  May not be specified with \f(CW\*(C`dir\*(C'\fR.
+.IP prefix 4
+.IX Item "prefix"
+String to prepend to the \f(CW\*(C`file\*(C'\fR field of the resulting output. This defaults
+to \fIlib\fR, which is the common case for most CPAN distributions with their
+\&\fI.pm\fR files in \fIlib\fR.  This option ensures the META information has the
+correct relative path even when the \f(CW\*(C`dir\*(C'\fR or \f(CW\*(C`files\*(C'\fR arguments are
+absolute or have relative paths from a location other than the distribution
+root.
+.PP
+For example, given \f(CW\*(C`dir\*(C'\fR of 'lib' and \f(CW\*(C`prefix\*(C'\fR of 'lib', the return value
+is a hashref of the form:
+.PP
+.Vb 7
+\&  {
+\&    \*(AqPackage::Name\*(Aq => {
+\&      version => \*(Aq0.123\*(Aq,
+\&      file => \*(Aqlib/Package/Name.pm\*(Aq
+\&    },
+\&    \*(AqOtherPackage::Name\*(Aq => ...
+\&  }
+.Ve
+.ie n .SS """package_versions_from_directory($dir, \e@files?)"""
+.el .SS "\f(CWpackage_versions_from_directory($dir, \e@files?)\fP"
+.IX Subsection "package_versions_from_directory($dir, @files?)"
+Scans \f(CW$dir\fR for .pm files (unless \f(CW@files\fR is given, in which case looks
+for those files in \f(CW$dir\fR \- and reads each file for packages and versions,
+returning a hashref of the form:
+.PP
+.Vb 7
+\&  {
+\&    \*(AqPackage::Name\*(Aq => {
+\&      version => \*(Aq0.123\*(Aq,
+\&      file => \*(AqPackage/Name.pm\*(Aq
+\&    },
+\&    \*(AqOtherPackage::Name\*(Aq => ...
+\&  }
+.Ve
+.PP
+The \f(CW\*(C`DB\*(C'\fR and \f(CW\*(C`main\*(C'\fR packages are always omitted, as are any "private"
+packages that have leading underscores in the namespace (e.g.
+\&\f(CW\*(C`Foo::_private\*(C'\fR)
+.PP
+Note that the file path is relative to \f(CW$dir\fR if that is specified.
+This \fBmust not\fR be used directly for CPAN META \f(CW\*(C`provides\*(C'\fR.  See
+the \f(CW\*(C`provides\*(C'\fR method instead.
+.ie n .SS """log_info (internal)"""
+.el .SS "\f(CWlog_info (internal)\fP"
+.IX Subsection "log_info (internal)"
+Used internally to perform logging; imported from Log::Contextual if
+Log::Contextual has already been loaded, otherwise simply calls warn.
+.SH "OBJECT METHODS"
+.IX Header "OBJECT METHODS"
+.ie n .SS name()
+.el .SS \f(CWname()\fP
+.IX Subsection "name()"
+Returns the name of the package represented by this module. If there
+is more than one package, it makes a best guess based on the
+filename. If it's a script (i.e. not a *.pm) the package name is
+\&'main'.
+.ie n .SS version($package)
+.el .SS \f(CWversion($package)\fP
+.IX Subsection "version($package)"
+Returns the version as defined by the \f(CW$VERSION\fR variable for the
+package as returned by the \f(CW\*(C`name\*(C'\fR method if no arguments are
+given. If given the name of a package it will attempt to return the
+version of that package if it is specified in the file.
+.ie n .SS filename()
+.el .SS \f(CWfilename()\fP
+.IX Subsection "filename()"
+Returns the absolute path to the file.
+Note that this file may not actually exist on disk yet, e.g. if the module was read from an in-memory filehandle.
+.ie n .SS packages_inside()
+.el .SS \f(CWpackages_inside()\fP
+.IX Subsection "packages_inside()"
+Returns a list of packages. Note: this is a raw list of packages
+discovered (or assumed, in the case of \f(CW\*(C`main\*(C'\fR).  It is not
+filtered for \f(CW\*(C`DB\*(C'\fR, \f(CW\*(C`main\*(C'\fR or private packages the way the
+\&\f(CW\*(C`provides\*(C'\fR method does.  Invalid package names are not returned,
+for example "Foo:Bar".  Strange but valid package names are
+returned, for example "Foo::Bar::", and are left up to the caller
+on how to handle.
+.ie n .SS pod_inside()
+.el .SS \f(CWpod_inside()\fP
+.IX Subsection "pod_inside()"
+Returns a list of POD sections.
+.ie n .SS contains_pod()
+.el .SS \f(CWcontains_pod()\fP
+.IX Subsection "contains_pod()"
+Returns true if there is any POD in the file.
+.ie n .SS pod($section)
+.el .SS \f(CWpod($section)\fP
+.IX Subsection "pod($section)"
+Returns the POD data in the given section.
+.ie n .SS "is_indexable($package) or is_indexable()"
+.el .SS "\f(CWis_indexable($package)\fP or \f(CWis_indexable()\fP"
+.IX Subsection "is_indexable($package) or is_indexable()"
+Available since version 1.000020.
+.PP
+Returns a boolean indicating whether the package (if provided) or any package
+(otherwise) is eligible for indexing by PAUSE, the Perl Authors Upload Server.
+Note This only checks for valid \f(CW\*(C`package\*(C'\fR declarations, and does not take any
+ownership information into account.
+.SH SUPPORT
+.IX Header "SUPPORT"
+Bugs may be submitted through the RT bug tracker <https://rt.cpan.org/Public/Dist/Display.html?Name=Module-Metadata>
+(or bug\-Module\-Metadata@rt.cpan.org <mailto:bug-Module-Metadata@rt.cpan.org>).
+.PP
+There is also a mailing list available for users of this distribution, at
+<http://lists.perl.org/list/cpan\-workers.html>.
+.PP
+There is also an irc channel available for users of this distribution, at
+\&\f(CW\*(C`#toolchain\*(C'\fR on \f(CW\*(C`irc.perl.org\*(C'\fR <irc://irc.perl.org/#toolchain>.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Original code from Module::Build::ModuleInfo by Ken Williams
+<kwilliams@cpan.org>, Randy W. Sims <RandyS@ThePierianSpring.org>
+.PP
+Released as Module::Metadata by Matt S Trout (mst) <mst@shadowcat.co.uk> with
+assistance from David Golden (xdg) <dagolden@cpan.org>.
+.SH CONTRIBUTORS
+.IX Header "CONTRIBUTORS"
+.IP \(bu 4
+Karen Etheridge <ether@cpan.org>
+.IP \(bu 4
+David Golden <dagolden@cpan.org>
+.IP \(bu 4
+Vincent Pit <perl@profvince.com>
+.IP \(bu 4
+Matt S Trout <mst@shadowcat.co.uk>
+.IP \(bu 4
+Chris Nehren <apeiron@cpan.org>
+.IP \(bu 4
+Tomas Doran <bobtfish@bobtfish.net>
+.IP \(bu 4
+Olivier Mengué <dolmen@cpan.org>
+.IP \(bu 4
+Graham Knop <haarg@haarg.org>
+.IP \(bu 4
+tokuhirom <tokuhirom@gmail.com>
+.IP \(bu 4
+Tatsuhiko Miyagawa <miyagawa@bulknews.net>
+.IP \(bu 4
+Christian Walde <walde.christian@googlemail.com>
+.IP \(bu 4
+Leon Timmermans <fawaka@gmail.com>
+.IP \(bu 4
+Peter Rabbitson <ribasushi@cpan.org>
+.IP \(bu 4
+Steve Hay <steve.m.hay@googlemail.com>
+.IP \(bu 4
+Jerry D. Hedden <jdhedden@cpan.org>
+.IP \(bu 4
+Craig A. Berry <cberry@cpan.org>
+.IP \(bu 4
+Craig A. Berry <craigberry@mac.com>
+.IP \(bu 4
+David Mitchell <davem@iabyn.com>
+.IP \(bu 4
+David Steinbrunner <dsteinbrunner@pobox.com>
+.IP \(bu 4
+Edward Zborowski <ed@rubensteintech.com>
+.IP \(bu 4
+Gareth Harper <gareth@broadbean.com>
+.IP \(bu 4
+James Raspass <jraspass@gmail.com>
+.IP \(bu 4
+Chris 'BinGOs' Williams <chris@bingosnet.co.uk>
+.IP \(bu 4
+Josh Jore <jjore@cpan.org>
+.IP \(bu 4
+Kent Fredric <kentnl@cpan.org>
+.SH "COPYRIGHT & LICENSE"
+.IX Header "COPYRIGHT & LICENSE"
+Original code Copyright (c) 2001\-2011 Ken Williams.
+Additional code Copyright (c) 2010\-2011 Matt Trout and David Golden.
+All rights reserved.
+.PP
+This library is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.