Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 171 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3pm/Test::Builder::Module.3pm b/upstream/mageia-cauldron/man3pm/Test::Builder::Module.3pm
new file mode 100644
index 00000000..5482db84
--- /dev/null
+++ b/upstream/mageia-cauldron/man3pm/Test::Builder::Module.3pm
@@ -0,0 +1,171 @@
+.\" -*- 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 "Test::Builder::Module 3pm"
+.TH Test::Builder::Module 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
+Test::Builder::Module \- Base class for test modules
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 2
+\&  # Emulates Test::Simple
+\&  package Your::Module;
+\&
+\&  my $CLASS = _\|_PACKAGE_\|_;
+\&
+\&  use parent \*(AqTest::Builder::Module\*(Aq;
+\&  @EXPORT = qw(ok);
+\&
+\&  sub ok ($;$) {
+\&      my $tb = $CLASS\->builder;
+\&      return $tb\->ok(@_);
+\&  }
+\&  
+\&  1;
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This is a superclass for Test::Builder\-based modules.  It provides a
+handful of common functionality and a method of getting at the underlying
+Test::Builder object.
+.SS Importing
+.IX Subsection "Importing"
+Test::Builder::Module is a subclass of Exporter which means your
+module is also a subclass of Exporter.  \f(CW@EXPORT\fR, \f(CW@EXPORT_OK\fR, etc...
+all act normally.
+.PP
+A few methods are provided to do the \f(CW\*(C`use Your::Module tests => 23\*(C'\fR part
+for you.
+.PP
+\fIimport\fR
+.IX Subsection "import"
+.PP
+Test::Builder::Module provides an \f(CWimport()\fR method which acts in the
+same basic way as Test::More's, setting the plan and controlling
+exporting of functions and variables.  This allows your module to set
+the plan independent of Test::More.
+.PP
+All arguments passed to \f(CWimport()\fR are passed onto 
+\&\f(CW\*(C`Your::Module\->builder\->plan()\*(C'\fR with the exception of 
+\&\f(CW\*(C`import =>[qw(things to import)]\*(C'\fR.
+.PP
+.Vb 1
+\&    use Your::Module import => [qw(this that)], tests => 23;
+.Ve
+.PP
+says to import the functions \f(CWthis()\fR and \f(CWthat()\fR as well as set the plan
+to be 23 tests.
+.PP
+\&\f(CWimport()\fR also sets the \f(CWexported_to()\fR attribute of your builder to be
+the caller of the \f(CWimport()\fR function.
+.PP
+Additional behaviors can be added to your \f(CWimport()\fR method by overriding
+\&\f(CWimport_extra()\fR.
+.PP
+\fIimport_extra\fR
+.IX Subsection "import_extra"
+.PP
+.Vb 1
+\&    Your::Module\->import_extra(\e@import_args);
+.Ve
+.PP
+\&\f(CWimport_extra()\fR is called by \f(CWimport()\fR.  It provides an opportunity for you
+to add behaviors to your module based on its import list.
+.PP
+Any extra arguments which shouldn't be passed on to \f(CWplan()\fR should be
+stripped off by this method.
+.PP
+See Test::More for an example of its use.
+.PP
+\&\fBNOTE\fR This mechanism is \fIVERY ALPHA AND LIKELY TO CHANGE\fR as it
+feels like a bit of an ugly hack in its current form.
+.SS Builder
+.IX Subsection "Builder"
+Test::Builder::Module provides some methods of getting at the underlying
+Test::Builder object.
+.PP
+\fIbuilder\fR
+.IX Subsection "builder"
+.PP
+.Vb 1
+\&  my $builder = Your::Class\->builder;
+.Ve
+.PP
+This method returns the Test::Builder object associated with Your::Class.
+It is not a constructor so you can call it as often as you like.
+.PP
+This is the preferred way to get the Test::Builder object.  You should
+\&\fInot\fR get it via \f(CW\*(C`Test::Builder\->new\*(C'\fR as was previously
+recommended.
+.PP
+The object returned by \f(CWbuilder()\fR may change at runtime so you should
+call \f(CWbuilder()\fR inside each function rather than store it in a global.
+.PP
+.Vb 2
+\&  sub ok {
+\&      my $builder = Your::Class\->builder;
+\&
+\&      return $builder\->ok(@_);
+\&  }
+.Ve
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Test2::Manual::Tooling::TestBuilder describes the improved
+options for writing testing modules provided by Test2.