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=7bdf2a64a24259cd649cf686f1d6b713d0ed8f51;hp=c6a30e2ed898b04ae27bdc51e7527a2e9b4be890;hb=f9f3d682a0332cec1207764dcada85a7ff7750f0;hpb=c80a0905834ed09d487b84d7a00a3e92e44bbb62 diff --git a/lib/Config/Any.pm b/lib/Config/Any.pm index c6a30e2..7bdf2a6 100644 --- a/lib/Config/Any.pm +++ b/lib/Config/Any.pm @@ -1,208 +1,364 @@ package Config::Any; -# $Id: $ -use warnings; + use strict; +use warnings; + use Carp; use Module::Pluggable::Object (); -our $VERSION = (qw$Rev: $)[-1]; + +our $VERSION = '0.25'; + +=head1 NAME + +Config::Any - Load configuration from different file formats, transparently + +=head1 SYNOPSIS + + use Config::Any; + + my $cfg = Config::Any->load_stems({stems => \@filepath_stems, ... }); + # or + my $cfg = Config::Any->load_files({files => \@filepaths, ... }); + + for (@$cfg) { + my ($filename, $config) = %$_; + $class->config($config); + warn "loaded config from file: $filename"; + } + +=head1 DESCRIPTION + +L provides a facility for Perl applications and libraries +to load configuration data from multiple different file formats. It supports XML, YAML, +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 +users may prefer different configuration formats than the developers. The flexibility +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 + +=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 +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 +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 +of a non-standard file extension while forcing it to be offered to a particular parser. +It is not compatible with 'use_ext'. + +You can supply a C hashref to pass special options to a particular +parser object. Example: + + Config::Any->load_files( { files => \@files, driver_args => { + General => { -LowerCaseNames => 1 } + } ) + +=cut sub load_files { - my ($class, $args) = @_; - croak "load_files requires a hashref argument" unless defined $args; - croak "no files specified!" unless defined $args->{files}; - my $files = [ grep { -f $_ } @{$args->{files}} ]; - my $filter_cb = delete $args->{filter}; - return $class->_load($files, $filter_cb); + my ( $class, $args ) = @_; + + unless ( $args && exists $args->{ files } ) { + warn "No files specified!"; + return; + } + + return $class->_load( $args ); } +=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, 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 +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 +parameters. Please read the C documentation before using this method. + +=cut + sub load_stems { - my ($class, $args) = @_; - croak "load_stems requires a hashref argument" unless defined $args; - croak "no stems specified!" unless defined $args->{stems}; - my $filter_cb = delete $args->{filter}; - my $stems = $args->{stems}; + my ( $class, $args ) = @_; + + unless ( $args && exists $args->{ stems } ) { + warn "No stems specified!"; + return; + } + + my $stems = delete $args->{ stems }; 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; + for my $s ( @$stems ) { + for my $ext ( $class->extensions ) { + push @files, "$s.$ext"; } } - return $class->_load(\@files, $filter_cb); + + $args->{ files } = \@files; + return $class->_load( $args ); } sub _load { - my ($class, $files_ref, $filter_cb) = @_; - croak "_load requires a arrayref of file paths" unless defined $files_ref; - - my $final_configs = []; + 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; + } - for my $loader ( $class->plugins ) { - for my $filename (@$files_ref) { - my $config = $loader->load( $filename ); - next if !$config; - $filter_cb->( $config ) if defined $filter_cb; - push @$final_configs, { $filename => $config }; + # 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 ); } - $final_configs; -} -sub finder { - my $class = shift; - my $finder = Module::Pluggable::Object->new( - search_path => [ __PACKAGE__ ], - require => 1 - ); - $finder; -} + # 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 } || {}; + } -sub plugins { - my $class = shift; - return $class->finder->plugins; -} + my @results; -sub extensions { - my $class = shift; - return [ map { $_->extensions } $class->plugins ]; -} + for my $filename ( @{ $args->{ files } } ) { -1; # Magic true value required at end of module -__END__ + # don't even bother if it's not there + next unless -f $filename; -=head1 NAME + my @try_plugins = @plugins; -Config::Any - [One line description of module's purpose here] + if ( $use_ext_lut ) { + $filename =~ m{\.($extension_re)\z}; + if ( !$1 ) { + $filename =~ m{\.([^.]+)\z}; + croak "There are no loaders available for .${1} files"; + } -=head1 VERSION + @try_plugins = @{ $extension_lut{ $1 } }; + } -This document describes Config::Any version 0.0.4 + # 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 $ok = do { + local $@; + @configs = eval { $loader->load( $filename, $loader_args{ $loader } ); }; + 1; + }; + + # fatal error if we used extension matching + croak "Error parsing $filename: $@" if !$ok and $use_ext_lut; + next if !$ok 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 ); + } + } -=head1 SYNOPSIS + if ( defined $args->{ flatten_to_hash } ) { + my %flattened = map { %$_ } @results; + return \%flattened; + } - use Config::Any; + return \@results; +} - my $cfg = Config::Any->load_stems({stems => \@filepath_stems, ... }); - # or - my $cfg = Config::Any->load_files({files => \@filepaths, ... }); +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 ); + } +} - for (@$cfg) { - my ($filename, $config) = each %$_; - $class->config($config); - warn "loaded config from file: $filename"; - } +=head2 finder( ) -=head1 DESCRIPTION +The C classmethod returns the +L +object which is used to load the plugins. See the documentation for that module for +more information. -=for author to fill in: - Write a full description of the module and its features here. - Use subsections (=head2, =head3) as appropriate. +=cut +sub finder { + my $class = shift; + my $finder = Module::Pluggable::Object->new( + search_path => [ __PACKAGE__ ], + except => [ __PACKAGE__ . '::Base' ], + require => 1 + ); + return $finder; +} -=head1 INTERFACE +=head2 plugins( ) -=for author to fill in: - Write a separate section listing the public components of the modules - interface. These normally consist of either subroutines that may be - exported, or methods that may be called on objects belonging to the - classes provided by the module. +The C classmethod returns the names of configuration loading plugins as +found by L. +=cut -=head1 DIAGNOSTICS +sub plugins { + my $class = shift; + + # filter out things that don't look like our plugins + return grep { $_->isa( 'Config::Any::Base' ) } $class->finder->plugins; +} -=for author to fill in: - List every single error and warning message that the module can - generate (even the ones that will "never happen"), with a full - explanation of each problem, one or more likely causes, and any - suggested remedies. +=head2 extensions( ) -=over +The C classmethod returns the possible file extensions which can be loaded +by C and C. This may be useful if you set the C +parameter to those methods. + +=cut + +sub extensions { + my $class = shift; + my @ext + = map { $_->extensions } $class->plugins; + return wantarray ? @ext : \@ext; +} -=item C<< Error message here, perhaps with %s placeholders >> +=head1 DIAGNOSTICS -[Description of error here] +=over -=item C<< Another error message here >> +=item C or C -[Description of error here] +The C and C methods will issue this warning if +called with an empty list of files/stems to load. -[Et cetera, et cetera] +=item C<_load requires a arrayref of file paths> -=back +This fatal error will be thrown by the internal C<_load> method. It should not occur +but is specified here for completeness. If your code dies with this error, please +email a failing test case to the authors below. +=back =head1 CONFIGURATION AND ENVIRONMENT -=for author to fill in: - A full explanation of any configuration system(s) used by the - module, including the names and locations of any configuration - files, and the meaning of any environment variables or properties - that can be set. These descriptions must also include details of any - configuration language used. - Config::Any requires no configuration files or environment variables. - =head1 DEPENDENCIES -=for author to fill in: - A list of all the other modules that this module relies upon, - including any restrictions on versions, and an indication whether - the module is part of the standard Perl distribution, part of the - module's distribution, or must be installed separately. ] - -None. +L +And at least one of the following: +L +L +L +L +L +L +L =head1 INCOMPATIBILITIES -=for author to fill in: - A list of any modules that this module cannot be used in conjunction - with. This may be due to name conflicts in the interface, or - competition for system or program resources, or due to internal - limitations of Perl (for example, many modules that use source code - filters are mutually incompatible). - None reported. - =head1 BUGS AND LIMITATIONS -=for author to fill in: - A list of known problems with the module, together with some - indication Whether they are likely to be fixed in an upcoming - release. Also a list of restrictions on the features the module - does provide: data types that cannot be handled, performance issues - and the circumstances in which they may arise, practical - limitations on the size of data sets, special cases that are not - (yet) handled, etc. - No bugs have been reported. Please report any bugs or feature requests to C, or through the web interface at L. - =head1 AUTHOR -Joel Bernstein C<< >> +Joel Bernstein Erataxis@cpan.orgE + +=head1 CONTRIBUTORS + +This module was based on the original +L +module by Brian Cassidy C<< >>. +With ideas and support from Matt S Trout C<< >>. + +Further enhancements suggested by Evan Kaufman C<< >>. =head1 LICENCE AND COPYRIGHT Copyright (c) 2006, Portugal Telecom C<< http://www.sapo.pt/ >>. All rights reserved. +Portions copyright 2007, Joel Bernstein C<< >>. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See L. - =head1 DISCLAIMER OF WARRANTY BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY @@ -225,3 +381,12 @@ RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + +=head1 SEE ALSO + +L +-- now a wrapper around this module. + +=cut + +"Drink more beer";