From: Joel Bernstein Date: Fri, 18 Aug 2006 22:25:58 +0000 (+0000) Subject: Config::Any ready for release to CPAN X-Git-Tag: v0.04~11 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit%2FConfig-Any.git;a=commitdiff_plain;h=59a8045203653a6f6cbccc3c24eb3884fba40ddc Config::Any ready for release to CPAN - Config::Any now working perfectly. - Added fix to Config::Any::General to avoid Config::General stupidly parsing Perl code as if it were an Apache-style config file. --- diff --git a/lib/Config/Any.pm b/lib/Config/Any.pm index c6a30e2..c7580a2 100644 --- a/lib/Config/Any.pm +++ b/lib/Config/Any.pm @@ -4,22 +4,112 @@ use warnings; use strict; use Carp; use Module::Pluggable::Object (); +use English qw(-no_match_vars); + our $VERSION = (qw$Rev: $)[-1]; +=head1 NAME + +Config::Any - Load configuration from different file formats, transparently + +=head1 VERSION + +This document describes Config::Any version 0.0.4 + +=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) = each %$_; + $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( ) + + Config::Any->load_files({files => \@files]}); + Config::Any->load_files({files => \@files, filter => \&filter}); + Config::Any->load_files({files => \@files, use_ext => 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. + +=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}; + return unless defined $args; + unless (exists $args->{files}) { + warn "no files specified"; + return; + } + my $files = [ grep { -f $_ } @{$args->{files}} ]; my $filter_cb = delete $args->{filter}; - return $class->_load($files, $filter_cb); + my $use_ext = delete $args->{use_ext}; + return $class->_load($files, $filter_cb, $use_ext); } +=head2 load_stems( ) + + Config::Any->load_stems({stems => \@stems]}); + Config::Any->load_stems({stems => \@stems, filter => \&filter}); + Config::Any->load_stems({stems => \@stems, use_ext => 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}; + return unless defined $args; + unless (exists $args->{stems}) { + warn "no stems specified"; + return; + } + my $filter_cb = delete $args->{filter}; + my $use_ext = delete $args->{use_ext}; my $stems = $args->{stems}; my @files; STEM: @@ -32,18 +122,35 @@ sub load_stems { last EXT; } } - return $class->_load(\@files, $filter_cb); + return $class->_load(\@files, $filter_cb, $use_ext); } +# 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, $files_ref, $filter_cb) = @_; + my ($class, $files_ref, $filter_cb, $use_ext) = @_; croak "_load requires a arrayref of file paths" unless defined $files_ref; - my $final_configs = []; + my $final_configs = []; + my $originally_loaded = {}; for my $loader ( $class->plugins ) { + my %ext = map { $_ => 1 } $loader->extensions; + FILE: for my $filename (@$files_ref) { - my $config = $loader->load( $filename ); + if (defined $use_ext) { + for my $e (keys %ext) { + my ($fileext) = $filename =~ m{ \. $e \z }xms; + next FILE unless exists $ext{$fileext}; + } + } + + my $config; + eval { + $config = $loader->load( $filename ); + }; + next if $EVAL_ERROR; next if !$config; $filter_cb->( $config ) if defined $filter_cb; push @$final_configs, { $filename => $config }; @@ -52,6 +159,15 @@ sub _load { $final_configs; } +=head2 finder( ) + +The C classmethod returns the +L +object which is used to load the plugins. See the documentation for that module for +more information. + +=cut + sub finder { my $class = shift; my $finder = Module::Pluggable::Object->new( @@ -61,139 +177,89 @@ sub finder { $finder; } +=head2 plugins( ) + +The C classmethod returns the names of configuration loading plugins as +found by L. + +=cut + sub plugins { my $class = shift; return $class->finder->plugins; } -sub extensions { - my $class = shift; - return [ map { $_->extensions } $class->plugins ]; -} - -1; # Magic true value required at end of module -__END__ - -=head1 NAME - -Config::Any - [One line description of module's purpose here] - - -=head1 VERSION - -This document describes Config::Any version 0.0.4 - - -=head1 SYNOPSIS - - use Config::Any; +=head2 extensions( ) - my $cfg = Config::Any->load_stems({stems => \@filepath_stems, ... }); - # or - my $cfg = Config::Any->load_files({files => \@filepaths, ... }); - - for (@$cfg) { - my ($filename, $config) = each %$_; - $class->config($config); - warn "loaded config from file: $filename"; - } - -=head1 DESCRIPTION +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. -=for author to fill in: - Write a full description of the module and its features here. - Use subsections (=head2, =head3) as appropriate. - - -=head1 INTERFACE - -=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. +=cut +sub extensions { + my $class = shift; + my @ext = map { $_->extensions } $class->plugins; + return wantarray ? @ext : [@ext]; +} =head1 DIAGNOSTICS -=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. - =over -=item C<< Error message here, perhaps with %s placeholders >> - -[Description of error here] +=item C or C -=item C<< Another error message here >> +The C and C methods will issue this warning if +called with an empty list of files/stems to load. -[Description of error here] +=item C<_load requires a arrayref of file paths> -[Et cetera, et cetera] +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<< >> +=head1 CONTRIBUTORS + +This module was based on the original +L +module by Brian Cassidy C<< >>. + +With ideas and support from Matt S Trout C<< >>. =head1 LICENCE AND COPYRIGHT @@ -202,7 +268,6 @@ Copyright (c) 2006, Portugal Telecom C<< http://www.sapo.pt/ >>. All rights rese 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 +290,13 @@ 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 + +1; # Magic true value required at end of module + diff --git a/lib/Config/Any/General.pm b/lib/Config/Any/General.pm index c91bd4d..1951488 100644 --- a/lib/Config/Any/General.pm +++ b/lib/Config/Any/General.pm @@ -41,6 +41,9 @@ sub load { my $class = shift; my $file = shift; + # work around bug (?) in Config::General + return if $class->_test_perl($file); + require Config::General; my $configfile = Config::General->new( $file ); my $config = { $configfile->getall }; @@ -48,6 +51,20 @@ sub load { return $config; } +# this is a bit of a hack but necessary, because Config::General is *far* too lax +# about what it will load -- specifically, it seems to be quite happy to load a Perl +# config file (ie, a file which is valid Perl and creates a hashref) as if it were +# an Apache-style configuration file, presumably due to laziness on the part of the +# developer. + +sub _test_perl { + my ($class, $file) = @_; + my $is_perl_src; + eval { $is_perl_src = do "$file"; }; + delete $INC{$file}; # so we don't screw stuff later on + return defined $is_perl_src; +} + =head1 AUTHOR =over 4 @@ -56,10 +73,20 @@ sub load { =back +=head1 CONTRIBUTORS + +=over 4 + +=item * Joel Bernstein C<< >> + +=back + =head1 COPYRIGHT AND LICENSE Copyright 2006 by Brian Cassidy +Portions Copyright 2006 Portugal Telecom + This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. @@ -77,4 +104,5 @@ it under the same terms as Perl itself. =cut -1; \ No newline at end of file +1; +