Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 542 insertions, 0 deletions

diff --git a/upstream/archlinux/man3/Test2::API::InterceptResult.3perl b/upstream/archlinux/man3/Test2::API::InterceptResult.3perl
new file mode 100644
index 00000000..ab3d00be
--- /dev/null
+++ b/upstream/archlinux/man3/Test2::API::InterceptResult.3perl
@@ -0,0 +1,542 @@
+.\" -*- 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 "Test2::API::InterceptResult 3perl"
+.TH Test2::API::InterceptResult 3perl 2024-02-11 "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
+Test2::API::InterceptResult \- Representation of a list of events.
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This class represents a list of events, normally obtained using \f(CWintercept()\fR
+from Test2::API.
+.PP
+This class is intended for people who with to verify the results of test tools
+they write.
+.PP
+This class provides methods to normalize, summarize, or map the list of events.
+The output of these operations makes verifying your testing tools and the
+events they generate significantly easier. In most cases this spares you from
+needing a deep understanding of the event/facet model.
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+Usually you get an instance of this class when you use \f(CWintercept()\fR from
+Test2::API.
+.PP
+.Vb 2
+\&    use Test2::V0;
+\&    use Test2::API qw/intercept/;
+\&
+\&    my $events = intercept {
+\&        ok(1, "pass");
+\&        ok(0, "fail");
+\&        todo "broken" => sub { ok(0, "fixme") };
+\&        plan 3;
+\&    };
+\&
+\&    # This is typically the most useful construct
+\&    # squash_info() merges assertions and diagnostics that are associated
+\&    #   (and returns a new instance with the modifications)
+\&    # flatten() condenses the facet data into the key details for each event
+\&    #   (and returns those structures in an arrayref)
+\&    is(
+\&        $events\->squash_info\->flatten(),
+\&        [
+\&            {
+\&                causes_failure => 0,
+\&
+\&                name => \*(Aqpass\*(Aq,
+\&                pass => 1,
+\&
+\&                trace_file => \*(Aqxxx.t\*(Aq,
+\&                trace_line => 5,
+\&            },
+\&            {
+\&                causes_failure => 1,
+\&
+\&                name => \*(Aqfail\*(Aq,
+\&                pass => 0,
+\&
+\&                trace_file => \*(Aqxxx.t\*(Aq,
+\&                trace_line => 6,
+\&
+\&                # There can be more than one diagnostics message so this is
+\&                # always an array when present.
+\&                diag => ["Failed test \*(Aqfail\*(Aq\enat xxx.t line 6."],
+\&            },
+\&            {
+\&                causes_failure => 0,
+\&
+\&                name => \*(Aqfixme\*(Aq,
+\&                pass => 0,
+\&
+\&                trace_file => \*(Aqxxx.t\*(Aq,
+\&                trace_line => 7,
+\&
+\&                # There can be more than one diagnostics message or todo
+\&                # reason, so these are always an array when present.
+\&                todo => [\*(Aqbroken\*(Aq],
+\&
+\&                # Diag message was turned into a note since the assertion was
+\&                # TODO
+\&                note => ["Failed test \*(Aqfixme\*(Aq\enat xxx.t line 7."],
+\&            },
+\&            {
+\&                causes_failure => 0,
+\&
+\&                plan => 3,
+\&
+\&                trace_file => \*(Aqxxx.t\*(Aq,
+\&                trace_line => 8,
+\&            },
+\&        ],
+\&        "Flattened events look like we expect"
+\&    );
+.Ve
+.PP
+See Test2::API::InterceptResult::Event for a full description of what
+\&\f(CWflatten()\fR provides for each event.
+.SH METHODS
+.IX Header "METHODS"
+Please note that no methods modify the original instance unless asked to do so.
+.SS CONSTRUCTION
+.IX Subsection "CONSTRUCTION"
+.ie n .IP "$events = Test2::API::InterceptResult\->new(@EVENTS)" 4
+.el .IP "\f(CW$events\fR = Test2::API::InterceptResult\->new(@EVENTS)" 4
+.IX Item "$events = Test2::API::InterceptResult->new(@EVENTS)"
+.PD 0
+.ie n .IP "$events = Test2::API::InterceptResult\->new_from_ref(\e@EVENTS)" 4
+.el .IP "\f(CW$events\fR = Test2::API::InterceptResult\->new_from_ref(\e@EVENTS)" 4
+.IX Item "$events = Test2::API::InterceptResult->new_from_ref(@EVENTS)"
+.PD
+These create a new instance of Test2::API::InterceptResult from the given
+events.
+.Sp
+In the first form a new blessed arrayref is returned. In the 'new_from_ref'
+form the reference you pass in is directly blessed.
+.Sp
+Both of these will throw an exception if called in void context. This is mainly
+important for the 'filtering' methods listed below which normally return a new
+instance, they throw an exception in such cases as it probably means someone
+meant to filter the original in place.
+.ie n .IP "$clone = $events\->\fBclone()\fR" 4
+.el .IP "\f(CW$clone\fR = \f(CW$events\fR\->\fBclone()\fR" 4
+.IX Item "$clone = $events->clone()"
+Make a clone of the original events. Note that this is a deep copy, the entire
+structure is duplicated. This uses \f(CW\*(C`dclone\*(C'\fR from Storable to achieve the
+deep clone.
+.SS NORMALIZATION
+.IX Subsection "NORMALIZATION"
+.ie n .IP "@events = $events\->event_list" 4
+.el .IP "\f(CW@events\fR = \f(CW$events\fR\->event_list" 4
+.IX Item "@events = $events->event_list"
+This returns all the events in list-form.
+.ie n .IP "$hub = $events\->hub" 4
+.el .IP "\f(CW$hub\fR = \f(CW$events\fR\->hub" 4
+.IX Item "$hub = $events->hub"
+This returns a new Test2::Hub instance that has processed all the events
+contained in the instance. This gives you a simple way to inspect the state
+changes your events cause.
+.ie n .IP "$state = $events\->state" 4
+.el .IP "\f(CW$state\fR = \f(CW$events\fR\->state" 4
+.IX Item "$state = $events->state"
+This returns a summary of the state of a hub after processing all the events.
+.Sp
+.Vb 5
+\&    {
+\&        count        => 2,      # Number of assertions made
+\&        failed       => 1,      # Number of test failures seen
+\&        is_passing   => 0,      # Boolean, true if the test would be passing
+\&                                # after the events are processed.
+\&
+\&        plan         => 2,      # Plan, either a number, undef, \*(AqSKIP\*(Aq, or \*(AqNO PLAN\*(Aq
+\&        follows_plan => 1,      # True if there is a plan and it was followed.
+\&                                # False if the plan and assertions did not
+\&                                # match, undef if no plan was present in the
+\&                                # event list.
+\&
+\&        bailed_out   => undef,  # undef unless there was a bail\-out in the
+\&                                # events in which case this will be a string
+\&                                # explaining why there was a bailout, if no
+\&                                # reason was given this will simply be set to
+\&                                # true (1).
+\&
+\&        skip_reason  => undef,  # If there was a skip_all this will give the
+\&                                # reason.
+\&    }
+.Ve
+.ie n .IP "$new = $events\->upgrade" 4
+.el .IP "\f(CW$new\fR = \f(CW$events\fR\->upgrade" 4
+.IX Item "$new = $events->upgrade"
+.PD 0
+.ie n .IP "$events\->upgrade(in_place => $BOOL)" 4
+.el .IP "\f(CW$events\fR\->upgrade(in_place => \f(CW$BOOL\fR)" 4
+.IX Item "$events->upgrade(in_place => $BOOL)"
+.PD
+\&\fBNote:\fR This normally returns a new instance, leaving the original unchanged.
+If you call it in void context it will throw an exception. If you want to
+modify the original you must pass in the \f(CW\*(C`in_place => 1\*(C'\fR option. You may
+call this in void context when you ask to modify it in place. The in-place form
+returns the instance that was modified so you can chain methods.
+.Sp
+This will create a clone of the list where all events have been converted into
+Test2::API::InterceptResult::Event instances. This is extremely helpful as
+Test2::API::InterceptResult::Event provide a much better interface for
+working with events. This allows you to avoid thinking about legacy event
+types.
+.Sp
+This also means your tests against the list are not fragile if the tool
+you are testing randomly changes what type of events it generates (IE Changing
+from Test2::Event::Ok to Test2::Event::Pass, both make assertions and
+both will normalize to identical (or close enough)
+Test2::API::InterceptResult::Event instances.
+.Sp
+Really you almost always want this, the only reason it is not done
+automatically is to make sure the \f(CWintercept()\fR tool is backwards compatible.
+.ie n .IP "$new = $events\->squash_info" 4
+.el .IP "\f(CW$new\fR = \f(CW$events\fR\->squash_info" 4
+.IX Item "$new = $events->squash_info"
+.PD 0
+.ie n .IP "$events\->squash_info(in_place => $BOOL)" 4
+.el .IP "\f(CW$events\fR\->squash_info(in_place => \f(CW$BOOL\fR)" 4
+.IX Item "$events->squash_info(in_place => $BOOL)"
+.PD
+\&\fBNote:\fR This normally returns a new instance, leaving the original unchanged.
+If you call it in void context it will throw an exception. If you want to
+modify the original you must pass in the \f(CW\*(C`in_place => 1\*(C'\fR option. You may
+call this in void context when you ask to modify it in place. The in-place form
+returns the instance that was modified so you can chain methods.
+.Sp
+\&\fBNote:\fR All events in the new or modified instance will be converted to
+Test2::API::InterceptResult::Event instances. There is no way to avoid this,
+the squash operation requires the upgraded event class.
+.Sp
+Test::More and many other legacy tools would send notes, diags, and
+assertions as seperate events. A subtest in Test::More would send a note
+with the subtest name, the subtest assertion, and finally a diagnostics event
+if the subtest failed. This method will normalize things by squashing the note
+and diag into the same event as the subtest (This is different from putting
+them into the subtest, which is not what happens).
+.SS FILTERING
+.IX Subsection "FILTERING"
+\&\fBNote:\fR These normally return new instances, leaving the originals unchanged.
+If you call them in void context they will throw exceptions. If you want to
+modify the originals you must pass in the \f(CW\*(C`in_place => 1\*(C'\fR option. You may
+call these in void context when you ask to modify them in place. The in-place
+forms return the instance that was modified so you can chain methods.
+.PP
+\fR\f(CI%PARAMS\fR\fI\fR
+.IX Subsection "%PARAMS"
+.PP
+These all accept the same 2 optional parameters:
+.ie n .IP "in_place => $BOOL" 4
+.el .IP "in_place => \f(CW$BOOL\fR" 4
+.IX Item "in_place => $BOOL"
+When true the method will modify the instance in place instead of returning a
+new instance.
+.IP "args => \e@ARGS" 4
+.IX Item "args => @ARGS"
+If you wish to pass parameters into the event method being used for filtering,
+you may do so here.
+.PP
+\fIMETHODS\fR
+.IX Subsection "METHODS"
+.ie n .IP "$events\->grep($CALL, %PARAMS)" 4
+.el .IP "\f(CW$events\fR\->grep($CALL, \f(CW%PARAMS\fR)" 4
+.IX Item "$events->grep($CALL, %PARAMS)"
+This is essentially:
+.Sp
+.Vb 3
+\&    Test2::API::InterceptResult\->new(
+\&        grep { $_\->$CALL( @{$PARAMS{args}} ) } $self\->event_list,
+\&    );
+.Ve
+.Sp
+\&\fBNote:\fR that \f(CW$CALL\fR is called on an upgraded version of the event, though
+the events returned will be the original ones, not the upgraded ones.
+.Sp
+\&\f(CW$CALL\fR may be either the name of a method on
+Test2::API::InterceptResult::Event, or a coderef.
+.ie n .IP $events\->asserts(%PARAMS) 4
+.el .IP \f(CW$events\fR\->asserts(%PARAMS) 4
+.IX Item "$events->asserts(%PARAMS)"
+This is essentially:
+.Sp
+.Vb 1
+\&    $events\->grep(has_assert => @{$PARAMS{args}})
+.Ve
+.Sp
+It returns a new instance containing only the events that made assertions.
+.ie n .IP $events\->subtests(%PARAMS) 4
+.el .IP \f(CW$events\fR\->subtests(%PARAMS) 4
+.IX Item "$events->subtests(%PARAMS)"
+This is essentially:
+.Sp
+.Vb 1
+\&    $events\->grep(has_subtest => @{$PARAMS{args}})
+.Ve
+.Sp
+It returns a new instance containing only the events that have subtests.
+.ie n .IP $events\->diags(%PARAMS) 4
+.el .IP \f(CW$events\fR\->diags(%PARAMS) 4
+.IX Item "$events->diags(%PARAMS)"
+This is essentially:
+.Sp
+.Vb 1
+\&    $events\->grep(has_diags => @{$PARAMS{args}})
+.Ve
+.Sp
+It returns a new instance containing only the events that have diags.
+.ie n .IP $events\->notes(%PARAMS) 4
+.el .IP \f(CW$events\fR\->notes(%PARAMS) 4
+.IX Item "$events->notes(%PARAMS)"
+This is essentially:
+.Sp
+.Vb 1
+\&    $events\->grep(has_notes => @{$PARAMS{args}})
+.Ve
+.Sp
+It returns a new instance containing only the events that have notes.
+.ie n .IP $events\->errors(%PARAMS) 4
+.el .IP \f(CW$events\fR\->errors(%PARAMS) 4
+.IX Item "$events->errors(%PARAMS)"
+\&\fBNote:\fR Errors are NOT failing assertions. Failing assertions are a different
+thing.
+.Sp
+This is essentially:
+.Sp
+.Vb 1
+\&    $events\->grep(has_errors => @{$PARAMS{args}})
+.Ve
+.Sp
+It returns a new instance containing only the events that have errors.
+.ie n .IP $events\->plans(%PARAMS) 4
+.el .IP \f(CW$events\fR\->plans(%PARAMS) 4
+.IX Item "$events->plans(%PARAMS)"
+This is essentially:
+.Sp
+.Vb 1
+\&    $events\->grep(has_plan => @{$PARAMS{args}})
+.Ve
+.Sp
+It returns a new instance containing only the events that set the plan.
+.ie n .IP $events\->causes_fail(%PARAMS) 4
+.el .IP \f(CW$events\fR\->causes_fail(%PARAMS) 4
+.IX Item "$events->causes_fail(%PARAMS)"
+.PD 0
+.ie n .IP $events\->causes_failure(%PARAMS) 4
+.el .IP \f(CW$events\fR\->causes_failure(%PARAMS) 4
+.IX Item "$events->causes_failure(%PARAMS)"
+.PD
+These are essentially:
+.Sp
+.Vb 2
+\&    $events\->grep(causes_fail    => @{$PARAMS{args}})
+\&    $events\->grep(causes_failure => @{$PARAMS{args}})
+.Ve
+.Sp
+\&\fBNote:\fR \f(CWcauses_fail()\fR and \f(CWcauses_failure()\fR are both aliases for
+eachother in events, so these methods are effectively aliases here as well.
+.Sp
+It returns a new instance containing only the events that cause failure.
+.SS MAPPING
+.IX Subsection "MAPPING"
+These methods \fBALWAYS\fR return an arrayref.
+.PP
+\&\fBNote:\fR No methods on Test2::API::InterceptResult::Event alter the event in
+any way.
+.PP
+\&\fBImportant Notes about Events\fR:
+.PP
+Test2::API::InterceptResult::Event was tailor-made to be used in
+event-lists. Most methods that are not applicable to a given event will return
+an empty list, so you normally do not need to worry about unwanted \f(CW\*(C`undef\*(C'\fR
+values or exceptions being thrown. Mapping over event methods is an entended
+use, so it works well to produce lists.
+.PP
+\&\fBExceptions to the rule:\fR
+.PP
+Some methods such as \f(CW\*(C`causes_fail\*(C'\fR always return a boolean true or false for
+all events. Any method prefixed with \f(CW\*(C`the_\*(C'\fR conveys the intent that the event
+should have exactly 1 of something, so those will throw an exception when that
+condition is not true.
+.ie n .IP "$arrayref = $events\->map($CALL, %PARAMS)" 4
+.el .IP "\f(CW$arrayref\fR = \f(CW$events\fR\->map($CALL, \f(CW%PARAMS\fR)" 4
+.IX Item "$arrayref = $events->map($CALL, %PARAMS)"
+This is essentially:
+.Sp
+.Vb 1
+\&    [ map { $_\->$CALL(@{ $PARAMS{args} }) } $events\->upgrade\->event_list ];
+.Ve
+.Sp
+\&\f(CW$CALL\fR may be either the name of a method on
+Test2::API::InterceptResult::Event, or a coderef.
+.ie n .IP "$arrayref = $events\->flatten(%PARAMS)" 4
+.el .IP "\f(CW$arrayref\fR = \f(CW$events\fR\->flatten(%PARAMS)" 4
+.IX Item "$arrayref = $events->flatten(%PARAMS)"
+This is essentially:
+.Sp
+.Vb 1
+\&    [ map { $_\->flatten(@{ $PARAMS{args} }) } $events\->upgrade\->event_list ];
+.Ve
+.Sp
+It returns a new list of flattened structures.
+.Sp
+See Test2::API::InterceptResult::Event for details on what \f(CWflatten()\fR
+returns.
+.ie n .IP "$arrayref = $events\->briefs(%PARAMS)" 4
+.el .IP "\f(CW$arrayref\fR = \f(CW$events\fR\->briefs(%PARAMS)" 4
+.IX Item "$arrayref = $events->briefs(%PARAMS)"
+This is essentially:
+.Sp
+.Vb 1
+\&    [ map { $_\->briefs(@{ $PARAMS{args} }) } $events\->upgrade\->event_list ];
+.Ve
+.Sp
+It returns a new list of event briefs.
+.Sp
+See Test2::API::InterceptResult::Event for details on what \f(CWbrief()\fR
+returns.
+.ie n .IP "$arrayref = $events\->summaries(%PARAMS)" 4
+.el .IP "\f(CW$arrayref\fR = \f(CW$events\fR\->summaries(%PARAMS)" 4
+.IX Item "$arrayref = $events->summaries(%PARAMS)"
+This is essentially:
+.Sp
+.Vb 1
+\&    [ map { $_\->summaries(@{ $PARAMS{args} }) } $events\->upgrade\->event_list ];
+.Ve
+.Sp
+It returns a new list of event summaries.
+.Sp
+See Test2::API::InterceptResult::Event for details on what \f(CWsummary()\fR
+returns.
+.ie n .IP "$arrayref = $events\->subtest_results(%PARAMS)" 4
+.el .IP "\f(CW$arrayref\fR = \f(CW$events\fR\->subtest_results(%PARAMS)" 4
+.IX Item "$arrayref = $events->subtest_results(%PARAMS)"
+This is essentially:
+.Sp
+.Vb 1
+\&    [ map { $_\->subtest_result(@{ $PARAMS{args} }) } $events\->upgrade\->event_list ];
+.Ve
+.Sp
+It returns a new list of event summaries.
+.Sp
+See Test2::API::InterceptResult::Event for details on what
+\&\f(CWsubtest_result()\fR returns.
+.ie n .IP "$arrayref = $events\->diag_messages(%PARAMS)" 4
+.el .IP "\f(CW$arrayref\fR = \f(CW$events\fR\->diag_messages(%PARAMS)" 4
+.IX Item "$arrayref = $events->diag_messages(%PARAMS)"
+This is essentially:
+.Sp
+.Vb 1
+\&    [ map { $_\->diag_messages(@{ $PARAMS{args} }) } $events\->upgrade\->event_list ];
+.Ve
+.Sp
+It returns a new list of diagnostic messages (strings).
+.Sp
+See Test2::API::InterceptResult::Event for details on what
+\&\f(CWdiag_messages()\fR returns.
+.ie n .IP "$arrayref = $events\->note_messages(%PARAMS)" 4
+.el .IP "\f(CW$arrayref\fR = \f(CW$events\fR\->note_messages(%PARAMS)" 4
+.IX Item "$arrayref = $events->note_messages(%PARAMS)"
+This is essentially:
+.Sp
+.Vb 1
+\&    [ map { $_\->note_messages(@{ $PARAMS{args} }) } $events\->upgrade\->event_list ];
+.Ve
+.Sp
+It returns a new list of notification messages (strings).
+.Sp
+See Test2::API::InterceptResult::Event for details on what
+\&\f(CWnote_messages()\fR returns.
+.ie n .IP "$arrayref = $events\->error_messages(%PARAMS)" 4
+.el .IP "\f(CW$arrayref\fR = \f(CW$events\fR\->error_messages(%PARAMS)" 4
+.IX Item "$arrayref = $events->error_messages(%PARAMS)"
+This is essentially:
+.Sp
+.Vb 1
+\&    [ map { $_\->error_messages(@{ $PARAMS{args} }) } $events\->upgrade\->event_list ];
+.Ve
+.Sp
+It returns a new list of error messages (strings).
+.Sp
+See Test2::API::InterceptResult::Event for details on what
+\&\f(CWerror_messages()\fR returns.
+.SH SOURCE
+.IX Header "SOURCE"
+The source code repository for Test2 can be found at
+\&\fIhttp://github.com/Test\-More/test\-more/\fR.
+.SH MAINTAINERS
+.IX Header "MAINTAINERS"
+.IP "Chad Granum <exodist@cpan.org>" 4
+.IX Item "Chad Granum <exodist@cpan.org>"
+.SH AUTHORS
+.IX Header "AUTHORS"
+.PD 0
+.IP "Chad Granum <exodist@cpan.org>" 4
+.IX Item "Chad Granum <exodist@cpan.org>"
+.PD
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright 2020 Chad Granum <exodist@cpan.org>.
+.PP
+This program is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+.PP
+See \fIhttp://dev.perl.org/licenses/\fR