NAME

MooX::PluginKit::Consumer - Declare a class as a consumer of PluginKit plugins.

SYNOPSIS

    package My::Class;
    use Moo;
    use MooX::PluginKit::Consumer;
    
    # Optional, defaults to just 'My::Class'.
    plugin_namespace 'My::Class::Plugin';
    
    has_pluggable_object some_object => (
        class => 'Some::Object',
    );
    
    my $object = My::Class->new(
        plugins => [...],
        some_object=>{...},
    );

DESCRIPTION

This module, when used, sets the callers base class to the MooX::PluginKit::ConsumerBase class, applies the MooX::PluginKit::ConsumerRole role to the caller, and exports several candy functions (see "CANDY") into the caller.

Some higher-level documentation about how to consume plugins can be found at "CONSUMING PLUGINS" in MooX::PluginKit.

CANDY

plugin_namespace

    plugin_namespace 'Location::Of::My::Plugins';

When the "plugins" in MooX::PluginKit::ConsumerRole argument is set the user may choose to pass relative plugins. Setting this namespace changes the default root namespace used to resolve these relative plugin names to absolute ones.

This defaults to the package name of the class which uses this module.

Read more about this at "Relative Plugin Namespace" in MooX::PluginKit.

has_pluggable_object

    has_pluggable_object foo_bar => (
        class => 'Foo::Bar',
    );

This function acts like "has" in Moo but adds a bunch of functionality, making it easy to cascade the creation of objects which automatically have applicable plugins applied to them, at run-time.

In the above foo_bar example, the user of your class can then specify the foo_bar argument as a hashref. This hashref will be used to create an object of the Foo::Bar class, but not until after any applicable plugins set on the consumer class have been applied to it.

Documented below are the "has" in Moo argument which are supported as well as several custom arguments (like class, above).

Note that you MUST set either "class", class_arg, or class_builder.

Read more about this at "Object Attributes" in MooX::PluginKit.

Moo Arguments

This function only supports a subset of the arguments that "has" in Moo supports. They are:

    builder
    default
    handles
    init_arg
    isa
    required
    weak_ref

class

Setting this to a class name does two things, 1) it declares the isa on the attributes to validate that the final value is an instance of the class or a subclass of it, and 2) sets "default_class" to it.

default_class

If no class is specified this will be the default class used. A common idiom of using both "class" and this is:

    has_pluggable_object foo => (
        class         => 'Foo',
        default_class => 'Foo::SubClass',
    );

Meaning, in the above example, that the final object may be any subclass of the Foo class, but if no class is specified, it will be constructed from the Foo::SubClass class.

class_arg

If the class to be instantiated can be derived from the hashref argument to this attribute then set this to the name of the key in the hashref to get the class from. Setting this to a 1 is the same as setting it to class. So, these are the same:

    has_pluggable_object foo => ( class_arg=>1 );
    has_pluggable_object foo => ( class_arg=>'class' );

Then when passing the hashref the class can be declared as part of it:

    my $thing = YourClass->new( foo=>{ class=>'Foo::Stuff', ... } );

class_builder

Set this to a method name or a code ref which will be used to build the class name. This sub will be called as a method and passed the args hashref and is expected to return a class name.

If this is set to 1 then the method name will be automatically generated based on the attribute name. So, these are identical:

    has_pluggable_object foo => ( class_builder=>1 );
    has_pluggable_object foo => ( class_builder=>'_foo_build_class' );

Then make the sub:

    sub _foo_build_class { my ($self, $args) = @_; ...; return $class }

Note that the class builder will not be called if "class_arg" if set and the user has specified a class argument.

class_namespace

Set this to allow the class to be relative. This way if the class starts with :: then this namespace will be automatically prefixed to it.

args_builder

Set this to a method name or a code ref which will be used to adjust the hashref arguments before the object is constructed from them. This sub will be called as a method and passed the args hashref and is epxected to return an args hashref.

If this is set to 1 then the method name will be automatically generated based on the attribute name. So, these are identical:

    has_pluggable_object foo => ( args_builder=>1 );
    has_pluggable_object foo => ( args_builder=>'_foo_build_args' );

Then make the sub:

    sub _foo_build_args { my ($self, $args) = @_; ...; return $args }

has_pluggable_class

    has_pluggable_class foo_bar_class => (
        default => 'Foo::Bar',
    );

This function acts like "has" in Moo but adds a bunch of functionality, making it easy to refer to a class that gets plugins applied to it at run-time.

In the above foo_bar_class example, the user of your class can then specify the foo_bar_class argument, if they wish, and the class they pass in will have any relevant plugins applied to it.

This function only supports a subset of the arguments that "has" in Moo supports. They are:

    builder
    default
    init_arg
    isa
    required

AUTHORS AND LICENSE

See "AUTHORS" in MooX::PluginKit and "LICENSE" in MooX::PluginKit.

cpanm MooX::PluginKit

perl -MCPAN -e shell
install MooX::PluginKit