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.065
11

13       Config::JFDI is an implementation of Catalyst::Plugin::ConfigLoader
14       that exists outside of Catalyst.
15
16       Essentially, Config::JFDI will scan a directory for files matching a
17       certain name. If such a file is found which also matches an extension
18       that Config::Any can read, then the configuration from that file will
19       be loaded.
20
21       Config::JFDI will also look for special files that end with a "_local"
22       suffix. Files with this special suffix will take precedence over any
23       other existing configuration file, if any. The precedence takes place
24       by merging the local configuration with the "standard" configuration
25       via Hash::Merge::Simple.
26
27       Finally, you can override/modify the path search from outside your
28       application, by setting the <NAME>_CONFIG variable outside your
29       application (where <NAME> is the uppercase version of what you passed
30       to Config::JFDI->new).
31

33           use Config::JFDI;
34
35           my $config = Config::JFDI->new(name => "my_application", path => "path/to/my/application");
36           my $config_hash = $config->get;
37
38       This will look for something like (depending on what Config::Any will
39       find):
40
41           path/to/my/application/my_application_local.{yml,yaml,cnf,conf,jsn,json,...} AND
42
43           path/to/my/application/my_application.{yml,yaml,cnf,conf,jsn,json,...}
44
45       ... and load the found configuration information appropiately, with
46       _local taking precedence.
47
48       You can also specify a file directly:
49
50           my $config = Config::JFDI->new(file => "/path/to/my/application/my_application.cnf");
51
52       To later reload your configuration, fresh from disk:
53
54           $config->reload;
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

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

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

198       Catalyst::Plugin::ConfigLoader
199
200       Config::Any
201
202       Catalyst
203
204       Config::Merge
205
206       Config::General
207

209       Robert Krimen <robertkrimen@gmail.com>
210

212       This software is copyright (c) 2011 by Robert Krimen.
213
214       This is free software; you can redistribute it and/or modify it under
215       the same terms as the Perl 5 programming language system itself.
216
217
218
219perl v5.32.0                      2020-07-28                   Config::JFDI(3)

NAME

VERSION

DESCRIPTION

SYNPOSIS

Config::Loader

Behavior change of the 'file' parameter in 0.06

METHODS

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE