Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 459 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3pm/NEXT.3pm b/upstream/mageia-cauldron/man3pm/NEXT.3pm
new file mode 100644
index 00000000..1f2ac5eb
--- /dev/null
+++ b/upstream/mageia-cauldron/man3pm/NEXT.3pm
@@ -0,0 +1,459 @@
+.\" -*- 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 "NEXT 3pm"
+.TH NEXT 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
+NEXT \- Provide a pseudo\-class NEXT (et al) that allows method redispatch
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&    use NEXT;
+\&
+\&    package P;
+\&    sub P::method   { print "$_[0]: P method\en";   $_[0]\->NEXT::method() }
+\&    sub P::DESTROY  { print "$_[0]: P dtor\en";     $_[0]\->NEXT::DESTROY() }
+\&
+\&    package Q;
+\&    use base qw( P );
+\&    sub Q::AUTOLOAD { print "$_[0]: Q AUTOLOAD\en"; $_[0]\->NEXT::AUTOLOAD() }
+\&    sub Q::DESTROY  { print "$_[0]: Q dtor\en";     $_[0]\->NEXT::DESTROY() }
+\&
+\&    package R;
+\&    sub R::method   { print "$_[0]: R method\en";   $_[0]\->NEXT::method() }
+\&    sub R::AUTOLOAD { print "$_[0]: R AUTOLOAD\en"; $_[0]\->NEXT::AUTOLOAD() }
+\&    sub R::DESTROY  { print "$_[0]: R dtor\en";     $_[0]\->NEXT::DESTROY() }
+\&
+\&    package S;
+\&    use base qw( Q R );
+\&    sub S::method   { print "$_[0]: S method\en";   $_[0]\->NEXT::method() }
+\&    sub S::AUTOLOAD { print "$_[0]: S AUTOLOAD\en"; $_[0]\->NEXT::AUTOLOAD() }
+\&    sub S::DESTROY  { print "$_[0]: S dtor\en";     $_[0]\->NEXT::DESTROY() }
+\&
+\&    package main;
+\&
+\&    my $obj = bless {}, "S";
+\&
+\&    $obj\->method();             # Calls S::method, P::method, R::method
+\&    $obj\->missing_method(); # Calls S::AUTOLOAD, Q::AUTOLOAD, R::AUTOLOAD
+\&
+\&    # Clean\-up calls S::DESTROY, Q::DESTROY, P::DESTROY, R::DESTROY
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The \f(CW\*(C`NEXT\*(C'\fR module adds a pseudoclass named \f(CW\*(C`NEXT\*(C'\fR to any program
+that uses it. If a method \f(CW\*(C`m\*(C'\fR calls \f(CW\*(C`$self\->NEXT::m()\*(C'\fR, the call to
+\&\f(CW\*(C`m\*(C'\fR is redispatched as if the calling method had not originally been found.
+.PP
+\&\fBNote:\fR before using this module,
+you should look at next::method <https://metacpan.org/pod/mro#next::method>
+in the core mro module.
+\&\f(CW\*(C`mro\*(C'\fR has been a core module since Perl 5.9.5.
+.PP
+In other words, a call to \f(CW\*(C`$self\->NEXT::m()\*(C'\fR resumes the depth-first,
+left-to-right search of \f(CW$self\fR's class hierarchy that resulted in the
+original call to \f(CW\*(C`m\*(C'\fR.
+.PP
+Note that this is not the same thing as \f(CW\*(C`$self\->SUPER::m()\*(C'\fR, which
+begins a new dispatch that is restricted to searching the ancestors
+of the current class. \f(CW\*(C`$self\->NEXT::m()\*(C'\fR can backtrack
+past the current class \-\- to look for a suitable method in other
+ancestors of \f(CW$self\fR \-\- whereas \f(CW\*(C`$self\->SUPER::m()\*(C'\fR cannot.
+.PP
+A typical use would be in the destructors of a class hierarchy,
+as illustrated in the SYNOPSIS above. Each class in the hierarchy
+has a DESTROY method that performs some class-specific action
+and then redispatches the call up the hierarchy. As a result,
+when an object of class S is destroyed, the destructors of \fIall\fR
+its parent classes are called (in depth-first, left-to-right order).
+.PP
+Another typical use of redispatch would be in \f(CW\*(C`AUTOLOAD\*(C'\fR'ed methods.
+If such a method determined that it was not able to handle a
+particular call, it might choose to redispatch that call, in the
+hope that some other \f(CW\*(C`AUTOLOAD\*(C'\fR (above it, or to its left) might
+do better.
+.PP
+By default, if a redispatch attempt fails to find another method
+elsewhere in the objects class hierarchy, it quietly gives up and does
+nothing (but see "Enforcing redispatch"). This gracious acquiescence
+is also unlike the (generally annoying) behaviour of \f(CW\*(C`SUPER\*(C'\fR, which
+throws an exception if it cannot redispatch.
+.PP
+Note that it is a fatal error for any method (including \f(CW\*(C`AUTOLOAD\*(C'\fR)
+to attempt to redispatch any method that does not have the
+same name. For example:
+.PP
+.Vb 1
+\&        sub S::oops { print "oops!\en"; $_[0]\->NEXT::other_method() }
+.Ve
+.SS "Enforcing redispatch"
+.IX Subsection "Enforcing redispatch"
+It is possible to make \f(CW\*(C`NEXT\*(C'\fR redispatch more demandingly (i.e. like
+\&\f(CW\*(C`SUPER\*(C'\fR does), so that the redispatch throws an exception if it cannot
+find a "next" method to call.
+.PP
+To do this, simple invoke the redispatch as:
+.PP
+.Vb 1
+\&        $self\->NEXT::ACTUAL::method();
+.Ve
+.PP
+rather than:
+.PP
+.Vb 1
+\&        $self\->NEXT::method();
+.Ve
+.PP
+The \f(CW\*(C`ACTUAL\*(C'\fR tells \f(CW\*(C`NEXT\*(C'\fR that there must actually be a next method to call,
+or it should throw an exception.
+.PP
+\&\f(CW\*(C`NEXT::ACTUAL\*(C'\fR is most commonly used in \f(CW\*(C`AUTOLOAD\*(C'\fR methods, as a means to
+decline an \f(CW\*(C`AUTOLOAD\*(C'\fR request, but preserve the normal exception-on-failure 
+semantics:
+.PP
+.Vb 8
+\&        sub AUTOLOAD {
+\&                if ($AUTOLOAD =~ /foo|bar/) {
+\&                        # handle here
+\&                }
+\&                else {  # try elsewhere
+\&                        shift()\->NEXT::ACTUAL::AUTOLOAD(@_);
+\&                }
+\&        }
+.Ve
+.PP
+By using \f(CW\*(C`NEXT::ACTUAL\*(C'\fR, if there is no other \f(CW\*(C`AUTOLOAD\*(C'\fR to handle the
+method call, an exception will be thrown (as usually happens in the absence of
+a suitable \f(CW\*(C`AUTOLOAD\*(C'\fR).
+.SS "Avoiding repetitions"
+.IX Subsection "Avoiding repetitions"
+If \f(CW\*(C`NEXT\*(C'\fR redispatching is used in the methods of a "diamond" class hierarchy:
+.PP
+.Vb 5
+\&        #     A   B
+\&        #    / \e /
+\&        #   C   D
+\&        #    \e /
+\&        #     E
+\&
+\&        use NEXT;
+\&
+\&        package A;                 
+\&        sub foo { print "called A::foo\en"; shift\->NEXT::foo() }
+\&
+\&        package B;                 
+\&        sub foo { print "called B::foo\en"; shift\->NEXT::foo() }
+\&
+\&        package C; @ISA = qw( A );
+\&        sub foo { print "called C::foo\en"; shift\->NEXT::foo() }
+\&
+\&        package D; @ISA = qw(A B);
+\&        sub foo { print "called D::foo\en"; shift\->NEXT::foo() }
+\&
+\&        package E; @ISA = qw(C D);
+\&        sub foo { print "called E::foo\en"; shift\->NEXT::foo() }
+\&
+\&        E\->foo();
+.Ve
+.PP
+then derived classes may (re\-)inherit base-class methods through two or
+more distinct paths (e.g. in the way \f(CW\*(C`E\*(C'\fR inherits \f(CW\*(C`A::foo\*(C'\fR twice \-\-
+through \f(CW\*(C`C\*(C'\fR and \f(CW\*(C`D\*(C'\fR). In such cases, a sequence of \f(CW\*(C`NEXT\*(C'\fR redispatches
+will invoke the multiply inherited method as many times as it is
+inherited. For example, the above code prints:
+.PP
+.Vb 6
+\&        called E::foo
+\&        called C::foo
+\&        called A::foo
+\&        called D::foo
+\&        called A::foo
+\&        called B::foo
+.Ve
+.PP
+(i.e. \f(CW\*(C`A::foo\*(C'\fR is called twice).
+.PP
+In some cases this \fImay\fR be the desired effect within a diamond hierarchy,
+but in others (e.g. for destructors) it may be more appropriate to 
+call each method only once during a sequence of redispatches.
+.PP
+To cover such cases, you can redispatch methods via:
+.PP
+.Vb 1
+\&        $self\->NEXT::DISTINCT::method();
+.Ve
+.PP
+rather than:
+.PP
+.Vb 1
+\&        $self\->NEXT::method();
+.Ve
+.PP
+This causes the redispatcher to only visit each distinct \f(CW\*(C`method\*(C'\fR method
+once. That is, to skip any classes in the hierarchy that it has
+already visited during redispatch. So, for example, if the
+previous example were rewritten:
+.PP
+.Vb 2
+\&        package A;                 
+\&        sub foo { print "called A::foo\en"; shift\->NEXT::DISTINCT::foo() }
+\&
+\&        package B;                 
+\&        sub foo { print "called B::foo\en"; shift\->NEXT::DISTINCT::foo() }
+\&
+\&        package C; @ISA = qw( A );
+\&        sub foo { print "called C::foo\en"; shift\->NEXT::DISTINCT::foo() }
+\&
+\&        package D; @ISA = qw(A B);
+\&        sub foo { print "called D::foo\en"; shift\->NEXT::DISTINCT::foo() }
+\&
+\&        package E; @ISA = qw(C D);
+\&        sub foo { print "called E::foo\en"; shift\->NEXT::DISTINCT::foo() }
+\&
+\&        E\->foo();
+.Ve
+.PP
+then it would print:
+.PP
+.Vb 5
+\&        called E::foo
+\&        called C::foo
+\&        called A::foo
+\&        called D::foo
+\&        called B::foo
+.Ve
+.PP
+and omit the second call to \f(CW\*(C`A::foo\*(C'\fR (since it would not be distinct
+from the first call to \f(CW\*(C`A::foo\*(C'\fR).
+.PP
+Note that you can also use:
+.PP
+.Vb 1
+\&        $self\->NEXT::DISTINCT::ACTUAL::method();
+.Ve
+.PP
+or:
+.PP
+.Vb 1
+\&        $self\->NEXT::ACTUAL::DISTINCT::method();
+.Ve
+.PP
+to get both unique invocation \fIand\fR exception-on-failure.
+.PP
+Note that, for historical compatibility, you can also use
+\&\f(CW\*(C`NEXT::UNSEEN\*(C'\fR instead of \f(CW\*(C`NEXT::DISTINCT\*(C'\fR.
+.SS "Invoking all versions of a method with a single call"
+.IX Subsection "Invoking all versions of a method with a single call"
+Yet another pseudo-class that \f(CW\*(C`NEXT\*(C'\fR provides is \f(CW\*(C`EVERY\*(C'\fR.
+Its behaviour is considerably simpler than that of the \f(CW\*(C`NEXT\*(C'\fR family.
+A call to:
+.PP
+.Vb 1
+\&        $obj\->EVERY::foo();
+.Ve
+.PP
+calls \fIevery\fR method named \f(CW\*(C`foo\*(C'\fR that the object in \f(CW$obj\fR has inherited.
+That is:
+.PP
+.Vb 1
+\&        use NEXT;
+\&
+\&        package A; @ISA = qw(B D X);
+\&        sub foo { print "A::foo " }
+\&
+\&        package B; @ISA = qw(D X);
+\&        sub foo { print "B::foo " }
+\&
+\&        package X; @ISA = qw(D);
+\&        sub foo { print "X::foo " }
+\&
+\&        package D;
+\&        sub foo { print "D::foo " }
+\&
+\&        package main;
+\&
+\&        my $obj = bless {}, \*(AqA\*(Aq;
+\&        $obj\->EVERY::foo();        # prints" A::foo B::foo X::foo D::foo
+.Ve
+.PP
+Prefixing a method call with \f(CW\*(C`EVERY::\*(C'\fR causes every method in the
+object's hierarchy with that name to be invoked. As the above example
+illustrates, they are not called in Perl's usual "left-most-depth-first"
+order. Instead, they are called "breadth-first-dependency-wise".
+.PP
+That means that the inheritance tree of the object is traversed breadth-first
+and the resulting order of classes is used as the sequence in which methods
+are called. However, that sequence is modified by imposing a rule that the
+appropriate method of a derived class must be called before the same method of
+any ancestral class. That's why, in the above example, \f(CW\*(C`X::foo\*(C'\fR is called
+before \f(CW\*(C`D::foo\*(C'\fR, even though \f(CW\*(C`D\*(C'\fR comes before \f(CW\*(C`X\*(C'\fR in \f(CW@B::ISA\fR.
+.PP
+In general, there's no need to worry about the order of calls. They will be
+left-to-right, breadth-first, most-derived-first. This works perfectly for
+most inherited methods (including destructors), but is inappropriate for
+some kinds of methods (such as constructors, cloners, debuggers, and
+initializers) where it's more appropriate that the least-derived methods be
+called first (as more-derived methods may rely on the behaviour of their
+"ancestors"). In that case, instead of using the \f(CW\*(C`EVERY\*(C'\fR pseudo-class:
+.PP
+.Vb 1
+\&        $obj\->EVERY::foo();        # prints" A::foo B::foo X::foo D::foo
+.Ve
+.PP
+you can use the \f(CW\*(C`EVERY::LAST\*(C'\fR pseudo-class:
+.PP
+.Vb 1
+\&        $obj\->EVERY::LAST::foo();  # prints" D::foo X::foo B::foo A::foo
+.Ve
+.PP
+which reverses the order of method call.
+.PP
+Whichever version is used, the actual methods are called in the same
+context (list, scalar, or void) as the original call via \f(CW\*(C`EVERY\*(C'\fR, and return:
+.IP \(bu 4
+A hash of array references in list context. Each entry of the hash has the
+fully qualified method name as its key and a reference to an array containing
+the method's list-context return values as its value.
+.IP \(bu 4
+A reference to a hash of scalar values in scalar context. Each entry of the hash has the
+fully qualified method name as its key and the method's scalar-context return values as its value.
+.IP \(bu 4
+Nothing in void context (obviously).
+.ie n .SS "Using ""EVERY"" methods"
+.el .SS "Using \f(CWEVERY\fP methods"
+.IX Subsection "Using EVERY methods"
+The typical way to use an \f(CW\*(C`EVERY\*(C'\fR call is to wrap it in another base
+method, that all classes inherit. For example, to ensure that every
+destructor an object inherits is actually called (as opposed to just the
+left-most-depth-first-est one):
+.PP
+.Vb 2
+\&        package Base;
+\&        sub DESTROY { $_[0]\->EVERY::Destroy }
+\&
+\&        package Derived1; 
+\&        use base \*(AqBase\*(Aq;
+\&        sub Destroy {...}
+\&
+\&        package Derived2; 
+\&        use base \*(AqBase\*(Aq, \*(AqDerived1\*(Aq;
+\&        sub Destroy {...}
+.Ve
+.PP
+et cetera. Every derived class than needs its own clean-up
+behaviour simply adds its own \f(CW\*(C`Destroy\*(C'\fR method (\fInot\fR a \f(CW\*(C`DESTROY\*(C'\fR method),
+which the call to \f(CW\*(C`EVERY::LAST::Destroy\*(C'\fR in the inherited destructor
+then correctly picks up.
+.PP
+Likewise, to create a class hierarchy in which every initializer inherited by
+a new object is invoked:
+.PP
+.Vb 6
+\&        package Base;
+\&        sub new {
+\&                my ($class, %args) = @_;
+\&                my $obj = bless {}, $class;
+\&                $obj\->EVERY::LAST::Init(\e%args);
+\&        }
+\&
+\&        package Derived1; 
+\&        use base \*(AqBase\*(Aq;
+\&        sub Init {
+\&                my ($argsref) = @_;
+\&                ...
+\&        }
+\&
+\&        package Derived2; 
+\&        use base \*(AqBase\*(Aq, \*(AqDerived1\*(Aq;
+\&        sub Init {
+\&                my ($argsref) = @_;
+\&                ...
+\&        }
+.Ve
+.PP
+et cetera. Every derived class than needs some additional initialization
+behaviour simply adds its own \f(CW\*(C`Init\*(C'\fR method (\fInot\fR a \f(CW\*(C`new\*(C'\fR method),
+which the call to \f(CW\*(C`EVERY::LAST::Init\*(C'\fR in the inherited constructor
+then correctly picks up.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+mro
+(in particular next::method <https://metacpan.org/pod/mro#next::method>),
+which has been a core module since Perl 5.9.5.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Damian Conway (damian@conway.org)
+.SH "BUGS AND IRRITATIONS"
+.IX Header "BUGS AND IRRITATIONS"
+Because it's a module, not an integral part of the interpreter, \f(CW\*(C`NEXT\*(C'\fR
+has to guess where the surrounding call was found in the method
+look-up sequence. In the presence of diamond inheritance patterns
+it occasionally guesses wrong.
+.PP
+It's also too slow (despite caching).
+.PP
+Comment, suggestions, and patches welcome.
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+.Vb 3
+\& Copyright (c) 2000\-2001, Damian Conway. All Rights Reserved.
+\& This module is free software. It may be used, redistributed
+\&    and/or modified under the same terms as Perl itself.
+.Ve