lib/Config/Any.pm

   1 package Config::Any;
   2
   3 use strict;
   4 use warnings;
   5
   6 use Carp;
   7 use Module::Pluggable::Object ();
   8
   9 our $VERSION = '0.26';
  10
  11 =head1 NAME
  12
  13 Config::Any - Load configuration from different file formats, transparently
  14
  15 =head1 SYNOPSIS
  16
  17     use Config::Any;
  18
  19     my $cfg = Config::Any->load_stems({stems => \@filepath_stems, ... });
  20     # or
  21     my $cfg = Config::Any->load_files({files => \@filepaths, ... });
  22
  23     for (@$cfg) {
  24         my ($filename, $config) = %$_;
  25         $class->config($config);
  26         warn "loaded config from file: $filename";
  27     }
  28
  29 =head1 DESCRIPTION
  30
  31 L<Config::Any|Config::Any> provides a facility for Perl applications and libraries
  32 to load configuration data from multiple different file formats. It supports XML, YAML,
  33 JSON, Apache-style configuration, Windows INI files, and even Perl code.
  34
  35 The rationale for this module is as follows: Perl programs are deployed on many different
  36 platforms and integrated with many different systems. Systems administrators and end
  37 users may prefer different configuration formats than the developers. The flexibility
  38 inherent in a multiple format configuration loader allows different users to make
  39 different choices, without generating extra work for the developers. As a developer
  40 you only need to learn a single interface to be able to use the power of different
  41 configuration formats.
  42
  43 =head1 INTERFACE
  44
  45 =cut
  46
  47 =head2 load_files( \%args )
  48
  49     Config::Any->load_files( { files => \@files } );
  50     Config::Any->load_files( { files => \@files, filter  => \&filter } );
  51     Config::Any->load_files( { files => \@files, use_ext => 1 } );
  52     Config::Any->load_files( { files => \@files, flatten_to_hash => 1 } );
  53
  54 C<load_files()> attempts to load configuration from the list of files passed in
  55 the C<files> parameter, if the file exists.
  56
  57 If the C<filter> parameter is set, it is used as a callback to modify the configuration
  58 data before it is returned. It will be passed a single hash-reference parameter which
  59 it should modify in-place.
  60
  61 If the C<use_ext> parameter is defined, the loader will attempt to parse the file
  62 extension from each filename and will skip the file unless it matches a standard
  63 extension for the loading plugins. Only plugins whose standard extensions match the
  64 file extension will be used. For efficiency reasons, its use is encouraged, but
  65 be aware that you will lose flexibility -- for example, a file called C<myapp.cfg>
  66 containing YAML data will not be offered to the YAML plugin, whereas C<myapp.yml>
  67 or C<myapp.yaml> would be.
  68
  69 When the C<flatten_to_hash> parameter is defined, the loader will return a hash
  70 keyed on the file names, as opposed to the usual list of single-key hashes.
  71
  72 C<load_files()> also supports a 'force_plugins' parameter, whose value should be an
  73 arrayref of plugin names like C<Config::Any::INI>. Its intended use is to allow the use
  74 of a non-standard file extension while forcing it to be offered to a particular parser.
  75 It is not compatible with 'use_ext'.
  76
  77 You can supply a C<driver_args> hashref to pass special options to a particular
  78 parser object. Example:
  79
  80     Config::Any->load_files( { files => \@files, driver_args => {
  81         General => { -LowerCaseNames => 1 }
  82     } )
  83
  84 =cut
  85
  86 sub load_files {
  87     my ( $class, $args ) = @_;
  88
  89     unless ( $args && exists $args->{ files } ) {
  90         warn "No files specified!";
  91         return;
  92     }
  93
  94     return $class->_load( $args );
  95 }
  96
  97 =head2 load_stems( \%args )
  98
  99     Config::Any->load_stems( { stems => \@stems } );
 100     Config::Any->load_stems( { stems => \@stems, filter  => \&filter } );
 101     Config::Any->load_stems( { stems => \@stems, use_ext => 1 } );
 102     Config::Any->load_stems( { stems => \@stems, flatten_to_hash => 1 } );
 103
 104 C<load_stems()> attempts to load configuration from a list of files which it generates
 105 by combining the filename stems list passed in the C<stems> parameter with the
 106 potential filename extensions from each loader, which you can check with the
 107 C<extensions()> classmethod described below. Once this list of possible filenames is
 108 built it is treated exactly as in C<load_files()> above, as which it takes the same
 109 parameters. Please read the C<load_files()> documentation before using this method.
 110
 111 =cut
 112
 113 sub load_stems {
 114     my ( $class, $args ) = @_;
 115
 116     unless ( $args && exists $args->{ stems } ) {
 117         warn "No stems specified!";
 118         return;
 119     }
 120
 121     my $stems = delete $args->{ stems };
 122     my @files;
 123     for my $s ( @$stems ) {
 124         for my $ext ( $class->extensions ) {
 125             push @files, "$s.$ext";
 126         }
 127     }
 128
 129     $args->{ files } = \@files;
 130     return $class->_load( $args );
 131 }
 132
 133 sub _load {
 134     my ( $class, $args ) = @_;
 135     croak "_load requires a arrayref of file paths" unless $args->{ files };
 136
 137     my $force = defined $args->{ force_plugins };
 138     if ( !$force and !defined $args->{ use_ext } ) {
 139         warn
 140             "use_ext argument was not explicitly set, as of 0.09, this is true by default";
 141         $args->{ use_ext } = 1;
 142     }
 143
 144     # figure out what plugins we're using
 145     my @plugins = $force
 146         ? map { eval "require $_;"; $_; } @{ $args->{ force_plugins } }
 147         : $class->plugins;
 148
 149     # map extensions if we have to
 150     my ( %extension_lut, $extension_re );
 151     my $use_ext_lut = !$force && $args->{ use_ext };
 152     if ( $use_ext_lut ) {
 153         for my $plugin ( @plugins ) {
 154             for ( $plugin->extensions ) {
 155                 $extension_lut{ $_ } ||= [];
 156                 push @{ $extension_lut{ $_ } }, $plugin;
 157             }
 158         }
 159
 160         $extension_re = join( '|', keys %extension_lut );
 161     }
 162
 163     # map args to plugins
 164     my $base_class = __PACKAGE__;
 165     my %loader_args;
 166     for my $plugin ( @plugins ) {
 167         $plugin =~ m{^$base_class\::(.+)};
 168         $loader_args{ $plugin } = $args->{ driver_args }->{ $1 } || {};
 169     }
 170
 171     my @results;
 172
 173     for my $filename ( @{ $args->{ files } } ) {
 174
 175         # don't even bother if it's not there
 176         next unless -f $filename;
 177
 178         my @try_plugins = @plugins;
 179
 180         if ( $use_ext_lut ) {
 181             $filename =~ m{\.($extension_re)\z};
 182
 183             if ( !$1 ) {
 184                 $filename =~ m{\.([^.]+)\z};
 185                 croak "There are no loaders available for .${1} files";
 186             }
 187
 188             @try_plugins = @{ $extension_lut{ $1 } };
 189         }
 190
 191         # not using use_ext means we try all plugins anyway, so we'll
 192         # ignore it for the "unsupported" error
 193         my $supported = $use_ext_lut ? 0 : 1;
 194         for my $loader ( @try_plugins ) {
 195             next unless $loader->is_supported;
 196             $supported = 1;
 197             my @configs;
 198             my $err = do {
 199                 local $@;
 200                 @configs = eval { $loader->load( $filename, $loader_args{ $loader } ); };
 201                 $@;
 202             };
 203
 204             # fatal error if we used extension matching
 205             croak "Error parsing $filename: $err" if $err and $use_ext_lut;
 206             next if $err or !@configs;
 207
 208             # post-process config with a filter callback
 209             if ( $args->{ filter } ) {
 210                 $args->{ filter }->( $_ ) for @configs;
 211             }
 212
 213             push @results,
 214                 { $filename => @configs == 1 ? $configs[ 0 ] : \@configs };
 215             last;
 216         }
 217
 218         if ( !$supported ) {
 219             croak
 220                 "Cannot load $filename: required support modules are not available.\nPlease install "
 221                 . join( " OR ", map { _support_error( $_ ) } @try_plugins );
 222         }
 223     }
 224
 225     if ( defined $args->{ flatten_to_hash } ) {
 226         my %flattened = map { %$_ } @results;
 227         return \%flattened;
 228     }
 229
 230     return \@results;
 231 }
 232
 233 sub _support_error {
 234     my $module = shift;
 235     if ( $module->can( 'requires_all_of' ) ) {
 236         return join( ' and ',
 237             map { ref $_ ? join( ' ', @$_ ) : $_ } $module->requires_all_of );
 238     }
 239     if ( $module->can( 'requires_any_of' ) ) {
 240         return 'one of '
 241             . join( ' or ',
 242             map { ref $_ ? join( ' ', @$_ ) : $_ } $module->requires_any_of );
 243     }
 244 }
 245
 246 =head2 finder( )
 247
 248 The C<finder()> classmethod returns the
 249 L<Module::Pluggable::Object|Module::Pluggable::Object>
 250 object which is used to load the plugins. See the documentation for that module for
 251 more information.
 252
 253 =cut
 254
 255 sub finder {
 256     my $class  = shift;
 257     my $finder = Module::Pluggable::Object->new(
 258         search_path => [ __PACKAGE__ ],
 259         except      => [ __PACKAGE__ . '::Base' ],
 260         require     => 1
 261     );
 262     return $finder;
 263 }
 264
 265 =head2 plugins( )
 266
 267 The C<plugins()> classmethod returns the names of configuration loading plugins as
 268 found by L<Module::Pluggable::Object|Module::Pluggable::Object>.
 269
 270 =cut
 271
 272 sub plugins {
 273     my $class = shift;
 274
 275     # filter out things that don't look like our plugins
 276     return grep { $_->isa( 'Config::Any::Base' ) } $class->finder->plugins;
 277 }
 278
 279 =head2 extensions( )
 280
 281 The C<extensions()> classmethod returns the possible file extensions which can be loaded
 282 by C<load_stems()> and C<load_files()>. This may be useful if you set the C<use_ext>
 283 parameter to those methods.
 284
 285 =cut
 286
 287 sub extensions {
 288     my $class = shift;
 289     my @ext
 290         = map { $_->extensions } $class->plugins;
 291     return wantarray ? @ext : \@ext;
 292 }
 293
 294 =head1 DIAGNOSTICS
 295
 296 =over
 297
 298 =item C<No files specified!> or C<No stems specified!>
 299
 300 The C<load_files()> and C<load_stems()> methods will issue this warning if
 301 called with an empty list of files/stems to load.
 302
 303 =item C<_load requires a arrayref of file paths>
 304
 305 This fatal error will be thrown by the internal C<_load> method. It should not occur
 306 but is specified here for completeness. If your code dies with this error, please
 307 email a failing test case to the authors below.
 308
 309 =back
 310
 311 =head1 CONFIGURATION AND ENVIRONMENT
 312
 313 Config::Any requires no configuration files or environment variables.
 314
 315 =head1 DEPENDENCIES
 316
 317 L<Module::Pluggable|Module::Pluggable>
 318
 319 And at least one of the following:
 320 L<Config::General|Config::General>
 321 L<Config::Tiny|Config::Tiny>
 322 L<JSON|JSON>
 323 L<YAML|YAML>
 324 L<JSON::Syck|JSON::Syck>
 325 L<YAML::Syck|YAML::Syck>
 326 L<XML::Simple|XML::Simple>
 327
 328 =head1 INCOMPATIBILITIES
 329
 330 None reported.
 331
 332 =head1 BUGS AND LIMITATIONS
 333
 334 No bugs have been reported.
 335
 336 Please report any bugs or feature requests to
 337 C<bug-config-any@rt.cpan.org>, or through the web interface at
 338 L<http://rt.cpan.org>.
 339
 340 =head1 AUTHOR
 341
 342 Joel Bernstein E<lt>rataxis@cpan.orgE<gt>
 343
 344 =head1 CONTRIBUTORS
 345
 346 This module was based on the original
 347 L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader>
 348 module by Brian Cassidy C<< <bricas@cpan.org> >>.
 349
 350 With ideas and support from Matt S Trout C<< <mst@shadowcatsystems.co.uk> >>.
 351
 352 Further enhancements suggested by Evan Kaufman C<< <evank@cpan.org> >>.
 353
 354 =head1 LICENCE AND COPYRIGHT
 355
 356 Copyright (c) 2006, Portugal Telecom C<< http://www.sapo.pt/ >>. All rights reserved.
 357 Portions copyright 2007, Joel Bernstein C<< <rataxis@cpan.org> >>.
 358
 359 This module is free software; you can redistribute it and/or
 360 modify it under the same terms as Perl itself. See L<perlartistic>.
 361
 362 =head1 DISCLAIMER OF WARRANTY
 363
 364 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
 365 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
 366 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
 367 PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
 368 EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 369 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
 370 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
 371 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
 372 NECESSARY SERVICING, REPAIR, OR CORRECTION.
 373
 374 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
 375 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
 376 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
 377 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
 378 OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
 379 THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
 380 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
 381 FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
 382 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
 383 SUCH DAMAGES.
 384
 385 =head1 SEE ALSO
 386
 387 L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader>
 388 -- now a wrapper around this module.
 389
 390 =cut
 391
 392 "Drink more beer";