Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 138 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3pm/Devel::SelfStubber.3pm b/upstream/mageia-cauldron/man3pm/Devel::SelfStubber.3pm
new file mode 100644
index 00000000..4cda9695
--- /dev/null
+++ b/upstream/mageia-cauldron/man3pm/Devel::SelfStubber.3pm
@@ -0,0 +1,138 @@
+.\" -*- 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 "Devel::SelfStubber 3pm"
+.TH Devel::SelfStubber 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
+Devel::SelfStubber \- generate stubs for a SelfLoading module
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+To generate just the stubs:
+.PP
+.Vb 2
+\&    use Devel::SelfStubber;
+\&    Devel::SelfStubber\->stub(\*(AqMODULENAME\*(Aq,\*(AqMY_LIB_DIR\*(Aq);
+.Ve
+.PP
+or to generate the whole module with stubs inserted correctly
+.PP
+.Vb 3
+\&    use Devel::SelfStubber;
+\&    $Devel::SelfStubber::JUST_STUBS=0;
+\&    Devel::SelfStubber\->stub(\*(AqMODULENAME\*(Aq,\*(AqMY_LIB_DIR\*(Aq);
+.Ve
+.PP
+MODULENAME is the Perl module name, e.g. Devel::SelfStubber,
+NOT 'Devel/SelfStubber' or 'Devel/SelfStubber.pm'.
+.PP
+MY_LIB_DIR defaults to '.' if not present.
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Devel::SelfStubber prints the stubs you need to put in the module
+before the _\|_DATA_\|_ token (or you can get it to print the entire
+module with stubs correctly placed). The stubs ensure that if
+a method is called, it will get loaded. They are needed specifically
+for inherited autoloaded methods.
+.PP
+This is best explained using the following example:
+.PP
+Assume four classes, A,B,C & D.
+.PP
+A is the root class, B is a subclass of A, C is a subclass of B,
+and D is another subclass of A.
+.PP
+.Vb 5
+\&                        A
+\&                       / \e
+\&                      B   D
+\&                     /
+\&                    C
+.Ve
+.PP
+If D calls an autoloaded method 'foo' which is defined in class A,
+then the method is loaded into class A, then executed. If C then
+calls method 'foo', and that method was reimplemented in class
+B, but set to be autoloaded, then the lookup mechanism never gets to
+the AUTOLOAD mechanism in B because it first finds the method
+already loaded in A, and so erroneously uses that. If the method
+foo had been stubbed in B, then the lookup mechanism would have
+found the stub, and correctly loaded and used the sub from B.
+.PP
+So, for classes and subclasses to have inheritance correctly
+work with autoloading, you need to ensure stubs are loaded.
+.PP
+The SelfLoader can load stubs automatically at module initialization
+with the statement 'SelfLoader\->\fBload_stubs()\fR';, but you may wish to
+avoid having the stub loading overhead associated with your
+initialization (though note that the SelfLoader::load_stubs method
+will be called sooner or later \- at latest when the first sub
+is being autoloaded). In this case, you can put the sub stubs
+before the _\|_DATA_\|_ token. This can be done manually, but this
+module allows automatic generation of the stubs.
+.PP
+By default it just prints the stubs, but you can set the
+global \f(CW$Devel::SelfStubber::JUST_STUBS\fR to 0 and it will
+print out the entire module with the stubs positioned correctly.
+.PP
+At the very least, this is useful to see what the SelfLoader
+thinks are stubs \- in order to ensure future versions of the
+SelfStubber remain in step with the SelfLoader, the
+SelfStubber actually uses the SelfLoader to determine which
+stubs are needed.