Config::JFDI(3pm)

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

6       Config::JFDI - Just * Do it: A Catalyst::Plugin::ConfigLoader-style
7       layer over Config::Any
8

10       Version 0.064
11

13           use Config::JFDI;
14
15           my $config = Config::JFDI->new(name => "my_application", path => "path/to/my/application");
16           my $config_hash = $config->get;
17
18       This will look for something like (depending on what Config::Any will
19       find):
20
21           path/to/my/application/my_application_local.{yml,yaml,cnf,conf,jsn,json,...} AND
22
23           path/to/my/application/my_application.{yml,yaml,cnf,conf,jsn,json,...}
24
25       ... and load the found configuration information appropiately, with
26       _local taking precedence.
27
28       You can also specify a file directly:
29
30           my $config = Config::JFDI->new(file => "/path/to/my/application/my_application.cnf");
31
32       To later reload your configuration, fresh from disk:
33
34           $config->reload;
35

37       Config::JFDI is an implementation of Catalyst::Plugin::ConfigLoader
38       that exists outside of Catalyst.
39
40       Essentially, Config::JFDI will scan a directory for files matching a
41       certain name. If such a file is found which also matches an extension
42       that Config::Any can read, then the configuration from that file will
43       be loaded.
44
45       Config::JFDI will also look for special files that end with a "_local"
46       suffix. Files with this special suffix will take precedence over any
47       other existing configuration file, if any. The precedence takes place
48       by merging the local configuration with the "standard" configuration
49       via Hash::Merge::Simple.
50
51       Finally, you can override/modify the path search from outside your
52       application, by setting the <NAME>_CONFIG variable outside your
53       application (where <NAME> is the uppercase version of what you passed
54       to Config::JFDI->new).
55

57       We are currently kicking around ideas for a next-generation
58       configuration loader. The goals are:
59
60           * A universal platform for configuration slurping and post-processing
61           * Use Config::Any to do configuration loading
62           * A sane API so that developers can roll their own loader according to the needs of their application
63           * A friendly interface so that users can have it just DWIM
64           * Host/application/instance specific configuration via _local and %ENV
65
66       Find more information and contribute at:
67
68       Roadmap: <http://sites.google.com/site/configloader/>
69
70       Mailing list:
71       http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/config-loader
72       <http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/config-loader>
73

75       In previous versions, Config::JFDI would treat the file parameter as a
76       path parameter, stripping off the extension (ignoring it) and globbing
77       what remained against all the extensions that Config::Any could
78       provide. That is, it would do this:
79
80           Config::JFDI->new( file => 'xyzzy.cnf' );
81           # Transform 'xyzzy.cnf' into 'xyzzy.pl', 'xyzzy.yaml', 'xyzzy_local.pl', ... (depending on what Config::Any could parse)
82
83       This is probably not what people intended. Config::JFDI will now squeak
84       a warning if you pass 'file' through, but you can suppress the warning
85       with 'no_06_warning' or 'quiet_deprecation'
86
87           Config::JFDI->new( file => 'xyzzy.cnf', no_06_warning => 1 );
88           Config::JFDI->new( file => 'xyzzy.cnf', quiet_deprecation => 1 ); # More general
89
90       If you *do* want the original behavior, simply pass in the file
91       parameter as the path parameter instead:
92
93           Config::JFDI->new( path => 'xyzzy.cnf' ); # Will work as before
94

