Initial Commit

database/perl/vendor/lib/Test2/Manual/Tooling/Plugin/TestExit.pm

@@ -0,0 +1,108 @@
+package Test2::Manual::Tooling::Plugin::TestExit;
+
+our $VERSION = '0.000139';
+
+1;
+
+__END__
+
+=head1 NAME
+
+Test2::Manual::Tooling::Plugin::TestExit - How to safely add pre-exit
+behaviors.
+
+=head1 DESCRIPTION
+
+This describes the correct/safe way to add pre-exit behaviors to tests via a
+custom plugin.
+
+The naive way to attempt this would be to add an C<END { ... }> block. That can
+work, and may not cause problems.... On the other hand there are a lot of ways
+that can bite you. Describing all the potential problems of an END block, and
+how it might conflict with Test2 (Which has its own END block) is beyond the
+scope of this document.
+
+=head1 COMPLETE CODE UP FRONT
+
+    package Test2::Plugin::MyPlugin;
+
+    use Test2::API qw{test2_add_callback_exit};
+
+    sub import {
+        my $class = shift;
+
+        test2_add_callback_exit(sub {
+            my ($ctx, $orig_code, $new_exit_code_ref) = @_;
+
+            return if $orig_code == 42;
+
+            $$new_exit_code_ref = 42;
+        });
+    }
+
+    1;
+
+=head1 LINE BY LINE
+
+=over 4
+
+=item use Test2::API qw{test2_add_callback_exit};
+
+This imports the C<(test2_add_callback_exit)> callback.
+
+=item test2_add_callback_exit(sub { ... });
+
+This adds our callback to be called before exiting.
+
+=item my ($ctx, $orig_code, $new_exit_code_ref) = @_
+
+The callback gets 3 arguments. First is a context object you may use. The
+second is the original exit code of the C<END> block Test2 is using. The third
+argument is a scalar reference which you may use to get the current exit code,
+or set a new one.
+
+=item return if $orig_code == 42
+
+This is a short-cut to do nothing if the original exit code was already 42.
+
+=item $$new_exit_code_ref = 42
+
+This changes the exit code to 42.
+
+=back
+
+=head1 SEE ALSO
+
+L<Test2::Manual> - Primary index of the manual.
+
+=head1 SOURCE
+
+The source code repository for Test2-Manual can be found at
+F<https://github.com/Test-More/Test2-Suite/>.
+
+=head1 MAINTAINERS
+
+=over 4
+
+=item Chad Granum E<lt>exodist@cpan.orgE<gt>
+
+=back
+
+=head1 AUTHORS
+
+=over 4
+
+=item Chad Granum E<lt>exodist@cpan.orgE<gt>
+
+=back
+
+=head1 COPYRIGHT
+
+Copyright 2018 Chad Granum E<lt>exodist@cpan.orgE<gt>.
+
+This program is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
+See F<http://dev.perl.org/licenses/>
+
+=cut

database/perl/vendor/lib/Test2/Manual/Tooling/Plugin/TestingDone.pm

