|
|
| |
General(3) |
User Contributed Perl Documentation |
General(3) |
Config::General - Generic Config Module
#
# the OOP way
use Config::General;
$conf = Config::General->new("rcfile");
my %config = $conf->getall;
#
# the procedural way
use Config::General qw(ParseConfig SaveConfig SaveConfigString);
my %config = ParseConfig("rcfile");
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 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.
- new()
- Possible ways to call new():
$conf = Config::General->new("rcfile");
$conf = Config::General->new(\%somehash);
$conf = Config::General->new( %options ); # see below for description of possible options
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 to
new() are:
* a filename of a configfile, which will be opened and parsed
by the parser
or
* a hash reference, which will be used as the config.
An alternative way to call new() is
supplying an option- hash with one or more of the following keys
set:
- -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
it is also possible to feed an array reference to -String:
-String => \@config_lines
- -AllowMultiOptions
- If the value is "no", then multiple identical options are
disallowed. The default is "yes". i.e.:
-AllowMultiOptions => "yes"
see IDENTICAL OPTIONS for details.
- -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).
It also supports apache's "IncludeOptional"
statement with the same behavior, that is, if the include file doesn't
exist no error will be thrown.
- -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").
If the variable -ConfigPath has been set and if the
file to be included could not be found in the location relative to the
current config file, the module will search within -ConfigPath
for the file. See the description of -ConfigPath for more
details.
- -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.
An include option will not cause a parser error if the glob
didn't return anything.
- -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.
Reincluding a configfile can be useful if it contains data
that you want to be present in multiple places in the data tree. See the
example under "INCLUDES".
Note, however, that there is currently no check for include
recursion.
- -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.
To provide multiple search paths you can specify an array
reference for the path. For example:
@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.
Setting this option implies -AllowMultiOptions == false
unless you set -AllowMultiOptions explicit to 'true'. In this
case duplicate blocks are allowed and put into an array but duplicate
options will be merged.
- -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.
The following values will be considered as true:
yes, on, 1, true
The following values will be considered as false:
no, off, 0, false
This effect is case-insensitive, i.e. both "Yes" or
"No" will result in 1.
- -FlagBits
- This option takes one required parameter, which must be a hash reference.
The supplied hash reference needs to define variables for
which you want to preset values. Each variable you have defined in this
hash-ref and which occurs in your config file, will cause this variable
being set to the preset values to which the value in the config file
refers to.
Multiple flags can be used, separated by the pipe character
|.
Well, an example will clarify things:
my $conf = Config::General->new(
-ConfigFile => "rcfile",
-FlagBits => {
Mode => {
CLEAR => 1,
STRONG => 1,
UNSECURE => "32bit" }
}
);
In this example we are defining a variable named
"Mode" which may contain one or more of
"CLEAR", "STRONG" and "UNSECURE" as
value.
The appropriate config entry may look like this:
# rcfile
Mode = CLEAR | UNSECURE
The parser will create a hash which will be the value of the
key "Mode". This hash will contain all flags which you
have pre-defined, but only those which were set in the config will
contain the pre-defined value, the other ones will be undefined.
The resulting config structure would look like this after
parsing:
%config = (
Mode => {
CLEAR => 1,
UNSECURE => "32bit",
STRONG => undef,
}
);
This method allows the user (or, the "maintainer" of
the configfile for your application) to set multiple pre-defined values
for one option.
Please beware, that all occurrences of those variables will be
handled this way, there is no way to distinguish between variables in
different scopes. That means, if "Mode" would also occur
inside a named block, it would also parsed this way.
Values which are not defined in the hash-ref supplied to the
parameter -FlagBits and used in the corresponding variable in the
config will be ignored.
Example:
# rcfile
Mode = BLAH | CLEAR
would result in this hash structure:
%config = (
Mode => {
CLEAR => 1,
UNSECURE => undef,
STRONG => undef,
}
);
"BLAH" will be ignored silently.
- -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.
Note that you probably want to use this with
-MergeDuplicateOptions, otherwise a default value already in the
configuration file will produce an array of two values.
- -Tie
- -Tie takes the name of a Tie class as argument that each new hash
should be based off of.
This hash will be used as the 'backing hash' instead of a
standard Perl hash, which allows you to affect the way, variable storing
will be done. You could, for example supply a tied hash, say
Tie::DxHash, which preserves ordering of the keys in the config (which a
standard Perl hash won't do). Or, you could supply a hash tied to a DBM
file to save the parsed variables to disk.
There are many more things to do in tie-land, see tie to get
some interesting ideas.
If you want to use the -Tie feature together with
-DefaultConfig make sure that the hash supplied to
-DefaultConfig must be tied to the same Tie class.
Make sure that the hash which receives the generated hash
structure (e.g. which you are using in the assignment:
%hash =
$config->getall()) must be tied to the
same Tie class.
Example:
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.
This implies -InterPolateVars.
- -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
information.
- -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.
However, sometime you may wish to make it more strictly for
some reason. In this case you can set -SplitPolicy. The possible
values are: 'guess' which is the default, 'whitespace' which causes the
module to split by whitespace, 'equalsign' which causes it to split
strictly by equal sign, or 'custom'. In the latter case you must also
set -SplitDelimiter to some regular expression of your choice.
For example:
-SplitDelimiter => '\s*:\s*'
will cause the module to split by colon while whitespace which
surrounds the delimiter will be removed.
Please note that the delimiter used when saving a config
(save_file() or save_string()) will be chosen according to
the current -SplitPolicy. If -SplitPolicy is set to 'guess' or
'whitespace', 3 spaces will be used to delimit saved options. If
'custom' is set, then you need to set -StoreDelimiter.
- -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'.
However, this parameter takes precedence over whatever is set
for -SplitPolicy.
Be very careful with this parameter.
- -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').
By default -CComments is turned on.
- -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.
By default this flag is turned off, which makes the module
somewhat incompatible to Apache configs, since such a setup will be
normally considered as an explicit empty block, just as XML defines
it.
For example, if you have the following config:
<Directory />
Index index.awk
</Directory>
you will get such an error message from the parser:
EndBlock "</Directory>" has no StartBlock statement (level: 1, chunk 10)!
This is caused by the fact that the config chunk below will be
internally converted to:
<Directory></Directory>
Index index.awk
</Directory>
Now there is one '</Directory>' too much. The proper
solution is to use quotation to circumvent this error:
<Directory "/">
Index index.awk
</Directory>
However, a raw apache config comes without such quotes. In
this case you may consider to turn on -SlashIsDirectory.
Please note that this is a new option (incorporated in version
2.30), it may lead to various unexpected side effects or other failures.
You've been warned.
- -UseApacheIfDefine
- Enables support for Apache <IfDefine> ... </IfDefine>. See
-Define.
- -Define
- Defines the symbols to be used for conditional configuration files.
Allowed arguments: scalar, scalar ref, array ref or hash ref.
Examples:
-Define => 'TEST'
-Define => \$testOrProduction
-Define => [qw(TEST VERBOSE)]
-Define => {TEST => 1, VERBOSE => 1}
Sample configuration:
<Logging>
<IfDefine TEST>
Level Debug
include test/*.cfg
</IfDef>
<IfDefine !TEST>
Level Notice
include production/*.cfg
</IfDefine>
</Logging>
- -ApacheCompatible
- Over the past years a lot of options has been incorporated into
Config::General to be able to parse real Apache configs.
The new -ApacheCompatible option now makes it possible
to tweak all options in a way that Apache configs can be parsed.
This is called "apache compatibility mode" - if you
will ever have problems with parsing Apache configs without this option
being set, you'll get no help by me. Thanks :)
The following options will be set:
UseApacheInclude = 1
IncludeRelative = 1
IncludeDirectories = 1
IncludeGlob = 1
SlashIsDirectory = 1
SplitPolicy = 'whitespace'
CComments = 0
UseApacheIfDefine = 1
Take a look into the particular documentation sections what
those options are doing.
Beside setting some options it also turns off support for
explicit empty blocks.
- -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.
- -NoEscape
- If you want to use the data ( scalar or final leaf ) without escaping
special character, turn this parameter on. It is not enabled by
default.
- -NormalizeBlock
- Takes a subroutine reference as parameter and gets the current block or
blockname passed as parameter and is expected to return it in some altered
way as a scalar string. The sub will be called before anything else will
be done by the module itself (e.g. interpolation).
Example:
-NormalizeBlock => sub { my $x = shift; $x =~ s/\s*$//; $x; }
This removes trailing whitespaces of block names.
- -NormalizeOption
- Same as -NormalizeBlock but applied on options only.
- -NormalizeValue
- Same as -NormalizeBlock but applied on values only.
- 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.
Please note that any occurrence of comments will be ignored by
getall() and thus be lost after you call 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>
Example:
$conf_obj->save_file("newrcfile", \%config);
or, if the config has already been parsed, or if it didn't
change:
$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.
It takes one optional parameter, which must be a reference to
a hash structure. If you omit this parameter, the internal config hash,
which has already been parsed, will be used.
Example:
my $content = $conf_obj->save_string(\%config);
or:
my $content = $conf_obj->save_string();
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 max
If 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.
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>.
A block start and end cannot be on the same line.
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.
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.
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.
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.
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!
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.
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 C<-s> "report from tripwire" \
honey@myotherhost.nl
command will become: "cat /var/log/secure/tripwire | mail
"-s" 'report from twire'
honey@myotherhost.nl"
You can also define a config value as a so called "here-document". You
must tell the module an identifier which indicates the end of a here document.
An identifier must follow a "<<".
Example:
message <<EOF
we want to
remove the
homedir of
root.
EOF
Everything 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.
EOF
After 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.
You can include an external file at any position 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.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 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.cfg
The 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.cfg
Include 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.
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 comment
If 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 = \#ffffcc
In 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!
You can alter the behavior of the parser by supplying closures which will be
called on certain hooks during config file processing and parsing.
The general aproach works like this:
sub ck {
my($file, $base) = @_;
print "_open() tries $file ... ";
if ($file =~ /blah/) {
print "ignored\n";
return (0);
} else {
print "allowed\n";
return (1, @_);
}
}
my %c = ParseConfig(
-IncludeGlob => 1,
-UseApacheInclude => 1,
-ConfigFile => shift,
-Plug => { pre_open => *ck }
);
Output:
_open() tries cfg ... allowed
_open() tries x/*.conf ... allowed
_open() tries x/1.conf ... allowed
_open() tries x/2.conf ... allowed
_open() tries x/blah.conf ... ignored
As you can see, we wrote a little sub which takes a filename and a
base directory as parameters. We tell Config::General via the Plug
parameter of new() to call this sub everytime before it
attempts to open a file.
General processing continues as usual if the first value of the
returned array is true. The second value of that array depends on the kind
of hook being called.
The following hooks are available so far:
- pre_open
- Takes two parameters: filename and basedirectory.
Has to return an array consisting of 3 values:
- 1 or 0 (continue processing or not)
- filename
- base directory
- pre_read
- Takes two parameters: the filehandle of the file to be read and an array
containing the raw contents of said file.
This hook will be applied in _read(). File contents are
already available at this stage, comments will be removed, here-docs
normalized and the like. This hook gets the unaltered, original
contents.
Has to return an array of 3 values:
- 1 or 0 (continue processing or not)
- the filehandle
- an array of strings
You can use this hook to apply your own normalizations or
whatever.
Be careful when returning the abort value (1st value of
returned array 0), since in this case nothing else would be done on the
contents. If it still contains comments or something, they will be
parsed as legal config options.
- post_read
- Takes one parameter: a reference to an array containing the prepared
config lines (after being processed by _read()).
This hook will be applied in _read() when everything
else has been done.
Has to return an array of 2 values:
- 1 or 0 (continue processing or not) [Ignored for post hooks]
- a reference to an array containing the config lines
- pre_parse_value
- Takes 2 parameters: an option name and its value.
This hook will be applied in _parse_value() before any
processing.
Has to return an array of 3 values:
- 1 or 0 (continue processing or not)
- option name
- value of the option
- post_parse_value
- Almost identical to pre_parse_value, but will be applied after
_parse_value() is finished and all usual processing and
normalization is done.
Not implemented yet: hooks for variable interpolation and block
parsing.
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.
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.
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.
Example:
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.
Example:
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.
Example:
use Config::General qw(ParseConfig SaveConfigString);
my %config = ParseConfig(-ConfigFile => "rcfile");
.. # change %config something
my $content = SaveConfigString(\%config);
No environment variables will be used.
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 one to use variables inside config files
Copyright (c) 2000-2016 Thomas Linden
This library is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
See rt.cpan.org for current bugs, if any.
To debug Config::General use the Perl debugger, see perldebug.
Config::General depends on the modules FileHandle, File::Spec::Functions,
File::Glob, which all are shipped with Perl.
Thomas Linden <tlinden |AT| cpan.org>
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc. |