-Config-Any version 0.0.4
+NAME
+ Config::Any - Load configuration from different file formats,
+ transparently
-This module generalises loading class configuration data from a number of different
-file formats.
+VERSION
+ This document describes Config::Any version 0.0.7
-INSTALLATION
+SYNOPSIS
+ use Config::Any;
-To install this module, run the following commands:
- perl Build.PL
- ./Build
- ./Build test
- ./Build install
+ 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";
+ }
+
+DESCRIPTION
+ 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.
+
+INTERFACE
+ 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});
+
+ "load_files()" attempts to load configuration from the list of files
+ passed in the "files" parameter, if the file exists.
+
+ If the "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 "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 "myapp.cfg" containing
+ YAML data will not be offered to the YAML plugin, whereas "myapp.yml" or
+ "myapp.yaml" would be.
+
+ "load_files()" also supports a 'force_plugins' parameter, whose value
+ should be an arrayref of plugin names like "Config::Any::INI". 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'.
+
+ 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});
+
+ "load_stems()" attempts to load configuration from a list of files which
+ it generates by combining the filename stems list passed in the "stems"
+ parameter with the potential filename extensions from each loader, which
+ you can check with the "extensions()" classmethod described below. Once
+ this list of possible filenames is built it is treated exactly as in
+ "load_files()" above, as which it takes the same parameters. Please read
+ the "load_files()" documentation before using this method.
+
+ finder( )
+ The "finder()" classmethod returns the Module::Pluggable::Object object
+ which is used to load the plugins. See the documentation for that module
+ for more information.
+
+ plugins( )
+ The "plugins()" classmethod returns the names of configuration loading
+ plugins as found by Module::Pluggable::Object.
+
+ extensions( )
+ The "extensions()" classmethod returns the possible file extensions
+ which can be loaded by "load_stems()" and "load_files()". This may be
+ useful if you set the "use_ext" parameter to those methods.
+
+DIAGNOSTICS
+ "no files specified" or "no stems specified"
+ The "load_files()" and "load_stems()" methods will issue this
+ warning if called with an empty list of files/stems to load.
+
+ "_load requires a arrayref of file paths"
+ This fatal error will be thrown by the internal "_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.
+
+CONFIGURATION AND ENVIRONMENT
+ Config::Any requires no configuration files or environment variables.
DEPENDENCIES
+ Module::Pluggable
+
+ And at least one of the following: Config::General Config::Tiny JSON
+ YAML JSON::Syck YAML::Syck XML::Simple
+
+INCOMPATIBILITIES
+ None reported.
+
+BUGS AND LIMITATIONS
+ No bugs have been reported.
+
+ Please report any bugs or feature requests to
+ "bug-config-any@rt.cpan.org", or through the web interface at
+ <http://rt.cpan.org>.
+
+AUTHOR
+ Joel Bernstein <rataxis@cpan.org>
+
+CONTRIBUTORS
+ This module was based on the original Catalyst::Plugin::ConfigLoader
+ module by Brian Cassidy "<bricas@cpan.org>".
+
+ With ideas and support from Matt S Trout "<mst@shadowcatsystems.co.uk>".
+
+ Further enhancements suggested by Evan Kaufman "<evank@cpan.org>".
+
+LICENCE AND COPYRIGHT
+ Copyright (c) 2006, Portugal Telecom "http://www.sapo.pt/". All rights
+ reserved. Portions copyright 2007, Joel Bernstein "<rataxis@cpan.org>".
-Module::Pluggable >= 3.01
+ This module is free software; you can redistribute it and/or modify it
+ under the same terms as Perl itself. See perlartistic.
-COPYRIGHT AND LICENCE
+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.
-The development of this module was sponsored by SAPO, a division of Portugal Telecom.
+ 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.
-Copyright (C) 2006, Portugal Telecom
+SEE ALSO
+ Catalyst::Plugin::ConfigLoader -- now a wrapper around this module.
-This library is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself.
projects / p5sagit/Config-Any.git / blobdiff