dist::zilla::role::pluginbundle::easy(3pm) [debian man page]

Dist::Zilla::Role::PluginBundle::Easy(3pm)		User Contributed Perl Documentation		Dist::Zilla::Role::PluginBundle::Easy(3pm)

NAME

       Dist::Zilla::Role::PluginBundle::Easy - something that bundles a bunch of plugins easily

VERSION

       version 4.300020

SYNOPSIS

	 package Dist::Zilla::PluginBundle::Example;
	 use Moose;
	 with 'Dist::Zilla::Role::PluginBundle::Easy';

	 sub configure {
	   my $self = shift;

	   $self->add_plugins('VersionFromModule');
	   $self->add_bundle('Basic');
	 }

DESCRIPTION

       This role builds upon the PluginBundle role, adding methods to take most of the grunt work out of creating a bundle.  It supplies the
       "bundle_config" method for you.	In exchange, you must supply a "configure" method, which will store the bundle's configuration in the
       "plugins" attribute by calling "add_plugins" and/or "add_bundle".

ATTRIBUTES

   name
       This is the bundle name, taken from the Section passed to "bundle_config".

   payload
       This hashref contains the bundle's parameters (if any), taken from the Section passed to "bundle_config".

   plugins
       This arrayref contains the configuration that will be returned by "bundle_config".  You normally modify this by using the "add_plugins" and
       "add_bundle" methods.

METHODS

   add_plugins
	 $self->add_plugins('Plugin1', [ Plugin2 => \%plugin2config ])

       Use this method to add plugins to your bundle.

       It is passed a list of plugin specifiers, which can be one of a few things:

       o   a plugin moniker (like you might provide in your config file)

       o   an arrayref of: "[ $moniker, $plugin_name, \%plugin_config"

       In the case of an arrayref, both $plugin_name and "\%plugin_config" are optional.

       The plugins are added to the config in the order given.

   add_bundle
	 $self->add_bundle(BundleName => \%bundle_config)

       Use this method to add all the plugins from another bundle to your bundle.  If you omit %bundle_config, an empty hashref will be supplied.

   config_slice
	 $hash_ref = $self->config_slice(arg1, { arg2 => 'plugin_arg2' })

       Use this method to extract parameters from your bundle's "payload" so that you can pass them to a plugin or subsidiary bundle.  It supports
       easy renaming of parameters, since a plugin may expect a parameter name that's too generic to be suitable for a bundle.

       Each arg is either a key in "payload", or a hashref that maps keys in "payload" to keys in the hash being constructed.  If any specified
       key does not exist in "payload", then it is omitted from the result.

AUTHOR

       Ricardo SIGNES <rjbs@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2012 by Ricardo SIGNES.

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

perl v5.14.2							    2012-06-21				Dist::Zilla::Role::PluginBundle::Easy(3pm)

Mason::Manual::Plugins(3pm)				User Contributed Perl Documentation			       Mason::Manual::Plugins(3pm)

NAME

       Mason::Manual::Plugins - Mason plugins

DESCRIPTION

       A Mason plugin modifies behavior in one or more of Mason's main classes simultaneously, using Moose roles. Many Mason features, even some
       that might be considered "core", are implemented with plugins.

FINDING PLUGINS

       By convention plugins live in the "Mason::Plugin::*" namespace, and plugin bundles live in the "Mason::PluginBundle::*" namespace. You can
       find both with this search:

	   http://search.cpan.org/search?query=Mason%3A%3APlugin&mode=all

USING PLUGINS

       Pass a list of plugin specs to the Mason constructor:

	   Mason->new(plugins =>
		   [
		    'OnePlugin',
		    'AnotherPlugin',
		    '+My::Mason::Plugin::AThirdPlugin',
		    '@APluginBundle',
		    '+My::Mason::PluginBundle::AnotherBundle',
		    '-PluginIDontLike',
		   ]);

       Each plugin spec can be one of the following;

       o   A simple name, which will have "Mason::Plugin::" prepended to it.

       o   A bundle name, prefixed with '@', which will have "Mason::PluginBundle::" prepended to it.

       o   A full plugin or bundle class name prefixed with '+'.

       o   Any spec prefixed with '-', which means do not include these plugin(s) in the final list.

       See Mason::t::Plugins::test_plugin_specs in the Mason distribution for some examples.

