view release on metacpan or  search on metacpan

lib/MooX/PluginKit/Consumer.pm  view on Meta::CPAN

use MooX::PluginKit::Core;
use MooX::PluginKit::ConsumerRole;
use Types::Standard -types;
use Types::Common::String -types;
use Class::Method::Modifiers qw( install_modifier );
use Module::Runtime qw( require_module );
use Scalar::Util qw( blessed );
use Carp qw( croak );
use Exporter qw();

use namespace::clean;

our @EXPORT = qw(
    plugin_namespace
    has_pluggable_object
    has_pluggable_class
);

sub import {
    {
        my $caller = (caller())[0];
        init_consumer( $caller );
        get_consumer_moo_extends( $caller )->('MooX::PluginKit::ConsumerBase');
        get_consumer_moo_with( $caller )->('MooX::PluginKit::ConsumerRole');
    }

    goto &Exporter::import;
}

=head1 CANDY

=head2 plugin_namespace

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

When the L<MooX::PluginKit::ConsumerRole/plugins> 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 L<MooX::PluginKit/Relative Plugin Namespace>.

=cut

sub plugin_namespace {
    my ($consumer) = caller();
    local $Carp::Internal{ (__PACKAGE__) } = 1;
    set_consumer_namespace( $consumer, @_ );
    return;
}

=head2 has_pluggable_object

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

This function acts like L<Moo/has> 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 C<foo_bar> example, the user of your class can then specify
the C<foo_bar> argument as a hashref.  This hashref will be used to
create an object of the C<Foo::Bar> class, but not until after any
applicable plugins set on the consumer class have been applied to it.

Documented below are the L<Moo/has> argument which are supported as well
as several custom arguments (like C<class>, above).

Note that you MUST set either L</class>, L<class_arg>, or L<class_builder>.

Read more about this at L<MooX::PluginKit/Object Attributes>.

=head3 Moo Arguments

This function only supports a subset of the arguments that L<Moo/has>
supports.  They are:

    builder
    default
    handles
    init_arg
    isa
    required
    weak_ref

=head3 class

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

=head3 default_class

If no class is specified this will be the default class used.  A common idiom
of using both L</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
C<Foo> class, but if no class is specified, it will be constructed from the
C<Foo::SubClass> class.

=head3 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 C<1> is the same as setting it to C<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', ... } );