LocalOverride - Transparently override subs with those in local module versions
version 1.000
use LocalOverride; # Load Foo, followed by Local::Foo use Foo;
Or
use LocalOverride ( base_namespace => 'MyApp', local_prefix => 'Custom' ); # Just load Moose, since it's not in MyApp::* use Moose; # Load MyApp::Base, followed by MyApp::Custom::Base use MyApp::Base
When this module is loaded and you use or require another module, it will automatically check for whether any local modules are present which override code from the module being loaded. By default, these override modules are placed in the file system at a location corresponding to Local::[original module name], however their code should be within the same package as the original module:
use
require
Local::[original module name]
In /path/to/libs/Foo.pm: package Foo; sub bar { ... } sub baz { ... } In /path/to/libs/Local/Foo.pm: package Foo; # Not Local::Foo! sub bar { ... } # Replaces the original sub Foo::bar
This is, obviously, a very extreme approach and one which should be used only after due consideration, as it can create bugs which are very difficult to debug if not used carefully.
If warnings are enabled, this will generate warnings about any redefined subroutines. You will typically want to include
no warnings 'redefine';
in your override modules to prevent this.
The following configuration settings can be used to enable/disable loading of local override modules or customize where they are located. They can be set either by including them as parameters to use LocalOverride or by setting $LocalOverride::[option].
use LocalOverride
$LocalOverride::[option]
Note that, because use is processed at compile-time, any changes made using the latter method must be made within a BEGIN block if they are intended to affect modules that you use. This is not necessary for modules you require, as require is processed within the normal flow of the program.
BEGIN
Default: ''
Local overrides will only be loaded for modules which fall within the base namespace. For example, if $base_namespace is set to 'Foo', then an override module will be loaded for Foo::Bar, but not for Bar or CGI.
$base_namespace
Foo::Bar
Bar
CGI
If $base_namespace is set, overrides will be searched for within that namespace, such as Foo::Local::Bar (not Local::Foo::Bar) in the previous paragraph's example case.
Foo::Local::Bar
Local::Foo::Bar
The default setting, an empty string, will attempt to load local overrides for all modules. Setting $base_namespace is recommended in order to avoid this.
Default: 0
If this is set to a true value, then local override processing will be disabled.
This module can also be disabled with no LocalOverride if you prefer to unload it more completely.
no LocalOverride
Default: 'Local'
The local prefix defines the namespace (within $base_namespace) used for local override definitions.
Dave Sherohman <dsheroh@cpan.org>
This software is copyright (c) 2010 by Lund University Library Head Office.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install LocalOverride, copy and paste the appropriate command in to your terminal.
cpanm
cpanm LocalOverride
CPAN shell
perl -MCPAN -e shell install LocalOverride
For more information on module installation, please visit the detailed CPAN module installation guide.