table of contents
- NAME
- SYNOPSIS
- DESCRIPTION
- SUBROUTINES/METHODS
- CONFIG FILE FORMAT
- BLOCKS
- NAMED BLOCKS
- WHITESPACE IN BLOCKS
- EXPLICIT EMPTY BLOCKS
- IDENTICAL OPTIONS (ARRAYS)
- LONG LINES
- HERE DOCUMENTS
- INCLUDES
- COMMENTS
- OBJECT ORIENTED INTERFACE
- VARIABLE INTERPOLATION
- EXPORTED FUNCTIONS
- CONFIGURATION AND ENVIRONMENT
- SEE ALSO
- LICENSE AND COPYRIGHT
- BUGS AND LIMITATIONS
- INCOMPATIBILITIES
- DIAGNOSTICS
- DEPENDENCIES
- AUTHOR
- VERSION
General(3pm) | User Contributed Perl Documentation | General(3pm) |
NAME¶
Config::General - Generic Config ModuleSYNOPSIS¶
# # the OOP way use Config::General; $conf = new Config::General("rcfile"); my %config = $conf->getall; # # the procedural way use Config::General qw(ParseConfig SaveConfig SaveConfigString); my %config = ParseConfig("rcfile");
DESCRIPTION¶
This module opens a config file and parses its 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 its 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 simplename/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.
SUBROUTINES/METHODS¶
- new()
- Possible ways to call new():
$conf = new Config::General("rcfile"); $conf = new Config::General(\%somehash); $conf = new Config::General( %options ); # see below for description of possible options
- -ConfigFile
- A filename or a filehandle, i.e.:
-ConfigFile => "rcfile" or -ConfigFile => \$FileHandle
- -ConfigHash
- A hash reference, which will be used as the config, i.e.:
-ConfigHash => \%somehash
- -String
- A string which contains a whole config, or an arrayref
containing the whole config line by line. The parser will parse the
contents of the string instead of a file. i.e:
-String => $complete_config
-String => \@config_lines
- -AllowMultiOptions
- If the value is "no", then multiple identical
options are disallowed. The default is "yes". i.e.:
-AllowMultiOptions => "yes"
- -LowerCaseNames
- If set to a true value, then all options found in the config will be converted to lowercase. This allows you to provide case-in-sensitive configs. The values of the options will not lowercased.
- -UseApacheInclude
- If set to a true value, the parser will consider "include ..." as valid include statement (just like the well known Apache include statement).
- -IncludeRelative
- If set to a true value, included files with a relative path
(i.e. "cfg/blah.conf") will be opened from within the location
of the configfile instead from within the location of the script($0). This
works only if the configfile has a absolute pathname (i.e.
"/etc/main.conf").
- -IncludeDirectories
- If set to a true value, you may specify include a directory, in which case all files inside the directory will be loaded in ASCII order. Directory includes will not recurse into subdirectories. This is comparable to including a directory in Apache-style config files.
- -IncludeGlob
- If set to a true value, you may specify a glob pattern for an include to include all matching files (e.g. <<include conf.d/*.conf>>). Also note that as with standard file patterns, * will not match dot-files, so <<include dir/*>> is often more desirable than including a directory with -IncludeDirectories.
- -IncludeAgain
- If set to a true value, you will be able to include a
sub-configfile multiple times. With the default, false, you will get a
warning about duplicate includes and only the first include will succeed.
- -ConfigPath
- As mentioned above, you can use this variable to specify a
search path for relative config files which have to be included.
Config::General will search within this path for the file if it cannot
find the file at the location relative to the current config file.
@path = qw(/usr/lib/perl /nfs/apps/lib /home/lib); .. -ConfigPath => \@path
- -MergeDuplicateBlocks
- If set to a true value, then duplicate blocks, that means blocks and named blocks, will be merged into a single one (see below for more details on this). The default behavior of Config::General is to create an array if some junk in a config appears more than once.
- -MergeDuplicateOptions
- If set to a true value, then duplicate options will be
merged. That means, if the same option occurs more than once, the last one
will be used in the resulting config hash.
- -AutoLaunder
- If set to a true value, then all values in your config file will be laundered to allow them to be used under a -T taint flag. This could be regarded as circumventing the purpose of the -T flag, however, if the bad guys can mess with your config file, you have problems that -T will not be able to stop. AutoLaunder will only handle a config file being read from -ConfigFile.
- -AutoTrue
- If set to a true value, then options in your config file,
whose values are set to true or false values, will be normalised to 1 or 0
respectively.
yes, on, 1, true
no, off, 0, false
- -FlagBits
- This option takes one required parameter, which must be a
hash reference.
my $conf = new Config::General( -ConfigFile => "rcfile", -FlagBits => { Mode => { CLEAR => 1, STRONG => 1, UNSECURE => "32bit" } } );
# rcfile Mode = CLEAR | UNSECURE
%config = ( Mode => { CLEAR => 1, UNSECURE => "32bit", STRONG => undef, } );
# rcfile Mode = BLAH | CLEAR
%config = ( Mode => { CLEAR => 1, UNSECURE => undef, STRONG => undef, } );
- -DefaultConfig
- This can be a hash reference or a simple scalar (string) of a config. This causes the module to preset the resulting config hash with the given values, which allows you to set default values for particular config options directly.
- -Tie
- -Tie takes the name of a Tie class as argument that
each new hash should be based off of.
use Config::General qw(ParseConfig); use Tie::IxHash; tie my %hash, "Tie::IxHash"; %hash = ParseConfig( -ConfigFile => shift(), -Tie => "Tie::IxHash" );
- -InterPolateVars
- If set to a true value, variable interpolation will be done on your config input. See Config::General::Interpolated for more information.
- -InterPolateEnv
- If set to a true value, environment variables can be used
in configs.
- -AllowSingleQuoteInterpolation
- By default variables inside single quotes will not be interpolated. If you turn on this option, they will be interpolated as well.
- -ExtendedAccess
- If set to a true value, you can use object oriented (extended) methods to access the parsed config. See Config::General::Extended for more informations.
- -StrictObjects
- By default this is turned on, which causes Config::General to croak with an error if you try to access a non-existent key using the OOP-way ( -ExtendedAcess enabled). If you turn -StrictObjects off (by setting to 0 or "no") it will just return an empty object/hash/scalar. This is valid for OOP-access 8via AUTOLOAD and for the methods obj(), hash() and value().
- -StrictVars
- By default this is turned on, which causes Config::General to croak with an error if an undefined variable with InterPolateVars turned on occurs in a config. Set to false (i.e. 0) to avoid such error messages.
- -SplitPolicy
- You can influence the way how Config::General decides which
part of a line in a config file is the key and which one is the value. By
default it tries its best to guess. That means you can mix equalsign
assignments and whitespace assignments.
-SplitDelimiter => '\s*:\s*'
- -SplitDelimiter
- Set this to any arbitrary regular expression which will be used for option/value splitting. -SplitPolicy must be set to 'custom' to make this work.
- -StoreDelimiter
- You can use this parameter to specify a custom delimiter to
use when saving configs to a file or string. You only need to set it if
you want to store the config back to disk and if you have
-SplitPolicy set to 'custom'.
- -CComments
- Config::General is able to notice c-style comments (see
section COMMENTS). But for some reason you might no need this. In this
case you can turn this feature off by setting -CComments to a false
value('no', 0, 'off').
- -BackslashEscape
- Deprecated Option.
- -SlashIsDirectory
- If you turn on this parameter, a single slash as the last
character of a named block will be considered as a directory name.
<Directory /> Index index.awk </Directory>
EndBlock "</Directory>" has no StartBlock statement (level: 1, chunk 10)!
<Directory></Directory> Index index.awk </Directory>
<Directory "/"> Index index.awk </Directory>
- -ApacheCompatible
- Over the past years a lot of options has been incorporated
into Config::General to be able to parse real Apache configs.
UseApacheInclude = 1 IncludeRelative = 1 IncludeDirectories = 1 IncludeGlob = 1 SlashIsDirectory = 1 SplitPolicy = 'equalsign' CComments = 0
- -UTF8
- If turned on, all files will be opened in utf8 mode. This may not work properly with older versions of Perl.
- -SaveSorted
- If you want to save configs in a sorted manner, turn this parameter on. It is not enabled by default.
- getall()
- Returns a hash structure which represents the whole config.
- files()
- Returns a list of all files read in.
- save_file()
- Writes the config hash back to the hard disk. This method
takes one or two parameters. The first parameter must be the filename
where the config should be written to. The second parameter is optional,
it must be a reference to a hash structure, if you set it. If you do not
supply this second parameter then the internal config hash, which has
already been parsed, will be used.
<user hans> id 13 </user>
<user> <hans> id 13 </hans> </user>
$conf_obj->save_file("newrcfile", \%config);
$conf_obj->save_file("newrcfile");
- save_string()
- This method is equivalent to the previous
save_file(), but it does not store the generated config to a file.
Instead it returns it as a string, which you can save yourself afterwards.
my $content = $conf_obj->save_string(\%config);
my $content = $conf_obj->save_string();
CONFIG FILE FORMAT¶
Lines beginning with # and empty lines will be ignored. (see section COMMENTS!) Spaces at the beginning 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 surround it with double quotes. An option line starts with its name followed by a value. An equal sign 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 you have turned on -LowerCaseNames (see new()) then blocks as in the following example:
<Dir> <AttriBUTES> Owner root </attributes> </dir>would produce the following hash structure:
$VAR1 = { 'dir' => { 'attributes' => { 'owner => "root", } } };As you can see, the keys inside the config hash are normalized. Please note, that the above config block would result in a valid hash structure, even if -LowerCaseNames is not set! This is because Config::General does not use the block names to check if a block ends, instead it uses an internal state counter, which indicates a block end. If the module cannot find an end-block statement, then this block will be ignored.
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.
WHITESPACE IN BLOCKS¶
The normal behavior of Config::General is to look for whitespace in block names to decide if it's a named block or just a simple block. Sometimes you may need blocknames which have whitespace in their names. With named blocks this is no problem, as the module only looks for the first whitespace:<person hugo gera> </person>would be parsed to:
$VAR1 = { 'person' => { 'hugo gera' => { }, } };The problem occurs, if you want to have a simple block containing whitespace:
<hugo gera> </hugo gera>This would be parsed as a named block, which is not what you wanted. In this very case you may use quotation marks to indicate that it is not a named block:
<"hugo gera"> </"hugo gera">The save() method of the module inserts automatically quotation marks in such cases.
EXPLICIT EMPTY BLOCKS¶
Beside the notation of blocks mentioned above it is possible to use explicit empty blocks. Normally you would write this in your config to define an empty block:<driver Apache> </driver>To save writing you can also write:
<driver Apache/>which is the very same as above. This works for normal blocks and for named blocks.
IDENTICAL OPTIONS (ARRAYS)¶
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 occurred only once or an array if it occurred more than once. If you expect multiple identical options, then you may need to check if an option occurred more than once:
$allowed = $hash{jonas}->{tablestructure}->{allowed}; if(ref($allowed) eq "ARRAY") { @ALLOWED = @{$allowed}; else { @ALLOWED = ($allowed); }The same applies to blocks and named blocks too (they are described in more detail below). For example, if you have the following config:
<dir blah> user max </dir> <dir blah> user hannes </dir>then you would end up with a data structure like this:
$VAR1 = { 'dir' => { 'blah' => [ { 'user' => 'max' }, { 'user' => 'hannes' } ] } };As you can see, the two identical blocks are stored in a hash which contains an array(-reference) of hashes. Under some rare conditions you might not want this behavior with blocks (and named blocks too). If you want to get one single hash with the contents of both identical blocks, then you need to turn the new() parameter -MergeDuplicateBlocks on (see above). The parsed structure of the example above would then look like this:
$VAR1 = { 'dir' => { 'blah' => { 'user' => [ 'max', 'hannes' ] } } };As you can see, there is only one hash "dir->{blah}" containing multiple "user" entries. As you can also see, turning on -MergeDuplicateBlocks does not affect scalar options (i.e. "option = value"). In fact you can tune merging of duplicate blocks and options independent from each other. If you don't want to allow more than one identical options, you may turn it off by setting the flag AllowMultiOptions in the new() method to "no". If turned off, Config::General will complain about multiple occurring options with identical names!
FORCE SINGLE VALUE ARRAYS¶
You may also force a single config line to get parsed into an array by turning on the option -ForceArray and by surrounding the value of the config entry by []. Example:hostlist = [ foo.bar ]Will be a singlevalue array entry if the option is turned on. If you want it to remain to be an array you have to turn on -ForceArray during save too.
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 idicates 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 whitespace 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 cut from every line inside the here-document.
INCLUDES¶
You can include an external file at any posision in your config file using the following statement in your config file:<<include externalconfig.rc>>If you turned on -UseApacheInclude (see new()), then you can also use the following statement to include an external file:
include externalconfig.rcThis 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 recursively 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 error message like "too many open files in system!". By default included files with a relative pathname will be opened from within the current working directory. Under some circumstances it maybe possible to open included files from the directory, where the configfile resides. You need to turn on the option -IncludeRelative (see new()) if you want that. An example:
my $conf = Config::General( -ConfigFile => "/etc/crypt.d/server.cfg" -IncludeRelative => 1 ); /etc/crypt.d/server.cfg: <<include acl.cfg>>In this example Config::General will try to include acl.cfg from /etc/crypt.d:
/etc/crypt.d/acl.cfgThe default behavior (if -IncludeRelative is not set!) will be to open just acl.cfg, wherever it is, i.e. if you did a chdir("/usr/local/etc"), then Config::General will include:
/usr/local/etc/acl.cfgInclude statements can be case insensitive (added in version 1.25). Include statements will be ignored within C-Comments and here-documents. By default, a config file will only be included the first time it is referenced. If you wish to include a file in multiple places, set /-IncludeAgain to true. But be warned: this may lead to infinite loops, so make sure, you're not including the same file from within itself! Example:
# main.cfg <object billy> class=Some::Class <printers> include printers.cfg </printers> # ... </object> <object bob> class=Another::Class <printers> include printers.cfg </printers> # ... </object>Now "printers.cfg" will be include in both the "billy" and "bob" objects. You will have to be careful to not recursively include a file. Behaviour in this case is undefined.
COMMENTS¶
A comment starts with the number sign #, there can be any number of spaces and/or tab stops 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 backslash 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!
OBJECT ORIENTED INTERFACE¶
There is a way to access a parsed config the OO-way. Use the module Config::General::Extended, which is supplied with the Config::General distribution.VARIABLE INTERPOLATION¶
You can use variables inside your config files if you like. To do that you have to use the module Config::General::Interpolated, which is supplied with the Config::General distribution.EXPORTED FUNCTIONS¶
Config::General exports some functions too, which makes it somewhat easier to use it, if you like this. How to import the functions:use Config::General qw(ParseConfig SaveConfig SaveConfigString);
- ParseConfig()
- This function takes exactly all those parameters, which are
allowed to the new() method of the standard
interface.
use Config::General qw(ParseConfig); my %config = ParseConfig(-ConfigFile => "rcfile", -AutoTrue => 1);
- SaveConfig()
- This function requires two arguments, a filename and a
reference to a hash structure.
use Config::General qw(SaveConfig); .. SaveConfig("rcfile", \%some_hash);
- SaveConfigString()
- This function requires a reference to a config hash as
parameter. It generates a configuration based on this hash as the
object-interface method save_string() does.
use Config::General qw(ParseConfig SaveConfigString); my %config = ParseConfig(-ConfigFile => "rcfile"); .. # change %config something my $content = SaveConfigString(\%config);
CONFIGURATION AND ENVIRONMENT¶
No environment variables will be used.SEE ALSO¶
I recommend you to read the following documents, which are supplied with Perl:perlreftut Perl references short introduction perlref Perl references, the rest of the story perldsc Perl data structures intro perllol Perl data structures: arrays of arrays Config::General::Extended Object oriented interface to parsed configs Config::General::Interpolated Allows to use variables inside config files
LICENSE AND COPYRIGHT¶
Copyright (c) 2000-2010 Thomas Linden This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.BUGS AND LIMITATIONS¶
See rt.cpan.org for current bugs, if any.INCOMPATIBILITIES¶
None known.DIAGNOSTICS¶
To debug Config::General use the Perl debugger, see perldebug.DEPENDENCIES¶
Config::General depends on the modules FileHandle, File::Spec::Functions, File::Glob, which all are shipped with Perl.AUTHOR¶
Thomas Linden <tlinden |AT| cpan.org>VERSION¶
2.502010-12-01 | perl v5.10.1 |