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