File Coverage

lib/Dist/Zilla/Role/PluginLoader.pm
Criterion Covered Total %
statement 13 15 86.6
branch n/a
condition n/a
subroutine 5 5 100.0
pod n/a
total 18 20 90.0


line stmt bran cond sub pod time code
1 1     1   1059 use 5.008; # utf8
  1         2  
  1         33  
2 1     1   5 use strict;
  1         1  
  1         27  
3 1     1   4 use warnings;
  1         2  
  1         27  
4 1     1   836 use utf8;
  1         10  
  1         8  
5              
6             package Dist::Zilla::Role::PluginLoader;
7              
8             our $VERSION = '0.001001';
9              
10             # ABSTRACT: A Plugin that can load others.
11              
12             our $AUTHORITY = 'cpan:KENTNL'; # AUTHORITY
13              
14 1     1   485 use Moose::Role qw( has around with requires );
  0            
  0            
15             use Dist::Zilla::Util::PluginLoader;
16              
17             requires 'load_plugins';
18             requires 'plugin_from_config';
19              
20             around plugin_from_config => sub {
21             my ( $orig, $plugin_class, $name, $arg, $own_section ) = @_;
22             my $own_object = $plugin_class->$orig( $name, $arg, $own_section );
23             my $loader = Dist::Zilla::Util::PluginLoader->new( sequence => $own_section->sequence );
24             $own_object->load_plugins($loader);
25             return $own_object;
26             };
27              
28             no Moose::Role;
29              
30             1;
31              
32             __END__
33              
34             =pod
35              
36             =encoding UTF-8
37              
38             =head1 NAME
39              
40             Dist::Zilla::Role::PluginLoader - A Plugin that can load others.
41              
42             =head1 VERSION
43              
44             version 0.001001
45              
46             =head1 WARNINGS
47              
48             =head2 STOP
49              
50             You probably don't want to use this module. You either want a C<@PluginBundle>, or L<<
51             C<PluginLoader::Configurable>
52             |Dist::Zilla::Role::PluginLoader::Configurable
53             >>
54              
55             =head2 WHEN YOU WANT THIS MODULE
56              
57             =over 4
58              
59             =item * You don't want a plugin bundle
60              
61             =item * You want something harder to understand for people who use your plugin.
62              
63             =item * You B<I<EXPRESSLY>> wish to hide the loaded modules from things like L<<
64             C<Dist::Zilla::App::Command::bakeini>
65             |Dist::Zilla::App::Command::bakeini
66             >>
67              
68             =item * You are loading a single, or handful of modules, all of which are I<BLATANTLY> obvious I<DIRECTLY> in C<dist.ini>,
69             except with some special loading semantics.
70              
71             =back
72              
73             =head2 ADVICE
74              
75             =over 4
76              
77             =item * Do make consuming plugins have to declare the loaded plugin somehow
78              
79             =item * Do make consuming plugins able to directly configure the loaded plugin somehow
80              
81             =item * If at all possible, load at most, one plugin.
82              
83             =item * If at all possible, and you are loading only one plugin, use L<<
84             C<PluginLoader::Configurable>
85             |Dist::Zilla::Role::PluginLoader::Configurable
86             >>
87              
88             =item * If you have read this far, and you still are considering using this Role, please contact me, C<kentnl> on
89             C<#distzilla@irc.perl.org>, and let me convince you not to.
90              
91             =back
92              
93             =head1 SYNOPSIS
94              
95             use Moose;
96             with 'Dist::Zilla::Role::Plugin', 'Dist::Zilla::Role::PluginLoader';
97              
98             sub load_plugins {
99             my ( $self, $loader ) = @_;
100             # Load raw config
101             $loader->load ( 'GatherDir', 'GatherDir-for-FooPlugin', [ include_dotfiles => 1, key => value, ... ]);
102             # Load using ini style input
103             $loader->load_ini( 'GatherDir', 'GatherDir2-for-FooPlugin', [ 'include_dotfiles = 1', 'key = value', ... ]);
104             }
105              
106             =head1 REQUIRES METHODS
107              
108             =head2 C<load_plugins>
109              
110             Signature:
111              
112             void < load_plugins( $self, $loader );
113              
114             $loader isa Dist::Zilla::Util::PluginLoader;
115              
116             See L<< C<Dist::Zilla::Util::PluginLoader>|Dist::Zilla::Util::PluginLoader >> for details.
117              
118             =head2 C<plugin_from_config>
119              
120             Signature:
121              
122             $object < plugin_from_config( $class, $plugin_name, $args, $section )
123              
124             $object does Dist::Zilla::Role::Plugin
125              
126             $class does Dist::Zilla::Role::Plugin
127              
128             $plugin_name is Str
129              
130             $args is HashRef
131              
132             $section isa Config::MVP::Section
133              
134             Recommended Provider:
135              
136             with 'Dist::Zilla::Role::Plugin';
137              
138             L<< C<Dist::Zilla::Role::Plugin>|Dist::Zilla::Role::Plugin >>
139              
140             =head1 AUTHOR
141              
142             Kent Fredric <kentfredric@gmail.com>
143              
144             =head1 COPYRIGHT AND LICENSE
145              
146             This software is copyright (c) 2014 by Kent Fredric <kentfredric@gmail.com>.
147              
148             This is free software; you can redistribute it and/or modify it under
149             the same terms as the Perl 5 programming language system itself.
150              
151             =cut