/ 
LocalOverride-1.000
River stage zero No dependents
/ LocalOverride

NAME

LocalOverride - Transparently override subs with those in local module versions

VERSION

version 1.000

SYNOPSIS

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

DESCRIPTION

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:

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.

CONFIGURATION

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].

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.

base_namespace

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.

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.

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.

core_only

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.

local_prefix

Default: 'Local'

The local prefix defines the namespace (within $base_namespace) used for local override definitions.

AUTHOR

Dave Sherohman <dsheroh@cpan.org>

COPYRIGHT AND LICENSE

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.