MooX::PluginRoles - add plugins via sets of Moo roles
# base class that accepts plugins package MyPkg; use Moo; # optional use MooX::PluginRoles ( plugin_dir => 'Plugins', # default plugin_role_dir => 'Roles', # default plugin_classes => [ 'Foo' ], # must be Moo classes ); # class within MyPkg that can be extended by plugin roles package MyPkg::Foo; use Moo; # class that is excluded from extending with plugin roles package MyPkg::NotMe; use Moo; # Readable plugin - provides role with read method for Foo class package MyPkg::Plugins::Readable::Roles::Foo; use Moo::Role; sub read { ... } # Writeable plugin - provides role with write method for Foo class package MyPkg::Plugins::Writeable::Roles::Foo; use Moo::Role; sub write { ... } # client using just the Readable plugin package ClientReadOnly; use MyPkg plugins => ['Readable']; $p = MyPkg->new(); $p->read; # succeeds # client using both Readable and Writeable plugins package ClientReadWrite; use MyPkg plugins => ['Readable', 'Writeable']; $p = MyPkg->new; $p->read; # succeeds $p->write('quux'); # succeeds
This is an alpha release of MooX::PluginRoles. The API is simple enough that it is unlikely to change much, but one never knows until users start testing the edge cases.
MooX::PluginRoles
The implementation works well, but is still a bit rough. It needs more work to detect and handle error cases better, and likely needs optimization as well.
MooX::PluginRoles is a plugin framework that allows plugins to be specified as sets of Moo roles that are applied to the Moo classes in the calling namespace.
Within the Moo* frameworks, it is simple to extend the behavior of a single class by applying one or more roles. MooX::PluginRoles extends that concept to a complete namespace.
The base class is the class that uses MooX::PluginRoles to provide plugins. It specifies where to find the plugins (plugin_dir and plugin_role_dir), and which classes may be extended (plugin_classes)
plugin_dir
plugin_role_dir
plugin_classes
The client package is the package that uses the base class, and specifies which plugins should be used (plugins).
plugins
The extendable classes are the classes listed by the base class in plugin_classes. These classes must be in the namespace of the base class, and plugin roles will be applied to them.
A plugin provides roles that will be applied to the extendable classes.
Each plugin creates the needed roles in a hierarchy that matches the base class hierarchy. For instance, if a client uses the base class MyBase with the plugin P, and MyBase lists C as an extendable class, then the plugin role MyBase::Plugins::P::Roles::C will be applied to the extendable class MyBase::C.
MyBase
P
C
MyBase::Plugins::P::Roles::C
MyBase::C
package MyBase; use MooX::PluginRoles ( plugin_classes => ['C'] ); package MyBase::C; has name => ( is => 'ro' ); # role within P plugin for MyBase::C class package MyBase::Plugins::P::Roles::C; has old_name => ( is => 'ro' ); package MyClient; use MyBase ( plugins => ['MyP'] ); $c = MyBase::C->new(); say $c->name; # succeeds say $c->old_name; # succeeds
At this point, when MyBase::C->new() is called, and the calling package starts with MyClient::, the constructor will return an instance of an anonymous class created by applying the P plugin role to the C extendable class.
MyBase::C->new()
MyClient::
A plugin is free to create additional packages as needed, as long as they are not in the ::Roles directory.
::Roles
Directory that contains the plugins. Defaults to "Plugins"
"Plugins"
Directory within plugin_dir that contains the roles. Defaults to "Roles"
"Roles"
Classes within the base class namespace that may be extended by plugin roles, as an ArrayRef of class names relative to the base class's namespace.
NOTE: Defaults to an empty list, so no classes will be extended unless they are explicitly listed here.
ArrayRef of plugins that should be applied to the base class when it is being used in this client.
When MooX::PluginRoles is used, adds a wrapper around the caller's import method that creates a MooX::PluginRoles::Base instance for the caller, and saves it in a class-scoped hash.
import
The Base instance finds the available plugins and roles, creates anonymous classes with the plugin roles applied, and creates an anonymous role for each base class that wraps the new method so that the proper anonymous class can be used to create the instances.
Base
new
Module::Pluggable::Object is used to find the roles within each plugin.
Module::Pluggable::Object
The plugin roles will only work if the immediate caller of the new constructor is in the namespace of the client that used the base class.
Moo and Moo::Role
Moo object-orientation system
MooX::Role::Pluggable, MooX::Object::Pluggable
Packages that apply plugin roles to instances of a single Moo class
MooX::Roles::Pluggable
Package that applies plugin roles to a single Moo class
MooseX::Object::Pluggable
Package that applies plugin roles to instances of a single Moose class
Noel Maddy <zhtwnpanta@gmail.com>
Copyright 2016 Noel Maddy
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install MooX::PluginRoles, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MooX::PluginRoles
CPAN shell
perl -MCPAN -e shell install MooX::PluginRoles
For more information on module installation, please visit the detailed CPAN module installation guide.