@@ -0,0 +1,121 @@
+package Test2::Manual::Tooling::Plugin::TestingDone;
+
+our $VERSION = '0.000139';
+
+1;
+
+__END__
+
+=head1 NAME
+
+Test2::Manual::Tooling::Plugin::TestingDone - Run code when the test file is
+finished, or when done_testing is called.
+
+=head1 DESCRIPTION
+
+This is a way to add behavior to the end of a test file. This code is run
+either when done_testing() is called, or when the test file has no more
+run-time code to run.
+
+When triggered by done_testing() this will be run BEFORE the plan is calculated
+and sent. This means it IS safe to make test assertions in this callback.
+
+=head1 COMPLETE CODE UP FRONT
+
+    package Test2::Plugin::MyPlugin;
+
+    use Test2::API qw{test2_add_callback_testing_done};
+
+    sub import {
+        my $class = shift;
+
+        test2_add_callback_testing_done(sub {
+            ok(!$some_global, '$some_global was not set');
+            print "The test file is done, or done_testing was just called\n"
+        });
+    }
+
+    1;
+
+=head1 LINE BY LINE
+
+=over 4
+
+=item use Test2::API qw{test2_add_callback_testing_done};
+
+This imports the C<test2_add_callback_testing_done()> callback.
+
+=item test2_add_callback_testing_done(sub { ... });
+
+This adds our callback to be called when testing is done.
+
+=item ok(!$some_global, '$some_global was not set')
+
+It is safe to make assertions in this type of callback. This code simply
+asserts that some global was never set over the course of the test.
+
+=item print "The test file is done, or done_testing was just called\n"
+
+This prints a message when the callback is run.
+
+=back
+
+=head1 UNDER THE HOOD
+
+Before test2_add_callback_testing_done() this kind of thing was still possible,
+but it was hard to get right, here is the code to do it:
+
+    test2_add_callback_post_load(sub {
+        my $stack = test2_stack();
+
+        # Insure we have at least one hub, but we do not necessarily want the
+        # one this returns.
+        $stack->top;
+
+        # We want the root hub, not the top one.
+        my ($root) = Test2::API::test2_stack->all;
+
+        # Make sure the hub does not believe nothing has happened.
+        $root->set_active(1);
+
+        # Now we can add our follow-up code
+        $root->follow_up(sub {
+            # Your callback code here
+        });
+    });
+
+=head1 SEE ALSO
+
+L<Test2::Manual> - Primary index of the manual.
+
+=head1 SOURCE
+
+The source code repository for Test2-Manual can be found at
+F<https://github.com/Test-More/Test2-Suite/>.
+
+=head1 MAINTAINERS
+
+=over 4
+
+=item Chad Granum E<lt>exodist@cpan.orgE<gt>
+
+=back
+
+=head1 AUTHORS
+
+=over 4
+
+=item Chad Granum E<lt>exodist@cpan.orgE<gt>
+
+=back
+
+=head1 COPYRIGHT
+
+Copyright 2018 Chad Granum E<lt>exodist@cpan.orgE<gt>.
+
+This program is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
+See F<http://dev.perl.org/licenses/>
+
+=cut

database/perl/vendor/lib/Test2/Manual/Tooling/Plugin/ToolCompletes.pm

@@ -0,0 +1,94 @@
+package Test2::Manual::Tooling::Plugin::ToolCompletes;
+
+our $VERSION = '0.000139';
+
+1;
+
+__END__
+
+=head1 NAME
+
+Test2::Manual::Tooling::Plugin::ToolCompletes - How to add behaviors that occur
+when a tool completes work.
+
+=head1 DESCRIPTION
+
+This tutorial helps you understand how to add behaviors that occur when a tool
+is done with its work. All tools need to acquire and then release a context,
+for this tutorial we make use of the release hooks that are called every time a
+tool releases the context object.
+
+=head1 COMPLETE CODE UP FRONT
+
+    package Test2::Plugin::MyPlugin;
+
+    use Test2::API qw{test2_add_callback_context_release};
+
+    sub import {
+        my $class = shift;
+
+        test2_add_callback_context_release(sub {
+            my $ctx_ref = shift;
+
+            print "Context was released\n";
+        });
+    }
+
+    1;
+
+=head1 LINE BY LINE
+
+=over 4
+
+=item use Test2::API qw{test2_add_callback_context_release};
+
+This imports the C<test2_add_callback_context_release()> callback.
+
+=item test2_add_callback_context_release(sub { ... })
+
+=item my $ctx_ref = shift
+
+The coderefs for test2_add_callback_context_release() will receive exactly 1
+argument, the context being released.
+
+=item print "Context was released\n"
+
+Print a notification whenever the context is released.
+
+=back
+
+=head1 SEE ALSO
+
+L<Test2::Manual> - Primary index of the manual.
+
+=head1 SOURCE
+
+The source code repository for Test2-Manual can be found at
+F<https://github.com/Test-More/Test2-Suite/>.
+
+=head1 MAINTAINERS
+
+=over 4
+
+=item Chad Granum E<lt>exodist@cpan.orgE<gt>
+
+=back
+
+=head1 AUTHORS
+
+=over 4
+
+=item Chad Granum E<lt>exodist@cpan.orgE<gt>
+
+=back
+
+=head1 COPYRIGHT
+
+Copyright 2018 Chad Granum E<lt>exodist@cpan.orgE<gt>.
+
+This program is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
+See F<http://dev.perl.org/licenses/>
+
+=cut

