local-lib5/man/man3/Config::Any.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Config::Any 3"
 132 .TH Config::Any 3 "2009-07-21" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Config::Any \- Load configuration from different file formats, transparently
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&    use Config::Any;
 139 .Ve
 140 .PP
 141 .Vb 3
 142 \&    my $cfg = Config::Any\->load_stems({stems => \e@filepath_stems, ... });
 143 \&    # or
 144 \&    my $cfg = Config::Any\->load_files({files => \e@filepaths, ... });
 145 .Ve
 146 .PP
 147 .Vb 5
 148 \&    for (@$cfg) {
 149 \&        my ($filename, $config) = %$_;
 150 \&        $class\->config($config);
 151 \&        warn "loaded config from file: $filename";
 152 \&    }
 153 .Ve
 154 .SH "DESCRIPTION"
 155 .IX Header "DESCRIPTION"
 156 Config::Any provides a facility for Perl applications and libraries
 157 to load configuration data from multiple different file formats. It supports \s-1XML\s0, \s-1YAML\s0,
 158 \&\s-1JSON\s0, Apache-style configuration, Windows \s-1INI\s0 files, and even Perl code.
 159 .PP
 160 The rationale for this module is as follows: Perl programs are deployed on many different
 161 platforms and integrated with many different systems. Systems administrators and end
 162 users may prefer different configuration formats than the developers. The flexibility
 163 inherent in a multiple format configuration loader allows different users to make
 164 different choices, without generating extra work for the developers. As a developer
 165 you only need to learn a single interface to be able to use the power of different
 166 configuration formats.
 167 .SH "INTERFACE"
 168 .IX Header "INTERFACE"
 169 .Sh "load_files( \e%args )"
 170 .IX Subsection "load_files( %args )"
 171 .Vb 4
 172 \&    Config::Any\->load_files( { files => \e@files } );
 173 \&    Config::Any\->load_files( { files => \e@files, filter  => \e&filter } );
 174 \&    Config::Any\->load_files( { files => \e@files, use_ext => 1 } );
 175 \&    Config::Any\->load_files( { files => \e@files, flatten_to_hash => 1 } );
 176 .Ve
 177 .PP
 178 \&\f(CW\*(C`load_files()\*(C'\fR attempts to load configuration from the list of files passed in
 179 the \f(CW\*(C`files\*(C'\fR parameter, if the file exists.
 180 .PP
 181 If the \f(CW\*(C`filter\*(C'\fR parameter is set, it is used as a callback to modify the configuration
 182 data before it is returned. It will be passed a single hash-reference parameter which
 183 it should modify in\-place.
 184 .PP
 185 If the \f(CW\*(C`use_ext\*(C'\fR parameter is defined, the loader will attempt to parse the file
 186 extension from each filename and will skip the file unless it matches a standard
 187 extension for the loading plugins. Only plugins whose standard extensions match the
 188 file extension will be used. For efficiency reasons, its use is encouraged, but
 189 be aware that you will lose flexibility \*(-- for example, a file called \f(CW\*(C`myapp.cfg\*(C'\fR
 190 containing \s-1YAML\s0 data will not be offered to the \s-1YAML\s0 plugin, whereas \f(CW\*(C`myapp.yml\*(C'\fR
 191 or \f(CW\*(C`myapp.yaml\*(C'\fR would be.
 192 .PP
 193 When the \f(CW\*(C`flatten_to_hash\*(C'\fR parameter is defined, the loader will return a hash
 194 keyed on the file names, as opposed to the usual list of single-key hashes.
 195 .PP
 196 \&\f(CW\*(C`load_files()\*(C'\fR also supports a 'force_plugins' parameter, whose value should be an
 197 arrayref of plugin names like \f(CW\*(C`Config::Any::INI\*(C'\fR. Its intended use is to allow the use
 198 of a non-standard file extension while forcing it to be offered to a particular parser.
 199 It is not compatible with 'use_ext'.
 200 .PP
 201 You can supply a \f(CW\*(C`driver_args\*(C'\fR hashref to pass special options to a particular
 202 parser object. Example:
 203 .PP
 204 .Vb 3
 205 \&    Config::Any\->load_files( { files => \e@files, driver_args => {
 206 \&        General => { \-LowerCaseNames => 1 }
 207 \&    } )
 208 .Ve
 209 .Sh "load_stems( \e%args )"
 210 .IX Subsection "load_stems( %args )"
 211 .Vb 4
 212 \&    Config::Any\->load_stems( { stems => \e@stems } );
 213 \&    Config::Any\->load_stems( { stems => \e@stems, filter  => \e&filter } );
 214 \&    Config::Any\->load_stems( { stems => \e@stems, use_ext => 1 } );
 215 \&    Config::Any\->load_stems( { stems => \e@stems, flatten_to_hash => 1 } );
 216 .Ve
 217 .PP
 218 \&\f(CW\*(C`load_stems()\*(C'\fR attempts to load configuration from a list of files which it generates
 219 by combining the filename stems list passed in the \f(CW\*(C`stems\*(C'\fR parameter with the
 220 potential filename extensions from each loader, which you can check with the
 221 \&\f(CW\*(C`extensions()\*(C'\fR classmethod described below. Once this list of possible filenames is
 222 built it is treated exactly as in \f(CW\*(C`load_files()\*(C'\fR above, as which it takes the same
 223 parameters. Please read the \f(CW\*(C`load_files()\*(C'\fR documentation before using this method.
 224 .Sh "finder( )"
 225 .IX Subsection "finder( )"
 226 The \f(CW\*(C`finder()\*(C'\fR classmethod returns the
 227 Module::Pluggable::Object
 228 object which is used to load the plugins. See the documentation for that module for
 229 more information.
 230 .Sh "plugins( )"
 231 .IX Subsection "plugins( )"
 232 The \f(CW\*(C`plugins()\*(C'\fR classmethod returns the names of configuration loading plugins as
 233 found by Module::Pluggable::Object.
 234 .Sh "extensions( )"
 235 .IX Subsection "extensions( )"
 236 The \f(CW\*(C`extensions()\*(C'\fR classmethod returns the possible file extensions which can be loaded
 237 by \f(CW\*(C`load_stems()\*(C'\fR and \f(CW\*(C`load_files()\*(C'\fR. This may be useful if you set the \f(CW\*(C`use_ext\*(C'\fR
 238 parameter to those methods.
 239 .SH "DIAGNOSTICS"
 240 .IX Header "DIAGNOSTICS"
 241 .ie n .IP """No files specified!""\fR or \f(CW""No stems specified!""" 4
 242 .el .IP "\f(CWNo files specified!\fR or \f(CWNo stems specified!\fR" 4
 243 .IX Item "No files specified! or No stems specified!"
 244 The \f(CW\*(C`load_files()\*(C'\fR and \f(CW\*(C`load_stems()\*(C'\fR methods will issue this warning if
 245 called with an empty list of files/stems to load.
 246 .ie n .IP """_load requires a arrayref of file paths""" 4
 247 .el .IP "\f(CW_load requires a arrayref of file paths\fR" 4
 248 .IX Item "_load requires a arrayref of file paths"
 249 This fatal error will be thrown by the internal \f(CW\*(C`_load\*(C'\fR method. It should not occur
 250 but is specified here for completeness. If your code dies with this error, please
 251 email a failing test case to the authors below.
 252 .SH "CONFIGURATION AND ENVIRONMENT"
 253 .IX Header "CONFIGURATION AND ENVIRONMENT"
 254 Config::Any requires no configuration files or environment variables.
 255 .SH "DEPENDENCIES"
 256 .IX Header "DEPENDENCIES"
 257 Module::Pluggable
 258 .PP
 259 And at least one of the following:
 260 Config::General
 261 Config::Tiny
 262 \&\s-1JSON\s0
 263 \&\s-1YAML\s0
 264 JSON::Syck
 265 YAML::Syck
 266 XML::Simple
 267 .SH "INCOMPATIBILITIES"
 268 .IX Header "INCOMPATIBILITIES"
 269 None reported.
 270 .SH "BUGS AND LIMITATIONS"
 271 .IX Header "BUGS AND LIMITATIONS"
 272 No bugs have been reported.
 273 .PP
 274 Please report any bugs or feature requests to
 275 \&\f(CW\*(C`bug\-config\-any@rt.cpan.org\*(C'\fR, or through the web interface at
 276 <http://rt.cpan.org>.
 277 .SH "AUTHOR"
 278 .IX Header "AUTHOR"
 279 Joel Bernstein <rataxis@cpan.org>
 280 .SH "CONTRIBUTORS"
 281 .IX Header "CONTRIBUTORS"
 282 This module was based on the original
 283 Catalyst::Plugin::ConfigLoader
 284 module by Brian Cassidy \f(CW\*(C`<bricas@cpan.org>\*(C'\fR.
 285 .PP
 286 With ideas and support from Matt S Trout \f(CW\*(C`<mst@shadowcatsystems.co.uk>\*(C'\fR.
 287 .PP
 288 Further enhancements suggested by Evan Kaufman \f(CW\*(C`<evank@cpan.org>\*(C'\fR.
 289 .SH "LICENCE AND COPYRIGHT"
 290 .IX Header "LICENCE AND COPYRIGHT"
 291 Copyright (c) 2006, Portugal Telecom \f(CW\*(C`http://www.sapo.pt/\*(C'\fR. All rights reserved.
 292 Portions copyright 2007, Joel Bernstein \f(CW\*(C`<rataxis@cpan.org>\*(C'\fR.
 293 .PP
 294 This module is free software; you can redistribute it and/or
 295 modify it under the same terms as Perl itself. See perlartistic.
 296 .SH "DISCLAIMER OF WARRANTY"
 297 .IX Header "DISCLAIMER OF WARRANTY"
 298 \&\s-1BECAUSE\s0 \s-1THIS\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1LICENSED\s0 \s-1FREE\s0 \s-1OF\s0 \s-1CHARGE\s0, \s-1THERE\s0 \s-1IS\s0 \s-1NO\s0 \s-1WARRANTY\s0
 299 \&\s-1FOR\s0 \s-1THE\s0 \s-1SOFTWARE\s0, \s-1TO\s0 \s-1THE\s0 \s-1EXTENT\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0. \s-1EXCEPT\s0 \s-1WHEN\s0
 300 \&\s-1OTHERWISE\s0 \s-1STATED\s0 \s-1IN\s0 \s-1WRITING\s0 \s-1THE\s0 \s-1COPYRIGHT\s0 \s-1HOLDERS\s0 \s-1AND/OR\s0 \s-1OTHER\s0 \s-1PARTIES\s0
 301 \&\s-1PROVIDE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \*(L"\s-1AS\s0 \s-1IS\s0\*(R" \s-1WITHOUT\s0 \s-1WARRANTY\s0 \s-1OF\s0 \s-1ANY\s0 \s-1KIND\s0, \s-1EITHER\s0
 302 \&\s-1EXPRESSED\s0 \s-1OR\s0 \s-1IMPLIED\s0, \s-1INCLUDING\s0, \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0, \s-1THE\s0 \s-1IMPLIED\s0
 303 \&\s-1WARRANTIES\s0 \s-1OF\s0 \s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. \s-1THE\s0
 304 \&\s-1ENTIRE\s0 \s-1RISK\s0 \s-1AS\s0 \s-1TO\s0 \s-1THE\s0 \s-1QUALITY\s0 \s-1AND\s0 \s-1PERFORMANCE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1WITH\s0
 305 \&\s-1YOU\s0. \s-1SHOULD\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1PROVE\s0 \s-1DEFECTIVE\s0, \s-1YOU\s0 \s-1ASSUME\s0 \s-1THE\s0 \s-1COST\s0 \s-1OF\s0 \s-1ALL\s0
 306 \&\s-1NECESSARY\s0 \s-1SERVICING\s0, \s-1REPAIR\s0, \s-1OR\s0 \s-1CORRECTION\s0.
 307 .PP
 308 \&\s-1IN\s0 \s-1NO\s0 \s-1EVENT\s0 \s-1UNLESS\s0 \s-1REQUIRED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0 \s-1OR\s0 \s-1AGREED\s0 \s-1TO\s0 \s-1IN\s0 \s-1WRITING\s0
 309 \&\s-1WILL\s0 \s-1ANY\s0 \s-1COPYRIGHT\s0 \s-1HOLDER\s0, \s-1OR\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1WHO\s0 \s-1MAY\s0 \s-1MODIFY\s0 \s-1AND/OR\s0
 310 \&\s-1REDISTRIBUTE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1AS\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1THE\s0 \s-1ABOVE\s0 \s-1LICENCE\s0, \s-1BE\s0
 311 \&\s-1LIABLE\s0 \s-1TO\s0 \s-1YOU\s0 \s-1FOR\s0 \s-1DAMAGES\s0, \s-1INCLUDING\s0 \s-1ANY\s0 \s-1GENERAL\s0, \s-1SPECIAL\s0, \s-1INCIDENTAL\s0,
 312 \&\s-1OR\s0 \s-1CONSEQUENTIAL\s0 \s-1DAMAGES\s0 \s-1ARISING\s0 \s-1OUT\s0 \s-1OF\s0 \s-1THE\s0 \s-1USE\s0 \s-1OR\s0 \s-1INABILITY\s0 \s-1TO\s0 \s-1USE\s0
 313 \&\s-1THE\s0 \s-1SOFTWARE\s0 (\s-1INCLUDING\s0 \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0 \s-1LOSS\s0 \s-1OF\s0 \s-1DATA\s0 \s-1OR\s0 \s-1DATA\s0 \s-1BEING\s0
 314 \&\s-1RENDERED\s0 \s-1INACCURATE\s0 \s-1OR\s0 \s-1LOSSES\s0 \s-1SUSTAINED\s0 \s-1BY\s0 \s-1YOU\s0 \s-1OR\s0 \s-1THIRD\s0 \s-1PARTIES\s0 \s-1OR\s0 A
 315 \&\s-1FAILURE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1TO\s0 \s-1OPERATE\s0 \s-1WITH\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1SOFTWARE\s0), \s-1EVEN\s0 \s-1IF\s0
 316 \&\s-1SUCH\s0 \s-1HOLDER\s0 \s-1OR\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1HAS\s0 \s-1BEEN\s0 \s-1ADVISED\s0 \s-1OF\s0 \s-1THE\s0 \s-1POSSIBILITY\s0 \s-1OF\s0
 317 \&\s-1SUCH\s0 \s-1DAMAGES\s0.
 318 .SH "SEE ALSO"
 319 .IX Header "SEE ALSO"
 320 Catalyst::Plugin::ConfigLoader
 321 \&\*(-- now a wrapper around this module.