perlancar > Module-Patch > Module::Patch

Download:
Module-Patch-0.20.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.20   Source  

NAME ^

Module::Patch - Patch package with a set of patches

VERSION ^

This document describes version 0.20 of Module::Patch (from Perl distribution Module-Patch), released on 2014-12-05.

SYNOPSIS ^

To use Module::Patch directly:

 # patching DBI modules so that calls are logged

 use Module::Patch qw(patch_package);
 use Log::Any '$log';
 my $handle = patch_package(['DBI', 'DBI::st', 'DBI::db'], [
     {action=>'wrap', mod_version=>':all', sub_name=>':public', code=>sub {
         my $ctx = shift;

         $log->tracef("Entering %s(%s) ...", $ctx->{orig_name}, \@_);
         my $res;
         if (wantarray) { $res=[$ctx->{orig}->(@_)] } else { $res=$ctx->{orig}->(@_) }
         $log->tracef("Returned from %s", $ctx->{orig_name});
         if (wantarray) { return @$res } else { return $res }
     }},
 ]);

 # restore original
 undef $handle;

To create a patch module by subclassing Module::Patch:

 # in your patch module

 package Some::Module::Patch::YourCategory;
 use parent qw(Module::Patch);

 sub patch_data {
     return {
         v => 3,
         patches => [...], # $patches_spec
         config => { # per-patch-module config
             a => {
                 default => 1,
             },
             b => {},
             c => {
                 default => 3,
             },
         },
     };
 }
 1;

 # using your patch module

 use Some::Module::Patch::YourCategory
     -force => 1, # optional, force patch even if target version does not match
     -config => {a=>10, b=>20}, # optional, set config value
 ;

 # accessing per-patch-module config data

 print $Some::Module::Patch::YourCategory::config->{a}; # 10
 print $Some::Module::Patch::YourCategory::config->{c}; # 3, default value

 # unpatch, restore original subroutines
 no Some::Module::Patch::YourCategory;

DESCRIPTION ^

Module::Patch is basically a convenient way to define and bundle a set of patches. Actual patching is done by Monkey::Patch::Action, which provides lexically scoped patching.

There are two ways to use this module:

FUNCTIONS ^

import()

If imported directly, will export @exports as arguments and export requested symbols.

If imported from subclass, will take %opts as arguments and run patch_package() on caller package. %opts include:

patch_package($package, $patches_spec, \%opts) => HANDLE

Patch target package $package with a set of patches.

$patches_spec is an arrayref containing a series of patches specifications. Each patch specification is a hashref containing these keys: action (string, required; either 'wrap', 'add', 'replace', 'add_or_replace', 'delete'), mod_version (string/regex or array of string/regex, can be ':all' to mean all versions; optional; defaults to ':all'). sub_name (string/regex or array of string/regex, subroutine(s) to patch, can be ':all' to mean all subroutine, ':public' to mean all public subroutines [those not prefixed by _], ':private' to mean all private), code (coderef, not required if action is 'delete').

Die if there is conflict with other patch modules, for example if target module has been patched 'delete' and another patch wants to 'wrap' it.

Known options:

FAQ ^

This module does not work! The target module does not get patched!

It probably does. Some of the common mistakes are:

SEE ALSO ^

Monkey::Patch::Action

Pod::Weaver::Plugin::ModulePatch

Some examples of patch modules that use Module::Patch by subclassing it: Net::HTTP::Methods::Patch::LogRequest, LWP::UserAgent::Patch::HTTPSHardTimeout.

Some examples of modules that use Module::Patch directly: Log::Any::For::Class.

HOMEPAGE ^

Please visit the project's homepage at https://metacpan.org/release/Module-Patch.

SOURCE ^

Source repository is at https://github.com/perlancar/perl-Module-Patch.

BUGS ^

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

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.

AUTHOR ^

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2014 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.

syntax highlighting: