lib/Config/Any.pm

   1 package Config::Any;
   2 # $Id: $
   3 use warnings;
   4 use strict;
   5 use Carp;
   6 use Module::Pluggable::Object ();
   7 use English qw(-no_match_vars);
   8
   9 our $VERSION = '0.04';
  10
  11 =head1 NAME
  12
  13 Config::Any - Load configuration from different file formats, transparently
  14
  15 =head1 VERSION
  16
  17 This document describes Config::Any version 0.0.4
  18
  19 =head1 SYNOPSIS
  20
  21     use Config::Any;
  22
  23         my $cfg = Config::Any->load_stems({stems => \@filepath_stems, ... });
  24         # or
  25         my $cfg = Config::Any->load_files({files => \@filepaths, ... });
  26
  27         for (@$cfg) {
  28                 my ($filename, $config) = each %$_;
  29                 $class->config($config);
  30                 warn "loaded config from file: $filename";
  31         }
  32
  33 =head1 DESCRIPTION
  34
  35 L<Config::Any|Config::Any> provides a facility for Perl applications and libraries
  36 to load configuration data from multiple different file formats. It supports XML, YAML,
  37 JSON, Apache-style configuration, Windows INI files, and even Perl code.
  38
  39 The rationale for this module is as follows: Perl programs are deployed on many different
  40 platforms and integrated with many different systems. Systems administrators and end
  41 users may prefer different configuration formats than the developers. The flexibility
  42 inherent in a multiple format configuration loader allows different users to make
  43 different choices, without generating extra work for the developers. As a developer
  44 you only need to learn a single interface to be able to use the power of different
  45 configuration formats.
  46
  47 =head1 INTERFACE
  48
  49 =cut
  50
  51 =head2 load_files( )
  52
  53     Config::Any->load_files({files => \@files]});
  54     Config::Any->load_files({files => \@files, filter  => \&filter});
  55     Config::Any->load_files({files => \@files, use_ext => 1});
  56
  57 C<load_files()> attempts to load configuration from the list of files passed in
  58 the C<files> parameter, if the file exists.
  59
  60 If the C<filter> parameter is set, it is used as a callback to modify the configuration
  61 data before it is returned. It will be passed a single hash-reference parameter which
  62 it should modify in-place.
  63
  64 If the C<use_ext> parameter is defined, the loader will attempt to parse the file
  65 extension from each filename and will skip the file unless it matches a standard
  66 extension for the loading plugins. Only plugins whose standard extensions match the
  67 file extension will be used. For efficiency reasons, its use is encouraged, but
  68 be aware that you will lose flexibility -- for example, a file called C<myapp.cfg>
  69 containing YAML data will not be offered to the YAML plugin, whereas C<myapp.yml>
  70 or C<myapp.yaml> would be.
  71
  72 =cut
  73
  74 sub load_files {
  75     my ($class, $args) = @_;
  76     return unless defined $args;
  77     unless (exists $args->{files}) {
  78         warn "no files specified";
  79         return;
  80     }
  81
  82     my $files = [ grep { -f $_ } @{$args->{files}} ];
  83     my $filter_cb = delete $args->{filter};
  84     my $use_ext   = delete $args->{use_ext};
  85     return $class->_load($files, $filter_cb, $use_ext);
  86 }
  87
  88 =head2 load_stems( )
  89
  90     Config::Any->load_stems({stems => \@stems]});
  91     Config::Any->load_stems({stems => \@stems, filter  => \&filter});
  92     Config::Any->load_stems({stems => \@stems, use_ext => 1});
  93
  94 C<load_stems()> attempts to load configuration from a list of files which it generates
  95 by combining the filename stems list passed in the C<stems> parameter with the
  96 potential filename extensions from each loader, which you can check with the
  97 C<extensions()> classmethod described below. Once this list of possible filenames is
  98 built it is treated exactly as in C<load_files()> above, as which it takes the same
  99 parameters. Please read the C<load_files()> documentation before using this method.
 100
 101 =cut
 102
 103 sub load_stems {
 104     my ($class, $args) = @_;
 105     return unless defined $args;
 106     unless (exists $args->{stems}) {
 107         warn "no stems specified";
 108         return;
 109     }
 110
 111     my $filter_cb = delete $args->{filter};
 112     my $use_ext   = delete $args->{use_ext};
 113     my $stems = $args->{stems};
 114     my @files;
 115     STEM:
 116     for my $s (@$stems) {
 117         EXT:
 118         for my $ext ($class->extensions) {
 119             my $file = "$s.$ext";
 120             next EXT unless -f $file;
 121             push @files, $file;
 122             last EXT;
 123         }
 124     }
 125     return $class->_load(\@files, $filter_cb, $use_ext);
 126 }
 127
 128 # this is where we do the real work
 129 # it's a private class-method because users should use the interface described
 130 # in the POD.
 131 sub _load {
 132     my ($class, $files_ref, $filter_cb, $use_ext) = @_;
 133     croak "_load requires a arrayref of file paths" unless defined $files_ref;
 134
 135     my $final_configs       = [];
 136     my $originally_loaded   = {};
 137         my %files = map { $_ => 1 } @$files_ref;
 138
 139     for my $loader ( $class->plugins ) {
 140                 last unless keys %files;
 141 #       warn "loader: $loader\n";
 142         my %ext = map { $_ => 1 } $loader->extensions;
 143         FILE:
 144         for my $filename (keys %files) {
 145             if (defined $use_ext) {
 146 #                       warn "using file extension to decide which loader to use for file $filename\n";
 147                                 my $matched_ext = 0;
 148                 EXT:
 149                 for my $e (keys %ext) {
 150 #                               warn "trying ext $e\n";
 151                     next EXT  unless $filename =~ m{ \. $e \z }xms;
 152 #                                       warn "filename $filename matched extension $e\n";
 153                     next FILE unless exists $ext{$e};
 154                                         $matched_ext = 1;
 155                 }
 156                                 next FILE unless $matched_ext;
 157             }
 158
 159             my $config;
 160                         eval {
 161                                 $config = $loader->load( $filename );
 162                         };
 163                         next if $EVAL_ERROR;
 164             next if !$config;
 165                         delete $files{$filename};
 166 #                       warn "loader $loader loaded file $filename\n";
 167             $filter_cb->( $config ) if defined $filter_cb;
 168             push @$final_configs, { $filename => $config };
 169         }
 170     }
 171     $final_configs;
 172 }
 173
 174 =head2 finder( )
 175
 176 The C<finder()> classmethod returns the
 177 L<Module::Pluggable::Object|Module::Pluggable::Object>
 178 object which is used to load the plugins. See the documentation for that module for
 179 more information.
 180
 181 =cut
 182
 183 sub finder {
 184     my $class = shift;
 185     my $finder = Module::Pluggable::Object->new(
 186         search_path => [ __PACKAGE__ ],
 187         require     => 1
 188     );
 189     $finder;
 190 }
 191
 192 =head2 plugins( )
 193
 194 The C<plugins()> classmethod returns the names of configuration loading plugins as
 195 found by L<Module::Pluggable::Object|Module::Pluggable::Object>.
 196
 197 =cut
 198
 199 sub plugins {
 200     my $class = shift;
 201     return $class->finder->plugins;
 202 }
 203
 204 =head2 extensions( )
 205
 206 The C<extensions()> classmethod returns the possible file extensions which can be loaded
 207 by C<load_stems()> and C<load_files()>. This may be useful if you set the C<use_ext>
 208 parameter to those methods.
 209
 210 =cut
 211
 212 sub extensions {
 213     my $class = shift;
 214     my @ext = map { $_->extensions } $class->plugins;
 215         return wantarray ? @ext : [@ext];
 216 }
 217
 218 =head1 DIAGNOSTICS
 219
 220 =over
 221
 222 =item C<no files specified> or C<no stems specified>
 223
 224 The C<load_files()> and C<load_stems()> methods will issue this warning if
 225 called with an empty list of files/stems to load.
 226
 227 =item C<_load requires a arrayref of file paths>
 228
 229 This fatal error will be thrown by the internal C<_load> method. It should not occur
 230 but is specified here for completeness. If your code dies with this error, please
 231 email a failing test case to the authors below.
 232
 233 =back
 234
 235 =head1 CONFIGURATION AND ENVIRONMENT
 236
 237 Config::Any requires no configuration files or environment variables.
 238
 239 =head1 DEPENDENCIES
 240
 241 L<Module::Pluggable|Module::Pluggable>
 242
 243 And at least one of the following:
 244 L<Config::General|Config::General>
 245 L<Config::Tiny|Config::Tiny>
 246 L<JSON|JSON>
 247 L<YAML|YAML>
 248 L<JSON::Syck|JSON::Syck>
 249 L<YAML::Syck|YAML::Syck>
 250 L<XML::Simple|XML::Simple>
 251
 252 =head1 INCOMPATIBILITIES
 253
 254 None reported.
 255
 256 =head1 BUGS AND LIMITATIONS
 257
 258 No bugs have been reported.
 259
 260 Please report any bugs or feature requests to
 261 C<bug-config-any@rt.cpan.org>, or through the web interface at
 262 L<http://rt.cpan.org>.
 263
 264 =head1 AUTHOR
 265
 266 Joel Bernstein  C<< <rataxis@cpan.org> >>
 267
 268 =head1 CONTRIBUTORS
 269
 270 This module was based on the original
 271 L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader>
 272 module by Brian Cassidy C<< <bricas@cpan.org> >>.
 273
 274 With ideas and support from Matt S Trout C<< <mst@shadowcatsystems.co.uk> >>.
 275
 276 =head1 LICENCE AND COPYRIGHT
 277
 278 Copyright (c) 2006, Portugal Telecom C<< http://www.sapo.pt/ >>. All rights reserved.
 279
 280 This module is free software; you can redistribute it and/or
 281 modify it under the same terms as Perl itself. See L<perlartistic>.
 282
 283 =head1 DISCLAIMER OF WARRANTY
 284
 285 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
 286 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
 287 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
 288 PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
 289 EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 290 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
 291 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
 292 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
 293 NECESSARY SERVICING, REPAIR, OR CORRECTION.
 294
 295 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
 296 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
 297 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
 298 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
 299 OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
 300 THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
 301 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
 302 FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
 303 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
 304 SUCH DAMAGES.
 305
 306 =head1 SEE ALSO
 307
 308 L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader>
 309 -- now a wrapper around this module.
 310
 311 =cut
 312
 313 1; # Magic true value required at end of module
 314