DEFAULT PLUGINS

       Mason will always add the @Default bundle regardless of whether you pass your own list. You can remove individual default plugins that you
       don't like:

	   plugins => ['-DollarDot', ...]

       or the whole list:

	   plugins => ['-@Default', ...]

CREATING PLUGINS

       Note: If you want to modify behavior for a particular application only, it might be more convenient to create subclasses.

       A plugin consists of the main plugin class and one or more roles. The main class currently looks like this:

	   package Mason::Plugin::MyPlugin;
	   use Moose;
	   with 'Mason::Plugin';

	   # Optional: declare other plugin dependencies
	   method requires_plugins { qw(A @D) }

	   1;

	   __END__

	   =pod

	   =head1 NAME

	   Mason::Plugin::MyPlugin - My plugin

	   ....

       Its main responsibilities are to include the role 'Mason::Plugin' and document itself. It may also specify a "requires_plugins" that
       returns a list of dependencies with the same syntax as the "plugins" parameter to "Mason-"new>.

       The real action is in the role classes, which live underneath, and each modify a single Mason class:

	   package Mason::Plugin::MyPlugin::Interp;
	   use Mason::PluginRole;

	   # Modify Mason::Interp

	   ...

	   package Mason::Plugin::MyPlugin::Compilation;
	   use Mason::PluginRole;

	   # Modify Mason::Compilation

	   ...

       When a plugin is applied, each of its roles will be automatically applied to the appropriate Mason class. For example, in the example above
       "Mason::Plugin::MyPlugin::Interp" and "Mason::Plugin::MyPlugin::Compilation" will be applied to Mason::Interp and Mason::Compilation
       respectively.

   Pluggable Mason classes
       As of this writing the following Mason classes can be modified with plugins:

	   Mason::CodeCache
	   Mason::Compilation
	   Mason::Component
	   Mason::Component::ClassMeta
	   Mason::Component::Import
	   Mason::Component::Moose
	   Mason::Interp
	   Mason::Request
	   Mason::Result

   Extra classes in plugin
       If you have extra classes in your plugin that aren't automatically providing a role to a Mason class, put them in "Extra.pm" or the "Extra"
       subdirectory, e.g.

	  package Mason::Plugin::MyPlugin::Extra::Utils;
	  ...

       That will ensure that your classname will not conflict with a future Mason class name.

CREATING PLUGIN BUNDLES

       A plugin bundle just collects one or more plugins and/or other bundles. It looks like this:

	   package Mason::PluginBundle::MyBundle
	   use Moose;
	   with 'Mason::PluginBundle';

	   sub requires_plugins {
	       return (
		   'A',
		   'B',
		   '+My::Plugin::C',
		   '@D',
		   '+My::PluginBundle::E',
		   );
	   }

	   1;

	   __END__

	   =pod

	   =head1 NAME

	   Mason::PluginBundle::MyBundle - My plugin bundle

	   =head1 INCLUDED PLUGINS

	   =over

	   =item A
	   =item B
	   =item +My::Plugin::C
	   =item @D
	   =item +My::PluginBundle::E

	   =back

	   ....

       The "requires_plugins" method returns a list of entries, with the same syntax as the "plugins" parameter to "Mason-"new>.

ACKNOWLEDGEMENTS

       Thanks to Ricardo Signes <rjbs@cpan.org> for Dist::Zilla and Pod::Weaver, which got me thinking in plugins and lent the plugin and bundle
       name syntax.

SEE ALSO

       Mason

AUTHOR

       Jonathan Swartz <swartz@pobox.com>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2011 by Jonathan Swartz.

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

perl v5.14.2							    2012-05-02					       Mason::Manual::Plugins(3pm)