.\" 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::Manual::Tooling::Plugin::ToolStarts 3pm" .TH Test2::Manual::Tooling::Plugin::ToolStarts 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::Manual::Tooling::Plugin::ToolStarts \- How to add behaviors that occur when a tool starts work. .SH "DESCRIPTION" .IX Header "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. .SH "COMPLETE CODE UP FRONT" .IX Header "COMPLETE CODE UP FRONT" .Vb 1 \& 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\en"; \& }); \& \& # 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\en"; \& }); \& } \& \& 1; .Ve .SH "LINE BY LINE" .IX Header "LINE BY LINE" .IP "use Test2::API qw{test2_add_callback_context_init test2_add_callback_context_acquire};" 4 .IX Item "use Test2::API qw{test2_add_callback_context_init test2_add_callback_context_acquire};" This imports the \f(CW\*(C`test2_add_callback_context_init()\*(C'\fR and \&\f(CW\*(C`test2_add_callback_context_acquire()\*(C'\fR callbacks. .IP "test2_add_callback_context_acquire(sub { ... })" 4 .IX Item "test2_add_callback_context_acquire(sub { ... })" This is where we add our callback for context acquisition. Every time \&\f(CW\*(C`Test2::API::context()\*(C'\fR is called the callback will be run. .ie n .IP "my $params_ref = shift" 4 .el .IP "my \f(CW$params_ref\fR = shift" 4 .IX Item "my $params_ref = shift" In the \fItest2_add_callback_context_acquire()\fR callbacks we get exactly 1 argument, a reference to the parameters that \f(CW\*(C`context()\*(C'\fR will use to find the context. .ie n .IP "print ""A tool has requested the context\en""" 4 .el .IP "print ``A tool has requested the context\en''" 4 .IX Item "print A tool has requested the contextn" Print a notification whenever a tool asks for a context. .IP "test2_add_callback_context_init(sub { ... })" 4 .IX 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. .ie n .IP "my $ctx_ref = shift" 4 .el .IP "my \f(CW$ctx_ref\fR = shift" 4 .IX Item "my $ctx_ref = shift" The coderefs for \fItest2_add_callback_context_init()\fR will receive exactly 1 argument, the newly created context. .ie n .IP "print ""A new context was created\en""" 4 .el .IP "print ``A new context was created\en''" 4 .IX Item "print A new context was createdn" Print a notification whenever a new context is created. .SH "SEE ALSO" .IX Header "SEE ALSO" Test2::Manual \- Primary index of the manual. .SH "SOURCE" .IX Header "SOURCE" The source code repository for Test2\-Manual can be found at \&\fIhttps://github.com/Test\-More/Test2\-Suite/\fR. .SH "MAINTAINERS" .IX Header "MAINTAINERS" .IP "Chad Granum " 4 .IX Item "Chad Granum " .SH "AUTHORS" .IX Header "AUTHORS" .PD 0 .IP "Chad Granum " 4 .IX Item "Chad Granum " .PD .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2018 Chad Granum . .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