use Carp;
use Module::Pluggable::Object ();
-our $VERSION = '0.09_01';
+our $VERSION = '0.31';
=head1 NAME
Config::Any - Load configuration from different file formats, transparently
-=head1 VERSION
-
-This document describes Config::Any version 0.09_01
-
=head1 SYNOPSIS
use Config::Any;
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";
}
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( \%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<load_files()> attempts to load configuration from the list of files passed in
the C<files> parameter, if the file exists.
-If the C<filter> 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<filter> 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<use_ext> 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<myapp.cfg>
+be aware that you will lose flexibility -- for example, a file called C<myapp.cfg>
containing YAML data will not be offered to the YAML plugin, whereas C<myapp.yml>
or C<myapp.yaml> would be.
+When the C<flatten_to_hash> 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<load_files()> also supports a 'force_plugins' parameter, whose value should be an
-arrayref of plugin names like C<Config::Any::INI>. Its intended use is to allow the use
+arrayref of plugin names like C<Config::Any::INI>. 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<driver_args> hashref to pass special options to a particular
parser object. Example:
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<load_stems()> attempts to load configuration from a list of files which it generates
-by combining the filename stems list passed in the C<stems> parameter with the
+by combining the filename stems list passed in the C<stems> parameter with the
potential filename extensions from each loader, which you can check with the
C<extensions()> classmethod described below. Once this list of possible filenames is
built it is treated exactly as in C<load_files()> above, as which it takes the same
}
# figure out what plugins we're using
- my @plugins = $force ? @{ $args->{ force_plugins } } : $class->plugins;
+ 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 ) {
- $extension_lut{ $_ } = $plugin for $plugin->extensions;
+ for ( $plugin->extensions ) {
+ $extension_lut{ $_ } ||= [];
+ push @{ $extension_lut{ $_ } }, $plugin;
+ }
}
$extension_re = join( '|', keys %extension_lut );
if ( $use_ext_lut ) {
$filename =~ m{\.($extension_re)\z};
- next unless $1;
- @try_plugins = $extension_lut{ $1 };
+
+ 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;
- my @configs
- = eval { $loader->load( $filename, $loader_args{ $loader } ); };
+ $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 file: $filename" if $@ and $use_ext_lut;
- next if $@ or !@configs;
+ 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 } ) {
{ $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 );
+ }
+ }
+
+ 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<finder()> classmethod returns the
+The C<finder()> classmethod returns the
L<Module::Pluggable::Object|Module::Pluggable::Object>
object which is used to load the plugins. See the documentation for that module for
more information.
my $class = shift;
my $finder = Module::Pluggable::Object->new(
search_path => [ __PACKAGE__ ],
+ except => [ __PACKAGE__ . '::Base' ],
require => 1
);
return $finder;
=head2 plugins( )
-The C<plugins()> classmethod returns the names of configuration loading plugins as
+The C<plugins()> classmethod returns the names of configuration loading plugins as
found by L<Module::Pluggable::Object|Module::Pluggable::Object>.
=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( )
sub extensions {
my $class = shift;
- my @ext = map { $_->extensions } $class->plugins;
+ my @ext
+ = map { $_->extensions } $class->plugins;
return wantarray ? @ext : \@ext;
}
=head1 DEPENDENCIES
-L<Module::Pluggable|Module::Pluggable>
+L<Module::Pluggable::Object|Module::Pluggable::Object>
And at least one of the following:
L<Config::General|Config::General>
Please report any bugs or feature requests to
C<bug-config-any@rt.cpan.org>, or through the web interface at
-L<http://rt.cpan.org>.
+L<https://rt.cpan.org/Public/Dist/Display.html?Name=Config-Any>.
=head1 AUTHOR
-Joel Bernstein E<lt>rataxis@cpan.orgE<gt>
+Joel Bernstein <rataxis@cpan.org>
=head1 CONTRIBUTORS
-This module was based on the original
+This module was based on the original
L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader>
module by Brian Cassidy C<< <bricas@cpan.org> >>.
=head1 SEE ALSO
-L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader>
+L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader>
-- now a wrapper around this module.
=cut
projects / p5sagit/Config-Any.git / blobdiff