[p5sagit/Config-Any.git] / lib / Config / Any.pm

package Config::Any;
# $Id: $
use warnings;
use strict;
use Carp;
use Module::Pluggable::Object ();
use English qw(-no_match_vars);

our $VERSION = '0.04';

=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<Config::Any|Config::Any> 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<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 
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> 
containing YAML data will not be offered to the YAML plugin, whereas C<myapp.yml>
or C<myapp.yaml> would be.

=cut

sub load_files {
    my ($class, $args) = @_;
    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};
    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<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 
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
parameters. Please read the C<load_files()> documentation before using this method.

=cut

sub load_stems {
    my ($class, $args) = @_;
    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:
    for my $s (@$stems) {
        EXT:
        for my $ext ($class->extensions) {
            my $file = "$s.$ext";
            next EXT unless -f $file;
            push @files, $file;
            last EXT;
        }
    }
    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, $use_ext) = @_;
    croak "_load requires a arrayref of file paths" unless defined $files_ref;

    my $final_configs       = [];
    my $originally_loaded   = {};
	my %files = map { $_ => 1 } @$files_ref;

    for my $loader ( $class->plugins ) {
		last unless keys %files;
#	warn "loader: $loader\n";
        my %ext = map { $_ => 1 } $loader->extensions;
        FILE:
        for my $filename (keys %files) {
            if (defined $use_ext) {
#			warn "using file extension to decide which loader to use for file $filename\n";
				my $matched_ext = 0;
                EXT:
                for my $e (keys %ext) {
#				warn "trying ext $e\n";
                    next EXT  unless $filename =~ m{ \. $e \z }xms; 
#					warn "filename $filename matched extension $e\n";
                    next FILE unless exists $ext{$e};
					$matched_ext = 1;
                }
				next FILE unless $matched_ext;
            }

            my $config;
			eval {
				$config = $loader->load( $filename );
			};
			next if $EVAL_ERROR;
            next if !$config;
			delete $files{$filename};
#			warn "loader $loader loaded file $filename\n";
            $filter_cb->( $config ) if defined $filter_cb;
            push @$final_configs, { $filename => $config };
        }
    }
    $final_configs;
}

=head2 finder( )

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 $finder = Module::Pluggable::Object->new(
        search_path => [ __PACKAGE__ ],
        require     => 1
    );
    $finder;
}

=head2 plugins( )

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;
}

=head2 extensions( )

The C<extensions()> classmethod returns the possible file extensions which can be loaded
by C<load_stems()> and C<load_files()>. This may be useful if you set the C<use_ext>
parameter to those methods.

=cut

sub extensions {
    my $class = shift;
    my @ext = map { $_->extensions } $class->plugins;
	return wantarray ? @ext : [@ext];
}

=head1 DIAGNOSTICS

=over

=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.

=item C<_load requires a arrayref of file paths>

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

Config::Any requires no configuration files or environment variables.

=head1 DEPENDENCIES

L<Module::Pluggable|Module::Pluggable>

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>

=head1 INCOMPATIBILITIES

None reported.

=head1 BUGS AND LIMITATIONS

No bugs have been reported.

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>.

=head1 AUTHOR

Joel Bernstein  C<< <rataxis@cpan.org> >>

=head1 CONTRIBUTORS

This module was based on the original 
L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader>
module by Brian Cassidy C<< <bricas@cpan.org> >>.

With ideas and support from Matt S Trout C<< <mst@shadowcatsystems.co.uk> >>.

=head1 LICENCE AND COPYRIGHT

Copyright (c) 2006, Portugal Telecom C<< http://www.sapo.pt/ >>. All rights reserved.

This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See L<perlartistic>.

=head1 DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
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<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader> 
-- now a wrapper around this module.

=cut

1; # Magic true value required at end of module
Commit	Line	Data
c80a0905	1	package Config::Any;
	2	# $Id: $
	3	use warnings;
	4	use strict;
	5	use Carp;
	6	use Module::Pluggable::Object ();
