Module::Replace - Replace functionality in other modules

Version 0.01

    use Module::Replace 'Other::Module' => qw(new);

The purpose of this module is to allow you to override functions in one module with the same-named functions in another.

This can be a global change, or a temporary change.

The reasons why you may want to do this include:

• Changing the behaviour of code you don't own by changing what it calls.
  
  For example, if you're using the popular Foo::Framework class, and you want to change what object it retrieves when it calls Foo::Object->new, you can simply replace Foo::Object::new with your own new which would then create your object, presumably derived from Foo::Object.
• Building a general framework that doesn't rely on the user specifying what objects to create. Here you merely tell the user to:
  
  

      use Module::Replace 'YourFramework::Type', qw(new);
  
  

  
  
  in their derived package and this will allow your framework to stay blissfully unaware of who is deriving from you in the current application.
  
  Note that this doesn't help when you want multiple derivations from the same type. A real factory is still required at that point.

There are two types of usage: global and local replacement.

Global replacement

This is primarily targetted at frameworks. Here you call:

    use Module::Replace 'YourFramework::Type', qw(new);

from within the derived object. This will both call use base 'YourFramework::Type' and override new with your own. Note that access to the original new method is still available via SUPER_new, e.g.:

    sub new {
        my $class = shift;
        # allow re-derivations
        $class = __PACKAGE__ if $class eq 'YourFramework::Type';
        my $self = bless $class->SUPER_new(), $class;
        # ...
    }

Local replacement

Sometimes you only want to replace a function for a little while. For example, changing the way that File::Spec::catdir works only when calling another function. Here you call the replace and restore functions directly.

    use Module::Replace;
    Module::Replace::replace('File::Spec', \'File::Spec::UNIX', qw(catdir));
    Some::Other::function();
    Module::Replace::restore('File::Spec', \'File::Spec::UNIX');

Note that if you leave off the reference to the source package, it will assume the caller package.

This will cause catdir to work UNIX-like on all platforms for the duration of Some::Other::function().

It is up to you to ensure that exceptions are handled so that the methods are restored at the proper time.

replace

Input:

1

Package to replace.

2

Reference to package that contains the wanted function (optional - defaults to caller's package)

3

List of functions to replace. Each function will be renamed to SUPER_$func so that the overridden function will work

restore

Input:

1

Package that is overridden

2

Reference to package that contains the wanted function (optional - defaults to caller's package)

Darin McBride, <dmcbride at cpan.org>

Please report any bugs or feature requests to bug-module-replace at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Replace. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

You can find documentation for this module with the perldoc command.

    perldoc Module::Replace

You can also look for information at:

* RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Replace

* AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/Module-Replace

* CPAN Ratings

http://cpanratings.perl.org/d/Module-Replace

* Search CPAN

http://search.cpan.org/dist/Module-Replace

Copyright 2008 Darin McBride, all rights reserved.

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