1General(3) User Contributed Perl Documentation General(3)
2
6 Config::General - Generic Config Module
7
9 #
10 # the OOP way
11 use Config::General;
12 $conf = new Config::General("rcfile");
13 my %config = $conf->getall;
14 #
16 # the procedural way
17 use Config::General qw(ParseConfig SaveConfig SaveConfigString);
18 my %config = ParseConfig("rcfile");
19
21 This module opens a config file and parses its contents for you. The
22 new method requires one parameter which needs to be a filename. The
23 method getall returns a hash which contains all options and its
24 associated values of your config file.
25 The format of config files supported by Config::General is inspired by
27 the well known Apache config format, in fact, this module is 100%
28 compatible to Apache configs, but you can also just use simple
29 name/value pairs in your config files.
30 In addition to the capabilities of an Apache config file it supports
32 some enhancements such as here-documents, C-style comments or multiline
33 options.
34
36 new()
37 Possible ways to call new():
38 $conf = new Config::General("rcfile");
40 $conf = new Config::General(\%somehash);
42 $conf = new Config::General( %options ); # see below for description of possible options
44 This method returns a Config::General object (a hash blessed into
46 "Config::General" namespace. All further methods must be used from
47 that returned object. see below.
48 You can use the new style with hash parameters or the old style
50 which is of course still supported. Possible parameters to new()
51 are:
52 * a filename of a configfile, which will be opened and parsed by
54 the parser
55 or
57 * a hash reference, which will be used as the config.
59 An alternative way to call new() is supplying an option- hash with
61 one or more of the following keys set:
62 -ConfigFile
64 A filename or a filehandle, i.e.:
65 -ConfigFile => "rcfile" or -ConfigFile => \$FileHandle
67 -ConfigHash
69 A hash reference, which will be used as the config, i.e.:
70 -ConfigHash => \%somehash
72 -String
74 A string which contains a whole config, or an arrayref
75 containing the whole config line by line. The parser will
76 parse the contents of the string instead of a file. i.e:
77 -String => $complete_config
79 it is also possible to feed an array reference to -String:
81 -String => \@config_lines
83 -AllowMultiOptions
85 If the value is "no", then multiple identical options are
86 disallowed. The default is "yes". i.e.:
87 -AllowMultiOptions => "yes"
89 see IDENTICAL OPTIONS for details.
91 -LowerCaseNames
93 If set to a true value, then all options found in the config
94 will be converted to lowercase. This allows you to provide
95 case-in-sensitive configs. The values of the options will not
96 lowercased.
97 -UseApacheInclude
99 If set to a true value, the parser will consider "include ..."
100 as valid include statement (just like the well known Apache
101 include statement).
102 -IncludeRelative
104 If set to a true value, included files with a relative path
105 (i.e. "cfg/blah.conf") will be opened from within the location
106 of the configfile instead from within the location of the
107 script($0). This works only if the configfile has a absolute
108 pathname (i.e. "/etc/main.conf").
109 If the variable -ConfigPath has been set and if the file to be
111 included could not be found in the location relative to the
112 current config file, the module will search within -ConfigPath
113 for the file. See the description of -ConfigPath for more
114 details.
115 -IncludeDirectories
117 If set to a true value, you may specify include a directory, in
118 which case all files inside the directory will be loaded in
119 ASCII order. Directory includes will not recurse into
120 subdirectories. This is comparable to including a directory in
121 Apache-style config files.
122 -IncludeGlob
124 If set to a true value, you may specify a glob pattern for an
125 include to include all matching files (e.g. <<include
126 conf.d/*.conf>>). Also note that as with standard file
127 patterns, * will not match dot-files, so <<include dir/*>> is
128 often more desirable than including a directory with
129 -IncludeDirectories.
130 -IncludeAgain
132 If set to a true value, you will be able to include a sub-
133 configfile multiple times. With the default, false, you will
134 get a warning about duplicate includes and only the first
135 include will succeed.
136 Reincluding a configfile can be useful if it contains data that
138 you want to be present in multiple places in the data tree.
139 See the example under "INCLUDES".
140 Note, however, that there is currently no check for include
142 recursion.
143 -ConfigPath
145 As mentioned above, you can use this variable to specify a
146 search path for relative config files which have to be
147 included. Config::General will search within this path for the
148 file if it cannot find the file at the location relative to the
149 current config file.
150 To provide multiple search paths you can specify an array
152 reference for the path. For example:
153 @path = qw(/usr/lib/perl /nfs/apps/lib /home/lib);
155 ..
156 -ConfigPath => \@path
157 -MergeDuplicateBlocks
159 If set to a true value, then duplicate blocks, that means
160 blocks and named blocks, will be merged into a single one (see
161 below for more details on this). The default behavior of
162 Config::General is to create an array if some junk in a config
163 appears more than once.
164 -MergeDuplicateOptions
166 If set to a true value, then duplicate options will be merged.
167 That means, if the same option occurs more than once, the last
168 one will be used in the resulting config hash.
169 Setting this option implies -AllowMultiOptions == false unless
171 you set -AllowMultiOptions explicit to 'true'. In this case
172 duplicate blocks are allowed and put into an array but
173 duplicate options will be merged.
174 -AutoLaunder
176 If set to a true value, then all values in your config file
177 will be laundered to allow them to be used under a -T taint
178 flag. This could be regarded as circumventing the purpose of
179 the -T flag, however, if the bad guys can mess with your config
180 file, you have problems that -T will not be able to stop.
181 AutoLaunder will only handle a config file being read from
182 -ConfigFile.
183 -AutoTrue
185 If set to a true value, then options in your config file, whose
186 values are set to true or false values, will be normalised to 1
187 or 0 respectively.
188 The following values will be considered as true:
190 yes, on, 1, true
192 The following values will be considered as false:
194 no, off, 0, false
196 This effect is case-insensitive, i.e. both "Yes" or "oN" will
198 result in 1.
199 -FlagBits
201 This option takes one required parameter, which must be a hash
202 reference.
203 The supplied hash reference needs to define variables for which
205 you want to preset values. Each variable you have defined in
206 this hash-ref and which occurs in your config file, will cause
207 this variable being set to the preset values to which the value
208 in the config file refers to.
209 Multiple flags can be used, separated by the pipe character |.
211 Well, an example will clarify things:
213 my $conf = new Config::General(
215 -ConfigFile => "rcfile",
216 -FlagBits => {
217 Mode => {
218 CLEAR => 1,
219 STRONG => 1,
220 UNSECURE => "32bit" }
221 }
222 );
223 In this example we are defining a variable named "Mode" which
225 may contain one or more of "CLEAR", "STRONG" and "UNSECURE" as
226 value.
227 The appropriate config entry may look like this:
229 # rcfile
231 Mode = CLEAR | UNSECURE
232 The parser will create a hash which will be the value of the
234 key "Mode". This hash will contain all flags which you have
235 pre-defined, but only those which were set in the config will
236 contain the pre-defined value, the other ones will be
237 undefined.
238 The resulting config structure would look like this after
240 parsing:
241 %config = (
243 Mode => {
244 CLEAR => 1,
245 UNSECURE => "32bit",
246 STRONG => undef,
247 }
248 );
249 This method allows the user (or, the "maintainer" of the
251 configfile for your application) to set multiple pre-defined
252 values for one option.
253 Please beware, that all occurrences of those variables will be
255 handled this way, there is no way to distinguish between
256 variables in different scopes. That means, if "Mode" would
257 also occur inside a named block, it would also parsed this way.
258 Values which are not defined in the hash-ref supplied to the
260 parameter -FlagBits and used in the corresponding variable in
261 the config will be ignored.
262 Example:
264 # rcfile
266 Mode = BLAH | CLEAR
267 would result in this hash structure:
269 %config = (
271 Mode => {
272 CLEAR => 1,
273 UNSECURE => undef,
274 STRONG => undef,
275 }
276 );
277 "BLAH" will be ignored silently.
279 -DefaultConfig
281 This can be a hash reference or a simple scalar (string) of a
282 config. This causes the module to preset the resulting config
283 hash with the given values, which allows you to set default
284 values for particular config options directly.
285 -Tie
287 -Tie takes the name of a Tie class as argument that each new
288 hash should be based off of.
289 This hash will be used as the 'backing hash' instead of a
291 standard Perl hash, which allows you to affect the way,
292 variable storing will be done. You could, for example supply a
293 tied hash, say Tie::DxHash, which preserves ordering of the
294 keys in the config (which a standard Perl hash won't do). Or,
295 you could supply a hash tied to a DBM file to save the parsed
296 variables to disk.
297 There are many more things to do in tie-land, see tie to get
299 some interesting ideas.
300 If you want to use the -Tie feature together with
302 -DefaultConfig make sure that the hash supplied to
303 -DefaultConfig must be tied to the same Tie class.
304 Make sure that the hash which receives the generated hash
306 structure (e.g. which you are using in the assignment: %hash =
307 $config->getall()) must be tied to the same Tie class.
308 Example:
310 use Config::General qw(ParseConfig);
312 use Tie::IxHash;
313 tie my %hash, "Tie::IxHash";
314 %hash = ParseConfig(
315 -ConfigFile => shift(),
316 -Tie => "Tie::IxHash"
317 );
318 -InterPolateVars
320 If set to a true value, variable interpolation will be done on
321 your config input. See Config::General::Interpolated for more
322 information.
323 -InterPolateEnv
325 If set to a true value, environment variables can be used in
326 configs.
327 This implies -InterPolateVars.
329 -AllowSingleQuoteInterpolation
331 By default variables inside single quotes will not be
332 interpolated. If you turn on this option, they will be
333 interpolated as well.
334 -ExtendedAccess
336 If set to a true value, you can use object oriented (extended)
337 methods to access the parsed config. See
338 Config::General::Extended for more informations.
339 -StrictObjects
341 By default this is turned on, which causes Config::General to
342 croak with an error if you try to access a non-existent key
343 using the OOP-way (-ExtendedAcess enabled). If you turn
344 -StrictObjects off (by setting to 0 or "no") it will just
345 return an empty object/hash/scalar. This is valid for OOP-
346 access 8via AUTOLOAD and for the methods obj(), hash() and
347 value().
348 -StrictVars
350 By default this is turned on, which causes Config::General to
351 croak with an error if an undefined variable with
352 InterPolateVars turned on occurs in a config. Set to false
353 (i.e. 0) to avoid such error messages.
354 -SplitPolicy
356 You can influence the way how Config::General decides which
357 part of a line in a config file is the key and which one is the
358 value. By default it tries its best to guess. That means you
359 can mix equalsign assignments and whitespace assignments.
360 However, somtime you may wish to make it more strictly for some
362 reason. In this case you can set -SplitPolicy. The possible
363 values are: 'guess' which is the default, 'whitespace' which
364 causes the module to split by whitespace, 'equalsign' which
365 causes it to split strictly by equal sign, or 'custom'. In the
366 latter case you must also set -SplitDelimiter to some regular
367 expression of your choice. For example:
368 -SplitDelimiter => '\s*:\s*'
370 will cause the module to split by colon while whitespace which
372 surrounds the delimiter will be removed.
373 Please note that the delimiter used when saving a config
375 (save_file() or save_string()) will be chosen according to the
376 current -SplitPolicy. If -SplitPolicy is set to 'guess' or
377 'whitespace', 3 spaces will be used to delimit saved options.
378 If 'custom' is set, then you need to set -StoreDelimiter.
379 -SplitDelimiter
381 Set this to any arbitrary regular expression which will be used
382 for option/value splitting. -SplitPolicy must be set to
383 'custom' to make this work.
384 -StoreDelimiter
386 You can use this parameter to specify a custom delimiter to use
387 when saving configs to a file or string. You only need to set
388 it if you want to store the config back to disk and if you have
389 -SplitPolicy set to 'custom'.
390 Be very careful with this parameter.
392 -CComments
394 Config::General is able to notice c-style comments (see section
395 COMMENTS). But for some reason you might no need this. In this
396 case you can turn this feature off by setting -CComments to a
397 false value('no', 0, 'off').
398 By default -CComments is turned on.
400 -BackslashEscape
402 Deprecated Option.
403 -SlashIsDirectory
405 If you turn on this parameter, a single slash as the last
406 character of a named block will be considered as a directory
407 name.
408 By default this flag is turned off, which makes the module
410 somewhat incompatible to Apache configs, since such a setup
411 will be normally considered as an explicit empty block, just as
412 XML defines it.
413 For example, if you have the following config:
415 <Directory />
417 Index index.awk
418 </Directory>
419 you will get such an error message from the parser:
421 EndBlock "</Directory>" has no StartBlock statement (level: 1, chunk 10)!
423 This is caused by the fact that the config chunk below will be
425 internally converted to:
426 <Directory></Directory>
428 Index index.awk
429 </Directory>
430 Now there is one '</Directory>' too much. The proper solution
432 is to use quotation to circumvent this error:
433 <Directory "/">
435 Index index.awk
436 </Directory>
437 However, a raw apache config comes without such quotes. In this
439 case you may consider to turn on -SlashIsDirectory.
440 Please note that this is a new option (incorporated in version
442 2.30), it may lead to various unexpected side effects or other
443 failures. You've been warned.
444 -ApacheCompatible
446 Over the past years a lot of options has been incorporated into
447 Config::General to be able to parse real Apache configs.
448 The new -ApacheCompatible option now makes it possible to tweak
450 all options in a way that Apache configs can be parsed.
451 This is called "apache compatibility mode" - if you will ever
453 have problems with parsing Apache configs without this option
454 being set, you'll get no help by me. Thanks :)
455 The following options will be set:
457 UseApacheInclude = 1
459 IncludeRelative = 1
460 IncludeDirectories = 1
461 IncludeGlob = 1
462 SlashIsDirectory = 1
463 SplitPolicy = 'equalsign'
464 CComments = 0
465 Take a look into the particular documentation sections what
467 those options are doing.
468 Beside setting some options it also turns off support for
470 explicit empty blocks.
471 -UTF8
473 If turned on, all files will be opened in utf8 mode. This may
474 not work properly with older versions of Perl.
475 -SaveSorted
477 If you want to save configs in a sorted manner, turn this
478 parameter on. It is not enabled by default.
479 getall()
481 Returns a hash structure which represents the whole config.
482 files()
484 Returns a list of all files read in.
485 save_file()
487 Writes the config hash back to the hard disk. This method takes one
488 or two parameters. The first parameter must be the filename where
489 the config should be written to. The second parameter is optional,
490 it must be a reference to a hash structure, if you set it. If you
491 do not supply this second parameter then the internal config hash,
492 which has already been parsed, will be used.
493 Please note that any occurence of comments will be ignored by
495 getall() and thus be lost after you call this method.
496 You need also to know that named blocks will be converted to nested
498 blocks (which is the same from the perl point of view). An example:
499 <user hans>
501 id 13
502 </user>
503 will become the following after saving:
505 <user>
507 <hans>
508 id 13
509 </hans>
510 </user>
511 Example:
513 $conf_obj->save_file("newrcfile", \%config);
515 or, if the config has already been parsed, or if it didn't change:
517 $conf_obj->save_file("newrcfile");
519 save_string()
521 This method is equivalent to the previous save_file(), but it does
522 not store the generated config to a file. Instead it returns it as
523 a string, which you can save yourself afterwards.
524 It takes one optional parameter, which must be a reference to a
526 hash structure. If you omit this parameter, the internal config
527 hash, which has already been parsed, will be used.
528 Example:
530 my $content = $conf_obj->save_string(\%config);
532 or:
534 my $content = $conf_obj->save_string();
536
538 Lines beginning with # and empty lines will be ignored. (see section
539 COMMENTS!) Spaces at the beginning and the end of a line will also be
540 ignored as well as tabulators. If you need spaces at the end or the
541 beginning of a value you can surround it with double quotes. An option
542 line starts with its name followed by a value. An equal sign is
543 optional. Some possible examples:
544 user max
546 user = max
547 user max
548 If there are more than one statements with the same name, it will
550 create an array instead of a scalar. See the example below.
551 The method getall returns a hash of all values.
553
555 You can define a block of options. A block looks much like a block in
556 the wellknown Apache config format. It starts with <blockname> and ends
557 with </blockname>. An example:
558 <database>
560 host = muli
561 user = moare
562 dbname = modb
563 dbpass = D4r_9Iu
564 </database>
565 Blocks can also be nested. Here is a more complicated example:
567 user = hans
569 server = mc200
570 db = maxis
571 passwd = D3rf$
572 <jonas>
573 user = tom
574 db = unknown
575 host = mila
576 <tablestructure>
577 index int(100000)
578 name char(100)
579 prename char(100)
580 city char(100)
581 status int(10)
582 allowed moses
583 allowed ingram
584 allowed joice
585 </tablestructure>
586 </jonas>
587 The hash which the method getall returns look like that:
589 print Data::Dumper(\%hash);
591 $VAR1 = {
592 'passwd' => 'D3rf$',
593 'jonas' => {
594 'tablestructure' => {
595 'prename' => 'char(100)',
596 'index' => 'int(100000)',
597 'city' => 'char(100)',
598 'name' => 'char(100)',
599 'status' => 'int(10)',
600 'allowed' => [
601 'moses',
602 'ingram',
603 'joice',
604 ]
605 },
606 'host' => 'mila',
607 'db' => 'unknown',
608 'user' => 'tom'
609 },
610 'db' => 'maxis',
611 'server' => 'mc200',
612 'user' => 'hans'
613 };
614 If you have turned on -LowerCaseNames (see new()) then blocks as in the
616 following example:
617 <Dir>
619 <AttriBUTES>
620 Owner root
621 </attributes>
622 </dir>
623 would produce the following hash structure:
625 $VAR1 = {
627 'dir' => {
628 'attributes' => {
629 'owner => "root",
630 }
631 }
632 };
633 As you can see, the keys inside the config hash are normalized.
635 Please note, that the above config block would result in a valid hash
637 structure, even if -LowerCaseNames is not set! This is because
638 Config::General does not use the block names to check if a block ends,
639 instead it uses an internal state counter, which indicates a block end.
640 If the module cannot find an end-block statement, then this block will
642 be ignored.
643
645 If you need multiple blocks of the same name, then you have to name
646 every block. This works much like Apache config. If the module finds a
647 named block, it will create a hashref with the left part of the named
648 block as the key containing one or more hashrefs with the right part of
649 the block as key containing everything inside the block(which may again
650 be nested!). As examples says more than words:
651 # given the following sample
653 <Directory /usr/frisco>
654 Limit Deny
655 Options ExecCgi Index
656 </Directory>
657 <Directory /usr/frik>
658 Limit DenyAll
659 Options None
660 </Directory>
661 # you will get:
663 $VAR1 = {
664 'Directory' => {
665 '/usr/frik' => {
666 'Options' => 'None',
667 'Limit' => 'DenyAll'
668 },
669 '/usr/frisco' => {
670 'Options' => 'ExecCgi Index',
671 'Limit' => 'Deny'
672 }
673 }
674 };
675 You cannot have more than one named block with the same name because it
677 will be stored in a hashref and therefore be overwritten if a block
678 occurs once more.
679
681 The normal behavior of Config::General is to look for whitespace in
682 block names to decide if it's a named block or just a simple block.
683 Sometimes you may need blocknames which have whitespace in their names.
685 With named blocks this is no problem, as the module only looks for the
687 first whitespace:
688 <person hugo gera>
690 </person>
691 would be parsed to:
693 $VAR1 = {
695 'person' => {
696 'hugo gera' => {
697 },
698 }
699 };
700 The problem occurs, if you want to have a simple block containing
702 whitespace:
703 <hugo gera>
705 </hugo gera>
706 This would be parsed as a named block, which is not what you wanted. In
708 this very case you may use quotation marks to indicate that it is not a
709 named block:
710 <"hugo gera">
712 </"hugo gera">
713 The save() method of the module inserts automatically quotation marks
715 in such cases.
716
718 Beside the notation of blocks mentioned above it is possible to use
719 explicit empty blocks.
720 Normally you would write this in your config to define an empty block:
722 <driver Apache>
724 </driver>
725 To save writing you can also write:
727 <driver Apache/>
729 which is the very same as above. This works for normal blocks and for
731 named blocks.
732
734 You may have more than one line of the same option with different
735 values.
736 Example:
738 log log1
739 log log2
740 log log2
741 You will get a scalar if the option occurred only once or an array if
743 it occurred more than once. If you expect multiple identical options,
744 then you may need to check if an option occurred more than once:
745 $allowed = $hash{jonas}->{tablestructure}->{allowed};
747 if(ref($allowed) eq "ARRAY") {
748 @ALLOWED = @{$allowed};
749 else {
750 @ALLOWED = ($allowed);
751 }
752 The same applies to blocks and named blocks too (they are described in
754 more detail below). For example, if you have the following config:
755 <dir blah>
757 user max
758 </dir>
759 <dir blah>
760 user hannes
761 </dir>
762 then you would end up with a data structure like this:
764 $VAR1 = {
766 'dir' => {
767 'blah' => [
768 {
769 'user' => 'max'
770 },
771 {
772 'user' => 'hannes'
773 }
774 ]
775 }
776 };
777 As you can see, the two identical blocks are stored in a hash which
779 contains an array(-reference) of hashes.
780 Under some rare conditions you might not want this behavior with blocks
782 (and named blocks too). If you want to get one single hash with the
783 contents of both identical blocks, then you need to turn the new()
784 parameter -MergeDuplicateBlocks on (see above). The parsed structure of
785 the example above would then look like this:
786 $VAR1 = {
788 'dir' => {
789 'blah' => {
790 'user' => [
791 'max',
792 'hannes'
793 ]
794 }
795 }
796 };
797 As you can see, there is only one hash "dir->{blah}" containing
799 multiple "user" entries. As you can also see, turning on
800 -MergeDuplicateBlocks does not affect scalar options (i.e. "option =
801 value"). In fact you can tune merging of duplicate blocks and options
802 independent from each other.
803 If you don't want to allow more than one identical options, you may
805 turn it off by setting the flag AllowMultiOptions in the new() method
806 to "no". If turned off, Config::General will complain about multiple
807 occurring options with identical names!
808 FORCE SINGLE VALUE ARRAYS
810 You may also force a single config line to get parsed into an array by
811 turning on the option -ForceArray and by surrounding the value of the
812 config entry by []. Example:
813 hostlist = [ foo.bar ]
815 Will be a singlevalue array entry if the option is turned on. If you
817 want it to remain to be an array you have to turn on -ForceArray during
818 save too.
819
821 If you have a config value, which is too long and would take more than
822 one line, you can break it into multiple lines by using the backslash
823 character at the end of the line. The Config::General module will
824 concatenate those lines to one single-value.
825 Example:
827 command = cat /var/log/secure/tripwire | \
829 mail "-s" "report from tripwire" \
830 honey@myotherhost.nl
831 command will become:
833 "cat /var/log/secure/tripwire | mail "-s" 'report from twire'
834 honey@myotherhost.nl"
835
837 You can also define a config value as a so called "here-document". You
838 must tell the module an identifier which idicates the end of a here
839 document. An identifier must follow a "<<".
840 Example:
842 message <<EOF
844 we want to
845 remove the
846 homedir of
847 root.
848 EOF
849 Everything between the two "EOF" strings will be in the option message.
851 There is a special feature which allows you to use indentation with
853 here documents. You can have any amount of whitespace or tabulators in
854 front of the end identifier. If the module finds spaces or tabs then it
855 will remove exactly those amount of spaces from every line inside the
856 here-document.
857 Example:
859 message <<EOF
861 we want to
862 remove the
863 homedir of
864 root.
865 EOF
866 After parsing, message will become:
868 we want to
870 remove the
871 homedir of
872 root.
873 because there were the string " " in front of EOF, which were cut
875 from every line inside the here-document.
876
878 You can include an external file at any posision in your config file
879 using the following statement in your config file:
880 <<include externalconfig.rc>>
882 If you turned on -UseApacheInclude (see new()), then you can also use
884 the following statement to include an external file:
885 include externalconfig.rc
887 This file will be inserted at the position where it was found as if the
889 contents of this file were directly at this position.
890 You can also recursively include files, so an included file may include
892 another one and so on. Beware that you do not recursively load the
893 same file, you will end with an error message like "too many open files
894 in system!".
895 By default included files with a relative pathname will be opened from
897 within the current working directory. Under some circumstances it maybe
898 possible to open included files from the directory, where the
899 configfile resides. You need to turn on the option -IncludeRelative
900 (see new()) if you want that. An example:
901 my $conf = Config::General(
903 -ConfigFile => "/etc/crypt.d/server.cfg"
904 -IncludeRelative => 1
905 );
906 /etc/crypt.d/server.cfg:
908 <<include acl.cfg>>
909 In this example Config::General will try to include acl.cfg from
911 /etc/crypt.d:
912 /etc/crypt.d/acl.cfg
914 The default behavior (if -IncludeRelative is not set!) will be to open
916 just acl.cfg, wherever it is, i.e. if you did a
917 chdir("/usr/local/etc"), then Config::General will include:
918 /usr/local/etc/acl.cfg
920 Include statements can be case insensitive (added in version 1.25).
922 Include statements will be ignored within C-Comments and here-
924 documents.
925 By default, a config file will only be included the first time it is
927 referenced. If you wish to include a file in multiple places, set
928 /-IncludeAgain to true. But be warned: this may lead to infinite loops,
929 so make sure, you're not including the same file from within itself!
930 Example:
932 # main.cfg
934 <object billy>
935 class=Some::Class
936 <printers>
937 include printers.cfg
938 </printers>
939 # ...
940 </object>
941 <object bob>
942 class=Another::Class
943 <printers>
944 include printers.cfg
945 </printers>
946 # ...
947 </object>
948 Now "printers.cfg" will be include in both the "billy" and "bob"
950 objects.
951 You will have to be careful to not recursively include a file.
953 Behaviour in this case is undefined.
954
956 A comment starts with the number sign #, there can be any number of
957 spaces and/or tab stops in front of the #.
958 A comment can also occur after a config statement. Example:
960 username = max # this is the comment
962 If you want to comment out a large block you can use C-style comments.
964 A /* signals the begin of a comment block and the */ signals the end of
965 the comment block. Example:
966 user = max # valid option
968 db = tothemax
969 /*
970 user = andors
971 db = toand
972 */
973 In this example the second options of user and db will be ignored.
975 Please beware of the fact, if the Module finds a /* string which is the
976 start of a comment block, but no matching end block, it will ignore the
977 whole rest of the config file!
978 NOTE: If you require the # character (number sign) to remain in the
980 option value, then you can use a backslash in front of it, to escape
981 it. Example:
982 bgcolor = \#ffffcc
984 In this example the value of $config{bgcolor} will be "#ffffcc",
986 Config::General will not treat the number sign as the begin of a
987 comment because of the leading backslash.
988 Inside here-documents escaping of number signs is NOT required!
990
992 There is a way to access a parsed config the OO-way. Use the module
993 Config::General::Extended, which is supplied with the Config::General
994 distribution.
995
997 You can use variables inside your config files if you like. To do that
998 you have to use the module Config::General::Interpolated, which is
999 supplied with the Config::General distribution.
1000
1002 Config::General exports some functions too, which makes it somewhat
1003 easier to use it, if you like this.
1004 How to import the functions:
1006 use Config::General qw(ParseConfig SaveConfig SaveConfigString);
1008 ParseConfig()
1010 This function takes exactly all those parameters, which are allowed
1011 to the new() method of the standard interface.
1012 Example:
1014 use Config::General qw(ParseConfig);
1016 my %config = ParseConfig(-ConfigFile => "rcfile", -AutoTrue => 1);
1017 SaveConfig()
1019 This function requires two arguments, a filename and a reference to
1020 a hash structure.
1021 Example:
1023 use Config::General qw(SaveConfig);
1025 ..
1026 SaveConfig("rcfile", \%some_hash);
1027 SaveConfigString()
1029 This function requires a reference to a config hash as parameter.
1030 It generates a configuration based on this hash as the object-
1031 interface method save_string() does.
1032 Example:
1034 use Config::General qw(ParseConfig SaveConfigString);
1036 my %config = ParseConfig(-ConfigFile => "rcfile");
1037 .. # change %config something
1038 my $content = SaveConfigString(\%config);
1039
1041 No environment variables will be used.
1042
1044 I recommend you to read the following documents, which are supplied
1045 with Perl:
1046 perlreftut Perl references short introduction
1048 perlref Perl references, the rest of the story
1049 perldsc Perl data structures intro
1050 perllol Perl data structures: arrays of arrays
1051 Config::General::Extended Object oriented interface to parsed configs
1053 Config::General::Interpolated Allows to use variables inside config files
1054
1056 Copyright (c) 2000-2010 Thomas Linden
1057 This library is free software; you can redistribute it and/or modify it
1059 under the same terms as Perl itself.
1060
1062 See rt.cpan.org for current bugs, if any.
1063
1065 None known.
1066
1068 To debug Config::General use the Perl debugger, see perldebug.
1069
1071 Config::General depends on the modules FileHandle,
1072 File::Spec::Functions, File::Glob, which all are shipped with Perl.
1073
1075 Thomas Linden <tlinden |AT| cpan.org>
1076
1078 2.50
1079perl v5.12.2 2010-12-01 General(3)