NAME

Module::Replace - Replace functionality in other modules

VERSION

Version 0.01

SYNOPSIS

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

DESCRIPTION

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.

USAGE

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.

FUNCTIONS

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)

AUTHOR

Darin McBride, <dmcbride at cpan.org>

BUGS

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.

SUPPORT

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

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

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.