Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kentnl/dist-zilla-util-configdumper

Easy implementation of 'dumpconfig'
https://github.com/kentnl/dist-zilla-util-configdumper

dist-zilla perl

Last synced: about 2 months ago
JSON representation

Easy implementation of 'dumpconfig'

Awesome Lists containing this project

README 

        
# NAME



Dist::Zilla::Util::ConfigDumper - A Dist::Zilla plugin configuration extraction utility



# VERSION



version 0.003010



# SYNOPSIS



    ...



    with 'Dist::Zilla::Role::Plugin';

    use Dist::Zilla::Util::ConfigDumper qw( config_dumper );



    around dump_config => config_dumper( __PACKAGE__, qw( foo bar baz ) );



# DESCRIPTION



This module contains a utility function for use within the `Dist::Zilla`

plugin ecosystem, to simplify extraction of plugin settings for plugin

authors, in order for plugins like `Dist::Zilla::Plugin::MetaConfig` to expose

those values to consumers.



Primarily, it specializes in:



- Making propagating configuration from the plugins inheritance hierarchy

nearly foolproof.

- Providing simple interfaces to extract values of lists of named methods

or accessors

- Providing a way to intelligently and easily probe the value of lazy

attributes without triggering their vivification.



# FUNCTIONS



## `config_dumper`



    config_dumper( __PACKAGE__, qw( method list ) );



Returns a function suitable for use with `around dump_config`.



    my $sub = config_dumper( __PACKAGE__, qw( method list ) );

    around dump_config => $sub;



Or



    around dump_config => sub {

      my ( $orig, $self, @args ) = @_;

      return config_dumper(__PACKAGE__, qw( method list ))->( $orig, $self, @args );

    };



Either way:



    my $function = config_dumper( $package_name_for_config, qw( methods to call on $self ));

    my $hash = $function->( $function_that_returns_a_hash, $instance_to_call_methods_on, @somethinggoeshere );



=~ All of this approximates:



    around dump_config => sub {

      my ( $orig , $self , @args ) = @_;

      my $conf = $self->$orig( @args );

      my $payload = {};



      for my $method ( @methods ) {

        try {

          $payload->{ $method } = $self->$method();

        };

      }

      $config->{+__PACKAGE__} = $payload;

    }



Except with some extra "things dun goofed" handling.



## `dump_plugin`



This function serves the other half of the equation, emulating `dzil`'s own

internal behavior for extracting the `plugin` configuration data.



    for my $plugin ( @{ $zilla->plugins } ) {

      pp( dump_plugin( $plugin )); # could prove useful somewhere.

    }



Its not usually something you need, but its useful in:



- Tests

- Crazy Stuff like injecting plugins

- Crazy Stuff like having "Child" plugins



This serves to be a little more complicated than merely calling `->dump_config`,

as the structure `dzil` uses is:



    {

      class   => ...

      name    => ...

      version => ...

      config  => $dump_config_results_here

    }



And of course, there's a bunch of magic stuff with `meta`, `can` and `if keys %$configresults`



All that insanity is wrapped in this simple interface.



# ADVANCED USE



## CALLBACKS



Internally



    config_dumper( $pkg, qw( method list ) );



Maps to a bunch of subs, so its more like:



    config_dumper( $pkg, sub {

      my ( $instance, $payload ) = @_;

      $payload->{'method'} = $instance->method;

    }, sub {

      $_[1]->{'list'} = $_[0]->list;

    });



So if you want to use that because its more convenient for some problem, be my guest.



    around dump_config => config_dumper( __PACKAGE__, sub {

      $_[1]->{'x'} = 'y'

    });



is much less ugly than



    around dump_config => sub {

      my ( $orig, $self, @args ) = @_;

      my $conf = $self->$orig(@args);

      $config->{+__PACKAGE__} = { # if you forget the +, things break

         'x' => 'y'

      };

      return $config;

    };



## DETAILED CONFIGURATION



There's an additional feature for advanced people:



    config_dumper( $pkg, \%config );



### `attrs`



    config_dumper( $pkg, { attrs => [qw( foo bar baz )] });



This is for cases where you want to deal with `Moose` attributes,

but want added safety of **NOT** loading attributes that have no value yet.



For each item in `attrs`, we'll call `Moose` attribute internals to determine

if the attribute named has a value, and only then will we fetch it.



# AUTHOR



Kent Fredric 



# COPYRIGHT AND LICENSE



This software is copyright (c) 2017 by Kent Fredric .



This is free software; you can redistribute it and/or modify it under

the same terms as the Perl 5 programming language system itself.