Provided by: libmonkey-patch-action-perl_0.061-2_all bug

NAME

       Monkey::Patch::Action - Wrap/add/replace/delete subs from other package (with restore)

VERSION

       This document describes version 0.061 of Monkey::Patch::Action (from Perl distribution
       Monkey-Patch-Action), released on 2018-04-02.

SYNOPSIS

       Patching package or class:

        use Monkey::Patch::Action qw(patch_package);

        package Foo;
        sub sub1  { say "Foo's sub1" }
        sub sub2  { say "Foo's sub2, args=", join(",", @_) }
        sub meth1 { my $self = shift; say "Foo's meth1" }

        package Bar;
        our @ISA = qw(Foo);

        package main;
        my $h; # handle object
        my $foo = Foo->new;
        my $bar = Bar->new;

        # replacing a subroutine
        $h = patch_package('Foo', 'sub1', 'replace', sub { "qux" });
        Foo::sub1(); # says "qux"
        undef $h;
        Foo::sub1(); # says "Foo's sub1"

        # adding a subroutine
        $h = patch_package('Foo', 'sub3', 'add', sub { "qux" });
        Foo::sub3(); # says "qux"
        undef $h;
        Foo::sub3(); # dies

        # deleting a subroutine
        $h = patch_package('Foo', 'sub2', 'delete');
        Foo::sub2(); # dies
        undef $h;
        Foo::sub2(); # says "Foo's sub2, args="

        # wrapping a subroutine
        $h = patch_package('Foo', 'sub2', 'wrap',
            sub {
                my $ctx = shift;
                say "wrapping $ctx->{package}::$ctx->{subname}";
                $ctx->{orig}->(@_);
            }
        );
        Foo::sub2(1,2,3); # says "wrapping Foo::sub2" then "Foo's sub2, args=1,2,3"
        undef $h;
        Foo::sub2(1,2,3); # says "Foo's sub2, args=1,2,3"

        # stacking patches (note: can actually be unapplied in random order)
        my ($h2, $h3);
        $h  = patch_package('Foo', 'sub1', 'replace', sub { "qux" });
        Foo::sub1(); # says "qux"
        $h2 = patch_package('Foo', 'sub1', 'delete');
        Foo::sub1(); # dies
        $h3 = patch_package('Foo', 'sub1', 'replace', sub { "quux" });
        Foo::sub1(); # says "quux"
        undef $h3;
        Foo::sub1(); # dies
        undef $h2;
        Foo::sub1(); # says "qux"
        undef $h;
        Foo::sub1(); # says "Foo's sub1"

       Patching object:

        use Monkey::Patch::Action qw(patch_package);

        package Foo;
        sub meth1 { say "Foo's meth1" }

        package Bar;
        our @ISA = qw(Foo);
        sub meth2 { say "Bar's meth2" }

        package main;
        my $h; # handle object
        my $foo1 = Foo->new;
        my $foo2 = Foo->new;
        my $bar1 = Bar->new;
        my $bar2 = Bar->new;

        # replacing a method
        $h = patch_object($foo1, 'meth1', 'replace', sub { say "Foo's modified meth1" });
        $foo1->meth1; # says "Foo's modified meth1"
        $foo2->meth1; # says "Foo's meth1"
        undef $h;
        $foo1->meth1; # says "Foo's meth1"

        $h = patch_object($bar1, 'meth3', 'add', sub { "Bar's meth3" });
        $bar1->meth3; # says "Bar's meth3"
        $bar2->meth3; # dies
        undef $h;
        $bar1->meth3; # dies

        # deleting a method
        $h = patch_object($foo1, 'meth1', 'delete');
        $foo1->meth1; # dies
        $foo2->meth1; # says "Foo's meth1"
        undef $h;
        $foo1->meth1; # says "Foo's meth1"

        # wrapping a method
        $h = patch_object($foo1, 'meth1', 'wrap',
            sub {
                my $ctx = shift;
                say "Wrapping $ctx->{package}::$ctx->{subname}";
                $ctx->{orig}->(@_);
            }
        );
        $foo1->meth1; # says "Wrapping Foo::meth1" then "Foo's meth1"
        $foo2->meth1; # says "Foo's meth1"
        undef $h;
        $foo1->meth1; # says "Foo's meth1"

