X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit%2FConfig-Any.git;a=blobdiff_plain;f=README;h=cef91054fc3731db26054d45fcc4d6f2eeeab7ef;hp=3d80d7ef5f64225ab9f395c09a7993567b761349;hb=f0e3c2214342d0d8a8839009b8b9c7e6bfbc7ab2;hpb=e17d1736c6f94fcf7b5a1f395eaac6ead5882f6c diff --git a/README b/README index 3d80d7e..cef9105 100644 --- a/README +++ b/README @@ -1,26 +1,163 @@ -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 + . + +AUTHOR + Joel Bernstein + +CONTRIBUTORS + This module was based on the original Catalyst::Plugin::ConfigLoader + module by Brian Cassidy "". + + With ideas and support from Matt S Trout "". + + Further enhancements suggested by Evan Kaufman "". + +LICENCE AND COPYRIGHT + Copyright (c) 2006, Portugal Telecom "http://www.sapo.pt/". All rights + reserved. Portions copyright 2007, Joel Bernstein "". -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.