Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 273 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/Test::Harness.3perl b/upstream/debian-unstable/man3/Test::Harness.3perl
new file mode 100644
index 00000000..1a9ad648
--- /dev/null
+++ b/upstream/debian-unstable/man3/Test::Harness.3perl
@@ -0,0 +1,273 @@
+.\" -*- 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::Harness 3perl"
+.TH Test::Harness 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
+Test::Harness \- Run Perl standard test scripts with statistics
+.SH VERSION
+.IX Header "VERSION"
+Version 3.44
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&  use Test::Harness;
+\&
+\&  runtests(@test_files);
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Although, for historical reasons, the Test::Harness distribution
+takes its name from this module it now exists only to provide
+TAP::Harness with an interface that is somewhat backwards compatible
+with Test::Harness 2.xx. If you're writing new code consider using
+TAP::Harness directly instead.
+.PP
+Emulation is provided for \f(CW\*(C`runtests\*(C'\fR and \f(CW\*(C`execute_tests\*(C'\fR but the
+pluggable 'Straps' interface that previous versions of Test::Harness
+supported is not reproduced here. Straps is now available as a stand
+alone module: Test::Harness::Straps.
+.PP
+See TAP::Parser, TAP::Harness for the main documentation for this
+distribution.
+.SH FUNCTIONS
+.IX Header "FUNCTIONS"
+The following functions are available.
+.ie n .SS "runtests( @test_files )"
+.el .SS "runtests( \f(CW@test_files\fP )"
+.IX Subsection "runtests( @test_files )"
+This runs all the given \fR\f(CI@test_files\fR\fI\fR and divines whether they passed
+or failed based on their output to STDOUT (details above).  It prints
+out each individual test which failed along with a summary report and
+a how long it all took.
+.PP
+It returns true if everything was ok.  Otherwise it will \f(CWdie()\fR with
+one of the messages in the DIAGNOSTICS section.
+.SS "execute_tests( tests => \e@test_files, out => \e*FH )"
+.IX Subsection "execute_tests( tests => @test_files, out => *FH )"
+Runs all the given \f(CW@test_files\fR (just like \f(CWruntests()\fR) but
+doesn't generate the final report.  During testing, progress
+information will be written to the currently selected output
+filehandle (usually \f(CW\*(C`STDOUT\*(C'\fR), or to the filehandle given by the
+\&\f(CW\*(C`out\*(C'\fR parameter.  The \fIout\fR is optional.
+.PP
+Returns a list of two values, \f(CW$total\fR and \f(CW$failed\fR, describing the
+results.  \f(CW$total\fR is a hash ref summary of all the tests run.  Its
+keys and values are this:
+.PP
+.Vb 5
+\&    bonus           Number of individual todo tests unexpectedly passed
+\&    max             Number of individual tests ran
+\&    ok              Number of individual tests passed
+\&    sub_skipped     Number of individual tests skipped
+\&    todo            Number of individual todo tests
+\&
+\&    files           Number of test files ran
+\&    good            Number of test files passed
+\&    bad             Number of test files failed
+\&    tests           Number of test files originally given
+\&    skipped         Number of test files skipped
+.Ve
+.PP
+If \f(CW\*(C`$total\->{bad} == 0\*(C'\fR and \f(CW\*(C`$total\->{max} > 0\*(C'\fR, you've
+got a successful test.
+.PP
+\&\f(CW$failed\fR is a hash ref of all the test scripts that failed.  Each key
+is the name of a test script, each value is another hash representing
+how that script failed.  Its keys are these:
+.PP
+.Vb 6
+\&    name        Name of the test which failed
+\&    estat       Script\*(Aqs exit value
+\&    wstat       Script\*(Aqs wait status
+\&    max         Number of individual tests
+\&    failed      Number which failed
+\&    canon       List of tests which failed (as string).
+.Ve
+.PP
+\&\f(CW$failed\fR should be empty if everything passed.
+.SH EXPORT
+.IX Header "EXPORT"
+\&\f(CW&runtests\fR is exported by \f(CW\*(C`Test::Harness\*(C'\fR by default.
+.PP
+\&\f(CW&execute_tests\fR, \f(CW$verbose\fR, \f(CW$switches\fR and \f(CW$debug\fR are
+exported upon request.
+.SH "ENVIRONMENT VARIABLES THAT TAP::HARNESS::COMPATIBLE SETS"
+.IX Header "ENVIRONMENT VARIABLES THAT TAP::HARNESS::COMPATIBLE SETS"
+\&\f(CW\*(C`Test::Harness\*(C'\fR sets these before executing the individual tests.
+.ie n .IP """HARNESS_ACTIVE""" 4
+.el .IP \f(CWHARNESS_ACTIVE\fR 4
+.IX Item "HARNESS_ACTIVE"
+This is set to a true value.  It allows the tests to determine if they
+are being executed through the harness or by any other means.
+.ie n .IP """HARNESS_VERSION""" 4
+.el .IP \f(CWHARNESS_VERSION\fR 4
+.IX Item "HARNESS_VERSION"
+This is the version of \f(CW\*(C`Test::Harness\*(C'\fR.
+.SH "ENVIRONMENT VARIABLES THAT AFFECT TEST::HARNESS"
+.IX Header "ENVIRONMENT VARIABLES THAT AFFECT TEST::HARNESS"
+.ie n .IP """HARNESS_PERL_SWITCHES""" 4
+.el .IP \f(CWHARNESS_PERL_SWITCHES\fR 4
+.IX Item "HARNESS_PERL_SWITCHES"
+Setting this adds perl command line switches to each test file run.
+.Sp
+For example, \f(CW\*(C`HARNESS_PERL_SWITCHES=\-T\*(C'\fR will turn on taint mode.
+\&\f(CW\*(C`HARNESS_PERL_SWITCHES=\-MDevel::Cover\*(C'\fR will run \f(CW\*(C`Devel::Cover\*(C'\fR for
+each test.
+.Sp
+\&\f(CW\*(C`\-w\*(C'\fR is always set.  You can turn this off in the test with \f(CW\*(C`BEGIN {
+$^W = 0 }\*(C'\fR.
+.ie n .IP """HARNESS_TIMER""" 4
+.el .IP \f(CWHARNESS_TIMER\fR 4
+.IX Item "HARNESS_TIMER"
+Setting this to true will make the harness display the number of
+milliseconds each test took.  You can also use \fIprove\fR's \f(CW\*(C`\-\-timer\*(C'\fR
+switch.
+.ie n .IP """HARNESS_VERBOSE""" 4
+.el .IP \f(CWHARNESS_VERBOSE\fR 4
+.IX Item "HARNESS_VERBOSE"
+If true, \f(CW\*(C`Test::Harness\*(C'\fR will output the verbose results of running
+its tests.  Setting \f(CW$Test::Harness::verbose\fR will override this,
+or you can use the \f(CW\*(C`\-v\*(C'\fR switch in the \fIprove\fR utility.
+.ie n .IP """HARNESS_OPTIONS""" 4
+.el .IP \f(CWHARNESS_OPTIONS\fR 4
+.IX Item "HARNESS_OPTIONS"
+Provide additional options to the harness. Currently supported options are:
+.RS 4
+.ie n .IP """j<n>""" 4
+.el .IP \f(CWj<n>\fR 4
+.IX Item "j<n>"
+Run <n> (default 9) parallel jobs.
+.ie n .IP """c""" 4
+.el .IP \f(CWc\fR 4
+.IX Item "c"
+Try to color output. See "new" in TAP::Formatter::Base.
+.ie n .IP """a<file.tgz>""" 4
+.el .IP \f(CWa<file.tgz>\fR 4
+.IX Item "a<file.tgz>"
+Will use TAP::Harness::Archive as the harness class, and save the TAP to
+\&\f(CW\*(C`file.tgz\*(C'\fR
+.ie n .IP """fPackage\-With\-Dashes""" 4
+.el .IP \f(CWfPackage\-With\-Dashes\fR 4
+.IX Item "fPackage-With-Dashes"
+Set the formatter_class of the harness being run. Since the \f(CW\*(C`HARNESS_OPTIONS\*(C'\fR
+is separated by \f(CW\*(C`:\*(C'\fR, we use \f(CW\*(C`\-\*(C'\fR instead.
+.RE
+.RS 4
+.Sp
+Multiple options may be separated by colons:
+.Sp
+.Vb 1
+\&    HARNESS_OPTIONS=j9:c make test
+.Ve
+.RE
+.ie n .IP """HARNESS_SUBCLASS""" 4
+.el .IP \f(CWHARNESS_SUBCLASS\fR 4
+.IX Item "HARNESS_SUBCLASS"
+Specifies a TAP::Harness subclass to be used in place of TAP::Harness.
+.ie n .IP """HARNESS_SUMMARY_COLOR_SUCCESS""" 4
+.el .IP \f(CWHARNESS_SUMMARY_COLOR_SUCCESS\fR 4
+.IX Item "HARNESS_SUMMARY_COLOR_SUCCESS"
+Determines the Term::ANSIColor for the summary in case it is successful.
+This color defaults to \f(CW\*(Aqgreen\*(Aq\fR.
+.ie n .IP """HARNESS_SUMMARY_COLOR_FAIL""" 4
+.el .IP \f(CWHARNESS_SUMMARY_COLOR_FAIL\fR 4
+.IX Item "HARNESS_SUMMARY_COLOR_FAIL"
+Determines the Term::ANSIColor for the failure in case it is successful.
+This color defaults to \f(CW\*(Aqred\*(Aq\fR.
+.SH "Taint Mode"
+.IX Header "Taint Mode"
+Normally when a Perl program is run in taint mode the contents of the
+\&\f(CW\*(C`PERL5LIB\*(C'\fR environment variable do not appear in \f(CW@INC\fR.
+.PP
+Because \f(CW\*(C`PERL5LIB\*(C'\fR is often used during testing to add build
+directories to \f(CW@INC\fR \f(CW\*(C`Test::Harness\*(C'\fR passes the names of any
+directories found in \f(CW\*(C`PERL5LIB\*(C'\fR as \-I switches. The net effect of this
+is that \f(CW\*(C`PERL5LIB\*(C'\fR is honoured even in taint mode.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+TAP::Harness
+.SH BUGS
+.IX Header "BUGS"
+Please report any bugs or feature requests to
+\&\f(CW\*(C`bug\-test\-harness at rt.cpan.org\*(C'\fR, or through the web interface at
+<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test\-Harness>.  I will be 
+notified, and then you'll automatically be notified of progress on your bug 
+as I make changes.
+.SH AUTHORS
+.IX Header "AUTHORS"
+Andy Armstrong  \f(CW\*(C`<andy@hexten.net>\*(C'\fR
+.PP
+Test::Harness 2.64 (maintained by Andy Lester and on which this
+module is based) has this attribution:
+.PP
+.Vb 5
+\&    Either Tim Bunce or Andreas Koenig, we don\*(Aqt know. What we know for
+\&    sure is, that it was inspired by Larry Wall\*(Aqs F<TEST> script that came
+\&    with perl distributions for ages. Numerous anonymous contributors
+\&    exist.  Andreas Koenig held the torch for many years, and then
+\&    Michael G Schwern.
+.Ve
+.SH "LICENCE AND COPYRIGHT"
+.IX Header "LICENCE AND COPYRIGHT"
+Copyright (c) 2007\-2011, Andy Armstrong \f(CW\*(C`<andy@hexten.net>\*(C'\fR. All rights reserved.
+.PP
+This module is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself. See perlartistic.