Config::Any(3pm)

1Config::Any(3)        User Contributed Perl Documentation       Config::Any(3)
2
3
4

NAME

6       Config::Any - Load configuration from different file formats,
7       transparently
8

SYNOPSIS

10           use Config::Any;
11
12           my $cfg = Config::Any->load_stems({stems => \@filepath_stems, ... });
13           # or
14           my $cfg = Config::Any->load_files({files => \@filepaths, ... });
15
16           for (@$cfg) {
17               my ($filename, $config) = %$_;
18               $class->config($config);
19               warn "loaded config from file: $filename";
20           }
21

DESCRIPTION

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
28       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

INTERFACE

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
44       load_files() attempts to load configuration from the list of files
45       passed in the "files" parameter, if the file exists.
46
47       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
51       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
60       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
64       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
70       You can supply a "driver_args" hashref to pass special options to a
71       particular parser object. Example:
72
73           Config::Any->load_files( { files => \@files, driver_args => {
74               General => { -LowerCaseNames => 1 }
75           } )
76
77   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
83       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
91   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
96   plugins( )
97       The plugins() classmethod returns the names of configuration loading
98       plugins as found by Module::Pluggable::Object.
99
100   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

DIAGNOSTICS

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
110       "_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

CONFIGURATION AND ENVIRONMENT

117       Config::Any requires no configuration files or environment variables.
118

DEPENDENCIES

120       Module::Pluggable::Object
121
122       And at least one of the following: Config::General Config::Tiny JSON
123       YAML JSON::Syck YAML::Syck XML::Simple
124

INCOMPATIBILITIES

126       None reported.
127

BUGS AND LIMITATIONS

129       No bugs have been reported.
130
131       Please report any bugs or feature requests to
132       "bug-config-any@rt.cpan.org", or through the web interface at
133       <https://rt.cpan.org/Public/Dist/Display.html?Name=Config-Any>.
134

AUTHOR

136       Joel Bernstein <rataxis@cpan.org>
137

CONTRIBUTORS

139       This module was based on the original Catalyst::Plugin::ConfigLoader
140       module by Brian Cassidy "<bricas@cpan.org>".
141
142       With ideas and support from Matt S Trout
143       "<mst@shadowcatsystems.co.uk>".
144
145       Further enhancements suggested by Evan Kaufman "<evank@cpan.org>".
146

LICENCE AND COPYRIGHT

148       Copyright (c) 2006, Portugal Telecom "http://www.sapo.pt/". All rights
149       reserved.  Portions copyright 2007, Joel Bernstein
150       "<rataxis@cpan.org>".
151
152       This module is free software; you can redistribute it and/or modify it
153       under the same terms as Perl itself. See perlartistic.
154

DISCLAIMER OF WARRANTY

156       BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
157       FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
158       WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
159       PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
160       EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
161       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
162       ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
163       YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
164       NECESSARY SERVICING, REPAIR, OR CORRECTION.
165
166       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
167       WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
168       REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
169       TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
170       CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
171       SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
172       RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
173       FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
174       SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
175       DAMAGES.
176