| 1 |
NAME |
| 2 |
Config::Any - Load configuration from different file formats, |
| 3 |
transparently |
| 4 |
|
| 5 |
SYNOPSIS |
| 6 |
use Config::Any; |
| 7 |
|
| 8 |
my $cfg = Config::Any->load_stems({stems => \@filepath_stems, ... }); |
| 9 |
# or |
| 10 |
my $cfg = Config::Any->load_files({files => \@filepaths, ... }); |
| 11 |
|
| 12 |
for (@$cfg) { |
| 13 |
my ($filename, $config) = %$_; |
| 14 |
$class->config($config); |
| 15 |
warn "loaded config from file: $filename"; |
| 16 |
} |
| 17 |
|
| 18 |
DESCRIPTION |
| 19 |
Config::Any provides a facility for Perl applications and libraries to |
| 20 |
load configuration data from multiple different file formats. It |
| 21 |
supports XML, YAML, JSON, Apache-style configuration, Windows INI files, |
| 22 |
and even Perl code. |
| 23 |
|
| 24 |
The rationale for this module is as follows: Perl programs are deployed |
| 25 |
on many different platforms and integrated with many different systems. |
| 26 |
Systems administrators and end users may prefer different configuration |
| 27 |
formats than the developers. The flexibility inherent in a multiple |
| 28 |
format configuration loader allows different users to make different |
| 29 |
choices, without generating extra work for the developers. As a |
| 30 |
developer you only need to learn a single interface to be able to use |
| 31 |
the power of different configuration formats. |
| 32 |
|
| 33 |
INTERFACE |
| 34 |
load_files( \%args ) |
| 35 |
Config::Any->load_files( { files => \@files } ); |
| 36 |
Config::Any->load_files( { files => \@files, filter => \&filter } ); |
| 37 |
Config::Any->load_files( { files => \@files, use_ext => 1 } ); |
| 38 |
Config::Any->load_files( { files => \@files, flatten_to_hash => 1 } ); |
| 39 |
|
| 40 |
load_files() attempts to load configuration from the list of files |
| 41 |
passed in the "files" parameter, if the file exists. |
| 42 |
|
| 43 |
If the "filter" parameter is set, it is used as a callback to modify the |
| 44 |
configuration data before it is returned. It will be passed a single |
| 45 |
hash-reference parameter which it should modify in-place. |
| 46 |
|
| 47 |
If the "use_ext" parameter is defined, the loader will attempt to parse |
| 48 |
the file extension from each filename and will skip the file unless it |
| 49 |
matches a standard extension for the loading plugins. Only plugins whose |
| 50 |
standard extensions match the file extension will be used. For |
| 51 |
efficiency reasons, its use is encouraged, but be aware that you will |
| 52 |
lose flexibility -- for example, a file called "myapp.cfg" containing |
| 53 |
YAML data will not be offered to the YAML plugin, whereas "myapp.yml" or |
| 54 |
"myapp.yaml" would be. |
| 55 |
|
| 56 |
When the "flatten_to_hash" parameter is defined, the loader will return |
| 57 |
a hash keyed on the file names, as opposed to the usual list of |
| 58 |
single-key hashes. |
| 59 |
|
| 60 |
load_files() also supports a 'force_plugins' parameter, whose value |
| 61 |
should be an arrayref of plugin names like "Config::Any::INI". Its |
| 62 |
intended use is to allow the use of a non-standard file extension while |
| 63 |
forcing it to be offered to a particular parser. It is not compatible |
| 64 |
with 'use_ext'. |
| 65 |
|
| 66 |
You can supply a "driver_args" hashref to pass special options to a |
| 67 |
particular parser object. Example: |
| 68 |
|
| 69 |
Config::Any->load_files( { files => \@files, driver_args => { |
| 70 |
General => { -LowerCaseNames => 1 } |
| 71 |
} ) |
| 72 |
|
| 73 |
load_stems( \%args ) |
| 74 |
Config::Any->load_stems( { stems => \@stems } ); |
| 75 |
Config::Any->load_stems( { stems => \@stems, filter => \&filter } ); |
| 76 |
Config::Any->load_stems( { stems => \@stems, use_ext => 1 } ); |
| 77 |
Config::Any->load_stems( { stems => \@stems, flatten_to_hash => 1 } ); |
| 78 |
|
| 79 |
load_stems() attempts to load configuration from a list of files which |
| 80 |
it generates by combining the filename stems list passed in the "stems" |
| 81 |
parameter with the potential filename extensions from each loader, which |
| 82 |
you can check with the extensions() classmethod described below. Once |
| 83 |
this list of possible filenames is built it is treated exactly as in |
| 84 |
load_files() above, as which it takes the same parameters. Please read |
| 85 |
the load_files() documentation before using this method. |
| 86 |
|
| 87 |
finder( ) |
| 88 |
The finder() classmethod returns the Module::Pluggable::Object object |
| 89 |
which is used to load the plugins. See the documentation for that module |
| 90 |
for more information. |
| 91 |
|
| 92 |
plugins( ) |
| 93 |
The plugins() classmethod returns the names of configuration loading |
| 94 |
plugins as found by Module::Pluggable::Object. |
| 95 |
|
| 96 |
extensions( ) |
| 97 |
The extensions() classmethod returns the possible file extensions which |
| 98 |
can be loaded by load_stems() and load_files(). This may be useful if |
| 99 |
you set the "use_ext" parameter to those methods. |
| 100 |
|
| 101 |
DIAGNOSTICS |
| 102 |
"No files specified!" or "No stems specified!" |
| 103 |
The load_files() and load_stems() methods will issue this warning if |
| 104 |
called with an empty list of files/stems to load. |
| 105 |
|
| 106 |
"_load requires a arrayref of file paths" |
| 107 |
This fatal error will be thrown by the internal "_load" method. It |
| 108 |
should not occur but is specified here for completeness. If your |
| 109 |
code dies with this error, please email a failing test case to the |
| 110 |
authors below. |
| 111 |
|
| 112 |
CONFIGURATION AND ENVIRONMENT |
| 113 |
Config::Any requires no configuration files or environment variables. |
| 114 |
|
| 115 |
DEPENDENCIES |
| 116 |
Module::Pluggable::Object |
| 117 |
|
| 118 |
And at least one of the following for each file type to be supported: |
| 119 |
|
| 120 |
* For ".cnf", ".conf" files: Config::General |
| 121 |
|
| 122 |
* For ".ini" files: Config::Tiny |
| 123 |
|
| 124 |
* For ".json", ".jsn" files: Cpanel::JSON::XS, JSON::MaybeXS, |
| 125 |
JSON::DWIW, JSON::XS, JSON::Syck, JSON::PP, JSON |
| 126 |
|
| 127 |
* For ".pl", ".perl" files: no additional requirements |
| 128 |
|
| 129 |
* For ".xml" files: XML::Simple |
| 130 |
|
| 131 |
* For ".yml", ".yaml" files: YAML::XS, YAML::Syck, YAML |
| 132 |
|
| 133 |
Additionally, other file types are supported by third-party plugins in |
| 134 |
the "Config::Any::" namespace, installed separately. |
| 135 |
|
| 136 |
BUGS AND LIMITATIONS |
| 137 |
Please report any bugs or feature requests to |
| 138 |
"[email protected]", or through the web interface at |
| 139 |
<https://rt.cpan.org/Public/Dist/Display.html?Name=Config-Any>. |
| 140 |
|
| 141 |
AUTHOR |
| 142 |
Joel Bernstein <[email protected]> |
| 143 |
|
| 144 |
CONTRIBUTORS |
| 145 |
This module was based on the original Catalyst::Plugin::ConfigLoader |
| 146 |
module by Brian Cassidy "<[email protected]>". |
| 147 |
|
| 148 |
With ideas and support from Matt S Trout "<[email protected]>". |
| 149 |
|
| 150 |
Further enhancements suggested by Evan Kaufman "<[email protected]>". |
| 151 |
|
| 152 |
LICENCE AND COPYRIGHT |
| 153 |
Copyright (c) 2006, Portugal Telecom "http://www.sapo.pt/". All rights |
| 154 |
reserved. Portions copyright 2007, Joel Bernstein "<[email protected]>". |
| 155 |
|
| 156 |
This module is free software; you can redistribute it and/or modify it |
| 157 |
under the same terms as Perl itself. See perlartistic. |
| 158 |
|
| 159 |
DISCLAIMER OF WARRANTY |
| 160 |
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY |
| 161 |
FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN |
| 162 |
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES |
| 163 |
PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER |
| 164 |
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED |
| 165 |
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE |
| 166 |
ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH |
| 167 |
YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL |
| 168 |
NECESSARY SERVICING, REPAIR, OR CORRECTION. |
| 169 |
|
| 170 |
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING |
| 171 |
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR |
| 172 |
REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE |
| 173 |
TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR |
| 174 |
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE |
| 175 |
SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING |
| 176 |
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A |
| 177 |
FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF |
| 178 |
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH |
| 179 |
DAMAGES. |
| 180 |
|
| 181 |
SEE ALSO |
| 182 |
Catalyst::Plugin::ConfigLoader -- now a wrapper around this module. |
| 183 |
|