<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from reference/bundled/Test2/Manual/Tooling/Plugin/ToolStarts.md. Do not edit. -->

```{index} single: Test2::Manual::Tooling::Plugin::ToolStarts
```

# Test2::Manual::Tooling::Plugin::ToolStarts

How to add behaviors that occur
when a tool starts work.

## 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.

## COMPLETE CODE UP FRONT

```perl
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;
```

## LINE BY LINE

- use Test2::API qw{test2\_add\_callback\_context\_init test2\_add\_callback\_context\_acquire};

    This imports the `test2_add_callback_context_init()` and
    `test2_add_callback_context_acquire()` callbacks.

- test2\_add\_callback\_context\_acquire(sub { ... })

    This is where we add our callback for context acquisition. Every time
    `Test2::API::context()` is called the callback will be run.

- my $params\_ref = shift

    In the test2\_add\_callback\_context\_acquire() callbacks we get exactly 1
    argument, a reference to the parameters that `context()` will use to find the
    context.

- print "A tool has requested the context\\n"

    Print a notification whenever a tool asks for a context.

- 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.

- my $ctx\_ref = shift

    The coderefs for test2\_add\_callback\_context\_init() will receive exactly 1
    argument, the newly created context.

- print "A new context was created\\n"

    Print a notification whenever a new context is created.

## SEE ALSO

[Test2::Manual](../../../Manual.md) - Primary index of the manual.

## SOURCE

The source code repository for Test2-Manual can be found at
`https://github.com/Test-More/test-more/`.

## MAINTAINERS

- Chad Granum <exodist@cpan.org>

## AUTHORS

- Chad Granum <exodist@cpan.org>

## COPYRIGHT

Copyright Chad Granum <exodist@cpan.org>.

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

See `http://dev.perl.org/licenses/`