.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Test2::Util::Grabber 3pm"
.TH Test2::Util::Grabber 3pm "2019-05-06" "perl v5.24.1" "User Contributed Perl Documentation"
.\" 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::Util::Grabber \- Object used to temporarily intercept all events.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Once created this object will intercept and stash all events sent to the shared
Test2::Hub object. Once the object is destroyed, events will once
again be sent to the shared hub.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Test2 qw/Core Grab/;
\&
\&    my $grab = grab();
\&
\&    # Generate some events, they are intercepted.
\&    ok(1, "pass");
\&    ok(0, "fail");
\&
\&    my $events_a = $grab\->flush;
\&
\&    # Generate some more events, they are intercepted.
\&    ok(1, "pass");
\&    ok(0, "fail");
\&
\&    # Same as flush, except it destroys the grab object.
\&    my $events_b = $grab\->finish;
.Ve
.PP
After calling \f(CW\*(C`finish()\*(C'\fR the grab object is destroyed and \f(CW$grab\fR is set to
undef. \f(CW$events_a\fR is an arrayref with the first two events. \f(CW$events_b\fR is an
arrayref with the second two events.
.SH "EXPORTS"
.IX Header "EXPORTS"
.ie n .IP "$grab = \fIgrab()\fR" 4
.el .IP "\f(CW$grab\fR = \fIgrab()\fR" 4
.IX Item "$grab = grab()"
This lets you intercept all events for a section of code without adding
anything to your call stack. This is useful for things that are sensitive to
changes in the stack depth.
.Sp
.Vb 3
\&    my $grab = grab();
\&        ok(1, \*(Aqfoo\*(Aq);
\&        ok(0, \*(Aqbar\*(Aq);
\&
\&    # $grab is magically undef after this.
\&    my $events = $grab\->finish;
\&
\&    is(@$events, 2, "grabbed two events.");
.Ve
.Sp
When you call \f(CW\*(C`finish()\*(C'\fR the \f(CW$grab\fR object will automagically undef itself,
but only for the reference used in the method call. If you have other
references to the \f(CW$grab\fR object they will not be set to undef.
.Sp
If the \f(CW$grab\fR object is destroyed without calling \f(CW\*(C`finish()\*(C'\fR, it will
automatically clean up after itself and restore the parent hub.
.Sp
.Vb 5
\&    {
\&        my $grab = grab();
\&        # Things are grabbed
\&    }
\&    # Things are back to normal
.Ve
.Sp
By default the hub used has \f(CW\*(C`no_ending\*(C'\fR set to true. This will prevent the hub
from enforcing that you issued a plan and ran at least one test. You can turn
enforcement back one like this:
.Sp
.Vb 1
\&    $grab\->hub\->set_no_ending(0);
.Ve
.Sp
With \f(CW\*(C`no_ending\*(C'\fR turned off, \f(CW\*(C`finish\*(C'\fR will run the post-test checks to
enforce the plan and that tests were run. In many cases this will result in
additional events in your events array.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "$grab = $class\->\fInew()\fR" 4
.el .IP "\f(CW$grab\fR = \f(CW$class\fR\->\fInew()\fR" 4
.IX Item "$grab = $class->new()"
Create a new grab object, immediately starts intercepting events.
.ie n .IP "$ar = $grab\->\fIflush()\fR" 4
.el .IP "\f(CW$ar\fR = \f(CW$grab\fR\->\fIflush()\fR" 4
.IX Item "$ar = $grab->flush()"
Get an arrayref of all the events so far, clearing the grab objects internal
list.
.ie n .IP "$ar = $grab\->\fIevents()\fR" 4
.el .IP "\f(CW$ar\fR = \f(CW$grab\fR\->\fIevents()\fR" 4
.IX Item "$ar = $grab->events()"
Get an arrayref of all events so far. Does not clear the internal list.
.ie n .IP "$ar = $grab\->\fIfinish()\fR" 4
.el .IP "\f(CW$ar\fR = \f(CW$grab\fR\->\fIfinish()\fR" 4
.IX Item "$ar = $grab->finish()"
Get an arrayref of all the events, then destroy the grab object.
.ie n .IP "$hub = $grab\->\fIhub()\fR" 4
.el .IP "\f(CW$hub\fR = \f(CW$grab\fR\->\fIhub()\fR" 4
.IX Item "$hub = $grab->hub()"
Get the hub that is used by the grab event.
.SH "ENDING BEHAVIOR"
.IX Header "ENDING BEHAVIOR"
By default the hub used has \f(CW\*(C`no_ending\*(C'\fR set to true. This will prevent the hub
from enforcing that you issued a plan and ran at least one test. You can turn
enforcement back one like this:
.PP
.Vb 1
\&    $grab\->hub\->set_no_ending(0);
.Ve
.PP
With \f(CW\*(C`no_ending\*(C'\fR turned off, \f(CW\*(C`finish\*(C'\fR will run the post-test checks to
enforce the plan and that tests were run. In many cases this will result in
additional events in your events array.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Test2::Tools::Intercept \- Accomplish the same thing, but using
blocks instead.
.SH "SOURCE"
.IX Header "SOURCE"
The source code repository for Test2 can be found at
\&\fIhttps://github.com/Test\-More/Test2\-Suite/\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 2018 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