Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 370 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3pm/version.3pm b/upstream/mageia-cauldron/man3pm/version.3pm
new file mode 100644
index 00000000..20af615d
--- /dev/null
+++ b/upstream/mageia-cauldron/man3pm/version.3pm
@@ -0,0 +1,370 @@
+.\" -*- 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 "version 3pm"
+.TH version 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
+version \- Perl extension for Version Objects
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&  # Parsing version strings (decimal or dotted\-decimal)
+\&
+\&  use version 0.77; # get latest bug\-fixes and API
+\&  $ver = version\->parse($string)
+\&
+\&  # Declaring a dotted\-decimal $VERSION (keep on one line!)
+\&
+\&  use version; our $VERSION = version\->declare("v1.2.3"); # formal
+\&  use version; our $VERSION = qv("v1.2.3");               # deprecated
+\&  use version; our $VERSION = qv("v1.2_3");               # deprecated
+\&
+\&  # Declaring an old\-style decimal $VERSION (use quotes!)
+\&
+\&  our $VERSION = "1.0203";                                # recommended
+\&  use version; our $VERSION = version\->parse("1.0203");   # formal
+\&  use version; our $VERSION = version\->parse("1.02_03");  # alpha
+\&
+\&  # Comparing mixed version styles (decimals, dotted\-decimals, objects)
+\&
+\&  if ( version\->parse($v1) == version\->parse($v2) ) {
+\&    # do stuff
+\&  }
+\&
+\&  # Sorting mixed version styles
+\&
+\&  @ordered = sort { version\->parse($a) <=> version\->parse($b) } @list;
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Version objects were added to Perl in 5.10.  This module implements version
+objects for older version of Perl and provides the version object API for all
+versions of Perl.  All previous releases before 0.74 are deprecated and should
+not be used due to incompatible API changes.  Version 0.77 introduces the new
+\&'parse' and 'declare' methods to standardize usage.  You are strongly urged to
+set 0.77 as a minimum in your code, e.g.
+.PP
+.Vb 1
+\&  use version 0.77; # even for Perl v.5.10.0
+.Ve
+.SH "TYPES OF VERSION OBJECTS"
+.IX Header "TYPES OF VERSION OBJECTS"
+There are two different types of version objects, corresponding to the two
+different styles of versions in use:
+.IP "Decimal Versions" 2
+.IX Item "Decimal Versions"
+The classic floating-point number \f(CW$VERSION\fR.  The advantage to this style is
+that you don't need to do anything special, just type a number into your
+source file.  Quoting is recommended, as it ensures that trailing zeroes
+("1.50") are preserved in any warnings or other output.
+.IP "Dotted Decimal Versions" 2
+.IX Item "Dotted Decimal Versions"
+The more modern form of version assignment, with 3 (or potentially more)
+integers separated by decimal points (e.g. v1.2.3).  This is the form that
+Perl itself has used since 5.6.0 was released.  The leading 'v' is now
+strongly recommended for clarity, and will throw a warning in a future
+release if omitted.  A leading 'v' character is required to pass the
+"\fBis_strict()\fR" test.
+.SH "DECLARING VERSIONS"
+.IX Header "DECLARING VERSIONS"
+If you have a module that uses a decimal \f(CW$VERSION\fR (floating point), and you
+do not intend to ever change that, this module is not for you.  There is
+nothing that version.pm gains you over a simple \f(CW$VERSION\fR assignment:
+.PP
+.Vb 1
+\&  our $VERSION = "1.02";
+.Ve
+.PP
+Since Perl v5.10.0 includes the version.pm comparison logic anyways,
+you don't need to do anything at all.
+.SS "How to convert a module from decimal to dotted-decimal"
+.IX Subsection "How to convert a module from decimal to dotted-decimal"
+If you have used a decimal \f(CW$VERSION\fR in the past and wish to switch to a
+dotted-decimal \f(CW$VERSION\fR, then you need to make a one-time conversion to
+the new format.
+.PP
+\&\fBImportant Note\fR: you must ensure that your new \f(CW$VERSION\fR is numerically
+greater than your current decimal \f(CW$VERSION\fR; this is not always obvious. First,
+convert your old decimal version (e.g. 1.02) to a normalized dotted-decimal
+form:
+.PP
+.Vb 2
+\&  $ perl \-Mversion \-e \*(Aqprint version\->parse("1.02")\->normal\*(Aq
+\&  v1.20.0
+.Ve
+.PP
+Then increment any of the dotted-decimal components (v1.20.1 or v1.21.0).
+.ie n .SS "How to declare() a dotted-decimal version"
+.el .SS "How to \f(CWdeclare()\fP a dotted-decimal version"
+.IX Subsection "How to declare() a dotted-decimal version"
+.Vb 1
+\&  use version; our $VERSION = version\->declare("v1.2.3");
+.Ve
+.PP
+The \f(CWdeclare()\fR method always creates dotted-decimal version objects.  When
+used in a module, you \fBmust\fR put it on the same line as "use version" to
+ensure that \f(CW$VERSION\fR is read correctly by PAUSE and installer tools.  You
+should also add 'version' to the 'configure_requires' section of your
+module metadata file.  See instructions in ExtUtils::MakeMaker or
+Module::Build for details.
+.PP
+\&\fBImportant Note\fR: Even if you pass in what looks like a decimal number
+("1.2"), a dotted-decimal will be created ("v1.200.0"). To avoid confusion
+or unintentional errors on older Perls, follow these guidelines:
+.IP \(bu 2
+Always use a dotted-decimal with (at least) three components
+.IP \(bu 2
+Always use a leading-v
+.IP \(bu 2
+Always quote the version
+.PP
+If you really insist on using version.pm with an ordinary decimal version,
+use \f(CWparse()\fR instead of declare.  See the "PARSING AND COMPARING VERSIONS"
+for details.
+.PP
+See also version::Internals for more on version number conversion,
+quoting, calculated version numbers and declaring developer or "alpha" version
+numbers.
+.SH "PARSING AND COMPARING VERSIONS"
+.IX Header "PARSING AND COMPARING VERSIONS"
+If you need to compare version numbers, but can't be sure whether they are
+expressed as numbers, strings, v\-strings or version objects,  then you should
+use version.pm to parse them all into objects for comparison.
+.ie n .SS "How to parse() a version"
+.el .SS "How to \f(CWparse()\fP a version"
+.IX Subsection "How to parse() a version"
+The \f(CWparse()\fR method takes in anything that might be a version and returns
+a corresponding version object, doing any necessary conversion along the way.
+.IP \(bu 2
+Dotted-decimal: bare v\-strings (v1.2.3) and strings with more than one
+decimal point and a leading 'v' ("v1.2.3"); NOTE you can technically use a
+v\-string or strings with a leading-v and only one decimal point (v1.2 or
+"v1.2"), but you will confuse both yourself and others.
+.IP \(bu 2
+Decimal: regular decimal numbers (literal or in a string)
+.PP
+Some examples:
+.PP
+.Vb 8
+\&  $variable   version\->parse($variable)
+\&  \-\-\-\-\-\-\-\-\-   \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&  1.23        v1.230.0
+\&  "1.23"      v1.230.0
+\&  v1.23       v1.23.0
+\&  "v1.23"     v1.23.0
+\&  "1.2.3"     v1.2.3
+\&  "v1.2.3"    v1.2.3
+.Ve
+.PP
+See version::Internals for more on version number conversion.
+.SS "How to check for a legal version string"
+.IX Subsection "How to check for a legal version string"
+If you do not want to actually create a full blown version object, but
+would still like to verify that a given string meets the criteria to
+be parsed as a version, there are two helper functions that can be
+employed directly:
+.ie n .IP is_lax() 4
+.el .IP \f(CWis_lax()\fR 4
+.IX Item "is_lax()"
+The lax criteria corresponds to what is currently allowed by the
+version parser.  All of the following formats are acceptable
+for dotted-decimal formats strings:
+.Sp
+.Vb 5
+\&    v1.2
+\&    1.2345.6
+\&    v1.23_4
+\&    1.2345
+\&    1.2345_01
+.Ve
+.ie n .IP is_strict() 4
+.el .IP \f(CWis_strict()\fR 4
+.IX Item "is_strict()"
+If you want to limit yourself to a much more narrow definition of what
+a version string constitutes, \f(CWis_strict()\fR is limited to version
+strings like the following list:
+.Sp
+.Vb 2
+\&    v1.234.5
+\&    2.3456
+.Ve
+.PP
+See version::Internals for details of the regular expressions
+that define the legal version string forms, as well as how to use
+those regular expressions in your own code if \f(CWis_lax()\fR and
+\&\f(CWis_strict()\fR are not sufficient for your needs.
+.SS "How to compare version objects"
+.IX Subsection "How to compare version objects"
+Version objects overload the \f(CW\*(C`cmp\*(C'\fR and \f(CW\*(C`<=>\*(C'\fR operators.  Perl
+automatically generates all of the other comparison operators based on those
+two so all the normal logical comparisons will work.
+.PP
+.Vb 3
+\&  if ( version\->parse($v1) == version\->parse($v2) ) {
+\&    # do stuff
+\&  }
+.Ve
+.PP
+If a version object is compared against a non-version object, the non-object
+term will be converted to a version object using \f(CWparse()\fR.  This may give
+surprising results:
+.PP
+.Vb 2
+\&  $v1 = version\->parse("v0.95.0");
+\&  $bool = $v1 < 0.94; # TRUE since 0.94 is v0.940.0
+.Ve
+.PP
+Always comparing to a version object will help avoid surprises:
+.PP
+.Vb 1
+\&  $bool = $v1 < version\->parse("v0.94.0"); # FALSE
+.Ve
+.PP
+Note that "alpha" version objects (where the version string contains
+a trailing underscore segment) compare as less than the equivalent
+version without an underscore:
+.PP
+.Vb 1
+\&  $bool = version\->parse("1.23_45") < version\->parse("1.2345"); # TRUE
+.Ve
+.PP
+See version::Internals for more details on "alpha" versions.
+.SH "OBJECT METHODS"
+.IX Header "OBJECT METHODS"
+.SS \fBis_alpha()\fP
+.IX Subsection "is_alpha()"
+True if and only if the version object was created with a underscore, e.g.
+.PP
+.Vb 2
+\&  version\->parse(\*(Aq1.002_03\*(Aq)\->is_alpha;  # TRUE
+\&  version\->declare(\*(Aq1.2.3_4\*(Aq)\->is_alpha; # TRUE
+.Ve
+.SS \fBis_qv()\fP
+.IX Subsection "is_qv()"
+True only if the version object is a dotted-decimal version, e.g.
+.PP
+.Vb 4
+\&  version\->parse(\*(Aqv1.2.0\*(Aq)\->is_qv;       # TRUE
+\&  version\->declare(\*(Aqv1.2\*(Aq)\->is_qv;       # TRUE
+\&  qv(\*(Aq1.2\*(Aq)\->is_qv;                      # TRUE
+\&  version\->parse(\*(Aq1.2\*(Aq)\->is_qv;          # FALSE
+.Ve
+.SS \fBnormal()\fP
+.IX Subsection "normal()"
+Returns a string with a standard 'normalized' dotted-decimal form with a
+leading-v and at least 3 components.
+.PP
+.Vb 2
+\& version\->declare(\*(Aqv1.2\*(Aq)\->normal;  # v1.2.0
+\& version\->parse(\*(Aq1.2\*(Aq)\->normal;     # v1.200.0
+.Ve
+.SS \fBnumify()\fP
+.IX Subsection "numify()"
+Returns a value representing the object in a pure decimal.
+.PP
+.Vb 2
+\& version\->declare(\*(Aqv1.2\*(Aq)\->numify;  # 1.002000
+\& version\->parse(\*(Aq1.2\*(Aq)\->numify;     # 1.200
+.Ve
+.SS \fBstringify()\fP
+.IX Subsection "stringify()"
+Returns a string that is as close to the original representation as possible.
+If the original representation was a numeric literal, it will be returned the
+way perl would normally represent it in a string.  This method is used whenever
+a version object is interpolated into a string.
+.PP
+.Vb 3
+\& version\->declare(\*(Aqv1.2\*(Aq)\->stringify;    # v1.2
+\& version\->parse(\*(Aq1.200\*(Aq)\->stringify;     # 1.2
+\& version\->parse(1.02_30)\->stringify;     # 1.023
+.Ve
+.SH "EXPORTED FUNCTIONS"
+.IX Header "EXPORTED FUNCTIONS"
+.SS \fBqv()\fP
+.IX Subsection "qv()"
+This function is no longer recommended for use, but is maintained for
+compatibility with existing code.  If you do not want to have it exported
+to your namespace, use this form:
+.PP
+.Vb 1
+\&  use version 0.77 ();
+.Ve
+.SS \fBis_lax()\fP
+.IX Subsection "is_lax()"
+(Not exported by default)
+.PP
+This function takes a scalar argument and returns a boolean value indicating
+whether the argument meets the "lax" rules for a version number.  Leading and
+trailing spaces are not allowed.
+.SS \fBis_strict()\fP
+.IX Subsection "is_strict()"
+(Not exported by default)
+.PP
+This function takes a scalar argument and returns a boolean value indicating
+whether the argument meets the "strict" rules for a version number.  Leading
+and trailing spaces are not allowed.
+.SH AUTHOR
+.IX Header "AUTHOR"
+John Peacock <jpeacock@cpan.org>
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+version::Internals.
+.PP
+perl.