X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit%2FConfig-Any.git;a=blobdiff_plain;f=lib%2FConfig%2FAny.pm;h=844af1b93a0476cc2a3746003b92ad8269701e16;hp=4f9b40113f90dad15e147a473290e774792c7745;hb=fcfdc024cf1d514b70a03e954d553f6cef3983fb;hpb=4efab5582d1ec3acd99a2ffb898bed58d5f2420b diff --git a/lib/Config/Any.pm b/lib/Config/Any.pm index 4f9b401..844af1b 100644 --- a/lib/Config/Any.pm +++ b/lib/Config/Any.pm @@ -5,18 +5,13 @@ use warnings; use Carp; use Module::Pluggable::Object (); -use English qw(-no_match_vars); -our $VERSION = '0.09'; +our $VERSION = '0.31'; =head1 NAME Config::Any - Load configuration from different file formats, transparently -=head1 VERSION - -This document describes Config::Any version 0.0.8 - =head1 SYNOPSIS use Config::Any; @@ -26,7 +21,7 @@ This document describes Config::Any version 0.0.8 my $cfg = Config::Any->load_files({files => \@filepaths, ... }); for (@$cfg) { - my ($filename, $config) = each %$_; + my ($filename, $config) = %$_; $class->config($config); warn "loaded config from file: $filename"; } @@ -38,42 +33,44 @@ to load configuration data from multiple different file formats. It supports XML JSON, Apache-style configuration, Windows INI files, and even Perl code. The rationale for this module is as follows: Perl programs are deployed on many different -platforms and integrated with many different systems. Systems administrators and end +platforms and integrated with many different systems. Systems administrators and end users may prefer different configuration formats than the developers. The flexibility -inherent in a multiple format configuration loader allows different users to make +inherent in a multiple format configuration loader allows different users to make different choices, without generating extra work for the developers. As a developer you only need to learn a single interface to be able to use the power of different configuration formats. -=head1 INTERFACE - -=cut +=head1 INTERFACE -=head2 load_files( ) +=head2 load_files( \%args ) Config::Any->load_files( { files => \@files } ); Config::Any->load_files( { files => \@files, filter => \&filter } ); Config::Any->load_files( { files => \@files, use_ext => 1 } ); + Config::Any->load_files( { files => \@files, flatten_to_hash => 1 } ); C attempts to load configuration from the list of files passed in the C parameter, if the file exists. -If the C parameter is set, it is used as a callback to modify the configuration -data before it is returned. It will be passed a single hash-reference parameter which +If the C parameter is set, it is used as a callback to modify the configuration +data before it is returned. It will be passed a single hash-reference parameter which it should modify in-place. If the C parameter is defined, the loader will attempt to parse the file extension from each filename and will skip the file unless it matches a standard extension for the loading plugins. Only plugins whose standard extensions match the file extension will be used. For efficiency reasons, its use is encouraged, but -be aware that you will lose flexibility -- for example, a file called C +be aware that you will lose flexibility -- for example, a file called C containing YAML data will not be offered to the YAML plugin, whereas C or C would be. +When the C parameter is defined, the loader will return a hash +keyed on the file names, as opposed to the usual list of single-key hashes. + C also supports a 'force_plugins' parameter, whose value should be an -arrayref of plugin names like C. Its intended use is to allow the use +arrayref of plugin names like C. Its intended use is to allow the use of a non-standard file extension while forcing it to be offered to a particular parser. -It is not compatible with 'use_ext'. +It is not compatible with 'use_ext'. You can supply a C hashref to pass special options to a particular parser object. Example: @@ -95,14 +92,15 @@ sub load_files { return $class->_load( $args ); } -=head2 load_stems( ) +=head2 load_stems( \%args ) - Config::Any->load_stems({stems => \@stems]}); - Config::Any->load_stems({stems => \@stems, filter => \&filter}); - Config::Any->load_stems({stems => \@stems, use_ext => 1}); + Config::Any->load_stems( { stems => \@stems } ); + Config::Any->load_stems( { stems => \@stems, filter => \&filter } ); + Config::Any->load_stems( { stems => \@stems, use_ext => 1 } ); + Config::Any->load_stems( { stems => \@stems, flatten_to_hash => 1 } ); C attempts to load configuration from a list of files which it generates -by combining the filename stems list passed in the C parameter with the +by combining the filename stems list passed in the C parameter with the potential filename extensions from each loader, which you can check with the C classmethod described below. Once this list of possible filenames is built it is treated exactly as in C above, as which it takes the same @@ -112,99 +110,140 @@ parameters. Please read the C documentation before using this meth sub load_stems { my ( $class, $args ) = @_; - return unless defined $args; - unless ( exists $args->{ stems } ) { - warn "no stems specified"; + + unless ( $args && exists $args->{ stems } ) { + warn "No stems specified!"; return; } - my %load_args - = map { $_ => defined $args->{ $_ } ? $args->{ $_ } : undef } - qw(filter use_ext force_plugins driver_args); - - $load_args{ files } = $class->_stems_to_files( $args->{ stems } ); - return $class->_load( \%load_args ); -} - -sub _stems_to_files { - my ( $class, $stems ) = @_; - return unless defined $stems; - + my $stems = delete $args->{ stems }; my @files; for my $s ( @$stems ) { for my $ext ( $class->extensions ) { push @files, "$s.$ext"; } } - return \@files; -} -sub _maphash { # syntactic sugar - map { $_ => 1 } @_; -} + $args->{ files } = \@files; + return $class->_load( $args ); +} -# this is where we do the real work -# it's a private class-method because users should use the interface described -# in the POD. sub _load { my ( $class, $args ) = @_; - my ( $files_ref, $filter_cb, $use_ext, $force_plugins_ref ) - = @{ $args }{ qw(files filter use_ext force_plugins) }; - croak "_load requires a arrayref of file paths" unless defined $files_ref; - - my %files = _maphash @$files_ref; - my %force_plugins = _maphash @$force_plugins_ref; - my $enforcing = keys %force_plugins ? 1 : 0; - - my $final_configs = []; - my $originally_loaded = {}; - - # perform a separate file loop for each loader - for my $loader ( $class->plugins ) { - next if $enforcing && not defined $force_plugins{ $loader }; - last unless keys %files; - my %ext = _maphash $loader->extensions; - - my ( $loader_class ) = $loader =~ /::([^:]+)$/; - my $driver_args = $args->{ driver_args }{ $loader_class } || {}; - - FILE: - for my $filename ( keys %files ) { - next unless -f $filename; - - # use file extension to decide whether this loader should try this file - # use_ext => 1 hits this block - if ( defined $use_ext && !$enforcing ) { - my $matched_ext = 0; - EXT: - for my $e ( keys %ext ) { - next EXT unless $filename =~ m{ \. $e \z }xms; - next FILE unless exists $ext{ $e }; - $matched_ext = 1; - } - - next FILE unless $matched_ext; + croak "_load requires a arrayref of file paths" unless $args->{ files }; + + my $force = defined $args->{ force_plugins }; + if ( !$force and !defined $args->{ use_ext } ) { + warn + "use_ext argument was not explicitly set, as of 0.09, this is true by default"; + $args->{ use_ext } = 1; + } + + # figure out what plugins we're using + my @plugins = $force + ? map { eval "require $_;"; $_; } @{ $args->{ force_plugins } } + : $class->plugins; + + # map extensions if we have to + my ( %extension_lut, $extension_re ); + my $use_ext_lut = !$force && $args->{ use_ext }; + if ( $use_ext_lut ) { + for my $plugin ( @plugins ) { + for ( $plugin->extensions ) { + $extension_lut{ $_ } ||= []; + push @{ $extension_lut{ $_ } }, $plugin; } + } + + $extension_re = join( '|', keys %extension_lut ); + } + + # map args to plugins + my $base_class = __PACKAGE__; + my %loader_args; + for my $plugin ( @plugins ) { + $plugin =~ m{^$base_class\::(.+)}; + $loader_args{ $plugin } = $args->{ driver_args }->{ $1 } || {}; + } - my $config; - eval { $config = $loader->load( $filename, $driver_args ); }; + my @results; - next if $EVAL_ERROR; # if it croaked or warned, we can't use it - next if !$config; - delete $files{ $filename }; + for my $filename ( @{ $args->{ files } } ) { - # post-process config with a filter callback, if we got one - $filter_cb->( $config ) if defined $filter_cb; + # don't even bother if it's not there + next unless -f $filename; - push @$final_configs, { $filename => $config }; + my @try_plugins = @plugins; + + if ( $use_ext_lut ) { + $filename =~ m{\.($extension_re)\z}; + + if ( !$1 ) { + $filename =~ m{\.([^.]+)\z}; + croak "There are no loaders available for .${1} files"; + } + + @try_plugins = @{ $extension_lut{ $1 } }; + } + + # not using use_ext means we try all plugins anyway, so we'll + # ignore it for the "unsupported" error + my $supported = $use_ext_lut ? 0 : 1; + for my $loader ( @try_plugins ) { + next unless $loader->is_supported; + $supported = 1; + my @configs; + my $err = do { + local $@; + @configs = eval { $loader->load( $filename, $loader_args{ $loader } ); }; + $@; + }; + + # fatal error if we used extension matching + croak "Error parsing $filename: $err" if $err and $use_ext_lut; + next if $err or !@configs; + + # post-process config with a filter callback + if ( $args->{ filter } ) { + $args->{ filter }->( $_ ) for @configs; + } + + push @results, + { $filename => @configs == 1 ? $configs[ 0 ] : \@configs }; + last; + } + + if ( !$supported ) { + croak + "Cannot load $filename: required support modules are not available.\nPlease install " + . join( " OR ", map { _support_error( $_ ) } @try_plugins ); } } - $final_configs; + + if ( defined $args->{ flatten_to_hash } ) { + my %flattened = map { %$_ } @results; + return \%flattened; + } + + return \@results; +} + +sub _support_error { + my $module = shift; + if ( $module->can( 'requires_all_of' ) ) { + return join( ' and ', + map { ref $_ ? join( ' ', @$_ ) : $_ } $module->requires_all_of ); + } + if ( $module->can( 'requires_any_of' ) ) { + return 'one of ' + . join( ' or ', + map { ref $_ ? join( ' ', @$_ ) : $_ } $module->requires_any_of ); + } } =head2 finder( ) -The C classmethod returns the +The C classmethod returns the L object which is used to load the plugins. See the documentation for that module for more information. @@ -215,21 +254,24 @@ sub finder { my $class = shift; my $finder = Module::Pluggable::Object->new( search_path => [ __PACKAGE__ ], + except => [ __PACKAGE__ . '::Base' ], require => 1 ); - $finder; + return $finder; } =head2 plugins( ) -The C classmethod returns the names of configuration loading plugins as +The C classmethod returns the names of configuration loading plugins as found by L. =cut sub plugins { my $class = shift; - return $class->finder->plugins; + + # filter out things that don't look like our plugins + return grep { $_->isa( 'Config::Any::Base' ) } $class->finder->plugins; } =head2 extensions( ) @@ -242,7 +284,8 @@ parameter to those methods. sub extensions { my $class = shift; - my @ext = map { $_->extensions } $class->plugins; + my @ext + = map { $_->extensions } $class->plugins; return wantarray ? @ext : \@ext; } @@ -250,7 +293,7 @@ sub extensions { =over -=item C or C +=item C or C The C and C methods will issue this warning if called with an empty list of files/stems to load. @@ -269,7 +312,7 @@ Config::Any requires no configuration files or environment variables. =head1 DEPENDENCIES -L +L And at least one of the following: L @@ -290,15 +333,15 @@ No bugs have been reported. Please report any bugs or feature requests to C, or through the web interface at -L. +L. =head1 AUTHOR -Joel Bernstein Erataxis@cpan.orgE +Joel Bernstein =head1 CONTRIBUTORS -This module was based on the original +This module was based on the original L module by Brian Cassidy C<< >>. @@ -339,7 +382,7 @@ SUCH DAMAGES. =head1 SEE ALSO -L +L -- now a wrapper around this module. =cut