NAME

Brickyard - Plugin system based on roles

VERSION

version 1.110040

SYNOPSIS

    use Brickyard;
    my $brickyard = Brickyard->new(base_package => 'My::App');
    my $root_config = MyApp::RootConfig->new;
    $brickyard->init_from_config('myapp.ini', $root_config);
    $_->some_method for $brickyard->plugins_with(-SomeRole);

DESCRIPTION

This is a lightweight plugin system based on roles. It does not use Moose but relies on Role::Basic instead, and very few other modules.

It takes its inspiration from Dist::Zilla, but has much less flexibility and therefore is also much less complex.

METHODS

new

Constructs a new object. Takes an optional hash of arguments to initialize the object.

base_package

Read-write accessor for the base package name that is used in expand_package(). Defaults to MyApp.

parse_ini

Takes a string that contains configuration in INI format and parses it into an array of configuration sections. It returns a reference to that array.

Using an array, as opposed to a hash, ensures that the section order is preserved, so we know in which order to process plugins in Brickyard's plugins_with() method.

Each array element corresponds to an INI section. Each section is itself a reference to an array with three elements:

The first element is the section name. The second element is the package name of the plugin; it is obtained by expanding the section name using expand_package(). The third element is a reference to a plugin configuration hash; it is the section's payload. If a section payload key occurs several times, it is turned into an array reference in the plugin configuration hash.

The first section is the global section, denoted by the name _. Any payload in the INI configuration that occurs before the first section ends up in this section.

For example:

    ; A comment
    name = Foobar

    [@Default]

    [Some::Thing]
    foo = bar
    baz = 43
    baz = blah

is parsed into this structure:

    [ '_',        'MyApp::Plugin::_',             { name => 'Foobar' } ],
    [ '@Default', 'MyApp::PluginBundle::Default', {} ],
    [   'Some::Thing',
        'MyApp::Plugin::Some::Thing',
        {   'baz' => [ '43', 'blah' ],
            'foo' => 'bar'
        }
    ]

expand_package

Takes an abbreviated package name and expands it into the real package name. INI section names are processed this way so you don't have to repeat common prefixes all the time.

If @ occurs at the start of the string, it is replaced by the base name plus <::PluginBundle::>.

A - is replaced by the base name plus ::Role::.

A = is replaced by the empty string, so the remained is returned unaltered.

Otherwise the base name plus ::Plugin:: is prepended.

The base name is normally whatever base_package() returns, but if the string starts with *, the asterisk is deleted and Brickyard is used for the base name.

Here are some examples of package name expansion:

    @Service::Default     MyApp::PluginBundle::Service::Default
    *@Filter              Brickyard::PluginBundle::Filter
    *Filter               Brickyard::Plugin::Filter
    =Foo::Bar             Foo::Bar
    Some::Thing           MyApp::Plugin::Some::Thing
    -Thing::Frobnulizer   MyApp::Role::Thing::Frobnulizer

init_from_config

Takes configuration and a root object. For each configuration section it creates a plugin object, initializes it with the plugin configuration hash and adds it to the brickyard's array of plugins.

Any configuration keys that appear in the configuration's root section are set on the root object. So the root object can be anything that has set-accessors for all the configuration keys that can appear in the configuration's root section.

If the configuration is a string in INI format, it is parsed. It can also be a configuration structure as returned by parse_ini() or a plugin bundle's bundle_config() method.

If an object is created that consumes the Brickyard::Role::PluginBundle role, the bundle is processed recursively.

plugins

Read-write accessor for the reference to an array of plugins.

plugins_with

Takes a role name and returns a list of all the plugins that consume this role. The result is cached, keyed by the role name.

reset_plugins

Clears the array of plugins as well as the cache - see plugins_with().

INSTALLATION

See perlmodinstall for information and options on installing Perl modules.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests through the web interface at http://rt.cpan.org/Public/Dist/Display.html?Name=Brickyard.

AVAILABILITY

The latest version of this module is available from the Comprehensive Perl Archive Network (CPAN). Visit http://www.perl.com/CPAN/ to find a CPAN site near you, or see http://search.cpan.org/dist/Brickyard/.

The development version lives at http://github.com/hanekomu/Brickyard.git and may be cloned from git://github.com/hanekomu/Brickyard.git. Instead of sending patches, please fork this project using the standard git and github infrastructure.

AUTHOR

Marcel Gruenauer <marcel@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by Marcel Gruenauer.

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

cpanm Brickyard

perl -MCPAN -e shell
install Brickyard