NAME

Module::Modular - Create optional plugins for your module

DESCRIPTION

Module::Modular allows you, or others, to create plugins for your modules. They are not loaded by default - only when you want them to be. This means you can even load them further on down in your module if you wish. The idea is to have your plugins handle certain tasks you don't want cluttering the core code of your module. I started writing this before I came across another plugin module called Module::Pluggable. So if you like how that one works better, or even prefer the name (I do), then go check it out. This one is different in the sense you explicitly tell your module what plugins to load, and each plugin may have an initialiser (__init) that will get run once it has been loaded, which I found pretty neat. This module is modular itself. By importing with followed by an array of options you can extend the functionality of Module::Modular. Currently just the one option is available (Accessors) which provides methods for accessing meta data of your plugins. A plugin can only be loaded if it's within the same namespace and within your path (ie: YourModule::Plugin::*)

SYNOPSIS

# MyModule.pm

package MyModule;

use Module::Modular;
load_plugins qw<Foo Bar>;

sub load_another_plugin {
    load_plugins 'DifferentOne';
}

# MyModule::Plugin::Foo
package MyModule::Plugin::Foo;

sub __init {
    my ($class, $name) = @_;
    # $class = MyModule::Plugin::Foo
    # $name  = Foo

    # some code here to be run when loaded
}

sub foo {
    print "You have been foo'd!\n";
}

Now, when you use MyModule, the Foo plugin will get loaded and run __init from MyModule::Plugin::Foo. Simple. The initialiser is completely optional. It's quite simple to get a list of plugins, or you can get hold of a single plugin to do stuff with.

# Run the foo() method within the Foo plugin
my $foo_plugin = $module->plugin('Foo')->foo();

Calling the plugins method will return an array of your loaded plugins. Each one will be blessed, so you have objects to work with which makes things easier.

# call the foo() method on every loaded plugin
for my $plugin ($module->plugins) {
    $plugin->foo();
}

METHODS

Module::Modular exports only a few functions into your module. They are...

load_plugins

void load_plugins(@list)

Takes an array of plugins (Not their entire path, just the name of the plugin. For example, if I wanted to load MyModule::Plugin::Foo I would only have to use load_plugins 'Foo'. If it can't load the module for any reason it will print out a warnings and move onto the next one if it's specified.

plugins

@array plugins(void)

Returns an array of your loaded plugins. It will only register those introduced by load_plugins, just having one in the right namespace and loaded by any other means will do nothing.

plugin

$object plugin(string)

Returns a blessed reference of a plugin (ie: The plugin object). You only need to supply the name, not the entire path. For example

my $plugin = $module->plugin('Foo');

OPTIONS

When you use Module::Modular you can pass a key called with as an array of options. There's only the one at the moment, and that is Accessors. What this does is give you accessor methods for the loaded plugins meta information, so you can do stuff like this

# MyModule.pm
use Module::Modular
    with => 'Accessors';

load_plugins qw<Foo Bar>;

# test.pl
for my $plugin ($module->plugins) {
    say "Name: " . $plugin->name;
    say "Version: " . $plugin->version;
}

Currently that's all there is, but it shows that this module itself is extremely modular. It will only load what you want, when you want.

AUTHOR

Brad Haywood <brad@perlpowered.com>

LICENSE

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