59a80452	7	use English qw(-no_match_vars);
59a80452	8
89706e8e	9	our $VERSION = '0.04';
c80a0905	10
59a80452	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
c80a0905	74	sub load_files {
c80a0905	75	my ($class, $args) = @_;
59a80452	76	return unless defined $args;
	77	unless (exists $args->{files}) {
	78	warn "no files specified";
	79	return;
	80	}
	81
c80a0905	82	my $files = [ grep { -f $_ } @{$args->{files}} ];
c80a0905	83	my $filter_cb = delete $args->{filter};
59a80452	84	my $use_ext = delete $args->{use_ext};
59a80452	85	return $class->_load($files, $filter_cb, $use_ext);
c80a0905	86	}
c80a0905	87
59a80452	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
c80a0905	103	sub load_stems {
c80a0905	104	my ($class, $args) = @_;
59a80452	105	return unless defined $args;
	106	unless (exists $args->{stems}) {
	107	warn "no stems specified";
	108	return;
	109	}
	110
c80a0905	111	my $filter_cb = delete $args->{filter};
59a80452	112	my $use_ext = delete $args->{use_ext};
c80a0905	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	}
59a80452	125	return $class->_load(\@files, $filter_cb, $use_ext);
c80a0905	126	}
c80a0905	127
59a80452	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.
c80a0905	131	sub _load {
59a80452	132	my ($class, $files_ref, $filter_cb, $use_ext) = @_;
c80a0905	133	croak "_load requires a arrayref of file paths" unless defined $files_ref;
c80a0905	134
59a80452	135	my $final_configs = [];
59a80452	136	my $originally_loaded = {};
e967a60f	137	my %files = map { $_ => 1 } @$files_ref;
c80a0905	138
c80a0905	139	for my $loader ( $class->plugins ) {
e967a60f	140	last unless keys %files;
e967a60f	141	# warn "loader: $loader\n";
59a80452	142	my %ext = map { $_ => 1 } $loader->extensions;
59a80452	143	FILE:
e967a60f	144	for my $filename (keys %files) {
59a80452	145	if (defined $use_ext) {
e967a60f	146	# warn "using file extension to decide which loader to use for file $filename\n";
	147	my $matched_ext = 0;
	148	EXT:
59a80452	149	for my $e (keys %ext) {
e967a60f	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;
59a80452	155	}
e967a60f	156	next FILE unless $matched_ext;
59a80452	157	}
	158
	159	my $config;
	160	eval {
	161	$config = $loader->load( $filename );
	162	};
	163	next if $EVAL_ERROR;
c80a0905	164	next if !$config;
e967a60f	165	delete $files{$filename};
e967a60f	166	# warn "loader $loader loaded file $filename\n";
c80a0905	167	$filter_cb->( $config ) if defined $filter_cb;
	168	push @$final_configs, { $filename => $config };
	169	}
	170	}
	171	$final_configs;
	172	}
	173
59a80452	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
c80a0905	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
59a80452	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
c80a0905	199	sub plugins {
	200	my $class = shift;
	201	return $class->finder->plugins;
	202	}
	203
59a80452	204	=head2 extensions( )
c80a0905	205
59a80452	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.
c80a0905	209
59a80452	210	=cut
c80a0905	211
59a80452	212	sub extensions {
	213	my $class = shift;
	214	my @ext = map { $_->extensions } $class->plugins;
	215	return wantarray ? @ext : [@ext];
	216	}
c80a0905	217
	218	=head1 DIAGNOSTICS
	219
c80a0905	220	=over
c80a0905	221
59a80452	222	=item C<no files specified> or C<no stems specified>
c80a0905	223
59a80452	224	The C<load_files()> and C<load_stems()> methods will issue this warning if
59a80452	225	called with an empty list of files/stems to load.
c80a0905	226
59a80452	227	=item C<_load requires a arrayref of file paths>
c80a0905	228
59a80452	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.
c80a0905	232
	233	=back
	234
c80a0905	235	=head1 CONFIGURATION AND ENVIRONMENT
c80a0905	236
c80a0905	237	Config::Any requires no configuration files or environment variables.
c80a0905	238
c80a0905	239	=head1 DEPENDENCIES
c80a0905	240
59a80452	241	L<Module::Pluggable\|Module::Pluggable>
c80a0905	242
59a80452	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>
c80a0905	251
	252	=head1 INCOMPATIBILITIES
	253
c80a0905	254	None reported.
c80a0905	255
c80a0905	256	=head1 BUGS AND LIMITATIONS
c80a0905	257
c80a0905	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
c80a0905	264	=head1 AUTHOR
	265
	266	Joel Bernstein C<< <rataxis@cpan.org> >>
	267
59a80452	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> >>.
c80a0905	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
c80a0905	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.
59a80452	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