NAME

Pod::Weaver::PluginBundle::Author::KENTNL::Role::Easy - Moo based instance based sugar syntax for mutable configuration declaration

VERSION

version 0.001003

QUICK REFERENCE

[>] bundle_prefix()                                         # [>] String
[>] instance_config()                                       # [>] mutator
->add_entry( $plugin_name, $confighash )                    # mutator
->add_named_entry( $name, $plugin_name, $confighash )       # mutator
->inhale_bundle( $name, $arg )                              # mutator

->mvp_bundle_config( $arg )                                 # List

->_push_state_prefixed( $name, $plugin_name, $confighash )  # mutator
->_push_state( $name, $plugin_name, $confighash )           # mutator
->_prefixify( $name, $plugin_name )                         # String
->_state()                                                  # ArrayRef


-~- MVP Magic -~-
[>?] mvp_multivalue_args                                    # [>] List[Str]
[>?] mvp_aliases                                            # [>] HashRef
[>?] mvp_bundle_config                                      # [>] List

SYNOPSIS

package Foo;
use Moo qw( with );
with 'Pod::Weaver::PluginBundle::Author::KENTNL::Role::Easy'; # this is the hardest part ;)

sub bundle_prefix { 'some_identifier_@foo_is_good' }

has 'ox_bollocks' => ( is => ro => ..., default => sub { 1 } );
has 'an_mvp_thinger' => ( is => ro => ..., default => sub { [] } );

sub mvp_multivalue_args { 'an_mvp_thinger' };

sub instance_config {
  my ( $self ) = @_;
  $self->add_entry( $pluginname, $config );
  if ( $self->ox_bollocks ) {
    $self->add_named_entry( $alias, $pluginname, $config );
  }
  for my $thing ( @{ $self->an_mvp_thinger } ) {
    ... # more things
  }
  $self->inhale_bundle( '@bundle', $maybeconfig );
}
1;

REQUIRED METHODS

bundle_prefix

Must return a string to prefix on ALL entries.

instance_config

Will be called for you to mutate state prior to returning the generated state.

METHODS

add_entry

Add a simple plugin to this bundle.

->add_entry( "Foo" , { a => 1 , b => [ 1, 2 ] } );
->add_entry( $name , { $config } );

Roughly corresponds to

[Foo / SomePrefix/Foo]
a = 1
b = 1
b = 2

For things that need to have unique names for plugins, use add_named_entry

add_named_entry

->add_named_entry( "Foo" , "Bar" , { a => 1, b => [1, 2]});
->add_entry( $name , { $config } );

Roughly corresponds to

[Bar / SomePrefix/Foo]
a = 1
b = 1
b = 2

NOTE: $name is subject to prefix expansion. Use $config explicitly to avoid side effects. That is, this mechanism only serves to create unique identifiers within a bundle.

Bundle prefixing should make sure it stays unique beyond that.

Relying on "name" field to communicate state within a bundle will break as soon as your bundle is inhaled.

So. Use $config ;)

->add_named_entry("SYNOPSIS", "Generic"); # Bad, will look for MyPrefix/SYNOPSIS, which won't exist.

->add_named_entry("SYNOPSIS", "Generic", { header => 'SYNOPSIS' }); # Resilient code.
  # { name => "MyPrefix/SYNOPIS",
  #   package => "Pod::Weaver::Section::Generic",
  #   payload => { header => 'SYNOPSIS' }
  # }

inhale_bundle

Include another bundle prefixed as a component of your own.

->inhale_bundle('@foobundle'); # Beginners mode
->inhale_bundle('@foobundle', $confighash ); # EXPERT MODE

Also, be aware that any bundle that has not been designed to be prefix resilient ( see "add_named_entry" ) will be likely broken if it relies on the "name" element to be meaningful.

You can circumvent this if you wear your expert hat and overload "_prefixify" and/or do it all yourself with "_push_state"

PRIVATE METHODS

_prefixify

Expands simple aliases into prefixed ones

->_prefixify( $oldname, $plugin_package )  >> String

Default implementation is simply

->bundle_prefix . q[/] . $oldname

And $plugin_package is passed for overloading convenience if you ever want to do something magical.

_push_state

Appends a configuration line to the internal array

->_push_state( $raw_name, $plugin_package, $config_hash )

_push_state_prefixed

Appends a configuration line to the internal array with $unprefixed_name prefixed

->_push_state_prefixed( $unprefixed_name, $plugin_package, $config_hash )

AUTHOR

Kent Fredric <kentnl@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Kent Fredric <kentfredric@gmail.com>.

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