Debian Codegraph @

README

raw
1 NAME
2 Config::Merge - load a configuration directory tree containing YAML,
3 JSON, XML, Perl, INI or Config::General files
4
5 SYNOPSIS
6 OO style
7 -------------------------------------------------------
8 use Config::Merge();
9
10 my $config = Config::Merge->new('/path/to/config');
11
12 @hosts = $config->('db.hosts.session');
13 $hosts_ref = $config->('db.hosts.session');
14 @cloned_hosts = $config->clone('db.hosts.session');
15 -------------------------------------------------------
16
17 OR
18
19 Functional style
20 -------------------------------------------------------
21 # On startup
22 use Config::Merge('My::Config' => '/path/to/config');
23
24
25 # Then, in any module where you want to use the config
26 package My::Module;
27 use My::Config;
28
29 @hosts = C('db.hosts.sesssion');
30 $hosts_ref = C('db.hosts.sesssion');
31 @cloned_hosts = My::Config::clone('db.hosts.session');
32 $config = My::Config::object;
33 -------------------------------------------------------
34
35 ADVANCED USAGE
36
37 OO style
38 -------------------------------------------------------
39 my $config = Config::Merge->new(
40 path => '/path/to/config',
41 skip => sub {} | regex | {} ,
42 is_local => sub {} | regex | {} ,
43 load_as => sub {} | regex ,
44 sort => sub {} ,
45 debug => 1 | 0
46 );
47 -------------------------------------------------------
48
49 Functional style
50 -------------------------------------------------------
51 use Config::Merge(
52 'My::Config' => '/path/to/config',
53 {
54 skip => sub {} | regex | {} ,
55 is_local => sub {} | regex | {} ,
56 load_as => sub {} | regex ,
57 sort => sub {} ,
58 debug => 1 | 0
59 }
60 );
61
62 # Also, you can subclass these:
63
64 package My::Config;
65 sub skip {
66 ...
67 }
68
69 -------------------------------------------------------
70
71 DESCRIPTION
72 Config::Merge is a configuration module which has six goals:
73
74 * Flexible storage
75
76 Store all configuration in your format(s) of choice (YAML, JSON,
77 INI, XML, Perl, Config::General / Apache-style config) broken down
78 into individual files in a configuration directory tree, for easy
79 maintenance. See "CONFIG TREE LAYOUT"
80
81 * Flexible access
82
83 Provide a simple, easy to read, concise way of accessing the
84 configuration values (similar to Template). See "ACCESSING CONFIG
85 DATA"
86
87 * Minimal maintenance
88
89 Specify the location of the configuration files only once per
90 application, so that it requires minimal effort to relocate. See
91 "USING Config::Merge"
92
93 * Easy to alter development environment
94
95 Provide a way for overriding configuration values on a development
96 machine, so that differences between the dev environment and the
97 live environment do not get copied over accidentally. See
98 "OVERRIDING CONFIG LOCALLY"
99
100 * Minimise memory use
101
102 Load all config at startup so that (eg in the mod_perl environment)
103 the data is shared between all child processes. See "MINIMISING
104 MEMORY USE"
105
106 * Flexible implementation
107
108 You may want to use a different schema for your configuration files,
109 so you can pass in (or subclass) methods for determining how your
110 files are merged. See "ADVANCED USAGE".
111
112 USING "Config::Merge"
113 There are two ways to use "Config::Merge":
114
115 OO STYLE
116 use Config::Merge();
117 my $config = Config::Merge->new('/path/to/config');
118
119 @hosts = $config->('db.hosts.session');
120 $hosts_ref = $config->('db.hosts.session');
121 @cloned_hosts = $config->clone('db.hosts.session');
122
123 Also, see "ADVANCED USAGE".
124
125 YOUR OWN CONFIG CLASS (functional style)
126 The following code:
127
128 # On startup
129 use Config::Merge('My::Config' => '/path/to/config');
130
131 * auto-generates the class "My::Config"
132
133 * loads the configuration data in '/path/to/config'
134
135 * creates the subs "My::Config::C", "My::Config::clone" and
136 "My::Config::object".
137
138 Then when you want your application to have access to your
139 configuration data, you add this (eg in your class "My::Module"):
140
141 package My::Module;
142 use My::Config; # Note, no ()
143
144 This exports the sub "C" into your current package, which allows you
145 to access your configuation data as follows:
146
147 @hosts = C('db.hosts.sesssion');
148 $hosts_ref = C('db.hosts.sesssion');
149 @cloned_hosts = My::Config::clone('db.hosts.session');
150 $config = My::Config::object;
151
152 CONFIG TREE LAYOUT
153 Config::Merge reads the data from any number (and type) of config files
154 stored in a directory tree. File names and directory names are used as
155 keys in the configuration hash.
156
157 It uses file extensions to decide what type of data the file contains,
158 so:
159
160 YAML : .yaml .yml
161 JSON : .json .jsn
162 XML : .xml
163 INI : .ini
164 Perl : .perl .pl
165 Config::General : .conf .cnf
166
167 When loading your config data, Config::Merge starts at the directory
168 specified at startup (see "USING Config::Merge") and looks through all
169 the sub-directories for files ending in one of the above extensions.
170
171 The name of the file or subdirectory is used as the first key. So:
172
173 global/
174 db.yaml:
175 username : admin
176 hosts:
177 - host1
178 - host2
179 password:
180 host1: password1
181 host2: password2
182
183 would be loaded as :
184
185 $Config = {
186 global => {
187 db => {
188 username => 'admin',
189 password => { host1 => 'password1', host2 => 'password2'},
190 hosts => ['host1','host2'],
191 }
192 }
193 }
194
195 Subdirectories are processed before the current directory, so you can
196 have a directory and a config file with the same name, and the values
197 will be merged into a single hash, so for instance, you can have:
198
199 confdir:
200 syndication/
201 --data_types/
202 --traffic.yaml
203 --headlines.yaml
204 --data_types.ini
205 syndication.conf
206
207 The config items in syndication.conf will be added to (or overwrite) the
208 items loaded into the syndication namespace via the subdirectory called
209 syndication.
210
211 OVERRIDING CONFIG LOCALLY
212 The situation often arises where it is necessary to specify different
213 config values on different machines. For instance, the database host on
214 a dev machine may be different from the host on the live application.
215 Also, see "ADVANCED USAGE" which provides you with other means to merge
216 local data.
217
218 Instead of changing this data during dev and then having to remember to
219 change it back before putting the new code live, we have a mechanism for
220 overriding config locally in a "local.*" file and then, as long as that
221 file never gets uploaded to live, you are protected.
222
223 You can put a file called "local.*" (where * is any of the recognised
224 extensions) in any sub-directory, and the data in this file will be
225 merged with the existing data.
226
227 Just make sure that the "local.*" files are never checked into your live
228 code.
229
230 For instance, if we have:
231
232 confdir:
233 db.yaml
234 local.yaml
235
236 and db.yaml has :
237
238 connections:
239 default_settings:
240 host: localhost
241 table: abc
242 password: 123
243
244 And in local.yaml:
245
246 db:
247 connections:
248 default_settings:
249 password: 456
250
251 the resulting configuration will look like this:
252
253 db:
254 connections:
255 default_settings:
256 host: localhost
257 table: abc
258 password: 456
259
260 ACCESSING CONFIG DATA
261 All configuration data is loaded into a single hash, eg:
262
263 $config = {
264 db => {
265 hosts => {
266 session => ['host1','host2','host3'],
267 images => ['host1','host2','host3'],
268 etc...
269 }
270 }
271 }
272
273 If you want to access it via standard Perl dereferences, you can just
274 ask for the hash:
275
276 OO:
277 $data_ref = $config->();
278 $hosts_ref = $data_ref->{db}{hosts}{session};
279 $host_1 = $data_ref->{db}{hosts}{session}[0];
280
281 Functional:
282 $data_ref = C();
283 $hosts_ref = $data_ref->{db}{hosts}{session};
284 $host_1 = $data_ref->{db}{hosts}{session}[0];
285
286 However, "Config::Merge" also provides an easy to read dot-notation in
287 the style of Template Toolkit: "('key1.key2.keyn')".
288
289 A key can be the key of a hash or the index of an array. The return
290 value is context sensitive, so if called in list context, a hash ref or
291 array ref will be dereferenced.
292
293 OO:
294 @hosts = $config->('db.hosts.session');
295 $hosts_ref = $config->('db.hosts.session');
296 $host_1 = $config->('db.hosts.session.0');
297
298 Functional:
299 @hosts = C('db.hosts.session');
300 $hosts_ref = C('db.hosts.session');
301 $host_1 = C('db.hosts.session.0');
302
303 These lookups are memo'ised, so lookups are fast.
304
305 If the specified key is not found, then an error is thrown.
306
307 MINIMISING MEMORY USE
308 The more configuration data you load, the more memory you use. In order
309 to keep the memory use as low as possible for mod_perl (or other forking
310 applications), the configuration data should be loaded at startup in the
311 parent process.
312
313 As long as the data is never changed by the children, the configuration
314 hash will be stored in shared memory, rather than there being a separate
315 copy in each child process.
316
317 (See
318 <http://search.cpan.org/~pgollucci/mod_perl-2.0.3/docs/user/performance/
319 mpm.pod>)
320
321 METHODS
322 "new()"
323 $conf = Config::Merge->new($config_dir);
324
325 new() instantiates a config object, loads the config from the
326 directory specified, and returns the object.
327
328 "C()"
329 $val = $config->C('key1.key2.keyn');
330 $val = $config->C('key1.key2.keyn',$hash_ref);
331
332 "Config::Merge" objects are overloaded so that this also works:
333
334 $val = $config->('key1.key2.keyn');
335 $val = $config->('key1.key2.keyn',$hash_ref);
336
337 Or, if used in the functional style (see "USING Config::Merge"):
338
339 $val = C('key1.key2.keyn');
340 $val = C('key1.key2.keyn',$hash_ref);
341
342 "key1" etc can be keys in a hash, or indexes of an array.
343
344 "C('key1.key2.keyn')" returns everything from "keyn" down, so you
345 can use the return value just as you would any normal Perl variable.
346
347 The return values are context-sensitive, so if called in list
348 context, an array ref or hash ref will be returned as lists. Scalar
349 values, code refs, regexes and blessed objects will always be
350 returned as themselves.
351
352 So for example:
353
354 $password = C('database.main.password');
355 $regex = C('database.main.password_regex');
356
357 @countries = C('lists.countries');
358 $countries_array_ref = C('lists.countries');
359
360 etc
361
362 If called with a hash ref as the second parameter, then that hash
363 ref will be examined, rather than the $config data.
364
365 "clone()"
366 This works exactly the same way as "C()" but it performs a deep
367 clone of the data before returning it.
368
369 This means that the returned data can be changed without affecting
370 the data stored in the $conf object;
371
372 The data is deep cloned, using Storable, so the bigger the data, the
373 more performance hit. That said, Storable's dclone is very fast.
374
375 "register_loader()"
376 Config::Merge->register_loader( 'Config::Merge::XYZ');
377
378 Config::Merge->register_loader( 'Config::Merge::XYZ' => 'xyz','xxx');
379
380 By default, "Config::Merge" uses the "Config::Any" plugins to
381 support YAML, JSON, INI, XML, Perl and Config::General configuration
382 files, using the standard file extensions to recognise the file
383 type. (See "CONFIG TREE LAYOUT").
384
385 If you would like to change the handler for an extension (eg, you
386 want ".conf" and ".cnf" files to be treated as YAML), do the
387 following:
388
389 Config::Merge->register_loader ('Config::Any::YAML' => 'conf', 'cnf');
390
391 If you would like to add a new config style, then your module should
392 have two methods: "extensions()" (which returns a list of the
393 extensions it handles), and "load()" which accepts the name of the
394 file to load, and returns a hash ref containing the data in the
395 file. See Config::Any for details.
396
397 Alternatively, you can specify the extensions when you load it:
398
399 Config::Merge->register_loader ('My::Merge' => 'conf', 'cnf');
400
401 "load_config()"
402 $config->load_config();
403
404 Will reload the config files located in the directory specified at
405 object creation (see "new()").
406
407 BEWARE : If you are using this in a mod_perl environment, you will
408 lose the benefit of shared memory by calling this in a child process
409 - each child will have its own copy of the data. See "MINIMISING
410 MEMORY USE".
411
412 Returns the config hash ref.
413
414 "clear_cache()"
415 $config->clear_cache();
416
417 Config data is generally not supposed to be changed at runtime.
418 However, if you do make changes, you may get inconsistent results,
419 because lookups are cached.
420
421 For instance:
422
423 print $config->C('db.hosts.session'); # Caches this lookup
424 > "host1 host2 host3"
425
426 $data = $config->C('db.hosts');
427 $data->{session} = 123;
428
429 print $config->C('db.hosts.session'); # uses cached value
430 > "host1 host2 host3"
431
432 $config->clear_cache();
433 print $config->C('db.hosts.session'); # uses actual value
434 > "123"
435
436 "import()"
437 "import()" will normally be called automatically when you "use
438 Config::Merge". However, you may want to do this:
439
440 use Config::Merge();
441 Config::Merge->register_loader('My::Plugin' => 'ext');
442 Config::Merge->import('My::Config' => '/path/to/config/dir');
443
444 If called with two params: $config_class and $config_dir, it
445 generates the new class (which inherits from Config::Merge)
446 specified in $config_class, creates a new object of that class and
447 creates 4 subs:
448
449 "C()"
450 As a function:
451 C('keys...')
452
453 is the equivalent of:
454 $config->C('keys...');
455
456 "clone()"
457 As a function:
458 clone('keys...')
459
460 is the equivalent of:
461 $config->clone('keys...');
462
463 "object()"
464 $config = My::Config->object();
465
466 Returns the $config object,
467
468 "import()"
469 When you use your generated config class, it exports the "C()"
470 sub into your package:
471
472 use My::Config;
473 $hosts = C('db.hosts.session');
474
475 ADVANCED USAGE
476 The items in the section allow you to customise how Config::Merge loads
477 your data. You may never need them.
478
479 You can:
480
481 * Override array values
482
483 * Skip the loading of parts of your config tree
484
485 * Specify which files / dirs are local
486
487 * Specify how to translate a file / dir name into a key
488
489 * Change order in which files are loaded
490
491 * See debug output
492
493 Overriding array values
494 Overriding hash values is easy, however arrays are more complex. it
495 may be simpler to copy and paste and edit the array you want to
496 change locally.
497
498 However, if your array is too long, and you want to make small
499 changes, then you can use the following:
500
501 In the main config:
502
503 {
504 cron => [qw( job1 job2 job3 job4)]
505 }
506
507 In the local file
508
509 {
510 cron => {
511 '3' => 'newjob4', # changes 'job4' -> 'newjob4'
512
513 '!' => { # signals an array override
514
515 '-' => [1], # deletes 'job2'
516
517 '+' => ['job5'], # appends 'job5'
518
519 OR '+' => { # inserts 'job3a' after 'job3'
520 2 => 'job3a'
521 }
522 }
523 }
524
525 * The override has to be a hash, with at least this structure "{
526 '!' => {} }" to signal an array override
527
528 * Any other keys with integers are treated as indexes and are used
529 to change the value at that index in the original array
530
531 * The '-' key should contain an array ref, with the indexes of the
532 elements to remove from the array.
533
534 * If the '+' key contains an array ref, then its contents are
535 appended to the original array.
536
537 * If the '+' key contains a hash ref, then each value is inserted
538 into the original array at the index given in the key
539
540 * Indexes are zero based, just as in Perl.
541
542 "skip()"
543 $c = Config::Merge->new(
544 path => '/path/to/config',
545 skip => qr/regex/,
546 | [ qr/regex1/, qr/regex2/...]
547 | { name1 => 1, name2 => 2}
548 | sub {}
549 );
550
551 "skip()" allows you to skip the loading of parts of your config
552 tree. For instance, if you don't need a list of cron jobs when
553 running your web server, you can skip it.
554
555 The decision is made based on the path to that value, eg
556 'app.db.hosts' rather than on filenames. Also, the check is only
557 performed for each new directory or filename - it doesn't check the
558 data within each file.
559
560 To use "skip()", you can either subclass it, or pass in a parameter
561 to new:
562
563 "qr/regex/" or "[qr/regex1/, qr/regex2]"
564 Each regex will be checked against the key path, and if it
565 matches then the loading of that tree will be skipped
566
567 "{key_path => 1}"
568 If the key path exists in the hash, then loading will be skipped
569
570 "sub {}" or subclassed "skip"
571 sub {
572 my ($self,$key_path) = @_;
573 ...make decision...
574 return 1 | 0;
575 }
576
577 "is_local()"
578 $c = Config::Merge->new(
579 path => '/path/to/config',
580 is_local => qr/regex/,
581 | [ qr/regex1/, qr/regex2/...]
582 | { name1 => 1, name2 => 2}
583 | sub {}
584 );
585
586 "is_local()" indicates whether a file or dir should be considered
587 part of the main config (and thus loaded normally) or part of the
588 local config (and thus merged into the main config).
589
590 The decision is made based on the name of the file / dir, without
591 any extension.
592
593 To use "is_local()", you can either subclass it, or pass in a
594 parameter to new:
595
596 "qr/regex/" or "[qr/regex1/, qr/regex2]"
597 Each regex will be checked against the file/dir name, and if it
598 matches then that tree will be merged
599
600 "{filename => 1, dirname => 1}"
601 If the file/dir name exists in the hash, then that tree will be
602 merged
603
604 "sub {}" or subclassed "is_local"
605 sub {
606 my ($self,$name) = @_;
607 ...make decision...
608 return 1 | 0;
609 }
610
611 See "EXAMPLE USING is_local() AND load_as()".
612
613 "load_as()"
614 $c = Config::Merge->new(
615 path => '/path/to/config',
616 load_as => qr/(regex)/,
617 | sub {}
618 );
619
620 "load_as()" returns the name of the key to use when loading the file
621 / dir. By default, it returns the $name for main config files, or ''
622 for local files.
623
624 The decision is made based on the name of the file / dir, without
625 any extension.
626
627 If "load_as()" returns an empty string, then each key in the
628 file/tree is merged separately. This is how the "local.*" files work
629 by default. See "OVERRIDING CONFIG LOCALLY".
630
631 For instance:
632
633 main.yaml:
634 key1: value
635 key2: value
636
637 db.yaml:
638 key3: value
639 key4: value
640
641 local.yaml:
642 main:
643 key1: new_value
644 db:
645 key4: new_value
646
647 To use "load_as()", you can either subclass it, or pass in a
648 parameter to new:
649
650 "qr/(regex)/"
651 The regex will be checked against the file/dir name, and if it
652 matches then it returns the string captured in the regex,
653 otherwise it returns the original name.
654
655 "sub {}" or subclassed "is_local"
656 sub {
657 my ($self,$name,$is_local) = @_;
658 ...make decision...
659 return 'string'; # string is used as the keyname
660 return ''; # acts like local.* (see above)
661 return undef; # don't load this file/dir
662 }
663
664 Also, see "EXAMPLE USING is_local() AND load_as()".
665
666 EXAMPLE USING "is_local()" AND "load_as()"
667 For instance, instead of using "local.*" files, you may want to keep
668 versioned copies of local configs for different machines, and so
669 use:
670
671 app.yaml
672 app-(dev1.domain.com).yaml
673 app-(dev2.domain.com).yaml
674
675 You would implement this as follows:
676
677 my $config = Config::Merge->new(
678 path => '/path/to/config',
679
680 # If matches 'xxx-(yyy)'
681 is_local => sub {
682 my ( $self, $name ) = @_;
683 return $name=~/- [(] .+ [)]/x ? 1 : 0;
684 },
685
686 # If local and matches 'xxx-(hostname)', return xxx
687 load_as => sub {
688 my ( $self, $name, $is_local ) = @_;
689 if ($is_local) {
690 if ( $name=~/(.*) - [(] ($hostname) [)] /x ) {
691 return $1;
692 }
693 return undef;
694 }
695 return $name;
696 }
697 );
698
699 See "examples/advanced.pl" for a working illustration.
700
701 "sort()"
702 $c = Config::Merge->new(
703 path => '/path/to/config',
704 sort => sub {}
705 );
706
707 By default, directory entries are sorted alphabetically, with
708 directories before filenames.
709
710 This would be the order for these directory entries:
711
712 api/
713 api-(dev1)/
714 api.yaml
715 api-(dev1).yaml
716
717 To override this, you can subclass "sort()" or pass it in as a
718 parameter to new:
719
720 sub {
721 my ($self,$names_array_ref) = @_
722 ...sort...
723 return $names_array_ref;
724 }
725
726 "debug()"
727 my $config = Config::Merge->new(
728 path => '/path/to/config',
729 debug => 1 | 0
730 );
731
732 If "debug" is true, then Config::Merge prints out an explanation of
733 what it is doing on STDERR.
734
735 SEE ALSO
736 Storable, Config::Any, Config::Any::YAML, Config::Any::JSON,
737 Config::Any::INI, Config::Any::XML, Config::Any::General
738
739 THANKS
740 Thanks to Hasanuddin Tamir [HASANT] for vacating the Config::Merge
741 namespace, which allowed me to rename Config::Loader to the more
742 meaningful Config::Merge.
743
744 His version of Config::Merge can be found in
745 <http://backpan.cpan.org/modules/by-authors/id/H/HA/HASANT/>.
746
747 Thanks to Joel Bernstein and Brian Cassidy for the interface to the
748 various configuration modules. Also to Ewan Edwards for his suggestions
749 about how to make Config::Merge more flexible.
750
751 BUGS
752 No bugs have been reported.
753
754 Please report any bugs or feature requests to
755 <http://github.com/clintongormley/ConfigMerge/issues>.
756
757 AUTHOR
758 Clinton Gormley, <[email protected]>
759
760 COPYRIGHT
761 Copyright (C) 2007-2010 by Clinton Gormley
762
763 LICENSE
764 This library is free software; you can redistribute it and/or modify it
765 under the same terms as Perl itself, either Perl version 5.8.7 or, at
766 your option, any later version of Perl 5 you may have available.
767