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