Commit | Line | Data |
f0e3c221 |
1 | NAME |
2 | Config::Any - Load configuration from different file formats, |
3 | transparently |
c80a0905 |
4 | |
f0e3c221 |
5 | VERSION |
6 | This document describes Config::Any version 0.0.7 |
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( ) |
38 | Config::Any->load_files({files => \@files]}); |
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 | |
64 | load_stems( ) |
65 | Config::Any->load_stems({stems => \@stems]}); |
66 | Config::Any->load_stems({stems => \@stems, filter => \&filter}); |
67 | Config::Any->load_stems({stems => \@stems, use_ext => 1}); |
68 | |
69 | "load_stems()" attempts to load configuration from a list of files which |
70 | it generates by combining the filename stems list passed in the "stems" |
71 | parameter with the potential filename extensions from each loader, which |
72 | you can check with the "extensions()" classmethod described below. Once |
73 | this list of possible filenames is built it is treated exactly as in |
74 | "load_files()" above, as which it takes the same parameters. Please read |
75 | the "load_files()" documentation before using this method. |
76 | |
77 | finder( ) |
78 | The "finder()" classmethod returns the Module::Pluggable::Object object |
79 | which is used to load the plugins. See the documentation for that module |
80 | for more information. |
81 | |
82 | plugins( ) |
83 | The "plugins()" classmethod returns the names of configuration loading |
84 | plugins as found by Module::Pluggable::Object. |
85 | |
86 | extensions( ) |
87 | The "extensions()" classmethod returns the possible file extensions |
88 | which can be loaded by "load_stems()" and "load_files()". This may be |
89 | useful if you set the "use_ext" parameter to those methods. |
90 | |
91 | DIAGNOSTICS |
92 | "no files specified" or "no stems specified" |
93 | The "load_files()" and "load_stems()" methods will issue this |
94 | warning if called with an empty list of files/stems to load. |
95 | |
96 | "_load requires a arrayref of file paths" |
97 | This fatal error will be thrown by the internal "_load" method. It |
98 | should not occur but is specified here for completeness. If your |
99 | code dies with this error, please email a failing test case to the |
100 | authors below. |
101 | |
102 | CONFIGURATION AND ENVIRONMENT |
103 | Config::Any requires no configuration files or environment variables. |
c80a0905 |
104 | |
105 | DEPENDENCIES |
f0e3c221 |
106 | Module::Pluggable |
107 | |
108 | And at least one of the following: Config::General Config::Tiny JSON |
109 | YAML JSON::Syck YAML::Syck XML::Simple |
110 | |
111 | INCOMPATIBILITIES |
112 | None reported. |
113 | |
114 | BUGS AND LIMITATIONS |
115 | No bugs have been reported. |
116 | |
117 | Please report any bugs or feature requests to |
118 | "bug-config-any@rt.cpan.org", or through the web interface at |
119 | <http://rt.cpan.org>. |
120 | |
121 | AUTHOR |
122 | Joel Bernstein <rataxis@cpan.org> |
123 | |
124 | CONTRIBUTORS |
125 | This module was based on the original Catalyst::Plugin::ConfigLoader |
126 | module by Brian Cassidy "<bricas@cpan.org>". |
127 | |
128 | With ideas and support from Matt S Trout "<mst@shadowcatsystems.co.uk>". |
129 | |
130 | Further enhancements suggested by Evan Kaufman "<evank@cpan.org>". |
131 | |
132 | LICENCE AND COPYRIGHT |
133 | Copyright (c) 2006, Portugal Telecom "http://www.sapo.pt/". All rights |
134 | reserved. Portions copyright 2007, Joel Bernstein "<rataxis@cpan.org>". |
c80a0905 |
135 | |
f0e3c221 |
136 | This module is free software; you can redistribute it and/or modify it |
137 | under the same terms as Perl itself. See perlartistic. |
c80a0905 |
138 | |
f0e3c221 |
139 | DISCLAIMER OF WARRANTY |
140 | BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY |
141 | FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN |
142 | OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES |
143 | PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER |
144 | EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED |
145 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE |
146 | ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH |
147 | YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL |
148 | NECESSARY SERVICING, REPAIR, OR CORRECTION. |
c80a0905 |
149 | |
f0e3c221 |
150 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING |
151 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR |
152 | REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE |
153 | TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR |
154 | CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE |
155 | SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING |
156 | RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A |
157 | FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF |
158 | SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH |
159 | DAMAGES. |
c80a0905 |
160 | |
f0e3c221 |
161 | SEE ALSO |
162 | Catalyst::Plugin::ConfigLoader -- now a wrapper around this module. |
c80a0905 |
163 | |