NAME
Config::Simple::Conf - A fast and lightweight configuration file handler
DESCRIPTION
The idea behind Config::Simple::Conf came from various INI style parsers I've used in the past. In general these have worked well with the exception of lack of complex configuration handling.
Config::Simple for example fails to account for common cases which are extremely useful in any configuration file. These include useful handling of duplicate keys (currently Config::Simple blows them away without any notice), and second, internal macros.
In many of my usage cases I want something like your standard .INI file format, with the above mentioned exceptions.
# Define a configuration section
[core section]
# Define an entry in core section
path = /root/to/my/stuff
# Define a new configuration file section
[section name]
# Define an entry list and use the value from another section to complete
# the configuration
path = [core section:path]/abc
path = [core section:path]/xyzSuch a configuration would allow me to do two things, establish a core path argument, which is then used in other sections, and have a section with multiple duplicate entires as a list.
An example of the code here would look something like:
#!/usr/bin/perl
use strict;
use Config::Simple::Conf;
my $conf = Config::Simple::Conf->new('/path/to/my.conf');
print "My root is: " . $conf->value('core section', 'path') . "\n";
print "My section paths are:\n";
for($conf->value('section name', 'path')){
print "\t$_\n";
}With the resulting output looking something like:
My root is: /root/to/my/stuff
My section paths are:
/root/to/my/stuff/abc
/root/to/my/stuff/xyzSYNOPSIS
use Config::Simple::Conf;
my $conf = Config::Simple::Conf->new('/etc/Something/Example.conf');
print $conf->value('global', 'example_key');
HANDLING COMMAND LINE ARGUMENTS
Command line arguments are processed automatically when detected within the @ARGV list. The values of these arguments are represented in the special argv section. Command line arguments can be in either a single or double (-) hash value such as --key or -k
A value can be assigned to each argument as well by either placing the value after the --key value or by using an (=) equals sign --key=value. Multiple duplicate keys can be used to generate a list.
Values may also be macros, so a value could be sourced from a configuration file. An example of this might be --color [colors:red] with the configuration file:
[colors]
red = 255,0,0
green = 0,255,0
blue = 0,0,255@ARGV_CLEAN
An @ARGV like list, cleaned of any arguments which have been captured by the parser.
CONFIG FILE FORMAT
Configuration files are defined as ascii text, with comments lines starting with a pound symbol #, sections, keys, and values. Values may be macro entries referencing other configuration keys.
SECTION
A section is defined as a single line entry with double square brakets [section]:
# Define a section
[section]KEYS
Keys are defined within a section as lines with keyname = value type entry
# Define a value for keyname in section [section]
[section]
keyname = valueUSING A MACRO
Macros are defined as square brakets with a section:key entry between them. These are automatically resolved to other configuration sections and keys and that keys value is utilized.
# Define a value based on a macro
[section2]
key = [section:keyname]
=head2 NOTEMacros may NOT utilize list entries of duplicate macro keys.
SPECIAL MACROS
Currently there are two special macros which perform useful tasks
- include
-
The include key name allows you to include another configuration file with additional configuration information
- die
-
The die key will result in the program dying at that spot with an error dumped to STDERR.
EXAMPLES
# Include another configuration file
include = /some/config.cfg
# Die right here so user changes things
dieAdditionally see the examples/ directory within this libraries distrobution for more configuration file examples
METHODS
new()
Config::Simple::Conf->new(FILE, CFHASH)
Generate / Regenerate the configuration hash reference based on on standard Ruckus configuration files and options.
FILE - The configuratino file to process, if
undefined @ARGV will be processed for
arguments.
CFHASH - An existing configuraiton hash generated
by Config::Simple::Conf in which data should be appended
to.Returns a hash reference with two types of values:
A standard string "abc", and array reference ["a","b","c"]. In cases of unique keys data is stored as a string. In cases were there are multiple duplicate keys data is stored in an array reference.
Keys may make use of other keys values with in the key value.
Example:
[example]
# sets [example:abc] to '123'
abc = 123
# sets [efg] to '123'
efg = [example:abc]
# sets [example:list] to [1, 2, 3]
list = 1
list = 2
list = 3When making use of other key's values (as explainded in the example above) the embedded key '[abc]' MUST be unique. Using embedded keys in a listing context is not allowed and will result in an fatal error.
In some cases configuration files may need to include other configuration files. The way this is done is via a speical key called 'include'. The same file will be automatically execluded if it's detected multiple times.
argv()
Returns the @ARGV_CLEAN list
value(SECTION, KEY)
Retrieve a configuration value or list from SECTION for KEY keyname.
By rule, entries outside of a section are 'global', entries within the CLI arguments list are in section 'argv'
islist(SECTION, KEY)
Return true if the SECTION's KEY is a list of entries
sections()
Return a list of available sections
keys(SECTION)
Return the keys for a given section
EXPORTS
@ARGV_CLEAN is exported automatically containing any additional arguments from the @ARGV list which have been cleaned of options (--help etc.)
AUTHOR
Colin Faber <cfaber@fpsn.net>
LICENSE AND COPYTIGHT
Copyright 2016 (C) Colin Faber
This library is licensed under the Perl Artistic license and may be freely used and distributed under the terms of Perl itself.