DESCRIPTION

       Monkey-patching is the act of modifying a package at runtime: adding a subroutine/method,
       replacing/deleting/wrapping another, etc. Perl makes it easy to do that, for example:

        # add a subroutine
        *{"Target::sub1"} = sub { ... };

        # another way, can be done from any file
        package Target;
        sub sub2 { ... }

        # delete a subroutine
        undef *{"Target::sub3"};

       This module makes things even easier by helping you apply a stack of patches and unapply
       them later in flexible order.

FUNCTIONS

   patch_package
       Usage:

        patch_package($package, $subname, $action, $code, @extra) => HANDLE

       Patch $package's subroutine named $subname. $action is either:

       •   "wrap"

           $subname must already exist. "code" is required.

           Your code receives a context hash as its first argument, followed by any arguments the
           subroutine would have normally gotten. Context hash contains: "orig" (the original
           subroutine that is being wrapped), "subname", "package", "extra".

       •   "add"

           "subname" must not already exist. "code" is required.

       •   "replace"

           "subname" must already exist. "code" is required.

       •   "add_or_replace"

           "code" is required.

       •   "delete"

           "code" is not needed.

       Die on error.

       Function returns a handle object. As soon as you lose the value of the handle (by calling
       in void context, assigning over the variable, undeffing the variable, letting it go out of
       scope, etc), the patch is unapplied.

       Patches can be unapplied in random order, but unapplying a patch where the next patch is a
       wrapper can lead to an error. Example: first patch (P1) adds a subroutine and second patch
       (P2) wraps it. If P1 is unapplied before P2, the subroutine is now no longer there, and P2
       no longer works. Unapplying P1 after P2 works, of course.

   patch_object
       Usage:

        patch_object($obj, $methname, $action, $code, @extra) => HANDLE

       Basically just a wrapper for "patch_package" to patch "only specific object(s)". Basically
       it does something like this:

        die "'$obj' is not an object" unless blessed($obj);
        my $package = ref($obj);
        patch_package($package, $methname, 'wrap',
            sub {
                my $ctx = shift;
                my $self = shift;

                my $o = $ctx->{extra}[0];
                no warnings 'numeric';
                if ($o == $self) {
                    # do stuff
                } else {
                    # not our target object
                    $ctx->{orig}->(@_);
                }
            },
        );

FAQ

   Differences with Monkey::Patch?
       This module is based on the wonderful Monkey::Patch by Paul Driver. The differences are:

       •   This module adds the ability to add/replace/delete subroutines instead of just
           wrapping them.

       •   Interface to patch_package() is slightly different (see previous item for the cause).

       •   Using this module, the wrapper receives a context hash instead of just the original
           subroutine.

       •

   How to patch classes and objects?
       Patching a class is basically the same as patching any other package, since Perl
       implements a class with a package. One thing to note is that to call a parent's method
       inside your wrapper code, instead of:

        $self->SUPER::methname(...)

       you need to do something like:

        use SUPER;
        SUPER::find_parent(ref($self), 'methname')->methname(...)

       Patching an object is also basically patching a class/package, because Perl does not have
       per-object method like Ruby. But if you just want to provide a modified behavior for a
       certain object only, you can do something like:

        patch_package($package, $methname, 'wrap',
        sub {
            my $ctx = shift;
            my $self = shift;

            my $obj = $ctx->{extra}[0];
            no warnings 'numeric';
            if ($obj == $self) {
                # do stuff
            }
            $ctx->{orig}->(@_);
        }, $obj);

       This is basically what "patch_object" does.

HOMEPAGE

       Please visit the project's homepage at <https://metacpan.org/release/Monkey-Patch-Action>.

SOURCE

       Source repository is at <https://github.com/perlancar/perl-Monkey-Patch-Action>.

BUGS

       Please report any bugs or feature requests on the bugtracker website
       <https://rt.cpan.org/Public/Dist/Display.html?Name=Monkey-Patch-Action>

       When submitting a bug or request, please include a test-file or a patch to an existing
       test-file that illustrates the bug or desired feature.

SEE ALSO

       Monkey::Patch

AUTHOR

       perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2018, 2017, 2012 by perlancar@cpan.org.

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