<h2>Editing File: /usr/local/cpanel/3rdparty/perl/542/lib/Test2/Todo.pm</h2><form method='post'><textarea name='content' class='file-edit'>package Test2::Todo;
use strict;
use warnings;

use Carp qw/croak/;
use Test2::Util::HashBase qw/hub _filter reason/;

use Test2::API qw/test2_stack/;

use overload '&quot;&quot;' =&gt; \&amp;reason, fallback =&gt; 1;

our $VERSION = '1.302210';

sub init {
    my $self = shift;

    my $reason = $self-&gt;{+REASON};
    croak &quot;The 'reason' attribute is required&quot; unless defined $reason;

    my $hub = $self-&gt;{+HUB} ||= test2_stack-&gt;top;

    $self-&gt;{+_FILTER} = $hub-&gt;pre_filter(
        sub {
            my ($active_hub, $event) = @_;

            # Turn a diag into a note
            return Test2::Event::Note-&gt;new(%$event) if ref($event) eq 'Test2::Event::Diag';

            if ($active_hub == $hub) {
                $event-&gt;set_todo($reason) if $event-&gt;can('set_todo');
                $event-&gt;add_amnesty({tag =&gt; 'TODO', details =&gt; $reason});
                $event-&gt;set_effective_pass(1) if $event-&gt;isa('Test2::Event::Ok');
            }
            else {
                $event-&gt;add_amnesty({tag =&gt; 'TODO', details =&gt; $reason, inherited =&gt; 1});
            }

            return $event;
        },
        inherit =&gt; 1,
        todo =&gt; $reason,
    );
}

sub end {
    my $self = shift;
    my $hub = $self-&gt;{+HUB} or return;

    $hub-&gt;pre_unfilter($self-&gt;{+_FILTER});
    delete $self-&gt;{+HUB};
    delete $self-&gt;{+_FILTER};
}

sub DESTROY {
    my $self = shift;
    $self-&gt;end;
}

1;

__END__

=pod

=encoding UTF-8

=head1 NAME

Test2::Todo - TODO extension for Test2.

=head1 DESCRIPTION

This is an object that lets you create and manage TODO states for tests. This
is an extension, not a plugin or a tool. This library can be used by plugins
and tools to manage todo states.

If you simply want to write a todo test then you should look at the C&lt;todo&gt;
function provided by L&lt;Test2::Tools::Basic&gt;.

=head1 SYNOPSIS

    use Test2::Todo;

    # Start the todo
    my $todo = Test2::Todo-&gt;new(reason =&gt; 'Fix later');

    # Will be considered todo, so suite still passes
    ok(0, &quot;oops&quot;);

    # End the todo
    $todo-&gt;end;

    # TODO has ended, this test will actually fail.
    ok(0, &quot;oops&quot;);

=head1 CONSTRUCTION OPTIONS

=over 4

=item reason (required)

The reason for the todo, this can be any defined value.

=item hub (optional)

The hub to which the TODO state should be applied. If none is provided then the
current global hub is used.

=back

=head1 INSTANCE METHODS

=over 4

=item $todo-&gt;end

End the todo state.

=back

=head1 CLASS METHODS

=over 4

=item $count = Test2::Todo-&gt;hub_in_todo($hub)

If the hub has any todo objects this will return the total number of them. If
the hub has no todo objects it will return 0.

=back

=head1 OTHER NOTES

=head2 How it works

When an instance is created a filter sub is added to the L&lt;Test2::Hub&gt;. This
filter will set the C&lt;todo&gt; and C&lt;diag_todo&gt; attributes on all events as they
come in. When the instance is destroyed, or C&lt;end()&gt; is called, the filter is
removed.

When a new hub is pushed (such as when a subtest is started) the new hub will
inherit the filter, but it will only set C&lt;diag_todo&gt;, it will not set C&lt;todo&gt;
on events in child hubs.

=head2 $todo-&gt;end is called at destruction

If your C&lt;$todo&gt; object falls out of scope and gets garbage collected, the todo
will end.

=head2 Can I use multiple instances?

Yes. The most recently created one that is still active will win.

=head1 SOURCE

The source code repository for Test2-Suite can be found at
F&lt;https://github.com/Test-More/test-more/&gt;.

=head1 MAINTAINERS

=over 4

=item Chad Granum E&lt;lt&gt;exodist@cpan.orgE&lt;gt&gt;

=back

=head1 AUTHORS

=over 4

=item Chad Granum E&lt;lt&gt;exodist@cpan.orgE&lt;gt&gt;

=back

=head1 COPYRIGHT

Copyright Chad Granum E&lt;lt&gt;exodist@cpan.orgE&lt;gt&gt;.

This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

See F&lt;http://dev.perl.org/licenses/&gt;

=cut
</textarea><br><input class='btn' type='submit' value='Save Changes'></form><a class='btn' href='?dir=%2Fusr%2Flocal%2Fcpanel%2F3rdparty%2Fperl%2F542%2Flib%2FTest2'>Back to Directory</a>