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;
18 my %config = ParseConfig("rcfile");
19
21 This module opens a config file and parses it's 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 it's asso‐
24 ciated 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% com‐
28 patible to apache configs, but you can also just use simple name/value
29 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 contain‐
75 ing the whole config line by line. The parser will parse the
76 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 dis‐
86 allowed. The default is "yes". i.e.:
87 -AllowMultiOptions => "no"
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 subdi‐
120 rectories. 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 pat‐
127 terns, * will not match dot-files, so <<include dir/*>> is
128 often more desirable than including a directory with
129 -IncludeDirectories.
130 -ConfigPath
132 As mentioned above, you can use this variable to specify a
133 search path for relative config files which have to be
134 included. Config::General will search within this path for the
135 file if it cannot find the file at the location relative to the
136 current config file.
137 To provide multiple search paths you can specify an array ref‐
139 erence for the path. For example:
140 @path = qw(/usr/lib/perl /nfs/apps/lib /home/lib);
142 ..
143 -ConfigPath => \@path
144 -MergeDuplicateBlocks
146 If set to a true value, then duplicate blocks, that means
147 blocks and named blocks, will be merged into a single one (see
148 below for more details on this). The default behavior of Con‐
149 fig::General is to create an array if some junk in a config
150 appears more than once.
151 -MergeDuplicateOptions
153 If set to a true value, then duplicate options will be merged.
154 That means, if the same option occurs more than once, the last
155 one will be used in the resulting config hash.
156 Setting this option implies -AllowMultiOptions == false unless
158 you set -AllowMultiOptions explicit to 'true'. In this case
159 duplicate blocks are allowed and put into an array but dupcli‐
160 cate options will be merged.
161 -AutoLaunder
163 If set to a true value, then all values in your config file
164 will be laundered to allow them to be used under a -T taint
165 flag. This could be regarded as circumventing the purpose of
166 the -T flag, however, if the bad guys can mess with your config
167 file, you have problems that -T will not be able to stop.
168 AutoLaunder will only handle a config file being read from
169 -ConfigFile.
170 -AutoTrue
172 If set to a true value, then options in your config file, whose
173 values are set to true or false values, will be normalised to 1
174 or 0 respectively.
175 The following values will be considered as true:
177 yes, on, 1, true
179 The following values will be considered as false:
181 no, off, 0, false
183 This effect is case-insensitive, i.e. both "Yes" or "oN" will
185 result in 1.
186 -FlagBits
188 This option takes one required parameter, which must be a hash
189 reference.
190 The supplied hash reference needs to define variables for which
192 you want to preset values. Each variable you have defined in
193 this hash-ref and which occurs in your config file, will cause
194 this variable being set to the preset values to which the value
195 in the config file refers to.
196 Multiple flags can be used, separated by the pipe character ⎪.
198 Well, an example will clarify things:
200 my $conf = new Config::General(
202 -ConfigFile => "rcfile",
203 -FlagBits => {
204 Mode => {
205 CLEAR => 1,
206 STRONG => 1,
207 UNSECURE => "32bit" }
208 }
209 );
210 In this example we are defining a variable named "Mode" which
212 may contain one or more of "CLEAR", "STRONG" and "UNSECURE" as
213 value.
214 The appropriate config entry may look like this:
216 # rcfile
218 Mode = CLEAR ⎪ UNSECURE
219 The parser will create a hash which will be the value of the
221 key "Mode". This hash will contain all flags which you have
222 pre-defined, but only those which were set in the config will
223 contain the pre-defined value, the other ones will be unde‐
224 fined.
225 The resulting config structure would look like this after pars‐
227 ing:
228 %config = (
230 Mode => {
231 CLEAR => 1,
232 UNSECURE => "32bit",
233 STRONG => undef,
234 }
235 );
236 This method allows the user (or, the "maintainer" of the con‐
238 figfile for your application) to set multiple pre-defined val‐
239 ues for one option.
240 Please beware, that all occurencies of those variables will be
242 handled this way, there is no way to distinguish between vari‐
243 ables in different scopes. That means, if "Mode" would also
244 occur inside a named block, it would also parsed this way.
245 Values which are not defined in the hash-ref supplied to the
247 parameter -FlagBits and used in the corresponding variable in
248 the config will be ignored.
249 Example:
251 # rcfile
253 Mode = BLAH ⎪ CLEAR
254 would result in this hash structure:
256 %config = (
258 Mode => {
259 CLEAR => 1,
260 UNSECURE => undef,
261 STRONG => undef,
262 }
263 );
264 "BLAH" will be ignored silently.
266 -DefaultConfig
268 This can be a hash reference or a simple scalar (string) of a
269 config. This causes the module to preset the resulting config
270 hash with the given values, which allows you to set default
271 values for particular config options directly.
272 -Tie
274 -Tie takes the name of a Tie class as argument that each new
275 hash should be based off of.
276 This hash will be used as the 'backing hash' instead of a stan‐
278 dard perl hash, which allows you to affect the way, variable
279 storing will be done. You could, for example supply a tied
280 hash, say Tie::DxHash, which preserves ordering of the keys in
281 the config (which a standard perl hash won't do). Or, you could
282 supply a hash tied to a DBM file to save the parsed variables
283 to disk.
284 There are many more things to do in tie-land, see tie to get
286 some interesting ideas.
287 If you want to use the -Tie feature together with -DefaultCon‐
289 fig make sure that the hash supplied to -DefaultConfig must be
290 tied to the same Tie class.
291 Make sure that the hash which receives the generated hash
293 structure (e.g. which you are using in the assignment: %hash =
294 $config->getall()) must be tied to the same Tie class.
295 Example:
297 use Config::General;
299 use Tie::IxHash;
300 tie my %hash, "Tie::IxHash";
301 %hash = ParseConfig(
302 -ConfigFile => shift(),
303 -Tie => "Tie::IxHash"
304 );
305 -InterPolateVars
307 If set to a true value, variable interpolation will be done on
308 your config input. See Config::General::Interpolated for more
309 informations.
310 -InterPolateEnv
312 If set to a true value, environment variables can be used in
313 configs.
314 This implies -InterPolateVars.
316 -ExtendedAccess
318 If set to a true value, you can use object oriented (extended)
319 methods to access the parsed config. See Config::Gen‐
320 eral::Extended for more informations.
321 -StrictObjects
323 By default this is turned on, which causes Config::General to
324 croak with an error if you try to access a non-existent key
325 using the oop-way (-ExtendedAcess enabled). If you turn -Stric‐
326 tObjects off (by setting to 0 or "no") it will just return an
327 empty object/hash/scalar. This is valid for OOP-access 8via
328 AUTOLOAD and for the methods obj(), hash() and value().
329 -StrictVars
331 By default this is turned on, which causes Config::General to
332 croak with an error if an undefined variable with InterPolate‐
333 Vars turned on occurs in a config. Set to false (i.e. 0) to
334 avoid such error messages.
335 -SplitPolicy
337 You can influence the way how Config::General decides which
338 part of a line in a config file is the key and which one is the
339 value. By default it tries it's best to guess. That means you
340 can mix equalsign assignments and whitespace assignments.
341 However, somtimes you may wish to make it more strictly for
343 some reason. In this case you can set -SplitPolicy. The possi‐
344 ble values are: 'guess' which is the default, 'whitespace'
345 which causes the module to split by whitespace, 'equalsign'
346 which causes it to split strictly by equal sign, or 'custom'.
347 In the latter case you must also set -SplitDelimiter to some
348 regular expression of your choice. For example:
349 -SplitDelimiter => '\s*:\s*'
351 will cause the module to split by colon while whitespaces which
353 surrounds the delimiter will be removed.
354 Please note that the delimiter used when saving a config
356 (save_file() or save_string()) will be choosen accordingto the
357 current -SplitPolicy. If -SplitPolicy is set to 'guess' or
358 'whitespace', 3 whitespaces will be used to delimit saved
359 options. If 'custom' is set, then you need to set -StoreDelim‐
360 iter.
361 -SplitDelimiter
363 Set this to any arbitrary regular expression which will be used
364 for option/value splitting. -SplitPolicy must be set to 'cus‐
365 tom' to make this work.
366 -StoreDelimiter
368 You can use this parameter to specify a custom delimiter to use
369 when saving configs to a file or string. You only need to set
370 it if you want to store the config back to disk and if you have
371 -SplitPolicy set to 'custom'.
372 Be very carefull with this parameter.
374 -CComments
376 Config::General is able to notice c-style comments (see section
377 COMMENTS). But for some reason you might no need this. In this
378 case you can turn this feature off by setting -CComments to a
379 false value('no', 0, 'off').
380 By default -CComments is turned on.
382 -BackslashEscape
384 If you turn on this parameter, a backslash can be used to
385 escape any special character within configurations.
386 By default it is turned off.
388 -SlashIsDirectory
390 If you turn on this parameter, a single slash as the last char‐
391 acter of a named block will be considered as a directory name.
392 By default this flag is turned off, which makes the module
394 somewhat incompatible to apache configs, since such a setup
395 will be normally considered as an explicit empty block, just as
396 XML defines it.
397 For example, if you have the following config:
399 <Directory />
401 Index index.awk
402 </Directory>
403 you will get such an error message from the parser:
405 EndBlock "</Directory>" has no StartBlock statement (level: 1, chunk 10)!
407 This is caused by the fact that the config chunk below will be
409 internally converted to:
410 <Directory><Directory />
412 Index index.awk
413 </Directory>
414 Now there is one '</Directory>' too much. The proper solution
416 is to use quotation to circumvent this error:
417 <Directory "/">
419 Index index.awk
420 </Directory>
421 However, a raw apache config comes without such quotes. In this
423 case you may consider to turn on -SlashIsDirectory.
424 Please note that this is a new option (incorporated in version
426 2.30), it may lead to various unexpected sideeffects or other
427 failures. You've been warned.
428 -ApacheCompatible
430 Over the past years a lot of options has been incorporated into
431 Config::General to be able to parse real apache configs.
432 The new -ApacheCompatible option now makes it possible to tweak
434 all options in a way that apache configs can be parsed.
435 This is called "apache compatibility mode" - if you will ever
437 have problems with parsing apache configs without this option
438 being set, you'll get no help by me. Thanks :)
439 The following options will be set:
441 UseApacheInclude = 1
443 IncludeRelative = 1
444 IncludeDirectories = 1
445 IncludeGlob = 1
446 SpashIsDirectory = 1
447 SplitPolicy = 'equalsign'
448 CComments = 0
449 BackslashEscape = 1
450 Take a look into the particular documentation sections what
452 those options are doing.
453 Beside setting some options it also turns off support for
455 explicit empty blocks.
456 getall()
458 Returns a hash structure which represents the whole config.
459 files()
461 Returns a list of all files read in.
462 save_file()
464 Writes the config hash back to the harddisk. This method takes one
465 or two parameters. The first parameter must be the filename where
466 the config should be written to. The second parameter is optional,
467 it must be a reference to a hash structure, if you set it. If you
468 do not supply this second parameter then the internal config hash,
469 which has already been parsed, will be used.
470 Please note, that any occurence of comments will be ignored by
472 getall() and thus be lost after you call this method.
473 You need also to know that named blocks will be converted to nested
475 blocks (which is the same from the perl point of view). An example:
476 <user hans>
478 id 13
479 </user>
480 will become the following after saving:
482 <user>
484 <hans>
485 id 13
486 </hans>
487 </user>
488 Example:
490 $conf_obj->save_file("newrcfile", \%config);
492 or, if the config has already been parsed, or if it didn't change:
494 $conf_obj->save_file("newrcfile");
496 save_string()
498 This method is equivalent to the previous save_file(), but it does
499 not store the generated config to a file. Instead it returns it as
500 a string, which you can save yourself afterwards.
501 It takes one optional parameter, which must be a reference to a
503 hash structure. If you omit this parameter, the internal config
504 hash, which has already been parsed, will be used.
505 Example:
507 my $content = $conf_obj->save_string(\%config);
509 or:
511 my $content = $conf_obj->save_string();
513
515 Lines begining with # and empty lines will be ignored. (see section
516 COMMENTS!) Spaces at the begining and the end of a line will also be
517 ignored as well as tabulators. If you need spaces at the end or the
518 beginning of a value you can use apostrophs ". An optionline starts
519 with it's name followed by a value. An equalsign is optional. Some
520 possible examples:
521 user max
523 user = max
524 user max
525 If there are more than one statements with the same name, it will cre‐
527 ate an array instead of a scalar. See the example below.
528 The method getall returns a hash of all values.
530
532 You can define a block of options. A block looks much like a block in
533 the wellknown apache config format. It starts with <blockname> and ends
534 with </blockname>. An example:
535 <database>
537 host = muli
538 user = moare
539 dbname = modb
540 dbpass = D4r_9Iu
541 </database>
542 Blocks can also be nested. Here is a more complicated example:
544 user = hans
546 server = mc200
547 db = maxis
548 passwd = D3rf$
549 <jonas>
550 user = tom
551 db = unknown
552 host = mila
553 <tablestructure>
554 index int(100000)
555 name char(100)
556 prename char(100)
557 city char(100)
558 status int(10)
559 allowed moses
560 allowed ingram
561 allowed joice
562 </tablestructure>
563 </jonas>
564 The hash which the method getall returns look like that:
566 print Data::Dumper(\%hash);
568 $VAR1 = {
569 'passwd' => 'D3rf$',
570 'jonas' => {
571 'tablestructure' => {
572 'prename' => 'char(100)',
573 'index' => 'int(100000)',
574 'city' => 'char(100)',
575 'name' => 'char(100)',
576 'status' => 'int(10)',
577 'allowed' => [
578 'moses',
579 'ingram',
580 'joice',
581 ]
582 },
583 'host' => 'mila',
584 'db' => 'unknown',
585 'user' => 'tom'
586 },
587 'db' => 'maxis',
588 'server' => 'mc200',
589 'user' => 'hans'
590 };
591 If you have turned on -LowerCaseNames (see new()) then blocks as in the
593 following example:
594 <Dir>
596 <AttriBUTES>
597 Owner root
598 </attributes>
599 </dir>
600 would produce the following hash structure:
602 $VAR1 = {
604 'dir' => {
605 'attributes' => {
606 'owner => "root",
607 }
608 }
609 };
610 As you can see, the keys inside the config hash are normalized.
612 Please note, that the above config block would result in a valid hash
614 structure, even if -LowerCaseNames is not set! This is because Con‐
615 fig::General does not use the blocknames to check if a block ends,
616 instead it uses an internal state counter, which indicates a block end.
617 If the module cannot find an end-block statement, then this block will
619 be ignored.
620
622 If you need multiple blocks of the same name, then you have to name
623 every block. This works much like apache config. If the module finds a
624 named block, it will create a hashref with the left part of the named
625 block as the key containing one or more hashrefs with the right part of
626 the block as key containing everything inside the block(which may again
627 be nested!). As examples says more than words:
628 # given the following sample
630 <Directory /usr/frisco>
631 Limit Deny
632 Options ExecCgi Index
633 </Directory>
634 <Directory /usr/frik>
635 Limit DenyAll
636 Options None
637 </Directory>
638 # you will get:
640 $VAR1 = {
641 'Directory' => {
642 '/usr/frik' => {
643 'Options' => 'None',
644 'Limit' => 'DenyAll'
645 },
646 '/usr/frisco' => {
647 'Options' => 'ExecCgi Index',
648 'Limit' => 'Deny'
649 }
650 }
651 };
652 You cannot have more than one named block with the same name because it
654 will be stored in a hashref and therefore be overwritten if a block
655 occurs once more.
656
658 The normal behavior of Config::General is to look for whitespaces in
659 block names to decide if it's a named block or just a simple block.
660 Sometimes you may need blocknames which have whitespaces in their
662 names.
663 With named blocks this is no problem, as the module only looks for the
665 first whitespace:
666 <person hugo gera>
668 </person>
669 would be parsed to:
671 $VAR1 = {
673 'person' => {
674 'hugo gera' => {
675 },
676 }
677 };
678 The problem occurs, if you want to have a simple block containing
680 whitespaces:
681 <hugo gera>
683 </hugo gera>
684 This would be parsed as a named block, which is not what you wanted. In
686 this very case you may use quotation marks to indicate that it is not a
687 named block:
688 <"hugo gera">
690 </"hugo gera">
691 The save() method of the module inserts automatically quotation marks
693 in such cases.
694
696 Beside the notation of blocks mentioned above it is possible to use
697 explicit empty blocks.
698 Normally you would write this in your config to define an empty block:
700 <driver Apache>
702 </driver>
703 To save writing you can also write:
705 <driver Apache/>
707 which is the very same as above. This works for normal blocks and for
709 named blocks.
710
712 You may have more than one line of the same option with different val‐
713 ues.
714 Example:
716 log log1
717 log log2
718 log log2
719 You will get a scalar if the option occured only once or an array if it
721 occured more than once. If you expect multiple identical options, then
722 you may need to check if an option occured more than once:
723 $allowed = $hash{jonas}->{tablestructure}->{allowed};
725 if(ref($allowed) eq "ARRAY") {
726 @ALLOWED = @{$allowed};
727 else {
728 @ALLOWED = ($allowed);
729 }
730 The same applies to blocks and named blocks too (they are described in
732 more detail below). For example, if you have the following config:
733 <dir blah>
735 user max
736 </dir>
737 <dir blah>
738 user hannes
739 </dir>
740 then you would end up with a data structure like this:
742 $VAR1 = {
744 'dir' => {
745 'blah' => [
746 {
747 'user' => 'max'
748 },
749 {
750 'user' => 'hannes'
751 }
752 ]
753 }
754 };
755 As you can see, the two identical blocks are stored in a hash which
757 contains an array(-reference) of hashes.
758 Under some rare conditions you might not want this behavior with blocks
760 (and named blocks too). If you want to get one single hash with the
761 contents of both identical blocks, then you need to turn the new()
762 parameter -MergeDuplicateBlocks on (see above). The parsed structure of
763 the example above would then look like this:
764 $VAR1 = {
766 'dir' => {
767 'blah' => [
768 'user' => 'max',
769 'user' => 'hannes'
770 ]
771 }
772 };
773 As you can see, there is only one hash "dir->{blah}" containing multi‐
775 ple "user" entries. As you can also see, turning on -MergeDuplicate‐
776 Blocks does not affect scalar options (i.e. "option = value"). In fact
777 you can tune merging of duplicate blocks and options independent from
778 each other.
779 If you don't want to allow more than one identical options, you may
781 turn it off by setting the flag AllowMultiOptions in the new() method
782 to "no". If turned off, Config::General will complain about multiple
783 occuring options with identical names!
784
786 If you have a config value, which is too long and would take more than
787 one line, you can break it into multiple lines by using the backslash
788 character at the end of the line. The Config::General module will con‐
789 catenate those lines to one single-value.
790 Example:
792 command = cat /var/log/secure/tripwire ⎪ \
794 mail "-s" "report from tripwire" \
795 honey@myotherhost.nl
796 command will become:
798 "cat /var/log/secure/tripwire ⎪ mail "-s" 'report from twire'
799 honey@myotherhost.nl"
800
802 You can also define a config value as a so called "here-document". You
803 must tell the module an identifier which identicates the end of a here
804 document. An identifier must follow a "<<".
805 Example:
807 message <<EOF
809 we want to
810 remove the
811 homedir of
812 root.
813 EOF
814 Everything between the two "EOF" strings will be in the option message.
816 There is a special feature which allows you to use indentation with
818 here documents. You can have any amount of whitespaces or tabulators
819 in front of the end identifier. If the module finds spaces or tabs then
820 it will remove exactly those amount of spaces from every line inside
821 the here-document.
822 Example:
824 message <<EOF
826 we want to
827 remove the
828 homedir of
829 root.
830 EOF
831 After parsing, message will become:
833 we want to
835 remove the
836 homedir of
837 root.
838 because there were the string " " in front of EOF, which were cut‐
840 ted from every line inside the here-document.
841
843 You can include an external file at any posision in your config file
844 using the following statement in your config file:
845 <<include externalconfig.rc>>
847 If you turned on -UseApacheInclude (see new()), then you can also use
849 the following statement to include an external file:
850 include externalconfig.rc
852 This file will be inserted at the position where it was found as if the
854 contents of this file were directly at this position.
855 You can also recurively include files, so an included file may include
857 another one and so on. Beware that you do not recursively load the
858 same file, you will end with an errormessage like "too many open files
859 in system!".
860 By default included files with a relative pathname will be opened from
862 within the current working directory. Under some circumstances it maybe
863 possible to open included files from the directory, where the config‐
864 file resides. You need to turn on the option -IncludeRelative (see
865 new()) if you want that. An example:
866 my $conf = Config::General(
868 -ConfigFile => "/etc/crypt.d/server.cfg"
869 -IncludeRelative => 1
870 );
871 /etc/crypt.d/server.cfg:
873 <<include acl.cfg>>
874 In this example Config::General will try to include acl.cfg from
876 /etc/crypt.d:
877 /etc/crypt.d/acl.cfg
879 The default behavior (if -IncludeRelative is not set!) will be to open
881 just acl.cfg, whereever it is, i.e. if you did a
882 chdir("/usr/local/etc"), then Config::General will include:
883 /usr/local/etc/acl.cfg
885 Include statements can be case insensitive (added in version 1.25).
887 Include statements will be ignored within C-Comments and here-docu‐
889 ments.
890
892 A comment starts with the number sign #, there can be any number of
893 spaces and/or tabstops in front of the #.
894 A comment can also occur after a config statement. Example:
896 username = max # this is the comment
898 If you want to comment out a large block you can use C-style comments.
900 A /* signals the begin of a comment block and the */ signals the end of
901 the comment block. Example:
902 user = max # valid option
904 db = tothemax
905 /*
906 user = andors
907 db = toand
908 */
909 In this example the second options of user and db will be ignored.
911 Please beware of the fact, if the Module finds a /* string which is the
912 start of a comment block, but no matching end block, it will ignore the
913 whole rest of the config file!
914 NOTE: If you require the # character (number sign) to remain in the
916 option value, then you can use a backlsash in front of it, to escape
917 it. Example:
918 bgcolor = \#ffffcc
920 In this example the value of $config{bgcolor} will be "#ffffcc", Con‐
922 fig::General will not treat the number sign as the begin of a comment
923 because of the leading backslash.
924 Inside here-documents escaping of number signs is NOT required!
926
928 There is a way to access a parsed config the OO-way. Use the module
929 Config::General::Extended, which is supplied with the Config::General
930 distribution.
931
933 You can use variables inside your configfiles if you like. To do that
934 you have to use the module Config::General::Interpolated, which is sup‐
935 plied with the Config::General distribution.
936
938 Config::General exports some functions too, which makes it somewhat
939 easier to use it, if you like this.
940 How to import the functions:
942 use Config::General qw(ParseConfig SaveConfig SaveConfigString);
944 ParseConfig()
946 This function takes exactly all those parameters, which are allowed
947 to the new() method of the standard interface.
948 Example:
950 use Config::General;
952 my %config = ParseConfig(-ConfigFile => "rcfile", -AutoTrue => 1);
953 SaveConfig()
955 This function requires two arguments, a filename and a reference to
956 a hash structure.
957 Example:
959 use Config::General;
961 ..
962 SaveConfig("rcfile", \%some_hash);
963 SaveConfigString()
965 This function requires a reference to a config hash as parameter.
966 It generates a configuration based on this hash as the object-
967 interface method save_string() does.
968 Example:
970 use Config::General;
972 my %config = ParseConfig(-ConfigFile => "rcfile");
973 .. # change %config something
974 my $content = SaveConfigString(\%config);
975
977 No environment variables will be used.
978
980 I recommend you to read the following documentations, which are sup‐
981 plied with perl:
982 perlreftut Perl references short introduction
984 perlref Perl references, the rest of the story
985 perldsc Perl data structures intro
986 perllol Perl data structures: arrays of arrays
987 Config::General::Extended Object oriented interface to parsed configs
989 Config::General::Interpolated Allows to use variables inside config files
990
992 Copyright (c) 2000-2007 Thomas Linden
993 This library is free software; you can redistribute it and/or modify it
995 under the same terms as Perl itself.
996
998 See rt.cpan.org for current bugs, if any.
999
1001 None known.
1002
1004 To debug Config::General use the perl debugger, see perldebug.
1005
1007 Config::General depends on the modules FileHandle, File::Spec::Func‐
1008 tions, File::Glob, which all are shipped with perl.
1009
1011 Thomas Linden <tlinden ⎪AT⎪ cpan.org>
1012
1014 2.33
1015perl v5.8.8 2007-04-17 General(3)