NAME
Config::General - Generic Config Module
SYNOPSIS
use Config::General;
$conf = new Config::General("rcfile");
my %config = $conf->getall;
# or
$conf = new Config::General(\%somehash);DESCRIPTION
This small module opens a config file and parses it's contents for you. The new method requires one parameter which needs to be a filename. The method getall returns a hash which contains all options and it's associated values of your config file.
The format of config files supported by Config::General is inspired by the well known apache config format, in fact, this module is 100% compatible to apache configs, but you can also just use simple name/value pairs in your config files.
In addition to the capabilities of an apache config file it supports some enhancements such as here-documents, C-style comments or multiline options.
METHODS
- new()
-
Possible ways to call new():
$conf = new Config::General("rcfile"); $conf = new Config::General(\%somehash); $conf = new Config::General( -file => "rcfile", -AllowMultiOptions => "no" ); $conf = new Config::General( -hash => \%somehash, );This method returns a Config::General object (a hash blessed into "Config::General" namespace. All further methods must be used from that returned object. see below.
You can use the new style with hash parameters or the old style which is of course still supported. Possible parameters are:
a filename of a configfile a hash reference or a hash with one or more of the following keys set: -file - a filename. -hash - a hash reference. -AllowMultiOptions - if the value is "no", then multiple identical options are disallowed. - NoMultiOptions()
-
This method only exists for compatibility reasons. Now you should set the new() flag -AllowMultiOptions to "no".
- The old description: This Turns off the feature of allwing multiple options with identical names. The default behavior is to create an array if an option occurs more than once. But under certain circumstances you may not be willed to allow that. In this case use this method before you call getall to turn it off.
Please note, that there is no method provided to turn this feature on.
- getall()
-
Returns a hash structure which represents the whole config.
- save("filename", %confighash)
-
Writes the config hash back to the harddisk. Please note, that any occurence of comments will be ignored and thus be lost after you called this method.
You need also to know that named blocks will be converted to nested blocks (which is the same from the perl point of view). An example:
<user hans> id 13 </user>will become the following after saving:
<user> <hans> id 13 </hans> </user>
CONFIG FILE FORMAT
Lines begining with # and empty lines will be ignored. (see section COMMENTS!) Spaces at the begining and the end of a line will also be ignored as well as tabulators. If you need spaces at the end or the beginning of a value you can use apostrophs ". An optionline starts with it's name followed by a value. An equalsign is optional. Some possible examples:
user max
user = max
user maxIf there are more than one statements with the same name, it will create an array instead of a scalar. See the example below.
The method getall returns a hash of all values.
BLOCKS
You can define a block of options. A block looks much like a block in the wellknown apache config format. It starts with <blockname> and ends with </blockname>. An example:
<database>
host = muli
user = moare
dbname = modb
dbpass = D4r_9Iu
</database>Blocks can also be nested. Here is a more complicated example:
user = hans
server = mc200
db = maxis
passwd = D3rf$
<jonas>
user = tom
db = unknown
host = mila
<tablestructure>
index int(100000)
name char(100)
prename char(100)
city char(100)
status int(10)
allowed moses
allowed ingram
allowed joice
</tablestructure>
</jonas>The hash which the method getall returns look like that:
print Data::Dumper(\%hash);
$VAR1 = {
'passwd' => 'D3rf$',
'jonas' => {
'tablestructure' => {
'prename' => 'char(100)',
'index' => 'int(100000)',
'city' => 'char(100)',
'name' => 'char(100)',
'status' => 'int(10)',
'allowed' => [
'moses',
'ingram',
'joice',
]
},
'host' => 'mila',
'db' => 'unknown',
'user' => 'tom'
},
'db' => 'maxis',
'server' => 'mc200',
'user' => 'hans'
};If the module cannot find an end-block statement, then this block will be ignored.
IDENTICAL OPTIONS
You may have more than one line of the same option with different values.
Example: log log1 log log2 log log2
You will get a scalar if the option occured only once or an array if it occured more than once. If you expect multiple identical options, then you may need to check if an option occured more than once:
$allowed = $hash{jonas}->{tablestructure}->{allowed};
if(ref($allowed) eq "ARRAY") {
@ALLOWED = @{$allowed};
else {
@ALLOWED = ($allowed);
}If you don't want to allow more than one identical options, you may turn it off by setting the flag AllowMutliOptions in the new() method to "no". If turned off, Config::General will complain about multiple occuring options whit identical names!
NAMED BLOCKS
If you need multiple blocks of the same name, then you have to name every block. This works much like apache config. If the module finds a named block, it will create a hashref with the left part of the named block as the key containing one or more hashrefs with the right part of the block as key containing everything inside the block(which may again be nested!). As examples says more than words:
# given the following sample
<Directory /usr/frisco>
Limit Deny
Options ExecCgi Index
</Directory>
<Directory /usr/frik>
Limit DenyAll
Options None
</Directory>
# you will get:
$VAR1 = {
'Directory' => {
'/usr/frik' => {
'Options' => 'None',
'Limit' => 'DenyAll'
},
'/usr/frisco' => {
'Options' => 'ExecCgi Index',
'Limit' => 'Deny'
}
}
};You cannot have more than one named block with the same name because it will be stored in a hashref and therefore be overwritten if a block occurs once more.
LONG LINES
If you have a config value, which is too long and would take more than one line, you can break it into multiple lines by using the backslash character at the end of the line. The Config::General module will concatenate those lines to one single-value.
Example:
command = cat /var/log/secure/tripwire | \ mail -s "report from tripwire" \ honey@myotherhost.nl
command will become: "cat /var/log/secure/tripwire | mail -s 'report from twire' honey@myotherhost.nl"
HERE DOCUMENTS
You can also define a config value as a so called "here-document". You must tell the module an identifier which identicates the end of a here document. An identifier must follow a "<<".
Example:
message <<EOF
we want to
remove the
homedir of
root.
EOFEverything between the two "EOF" strings will be in the option message.
There is a special feature which allows you to use indentation with here documents. You can have any amount of whitespaces or tabulators in front of the end identifier. If the module finds spaces or tabs then it will remove exactly those amount of spaces from every line inside the here-document.
Example:
message <<EOF
we want to
remove the
homedir of
root.
EOFAfter parsing, message will become:
we want to
remove the
homedir of
root.because there were the string " " in front of EOF, which were cutted from every line inside the here-document.
INCLUDES
You can include an external file at any posision in you config file using the following statement in your config file:
<<include externalconfig.rc>>This file will be inserted at the position where it was found as if the contents of this file were directly at this position.
You can also recurively include files, so an included file may include another one and so on. Beware that you do not recursively load the same file, you will end with an errormessage like "too many files in system!".
Include statements will be ignored within C-Comments and here-documents.
COMMENTS
A comment starts with the number sign #, there can be any number of spaces and/or tabstops in front of the #.
A comment can also occur after a config statement. Example:
username = max # this is the commentIf you want to comment out a large block you can use C-style comments. A /* signals the begin of a comment block and the */ signals the end of the comment block. Example:
user = max # valid option
db = tothemax
/*
user = andors
db = toand
*/In this example the second options of user and db will be ignored. Please beware of the fact, if the Module finds a /* string which is the start of a comment block, but no matching end block, it will ignore the whole rest of the config file!
NOTE: If you require the # character (number sign) to remain in the option value, then you can use a backlsash in front of it, to escape it. Example:
bgcolor = \#ffffccIn this example the value of $config{bgcolor} will be "#ffffcc", Config::General will not treat the number sign as the begin of a comment because of the leading backslash.
Inside here-documents escaping of number signs is NOT required!
COPYRIGHT
Copyright (c) 2000-2001 Thomas Linden
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
BUGS
none known yet.
AUTHOR
Thomas Linden <tom@daemon.de>
VERSION
1.20