+++ /dev/null
-NAME
- Config::Any - Load configuration from different file formats,
- transparently
-
-VERSION
- This document describes Config::Any version 0.0.8
-
-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";
- }
-
-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'.
-
- You can supply a "driver_args" hashref to pass special options to a
- particular parser object. Example:
-
- Config::Any->load_files( { files => \@files, driver_args => {
- General => { -LowerCaseNames => 1 }
- } )
-
- 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>".
-
- This module is free software; you can redistribute it and/or modify it
- under the same terms as Perl itself. See perlartistic.
-
-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.
-
-SEE ALSO
- Catalyst::Plugin::ConfigLoader -- now a wrapper around this module.
-
projects / p5sagit/Config-Any.git / commitdiff