<html><head><title>Dist::Zilla::Role::PluginBundle::Merged</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
</head>
<body class='pod'>
<!--
generated by Pod::Simple::HTML v3.20,
using Pod::Simple::PullParser v3.20,
under Perl v5.016000 at Mon Aug 6 16:03:55 2012 GMT.
If you want to change this HTML document, you probably shouldn't do that
by changing it directly. Instead, see about changing the calling options
to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
then reconverting this document from the Pod source.
When in doubt, email the author of Pod::Simple::HTML for advice.
See 'perldoc Pod::Simple::HTML' for more info.
-->
<!-- start doc -->
<a name='___top' class='dummyTopAnchor' ></a>
<h1><a class='u'
name="NAME"
>NAME</a></h1>
<p>Dist::Zilla::Role::PluginBundle::Merged - Mindnumbingly easy way to create a PluginBundle</p>
<h1><a class='u'
name="SYNOPSIS"
>SYNOPSIS</a></h1>
<pre> ; Yes, three lines of code works!
package Dist::Zilla::PluginBundle::Foobar;
Moose::with 'Dist::Zilla::Role::PluginBundle::Merged';
sub configure { shift->add_merged( qw[ Plugin1 Plugin2 Plugin3 Plugin4 ] ); }
; Or, as a more complex example...
package Dist::Zilla::PluginBundle::Foobar;
use Moose;
with 'Dist::Zilla::Role::PluginBundle::Merged' => {
mv_plugins => [ qw( Plugin1 =Dist::Zilla::Bizarro::Foobar Plugin2 ) ],
};
sub configure {
my $self = shift;
$self->add_merged(
qw( Plugin1 @Bundle1 =Dist::Zilla::Bizarro::Foobar ),
{}, # force no options on the following plugins
qw( ArglessPlugin1 ArglessPlugin2 ),
$self->config_rename(plugin_dupearg => 'dupearg', removearg => undef),
qw( Plugin2 ),
);
}</pre>
<h1><a class='u'
name="DESCRIPTION"
>DESCRIPTION</a></h1>
<p>This is a PluginBundle role, based partially on the underlying code from <a href="http://search.cpan.org/perldoc?Dist%3A%3AZilla%3A%3APluginBundle%3A%3AGit" class="podlinkpod"
>Dist::Zilla::PluginBundle::Git</a>. As you can see from the example above, it's incredibly easy to make a bundle from this role. It uses <a href="http://search.cpan.org/perldoc?Dist%3A%3AZilla%3A%3ARole%3A%3APluginBundle%3A%3AEasy" class="podlinkpod"
>Dist::Zilla::Role::PluginBundle::Easy</a>, so you have access to those same methods.</p>
<h1><a class='u'
name="METHODS"
>METHODS</a></h1>
<h2><a class='u'
name="add_merged"
>add_merged</a></h2>
<p>The <code>add_merged</code> method takes a list (not arrayref) of plugin names, bundle names (with the <code>@</code> prefix), or full module names (with the <code>=</code> prefix). This method combines <code>add_plugins</code> & <code>add_bundle</code>, and handles all of the payload merging for you. For example, if your bundle is passed the following options:</p>
<pre> [@Bundle]
arg1 = blah
arg2 = foobar</pre>
<p>Then it will pass the <code>arg1/arg2</code> options to each of the plugins, <b>IF</b> they support the option. Specifically, it does a <code>$class->can($arg)</code> check. (Bundles are passed the entire payload set.) If <code>arg1</code> exists for multiple plugins, it will pass the same option to all of them. If you need separate options, you should consider using the <code>config_rename</code> method.</p>
<p>It will also accept hashrefs anywhere in the list, which will replace the payload arguments while it processes. This is useful for changing the options "on-the-fly" as plugins get processed. The replacement is done in order, and the changes will persist until it reaches the end of the list, or receives another replacement.</p>
<h2><a class='u'
name="config_rename"
>config_rename</a></h2>
<p>This method is sort of like the <code>[config_slice|Dist::Zilla::Role::PluginBundle::Easy/config_slice]</code> method, but is more implicit than explicit. It starts off with the entire payload (cloned), and renames any hash pair that was passed:</p>
<pre> my $hash = $self->config_rename(foobar_arg1 => 'arg1');</pre>
<p>This example will change the argument <code>foobar_arg1</code> to <code>arg1</code>. This is handy if you want to make a specific option for the plugin "Foobar" that doesn't clash with <code>arg1</code> on plugin "Baz":</p>
<pre> $self->add_merged(
'Baz',
$self->config_rename(foobar_arg1 => 'arg1', killme => ''),
'Foobar',
);</pre>
<p>Any destination options are replaced. Also, if the destination value is undef (or non-true), the key will simply be deleted. Keep in mind that this is all a clone of the payload, so extra calls to this method will still start out with the original payload.</p>
<h1><a class='u'
name="ROLE_PARAMETERS"
>ROLE PARAMETERS</a></h1>
<h2><a class='u'
name="mv_plugins"
>mv_plugins</a></h2>
<p>Certain configuration parameters are "multi-value" ones (or MVPs), and <a href="http://search.cpan.org/perldoc?Config%3A%3AMVP" class="podlinkpod"
>Config::MVP</a> uses the <code>mvp_multivalue_args</code> sub in each class to identify which ones exist. Since you are trying to merge the configuration parameters of multiple plugins, you'll need to make your new plugin bundle identifies those same MVPs.</p>
<p>Because the INI reader is closer to the beginning of the DZ plugin process, it would be too late for <code>add_merged</code> to start adding in keys to your <code>mvp_multivalue_args</code> array. Thus, this role is parameterized with this single parameter, and comes with its own <code>mvp_multivalue_args</code> method. The syntax is a single arrayref of strings in the same prefix structure as <code>add_merged</code>. For example:</p>
<pre> with 'Dist::Zilla::Role::PluginBundle::Merged' => {
mv_plugins => [ qw( Plugin1 Plugin2 ) ],
};</pre>
<p>The above will identify these two plugins has having MVPs. When <a href="http://search.cpan.org/perldoc?Config%3A%3AMVP" class="podlinkpod"
>Config::MVP</a> calls your <code>mvp_multivalue_args</code> sub (which is built into this role), it will load these two plugin classes and populate the contents of <b>their</b> <code>mvp_multivalue_args</code> sub as a combined list to pass over to <a href="http://search.cpan.org/perldoc?Config%3A%3AMVP" class="podlinkpod"
>Config::MVP</a>. In other words, as long as you identify all of the plugins that would have multiple values, your stuff "just works".</p>
<p>If you need to identify any extra parameters as MVPs (like your own custom MVPs or "dupe preventing" parameters that happen to be MVPs), you should consider combining <code>mv_plugins</code> with an <code>after mvp_multivalue_args</code> sub.</p>
<h1><a class='u'
name="AVAILABILITY"
>AVAILABILITY</a></h1>
<p>The project homepage is <a href="https://github.com/SineSwiper/Dist-Zilla-Role-PluginBundle-Merged/wiki" class="podlinkurl"
>https://github.com/SineSwiper/Dist-Zilla-Role-PluginBundle-Merged/wiki</a>.</p>
<p>The latest version of this module is available from the Comprehensive Perl Archive Network (CPAN). Visit <a href="http://www.perl.com/CPAN/" class="podlinkurl"
>http://www.perl.com/CPAN/</a> to find a CPAN site near you, or see <a href="https://metacpan.org/module/Dist::Zilla::Role::PluginBundle::Merged/" class="podlinkurl"
>https://metacpan.org/module/Dist::Zilla::Role::PluginBundle::Merged/</a>.</p>
<h1><a class='u'
name="SUPPORT"
>SUPPORT</a></h1>
<h2><a class='u'
name="Internet_Relay_Chat"
>Internet Relay Chat</a></h2>
<p>You can get live help by using IRC ( Internet Relay Chat ). If you don't know what IRC is, please read this excellent guide: <a href="http://en.wikipedia.org/wiki/Internet_Relay_Chat" class="podlinkurl"
>http://en.wikipedia.org/wiki/Internet_Relay_Chat</a>. Please be courteous and patient when talking to us, as we might be busy or sleeping! You can join those networks/channels and get help:</p>
<ul>
<li>irc.perl.org
<p>You can connect to the server at 'irc.perl.org' and join this channel: #distzilla then talk to this person for help: SineSwiper.</p>
</li>
</ul>
<h2><a class='u'
name="Bugs_/_Feature_Requests"
>Bugs / Feature Requests</a></h2>
<p>Please report any bugs or feature requests via <a href="http://search.cpan.org/perldoc?GitHub" class="podlinkpod"
><a href="https://github.com/SineSwiper/Dist-Zilla-Role-PluginBundle-Merged/issues" class="podlinkurl"
>https://github.com/SineSwiper/Dist-Zilla-Role-PluginBundle-Merged/issues</a></a>.</p>
<h1><a class='u'
name="AUTHOR"
>AUTHOR</a></h1>
<p>Brendan Byrd <BBYRD@CPAN.org></p>
<h1><a class='u'
name="COPYRIGHT_AND_LICENSE"
>COPYRIGHT AND LICENSE</a></h1>
<p>This software is Copyright (c) 2012 by Brendan Byrd.</p>
<p>This is free software, licensed under:</p>
<pre> The Artistic License 2.0 (GPL Compatible)</pre>
<!-- end doc -->
</body></html>