NAME Config::Loader - Module to find and parse config files and to combine with command line switches.
SYNOPSIS
use Config::Loader();
my $c = Config::Loader->new (
config_file => 'name' / '/absolute/path',
config_dir => 'dir_name',
options => {
bool => '!',
incr => '+',
opt_string => ':s',
opt_int => ':i',
opt_float => ':f',
opt:extint => ':o',
req_string => '=s',
etc
opt_string_array => ':s@',
etc
}
cli => 1,
order => [qw(user global)],
mode => 'combine',
warn => 1,
debug => 0,
check_options => 1,
ignore_unknown => 1,
};ABSTRACT
Config::Loader finds and parses config file and combines them with command line switches (in a Getopt::Long style).
The format of data in the config files is quite flexible (but simple). All forms below are legal:
# ignore this line
bool1
nobool2
no-bool3
bool4 = 1
bool5 = 0
incr1
incr1
incr2 = 3
key1 value1 #ignore this comment
key2 = value2
key3 : value3
key4 = "value 4 # include this comment"
key5 = "value 5 \
include this with whitespace"\\
array4 = value1 value2 value3 "value 4"
array4
array4
array5 = value1, value2, value3 ,"value 4"
array6 = value1 \
value2 \
\
value3 \
" value 4 "
multiline_array -
This text #include this comment
and more
" just like this "
until .
.
multiline_scalar -
"This text #ignore this comment
and more
\" just like this \"
until ."
.
DESCRIPTION
A list of all the methods available. This is a completely OO module, there are no function calls.
new()
Create a new Config::Loader object - any of the parameters can be set by passing them in to the new() method. Returns the object if succesful or throws an error of type Config::Loader::Error, pointing to the line at which your script called Config::Loader.
parse()
After constructing the object and setting any parameters you would like to set, call
%config_hash = $c->parse()
$config_ref = $c->parse()
This will parse the files and command line and return a hash of the read in configuration.
data()
Returns the config data. You can specifiy a key to receive one value, or it returns a hash/hash-ref of all the values.
$scalar/$ref = $c->data($key)
$hash_ref = $c->data
%hash = $c->datafiles_processed()
Read only. Returns an array ref listing all files that were processed, in descending order or priority.
$array_ref = $c->files_processed()config_file()
Use for setting which configuration file to look for. If this value is absolute, it will look ONLY for this file. Otherwise it searches through likely directories to find an appropriate file - uses Config::Find to these.
See order() and config_dir() for more.
absolute()
Returns true if Config::Loader reckons that the config_file you passed in is absolute. Normally you wouldn't need this, but it's available.
config_dir()
If you have a configuration directory specific to your program (and not in the normal locations) you can specify it here. Config::Find will find config files in (eg) /usr/local/program/conf/ if your program is being run from /usr/local/program/bin/, but it will fail if you have a symlink to your program.
cli()
Should Config::Loader parse the command line? True by default. If it is true, you need to provide an option list to specify what you expect to have returned to you.
$c->cli(1)
check_options()
Should Config::Loader check the options specified in the configuration file? If no, then just loads whatever it finds into data (trying to make sense out of it), otherwise every value is checked against the specified options.
$c->check_options(1)True by default
order()
Specify the order of config files to process. Can use 'user' and 'global'.
'user' - implies config files in the user's directory of the form .config_file 'global' - looks first in the config_dir, and if nothing there, then looks in the "usual places"
If you leave out either option (or both) then those files won't be processed.
$c->config('user','global')
$c->config(qw [user global])options()
Use to specify the options (and their formats) that should be looked for. The option formats are similar to those used in Getopt::Long.
Special formats
'!' : boolean, option can be specified as 'key','no-key','nokey'
: in config files, can also be specified as key = 1 or key = 0
'+' : incremental, so 'key key key' gives you key = 3
: in config files, can also set key = 3
Normal formats take the form 'RequirementDatatypeVartype'
...where Requirement is :
':' : optional
'=' : requiredDatatype is :
's' : strings
'i' : integer
'f' : floating number
'o' : extended integer, perl style - see Getopt::Long for details
and Vartype is :
'@' : array
blank : scalar
'%' : Not supported
So a format of ':s@' would indicate an optional array of strings.
mode()
Mode can be one of 'combine' or 'separate'. If 'combine' (default) then the user file and global file are merged, with the file earlier in 'order' taking precedence. If 'separate' then only the first file to be found is used.
The command line arguments are always merged and take precedence (assuming that you have not set $c->cli(0))
$c->mode('combine')
warn()
If no config file is found, then a warning is issued stating that no config file has been found, and that the user should probably write one. If you set
$c->warn(0)
then they do not get this message.
debug()
If any error occurred, then the Config::Loader object is dumped along with the error message.
$c->debug(0)
is the default
ignore_unknown()
You may have groups of config switches sitting in the same file, but for a particular part of the program, you only want a subset of switches. If ignore_unknown is set to true, then any unknown switches are ignored. Otherwise, it throws an error.
This only applies if check_options is set to true. Otherwise, all options set in config files are included.
EXPORT
None by default.
TODO
Add parsing to recognise hash style lists Write tests
KNOWN BUGS
None, but please let me know
SEE ALSO
Config::Find
AUTHOR
Clinton Gormley, <develop@traveljury.com>
COPYRIGHT AND LICENSE
Copyright (C) 2004 by Clinton Gormley
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.3 or, at your option, any later version of Perl 5 you may have available.