Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 902 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/Test::Builder.3perl b/upstream/debian-unstable/man3/Test::Builder.3perl
new file mode 100644
index 00000000..e630a470
--- /dev/null
+++ b/upstream/debian-unstable/man3/Test::Builder.3perl
@@ -0,0 +1,902 @@
+.\" -*- 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 3perl"
+.TH Test::Builder 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::Builder \- Backend for building test libraries
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 2
+\&  package My::Test::Module;
+\&  use base \*(AqTest::Builder::Module\*(Aq;
+\&
+\&  my $CLASS = _\|_PACKAGE_\|_;
+\&
+\&  sub ok {
+\&      my($test, $name) = @_;
+\&      my $tb = $CLASS\->builder;
+\&
+\&      $tb\->ok($test, $name);
+\&  }
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Test::Simple and Test::More have proven to be popular testing modules,
+but they're not always flexible enough.  Test::Builder provides a
+building block upon which to write your own test libraries \fIwhich can
+work together\fR.
+.SS Construction
+.IX Subsection "Construction"
+.IP \fBnew\fR 4
+.IX Item "new"
+.Vb 1
+\&  my $Test = Test::Builder\->new;
+.Ve
+.Sp
+Returns a Test::Builder object representing the current state of the
+test.
+.Sp
+Since you only run one test per program \f(CW\*(C`new\*(C'\fR always returns the same
+Test::Builder object.  No matter how many times you call \f(CWnew()\fR, you're
+getting the same object.  This is called a singleton.  This is done so that
+multiple modules share such global information as the test counter and
+where test output is going.
+.Sp
+If you want a completely new Test::Builder object different from the
+singleton, use \f(CW\*(C`create\*(C'\fR.
+.IP \fBcreate\fR 4
+.IX Item "create"
+.Vb 1
+\&  my $Test = Test::Builder\->create;
+.Ve
+.Sp
+Ok, so there can be more than one Test::Builder object and this is how
+you get it.  You might use this instead of \f(CWnew()\fR if you're testing
+a Test::Builder based module, but otherwise you probably want \f(CW\*(C`new\*(C'\fR.
+.Sp
+\&\fBNOTE\fR: the implementation is not complete.  \f(CW\*(C`level\*(C'\fR, for example, is still
+shared by \fBall\fR Test::Builder objects, even ones created using this method.
+Also, the method name may change in the future.
+.IP \fBsubtest\fR 4
+.IX Item "subtest"
+.Vb 1
+\&    $builder\->subtest($name, \e&subtests, @args);
+.Ve
+.Sp
+See documentation of \f(CW\*(C`subtest\*(C'\fR in Test::More.
+.Sp
+\&\f(CW\*(C`subtest\*(C'\fR also, and optionally, accepts arguments which will be passed to the
+subtests reference.
+.IP \fBname\fR 4
+.IX Item "name"
+.Vb 1
+\& diag $builder\->name;
+.Ve
+.Sp
+Returns the name of the current builder.  Top level builders default to \f(CW$0\fR
+(the name of the executable).  Child builders are named via the \f(CW\*(C`child\*(C'\fR
+method.  If no name is supplied, will be named "Child of \f(CW$parent\fR\->name".
+.IP \fBreset\fR 4
+.IX Item "reset"
+.Vb 1
+\&  $Test\->reset;
+.Ve
+.Sp
+Reinitializes the Test::Builder singleton to its original state.
+Mostly useful for tests run in persistent environments where the same
+test might be run multiple times in the same process.
+.SS "Setting up tests"
+.IX Subsection "Setting up tests"
+These methods are for setting up tests and declaring how many there
+are.  You usually only want to call one of these methods.
+.IP \fBplan\fR 4
+.IX Item "plan"
+.Vb 3
+\&  $Test\->plan(\*(Aqno_plan\*(Aq);
+\&  $Test\->plan( skip_all => $reason );
+\&  $Test\->plan( tests => $num_tests );
+.Ve
+.Sp
+A convenient way to set up your tests.  Call this and Test::Builder
+will print the appropriate headers and take the appropriate actions.
+.Sp
+If you call \f(CWplan()\fR, don't call any of the other methods below.
+.IP \fBexpected_tests\fR 4
+.IX Item "expected_tests"
+.Vb 2
+\&    my $max = $Test\->expected_tests;
+\&    $Test\->expected_tests($max);
+.Ve
+.Sp
+Gets/sets the number of tests we expect this test to run and prints out
+the appropriate headers.
+.IP \fBno_plan\fR 4
+.IX Item "no_plan"
+.Vb 1
+\&  $Test\->no_plan;
+.Ve
+.Sp
+Declares that this test will run an indeterminate number of tests.
+.IP \fBdone_testing\fR 4
+.IX Item "done_testing"
+.Vb 2
+\&  $Test\->done_testing();
+\&  $Test\->done_testing($num_tests);
+.Ve
+.Sp
+Declares that you are done testing, no more tests will be run after this point.
+.Sp
+If a plan has not yet been output, it will do so.
+.Sp
+\&\f(CW$num_tests\fR is the number of tests you planned to run.  If a numbered
+plan was already declared, and if this contradicts, a failing test
+will be run to reflect the planning mistake.  If \f(CW\*(C`no_plan\*(C'\fR was declared,
+this will override.
+.Sp
+If \f(CWdone_testing()\fR is called twice, the second call will issue a
+failing test.
+.Sp
+If \f(CW$num_tests\fR is omitted, the number of tests run will be used, like
+no_plan.
+.Sp
+\&\f(CWdone_testing()\fR is, in effect, used when you'd want to use \f(CW\*(C`no_plan\*(C'\fR, but
+safer. You'd use it like so:
+.Sp
+.Vb 2
+\&    $Test\->ok($a == $b);
+\&    $Test\->done_testing();
+.Ve
+.Sp
+Or to plan a variable number of tests:
+.Sp
+.Vb 4
+\&    for my $test (@tests) {
+\&        $Test\->ok($test);
+\&    }
+\&    $Test\->done_testing(scalar @tests);
+.Ve
+.IP \fBhas_plan\fR 4
+.IX Item "has_plan"
+.Vb 1
+\&  $plan = $Test\->has_plan
+.Ve
+.Sp
+Find out whether a plan has been defined. \f(CW$plan\fR is either \f(CW\*(C`undef\*(C'\fR (no plan
+has been set), \f(CW\*(C`no_plan\*(C'\fR (indeterminate # of tests) or an integer (the number
+of expected tests).
+.IP \fBskip_all\fR 4
+.IX Item "skip_all"
+.Vb 2
+\&  $Test\->skip_all;
+\&  $Test\->skip_all($reason);
+.Ve
+.Sp
+Skips all the tests, using the given \f(CW$reason\fR.  Exits immediately with 0.
+.IP \fBexported_to\fR 4
+.IX Item "exported_to"
+.Vb 2
+\&  my $pack = $Test\->exported_to;
+\&  $Test\->exported_to($pack);
+.Ve
+.Sp
+Tells Test::Builder what package you exported your functions to.
+.Sp
+This method isn't terribly useful since modules which share the same
+Test::Builder object might get exported to different packages and only
+the last one will be honored.
+.SS "Running tests"
+.IX Subsection "Running tests"
+These actually run the tests, analogous to the functions in Test::More.
+.PP
+They all return true if the test passed, false if the test failed.
+.PP
+\&\f(CW$name\fR is always optional.
+.IP \fBok\fR 4
+.IX Item "ok"
+.Vb 1
+\&  $Test\->ok($test, $name);
+.Ve
+.Sp
+Your basic test.  Pass if \f(CW$test\fR is true, fail if \f(CW$test\fR is false.  Just
+like Test::Simple's \f(CWok()\fR.
+.IP \fBis_eq\fR 4
+.IX Item "is_eq"
+.Vb 1
+\&  $Test\->is_eq($got, $expected, $name);
+.Ve
+.Sp
+Like Test::More's \f(CWis()\fR.  Checks if \f(CW\*(C`$got eq $expected\*(C'\fR.  This is the
+string version.
+.Sp
+\&\f(CW\*(C`undef\*(C'\fR only ever matches another \f(CW\*(C`undef\*(C'\fR.
+.IP \fBis_num\fR 4
+.IX Item "is_num"
+.Vb 1
+\&  $Test\->is_num($got, $expected, $name);
+.Ve
+.Sp
+Like Test::More's \f(CWis()\fR.  Checks if \f(CW\*(C`$got == $expected\*(C'\fR.  This is the
+numeric version.
+.Sp
+\&\f(CW\*(C`undef\*(C'\fR only ever matches another \f(CW\*(C`undef\*(C'\fR.
+.IP \fBisnt_eq\fR 4
+.IX Item "isnt_eq"
+.Vb 1
+\&  $Test\->isnt_eq($got, $dont_expect, $name);
+.Ve
+.Sp
+Like Test::More's \f(CWisnt()\fR.  Checks if \f(CW\*(C`$got ne $dont_expect\*(C'\fR.  This is
+the string version.
+.IP \fBisnt_num\fR 4
+.IX Item "isnt_num"
+.Vb 1
+\&  $Test\->isnt_num($got, $dont_expect, $name);
+.Ve
+.Sp
+Like Test::More's \f(CWisnt()\fR.  Checks if \f(CW\*(C`$got ne $dont_expect\*(C'\fR.  This is
+the numeric version.
+.IP \fBlike\fR 4
+.IX Item "like"
+.Vb 2
+\&  $Test\->like($thing, qr/$regex/, $name);
+\&  $Test\->like($thing, \*(Aq/$regex/\*(Aq, $name);
+.Ve
+.Sp
+Like Test::More's \f(CWlike()\fR.  Checks if \f(CW$thing\fR matches the given \f(CW$regex\fR.
+.IP \fBunlike\fR 4
+.IX Item "unlike"
+.Vb 2
+\&  $Test\->unlike($thing, qr/$regex/, $name);
+\&  $Test\->unlike($thing, \*(Aq/$regex/\*(Aq, $name);
+.Ve
+.Sp
+Like Test::More's \f(CWunlike()\fR.  Checks if \f(CW$thing\fR \fBdoes not match\fR the
+given \f(CW$regex\fR.
+.IP \fBcmp_ok\fR 4
+.IX Item "cmp_ok"
+.Vb 1
+\&  $Test\->cmp_ok($thing, $type, $that, $name);
+.Ve
+.Sp
+Works just like Test::More's \f(CWcmp_ok()\fR.
+.Sp
+.Vb 1
+\&    $Test\->cmp_ok($big_num, \*(Aq!=\*(Aq, $other_big_num);
+.Ve
+.SS "Other Testing Methods"
+.IX Subsection "Other Testing Methods"
+These are methods which are used in the course of writing a test but are not themselves tests.
+.IP \fBBAIL_OUT\fR 4
+.IX Item "BAIL_OUT"
+.Vb 1
+\&    $Test\->BAIL_OUT($reason);
+.Ve
+.Sp
+Indicates to the Test::Harness that things are going so badly all
+testing should terminate.  This includes running any additional test
+scripts.
+.Sp
+It will exit with 255.
+.IP \fBskip\fR 4
+.IX Item "skip"
+.Vb 2
+\&    $Test\->skip;
+\&    $Test\->skip($why);
+.Ve
+.Sp
+Skips the current test, reporting \f(CW$why\fR.
+.IP \fBtodo_skip\fR 4
+.IX Item "todo_skip"
+.Vb 2
+\&  $Test\->todo_skip;
+\&  $Test\->todo_skip($why);
+.Ve
+.Sp
+Like \f(CWskip()\fR, only it will declare the test as failing and TODO.  Similar
+to
+.Sp
+.Vb 1
+\&    print "not ok $tnum # TODO $why\en";
+.Ve
+.SS "Test building utility methods"
+.IX Subsection "Test building utility methods"
+These methods are useful when writing your own test methods.
+.IP \fBmaybe_regex\fR 4
+.IX Item "maybe_regex"
+.Vb 2
+\&  $Test\->maybe_regex(qr/$regex/);
+\&  $Test\->maybe_regex(\*(Aq/$regex/\*(Aq);
+.Ve
+.Sp
+This method used to be useful back when Test::Builder worked on Perls
+before 5.6 which didn't have qr//.  Now its pretty useless.
+.Sp
+Convenience method for building testing functions that take regular
+expressions as arguments.
+.Sp
+Takes a quoted regular expression produced by \f(CW\*(C`qr//\*(C'\fR, or a string
+representing a regular expression.
+.Sp
+Returns a Perl value which may be used instead of the corresponding
+regular expression, or \f(CW\*(C`undef\*(C'\fR if its argument is not recognized.
+.Sp
+For example, a version of \f(CWlike()\fR, sans the useful diagnostic messages,
+could be written as:
+.Sp
+.Vb 7
+\&  sub laconic_like {
+\&      my ($self, $thing, $regex, $name) = @_;
+\&      my $usable_regex = $self\->maybe_regex($regex);
+\&      die "expecting regex, found \*(Aq$regex\*(Aq\en"
+\&          unless $usable_regex;
+\&      $self\->ok($thing =~ m/$usable_regex/, $name);
+\&  }
+.Ve
+.IP \fBis_fh\fR 4
+.IX Item "is_fh"
+.Vb 1
+\&    my $is_fh = $Test\->is_fh($thing);
+.Ve
+.Sp
+Determines if the given \f(CW$thing\fR can be used as a filehandle.
+.SS "Test style"
+.IX Subsection "Test style"
+.IP \fBlevel\fR 4
+.IX Item "level"
+.Vb 1
+\&    $Test\->level($how_high);
+.Ve
+.Sp
+How far up the call stack should \f(CW$Test\fR look when reporting where the
+test failed.
+.Sp
+Defaults to 1.
+.Sp
+Setting \f(CW$Test::Builder::Level\fR overrides.  This is typically useful
+localized:
+.Sp
+.Vb 2
+\&    sub my_ok {
+\&        my $test = shift;
+\&
+\&        local $Test::Builder::Level = $Test::Builder::Level + 1;
+\&        $TB\->ok($test);
+\&    }
+.Ve
+.Sp
+To be polite to other functions wrapping your own you usually want to increment \f(CW$Level\fR rather than set it to a constant.
+.IP \fBuse_numbers\fR 4
+.IX Item "use_numbers"
+.Vb 1
+\&    $Test\->use_numbers($on_or_off);
+.Ve
+.Sp
+Whether or not the test should output numbers.  That is, this if true:
+.Sp
+.Vb 3
+\&  ok 1
+\&  ok 2
+\&  ok 3
+.Ve
+.Sp
+or this if false
+.Sp
+.Vb 3
+\&  ok
+\&  ok
+\&  ok
+.Ve
+.Sp
+Most useful when you can't depend on the test output order, such as
+when threads or forking is involved.
+.Sp
+Defaults to on.
+.IP \fBno_diag\fR 4
+.IX Item "no_diag"
+.Vb 1
+\&    $Test\->no_diag($no_diag);
+.Ve
+.Sp
+If set true no diagnostics will be printed.  This includes calls to
+\&\f(CWdiag()\fR.
+.IP \fBno_ending\fR 4
+.IX Item "no_ending"
+.Vb 1
+\&    $Test\->no_ending($no_ending);
+.Ve
+.Sp
+Normally, Test::Builder does some extra diagnostics when the test
+ends.  It also changes the exit code as described below.
+.Sp
+If this is true, none of that will be done.
+.IP \fBno_header\fR 4
+.IX Item "no_header"
+.Vb 1
+\&    $Test\->no_header($no_header);
+.Ve
+.Sp
+If set to true, no "1..N" header will be printed.
+.SS Output
+.IX Subsection "Output"
+Controlling where the test output goes.
+.PP
+It's ok for your test to change where STDOUT and STDERR point to,
+Test::Builder's default output settings will not be affected.
+.IP \fBdiag\fR 4
+.IX Item "diag"
+.Vb 1
+\&    $Test\->diag(@msgs);
+.Ve
+.Sp
+Prints out the given \f(CW@msgs\fR.  Like \f(CW\*(C`print\*(C'\fR, arguments are simply
+appended together.
+.Sp
+Normally, it uses the \f(CWfailure_output()\fR handle, but if this is for a
+TODO test, the \f(CWtodo_output()\fR handle is used.
+.Sp
+Output will be indented and marked with a # so as not to interfere
+with test output.  A newline will be put on the end if there isn't one
+already.
+.Sp
+We encourage using this rather than calling print directly.
+.Sp
+Returns false.  Why?  Because \f(CWdiag()\fR is often used in conjunction with
+a failing test (\f(CW\*(C`ok() || diag()\*(C'\fR) it "passes through" the failure.
+.Sp
+.Vb 1
+\&    return ok(...) || diag(...);
+.Ve
+.IP \fBnote\fR 4
+.IX Item "note"
+.Vb 1
+\&    $Test\->note(@msgs);
+.Ve
+.Sp
+Like \f(CWdiag()\fR, but it prints to the \f(CWoutput()\fR handle so it will not
+normally be seen by the user except in verbose mode.
+.IP \fBexplain\fR 4
+.IX Item "explain"
+.Vb 1
+\&    my @dump = $Test\->explain(@msgs);
+.Ve
+.Sp
+Will dump the contents of any references in a human readable format.
+Handy for things like...
+.Sp
+.Vb 1
+\&    is_deeply($have, $want) || diag explain $have;
+.Ve
+.Sp
+or
+.Sp
+.Vb 1
+\&    is_deeply($have, $want) || note explain $have;
+.Ve
+.IP \fBoutput\fR 4
+.IX Item "output"
+.PD 0
+.IP \fBfailure_output\fR 4
+.IX Item "failure_output"
+.IP \fBtodo_output\fR 4
+.IX Item "todo_output"
+.PD
+.Vb 4
+\&    my $filehandle = $Test\->output;
+\&    $Test\->output($filehandle);
+\&    $Test\->output($filename);
+\&    $Test\->output(\e$scalar);
+.Ve
+.Sp
+These methods control where Test::Builder will print its output.
+They take either an open \f(CW$filehandle\fR, a \f(CW$filename\fR to open and write to
+or a \f(CW$scalar\fR reference to append to.  It will always return a \f(CW$filehandle\fR.
+.Sp
+\&\fBoutput\fR is where normal "ok/not ok" test output goes.
+.Sp
+Defaults to STDOUT.
+.Sp
+\&\fBfailure_output\fR is where diagnostic output on test failures and
+\&\f(CWdiag()\fR goes.  It is normally not read by Test::Harness and instead is
+displayed to the user.
+.Sp
+Defaults to STDERR.
+.Sp
+\&\f(CW\*(C`todo_output\*(C'\fR is used instead of \f(CWfailure_output()\fR for the
+diagnostics of a failing TODO test.  These will not be seen by the
+user.
+.Sp
+Defaults to STDOUT.
+.IP reset_outputs 4
+.IX Item "reset_outputs"
+.Vb 1
+\&  $tb\->reset_outputs;
+.Ve
+.Sp
+Resets all the output filehandles back to their defaults.
+.IP carp 4
+.IX Item "carp"
+.Vb 1
+\&  $tb\->carp(@message);
+.Ve
+.Sp
+Warns with \f(CW@message\fR but the message will appear to come from the
+point where the original test function was called (\f(CW\*(C`$tb\->caller\*(C'\fR).
+.IP croak 4
+.IX Item "croak"
+.Vb 1
+\&  $tb\->croak(@message);
+.Ve
+.Sp
+Dies with \f(CW@message\fR but the message will appear to come from the
+point where the original test function was called (\f(CW\*(C`$tb\->caller\*(C'\fR).
+.SS "Test Status and Info"
+.IX Subsection "Test Status and Info"
+.IP \fBno_log_results\fR 4
+.IX Item "no_log_results"
+This will turn off result long-term storage. Calling this method will make
+\&\f(CW\*(C`details\*(C'\fR and \f(CW\*(C`summary\*(C'\fR useless. You may want to use this if you are running
+enough tests to fill up all available memory.
+.Sp
+.Vb 1
+\&    Test::Builder\->new\->no_log_results();
+.Ve
+.Sp
+There is no way to turn it back on.
+.IP \fBcurrent_test\fR 4
+.IX Item "current_test"
+.Vb 2
+\&    my $curr_test = $Test\->current_test;
+\&    $Test\->current_test($num);
+.Ve
+.Sp
+Gets/sets the current test number we're on.  You usually shouldn't
+have to set this.
+.Sp
+If set forward, the details of the missing tests are filled in as 'unknown'.
+if set backward, the details of the intervening tests are deleted.  You
+can erase history if you really want to.
+.IP \fBis_passing\fR 4
+.IX Item "is_passing"
+.Vb 1
+\&   my $ok = $builder\->is_passing;
+.Ve
+.Sp
+Indicates if the test suite is currently passing.
+.Sp
+More formally, it will be false if anything has happened which makes
+it impossible for the test suite to pass.  True otherwise.
+.Sp
+For example, if no tests have run \f(CWis_passing()\fR will be true because
+even though a suite with no tests is a failure you can add a passing
+test to it and start passing.
+.Sp
+Don't think about it too much.
+.IP \fBsummary\fR 4
+.IX Item "summary"
+.Vb 1
+\&    my @tests = $Test\->summary;
+.Ve
+.Sp
+A simple summary of the tests so far.  True for pass, false for fail.
+This is a logical pass/fail, so todos are passes.
+.Sp
+Of course, test #1 is \f(CW$tests\fR[0], etc...
+.IP \fBdetails\fR 4
+.IX Item "details"
+.Vb 1
+\&    my @tests = $Test\->details;
+.Ve
+.Sp
+Like \f(CWsummary()\fR, but with a lot more detail.
+.Sp
+.Vb 7
+\&    $tests[$test_num \- 1] =
+\&            { \*(Aqok\*(Aq       => is the test considered a pass?
+\&              actual_ok  => did it literally say \*(Aqok\*(Aq?
+\&              name       => name of the test (if any)
+\&              type       => type of test (if any, see below).
+\&              reason     => reason for the above (if any)
+\&            };
+.Ve
+.Sp
+\&'ok' is true if Test::Harness will consider the test to be a pass.
+.Sp
+\&'actual_ok' is a reflection of whether or not the test literally
+printed 'ok' or 'not ok'.  This is for examining the result of 'todo'
+tests.
+.Sp
+\&'name' is the name of the test.
+.Sp
+\&'type' indicates if it was a special test.  Normal tests have a type
+of ''.  Type can be one of the following:
+.Sp
+.Vb 4
+\&    skip        see skip()
+\&    todo        see todo()
+\&    todo_skip   see todo_skip()
+\&    unknown     see below
+.Ve
+.Sp
+Sometimes the Test::Builder test counter is incremented without it
+printing any test output, for example, when \f(CWcurrent_test()\fR is changed.
+In these cases, Test::Builder doesn't know the result of the test, so
+its type is 'unknown'.  These details for these tests are filled in.
+They are considered ok, but the name and actual_ok is left \f(CW\*(C`undef\*(C'\fR.
+.Sp
+For example "not ok 23 \- hole count # TODO insufficient donuts" would
+result in this structure:
+.Sp
+.Vb 7
+\&    $tests[22] =    # 23 \- 1, since arrays start from 0.
+\&      { ok        => 1,   # logically, the test passed since its todo
+\&        actual_ok => 0,   # in absolute terms, it failed
+\&        name      => \*(Aqhole count\*(Aq,
+\&        type      => \*(Aqtodo\*(Aq,
+\&        reason    => \*(Aqinsufficient donuts\*(Aq
+\&      };
+.Ve
+.IP \fBtodo\fR 4
+.IX Item "todo"
+.Vb 2
+\&    my $todo_reason = $Test\->todo;
+\&    my $todo_reason = $Test\->todo($pack);
+.Ve
+.Sp
+If the current tests are considered "TODO" it will return the reason,
+if any.  This reason can come from a \f(CW$TODO\fR variable or the last call
+to \f(CWtodo_start()\fR.
+.Sp
+Since a TODO test does not need a reason, this function can return an
+empty string even when inside a TODO block.  Use \f(CW\*(C`$Test\->in_todo\*(C'\fR
+to determine if you are currently inside a TODO block.
+.Sp
+\&\f(CWtodo()\fR is about finding the right package to look for \f(CW$TODO\fR in.  It's
+pretty good at guessing the right package to look at.  It first looks for
+the caller based on \f(CW\*(C`$Level + 1\*(C'\fR, since \f(CWtodo()\fR is usually called inside
+a test function.  As a last resort it will use \f(CWexported_to()\fR.
+.Sp
+Sometimes there is some confusion about where \f(CWtodo()\fR should be looking
+for the \f(CW$TODO\fR variable.  If you want to be sure, tell it explicitly
+what \f(CW$pack\fR to use.
+.IP \fBfind_TODO\fR 4
+.IX Item "find_TODO"
+.Vb 2
+\&    my $todo_reason = $Test\->find_TODO();
+\&    my $todo_reason = $Test\->find_TODO($pack);
+.Ve
+.Sp
+Like \f(CWtodo()\fR but only returns the value of \f(CW$TODO\fR ignoring
+\&\f(CWtodo_start()\fR.
+.Sp
+Can also be used to set \f(CW$TODO\fR to a new value while returning the
+old value:
+.Sp
+.Vb 1
+\&    my $old_reason = $Test\->find_TODO($pack, 1, $new_reason);
+.Ve
+.IP \fBin_todo\fR 4
+.IX Item "in_todo"
+.Vb 1
+\&    my $in_todo = $Test\->in_todo;
+.Ve
+.Sp
+Returns true if the test is currently inside a TODO block.
+.IP \fBtodo_start\fR 4
+.IX Item "todo_start"
+.Vb 2
+\&    $Test\->todo_start();
+\&    $Test\->todo_start($message);
+.Ve
+.Sp
+This method allows you declare all subsequent tests as TODO tests, up until
+the \f(CW\*(C`todo_end\*(C'\fR method has been called.
+.Sp
+The \f(CW\*(C`TODO:\*(C'\fR and \f(CW$TODO\fR syntax is generally pretty good about figuring out
+whether or not we're in a TODO test.  However, often we find that this is not
+possible to determine (such as when we want to use \f(CW$TODO\fR but
+the tests are being executed in other packages which can't be inferred
+beforehand).
+.Sp
+Note that you can use this to nest "todo" tests
+.Sp
+.Vb 6
+\& $Test\->todo_start(\*(Aqworking on this\*(Aq);
+\& # lots of code
+\& $Test\->todo_start(\*(Aqworking on that\*(Aq);
+\& # more code
+\& $Test\->todo_end;
+\& $Test\->todo_end;
+.Ve
+.Sp
+This is generally not recommended, but large testing systems often have weird
+internal needs.
+.Sp
+We've tried to make this also work with the TODO: syntax, but it's not
+guaranteed and its use is also discouraged:
+.Sp
+.Vb 9
+\& TODO: {
+\&     local $TODO = \*(AqWe have work to do!\*(Aq;
+\&     $Test\->todo_start(\*(Aqworking on this\*(Aq);
+\&     # lots of code
+\&     $Test\->todo_start(\*(Aqworking on that\*(Aq);
+\&     # more code
+\&     $Test\->todo_end;
+\&     $Test\->todo_end;
+\& }
+.Ve
+.Sp
+Pick one style or another of "TODO" to be on the safe side.
+.ie n .IP """todo_end""" 4
+.el .IP \f(CWtodo_end\fR 4
+.IX Item "todo_end"
+.Vb 1
+\& $Test\->todo_end;
+.Ve
+.Sp
+Stops running tests as "TODO" tests.  This method is fatal if called without a
+preceding \f(CW\*(C`todo_start\*(C'\fR method call.
+.IP \fBcaller\fR 4
+.IX Item "caller"
+.Vb 3
+\&    my $package = $Test\->caller;
+\&    my($pack, $file, $line) = $Test\->caller;
+\&    my($pack, $file, $line) = $Test\->caller($height);
+.Ve
+.Sp
+Like the normal \f(CWcaller()\fR, except it reports according to your \f(CWlevel()\fR.
+.Sp
+\&\f(CW$height\fR will be added to the \f(CWlevel()\fR.
+.Sp
+If \f(CWcaller()\fR winds up off the top of the stack it report the highest context.
+.SH "EXIT CODES"
+.IX Header "EXIT CODES"
+If all your tests passed, Test::Builder will exit with zero (which is
+normal).  If anything failed it will exit with how many failed.  If
+you run less (or more) tests than you planned, the missing (or extras)
+will be considered failures.  If no tests were ever run Test::Builder
+will throw a warning and exit with 255.  If the test died, even after
+having successfully completed all its tests, it will still be
+considered a failure and will exit with 255.
+.PP
+So the exit codes are...
+.PP
+.Vb 3
+\&    0                   all tests successful
+\&    255                 test died or all passed but wrong # of tests run
+\&    any other number    how many failed (including missing or extras)
+.Ve
+.PP
+If you fail more than 254 tests, it will be reported as 254.
+.SH THREADS
+.IX Header "THREADS"
+In perl 5.8.1 and later, Test::Builder is thread-safe.  The test number is
+shared by all threads.  This means if one thread sets the test number using
+\&\f(CWcurrent_test()\fR they will all be effected.
+.PP
+While versions earlier than 5.8.1 had threads they contain too many
+bugs to support.
+.PP
+Test::Builder is only thread-aware if threads.pm is loaded \fIbefore\fR
+Test::Builder.
+.PP
+You can directly disable thread support with one of the following:
+.PP
+.Vb 1
+\&    $ENV{T2_NO_IPC} = 1
+.Ve
+.PP
+or
+.PP
+.Vb 1
+\&    no Test2::IPC;
+.Ve
+.PP
+or
+.PP
+.Vb 1
+\&    Test2::API::test2_ipc_disable()
+.Ve
+.SH MEMORY
+.IX Header "MEMORY"
+An informative hash, accessible via \f(CWdetails()\fR, is stored for each
+test you perform.  So memory usage will scale linearly with each test
+run. Although this is not a problem for most test suites, it can
+become an issue if you do large (hundred thousands to million)
+combinatorics tests in the same run.
+.PP
+In such cases, you are advised to either split the test file into smaller
+ones, or use a reverse approach, doing "normal" (code) compares and
+triggering \f(CWfail()\fR should anything go unexpected.
+.PP
+Future versions of Test::Builder will have a way to turn history off.
+.SH EXAMPLES
+.IX Header "EXAMPLES"
+CPAN can provide the best examples.  Test::Simple, Test::More,
+Test::Exception and Test::Differences all use Test::Builder.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+.SS INTERNALS
+.IX Subsection "INTERNALS"
+Test2, Test2::API
+.SS LEGACY
+.IX Subsection "LEGACY"
+Test::Simple, Test::More
+.SS EXTERNAL
+.IX Subsection "EXTERNAL"
+Test::Harness
+.SH AUTHORS
+.IX Header "AUTHORS"
+Original code by chromatic, maintained by Michael G Schwern
+<schwern@pobox.com>
+.SH MAINTAINERS
+.IX Header "MAINTAINERS"
+.IP "Chad Granum <exodist@cpan.org>" 4
+.IX Item "Chad Granum <exodist@cpan.org>"
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright 2002\-2008 by chromatic <chromatic@wgz.org> and
+                       Michael G Schwern <schwern@pobox.com>.
+.PP
+This program is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+.PP
+See \fIhttp://www.perl.com/perl/misc/Artistic.html\fR