database/perl/vendor/lib/Test2/Manual/Tooling/Plugin/ToolStarts.pm

@@ -0,0 +1,126 @@
+package Test2::Manual::Tooling::Plugin::ToolStarts;
+
+our $VERSION = '0.000139';
+
+1;
+
+__END__
+
+=head1 NAME
+
+Test2::Manual::Tooling::Plugin::ToolStarts - How to add behaviors that occur
+when a tool starts work.
+
+=head1 DESCRIPTION
+
+This tutorial will help you write plugins that have behavior when a tool
+starts. All tools should start by acquiring a context object. This tutorial
+shows you the hooks you can use to take advantage of the context acquisition.
+
+=head1 COMPLETE CODE UP FRONT
+
+    package Test2::Plugin::MyPlugin;
+
+    use Test2::API qw{
+        test2_add_callback_context_init
+        test2_add_callback_context_acquire
+    };
+
+    sub import {
+        my $class = shift;
+
+        # Let us know every time a tool requests a context, and give us a
+        # chance to modify the parameters before we find it.
+        test2_add_callback_context_acquire(sub {
+            my $params_ref = shift;
+
+            print "A tool has requested the context\n";
+        });
+
+        # Callback every time a new context is created, not called if an
+        # existing context is found.
+        test2_add_callback_context_init(sub {
+            my $ctx_ref = shift;
+
+            print "A new context was created\n";
+        });
+    }
+
+    1;
+
+=head1 LINE BY LINE
+
+=over 4
+
+=item use Test2::API qw{test2_add_callback_context_init test2_add_callback_context_acquire};
+
+This imports the C<test2_add_callback_context_init()> and
+C<test2_add_callback_context_acquire()> callbacks.
+
+=item test2_add_callback_context_acquire(sub { ... })
+
+This is where we add our callback for context acquisition. Every time
+C<Test2::API::context()> is called the callback will be run.
+
+=item my $params_ref = shift
+
+In the test2_add_callback_context_acquire() callbacks we get exactly 1
+argument, a reference to the parameters that C<context()> will use to find the
+context.
+
+=item print "A tool has requested the context\n"
+
+Print a notification whenever a tool asks for a context.
+
+=item test2_add_callback_context_init(sub { ... })
+
+Add our context init callback. These callbacks are triggered whenever a
+completely new context is created. This is not called if an existing context is
+found. In short this only fires off for the top level tool, not nested tools.
+
+=item my $ctx_ref = shift
+
+The coderefs for test2_add_callback_context_init() will receive exactly 1
+argument, the newly created context.
+
+=item print "A new context was created\n"
+
+Print a notification whenever a new context is created.
+
+=back
+
+=head1 SEE ALSO
+
+L<Test2::Manual> - Primary index of the manual.
+
+=head1 SOURCE
+
+The source code repository for Test2-Manual can be found at
+F<https://github.com/Test-More/Test2-Suite/>.
+
+=head1 MAINTAINERS
+
+=over 4
+
+=item Chad Granum E<lt>exodist@cpan.orgE<gt>
+
+=back
+
+=head1 AUTHORS
+
+=over 4
+
+=item Chad Granum E<lt>exodist@cpan.orgE<gt>
+
+=back
+
+=head1 COPYRIGHT
+
+Copyright 2018 Chad Granum E<lt>exodist@cpan.orgE<gt>.
+
+This program is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
+See F<http://dev.perl.org/licenses/>
+
+=cut