package Config::Any;
-# $Id: $
-use warnings;
+
use strict;
+use warnings;
+
use Carp;
use Module::Pluggable::Object ();
-use English qw(-no_match_vars);
-our $VERSION = '0.08';
+our $VERSION = '0.32';
=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;
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( )
+=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 } );
+ 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:
=cut
sub load_files {
- my ($class, $args) = @_;
- return unless defined $args;
- unless (exists $args->{files}) {
- warn "no files specified";
+ my ( $class, $args ) = @_;
+
+ unless ( $args && exists $args->{ files } ) {
+ warn "No files specified!";
return;
}
- my %load_args = map { $_ => defined $args->{$_} ? $args->{$_} : undef }
- qw(filter use_ext force_plugins driver_args);
- $load_args{files} = [ grep { -f $_ } @{$args->{files}} ];
- return $class->_load(\%load_args);
+ 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<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
=cut
sub load_stems {
- my ($class, $args) = @_;
- return unless defined $args;
- unless (exists $args->{stems}) {
- warn "no stems specified";
+ my ( $class, $args ) = @_;
+
+ 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);
- my $filenames = $class->_stems_to_files($args->{stems});
- $load_args{files} = [ grep { -f $_ } @{$filenames} ];
- return $class->_load(\%load_args);
+ my $stems = delete $args->{ stems };
+ my @files;
+ for my $s ( @$stems ) {
+ for my $ext ( $class->extensions ) {
+ push @files, "$s.$ext";
+ }
+ }
+
+ $args->{ files } = \@files;
+ return $class->_load( $args );
}
-sub _stems_to_files {
- my ($class, $stems) = @_;
- return unless defined $stems;
+sub _load {
+ my ( $class, $args ) = @_;
+ 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;
+ }
- my @files;
- STEM:
- for my $s (@$stems) {
- EXT:
- for my $ext ($class->extensions) {
- my $file = "$s.$ext";
- next EXT unless -f $file;
- push @files, $file;
- last EXT;
+ # 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 );
}
- \@files;
-}
-sub _maphash (@) { map { $_ => 1 } @_ } # sugar
+ # 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 } || {};
+ }
-# 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) {
- # 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;
+ my @results;
+
+ for my $filename ( @{ $args->{ files } } ) {
+
+ # don't even bother if it's not there
+ next unless -f $filename;
+
+ 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";
}
- my $config;
- eval {
- $config = $loader->load( $filename, $driver_args );
+ @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 } ); };
+ $@;
};
- next if $EVAL_ERROR; # if it croaked or warned, we can't use it
- next if !$config;
- delete $files{$filename};
+ # 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 we got one
- $filter_cb->( $config ) if defined $filter_cb;
+ # post-process config with a filter callback
+ if ( $args->{ filter } ) {
+ $args->{ filter }->( $_ ) for @configs;
+ }
+
+ push @results,
+ { $filename => @configs == 1 ? $configs[ 0 ] : \@configs };
+ last;
+ }
- push @$final_configs, { $filename => $config };
+ 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<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.
=cut
sub finder {
- my $class = shift;
+ my $class = shift;
my $finder = Module::Pluggable::Object->new(
search_path => [ __PACKAGE__ ],
+ except => [ __PACKAGE__ . '::Base' ],
require => 1
);
- $finder;
+ 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;
- return wantarray ? @ext : [@ext];
+ my @ext
+ = map { $_->extensions } $class->plugins;
+ return wantarray ? @ext : \@ext;
}
=head1 DIAGNOSTICS
=over
-=item C<no files specified> or C<no stems specified>
+=item C<No files specified!> or C<No stems specified!>
The C<load_files()> and C<load_stems()> methods will issue this warning if
called with an empty list of files/stems to load.
=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>
-L<Config::Tiny|Config::Tiny>
-L<JSON|JSON>
-L<YAML|YAML>
-L<JSON::Syck|JSON::Syck>
-L<YAML::Syck|YAML::Syck>
-L<XML::Simple|XML::Simple>
+And at least one of the following for each file type to be supported:
-=head1 INCOMPATIBILITIES
+=over 4
-None reported.
+=item *
-=head1 BUGS AND LIMITATIONS
+For C<.cnf>, C<.conf> files: L<Config::General>
+
+=item *
-No bugs have been reported.
+For C<.ini> files: L<Config::Tiny>
+
+=item *
+
+For C<.json>, C<.jsn> files: L<Cpanel::JSON::XS>, L<JSON::MaybeXS>, L<JSON::DWIW>, L<JSON::XS>, L<JSON::Syck>, L<JSON::PP>, L<JSON>
+
+=item *
+
+For C<.pl>, C<.perl> files: no additional requirements
+
+=item *
+
+For C<.xml> files: L<XML::Simple>
+
+=item *
+
+For C<.yml>, C<.yaml> files: L<YAML::XS>, L<YAML::Syck>, L<YAML>
+
+=back
+
+Additionally, other file types are supported by third-party plugins in the C<Config::Any::>
+namespace, installed separately.
+
+=head1 BUGS AND LIMITATIONS
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