96   $config = Config::JFDI->new(...)
97       You can configure the $config object by passing the following to new:
98
99           name                The name specifying the prefix of the configuration file to look for and
100                               the ENV variable to read. This can be a package name. In any case,
101                               :: will be substituted with _ in <name> and the result will be lowercased.
102
103                               To prevent modification of <name>, pass it in as a scalar reference.
104
105           path                The directory to search in
106
107           file                Directly read the configuration from this file. Config::Any must recognize
108                               the extension. Setting this will override path
109
110           no_local            Disable lookup of a local configuration. The 'local_suffix' option will be ignored. Off by default
111
112           local_suffix        The suffix to match when looking for a local configuration. "local" By default
113                               ("config_local_suffix" will also work so as to be drop-in compatible with C::P::CL)
114
115           no_env              Set this to 1 to disregard anything in the ENV. The 'env_lookup' option will be ignored. Off by default
116
117           env_lookup          Additional ENV to check if $ENV{<NAME>...} is not found
118
119           driver              A hash consisting of Config:: driver information. This is passed directly through
120                               to Config::Any
121
122           install_accessor    Set this to 1 to install a Catalyst-style accessor as <name>::config
123                               You can also specify the package name directly by setting install_accessor to it
124                               (e.g. install_accessor => "My::Application")
125
126           substitute          A hash consisting of subroutines called during the substitution phase of configuration
127                               preparation. ("substitutions" will also work so as to be drop-in compatible with C::P::CL)
128                               A substitution subroutine has the following signature: ($config, [ $argument1, $argument2, ... ])
129
130           path_to             The path to dir to use for the __path_to(...)__ substitution. If nothing is given, then the 'home'
131                               config value will be used ($config->get->{home}). Failing that, the current directory will be used.
132
133           default             A hash filled with default keys/values
134
135       Returns a new Config::JFDI object
136
137   $config_hash = Config::JFDI->open( ... )
138       As an alternative way to load a config, ->open will pass given
139       arguments to ->new( ... ), then attempt to do ->load
140
141       Unlike ->get or ->load, if no configuration files are found, ->open
142       will return undef (or the empty list)
143
144       This is so you can do something like:
145
146           my $config_hash = Config::JFDI->open( "/path/to/application.cnf" ) or croak "Couldn't find config file!"
147
148       In scalar context, ->open will return the config hash, NOT the config
149       object. If you want the config object, call ->open in list context:
150
151           my ($config_hash, $config) = Config::JFDI->open( ... )
152
153       You can pass any arguments to ->open that you would to ->new
154
155   $config->get
156   $config->config
157   $config->load
158       Load a config as specified by ->new( ... ) and ENV and return a hash
159
160       These will only load the configuration once, so it's safe to call them
161       multiple times without incurring any loading-time penalty
162
163   $config->found
164       Returns a list of files found
165
166       If the list is empty, then no files were loaded/read
167
168   $config->clone
169       Return a clone of the configuration hash using Clone
170
171       This will load the configuration first, if it hasn't already
172
173   $config->reload
174       Reload the configuration, examining ENV and scanning the path anew
175
176       Returns a hash of the configuration
177
178   $config->substitute( <value>, <value>, ... )
179       For each given <value>, if <value> looks like a substitution
180       specification, then run the substitution macro on <value> and store the
181       result.
182
183       There are three default substitutions (the same as
184       Catalyst::Plugin::ConfigLoader)
185
186       ·   "__HOME__" - replaced with "$c->path_to('')"
187
188       ·   "__path_to(foo/bar)__" - replaced with "$c->path_to('foo/bar')"
189
190       ·   "__literal(__FOO__)__" - leaves __FOO__ alone (allows you to use
191           "__DATA__" as a config value, for example)
192
193       The parameter list is split on comma (",").
194
195       You can define your own substitutions by supplying the substitute
196       option to ->new
197

199       Robert Krimen, "<rkrimen at cpan.org>"
200

202       Catalyst::Plugin::ConfigLoader, Config::Any, Catalyst
203

205       You can contribute or fork this project via GitHub:
206
207       http://github.com/robertkrimen/config-jfdi/tree/master
208       <http://github.com/robertkrimen/config-jfdi/tree/master>
209
210           git clone git://github.com/robertkrimen/config-jfdi.git PACKAGE
211

213       Please report any bugs or feature requests to "bug-config-jfdi at
214       rt.cpan.org", or through the web interface at
215       http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Config-JFDI
216       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Config-JFDI>.  I will
217       be notified, and then you'll automatically be notified of progress on
218       your bug as I make changes.
219

221       You can find documentation for this module with the perldoc command.
222
223           perldoc Config::JFDI
224
225       You can also look for information at:
226
227       ·   RT: CPAN's request tracker
228
229           http://rt.cpan.org/NoAuth/Bugs.html?Dist=Config-JFDI
230           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Config-JFDI>
231
232       ·   AnnoCPAN: Annotated CPAN documentation
233
234           http://annocpan.org/dist/Config-JFDI
235           <http://annocpan.org/dist/Config-JFDI>
236
237       ·   CPAN Ratings
238
239           http://cpanratings.perl.org/d/Config-JFDI
240           <http://cpanratings.perl.org/d/Config-JFDI>
241
242       ·   Search CPAN
243
244           http://search.cpan.org/dist/Config-JFDI
245           <http://search.cpan.org/dist/Config-JFDI>
246

249       Copyright 2008 Robert Krimen, all rights reserved.
250
251       This program is free software; you can redistribute it and/or modify it
252       under the same terms as Perl itself.
253
254
255
256perl v5.12.0                      2009-10-19                   Config::JFDI(3)

NAME

VERSION

SYNPOSIS

DESCRIPTION

Config::Loader

Behavior change of the 'file' parameter in 0.06

METHODS

AUTHOR

SEE ALSO

SOURCE

BUGS

SUPPORT

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE