|
App::Config - Perl5 extension for managing global application configuration information. |
App::Config - Perl5 extension for managing global application configuration information.
use App::Config;
my $cfg = App::Config->new();
$cfg->define("foo"); # very simple variable definition
$cfg->set("foo", 123); # trivial set/get examples
$fval = $cfg->get("foo");
$cfg->foo(456); # direct variable access
$cfg->cfg_file(".myconfigrc"); # read config file
$cfg->cmd_line(\@ARGV); # process command line
App::Config is a Perl5 module to handle global configuration variables for perl programs. The advantages of using such a module over the standard ``global variables'' approach include:
App::Config requires Perl version 5.004 or later. If you have an older version of Perl, please upgrade to latest version. Perl 5.004 is known to be stable and includes new features and bug fixes over previous versions. Perl itself is available from your nearest CPAN site (see http://www.perl.com/CPAN).
To install this module type the following:
perl Makefile.PL
make
make install
The 'make install' will install the module on your system. You may need
root access to perform this task. If you install the module in a local
directory (for example, by executing ``perl Makefile.PL LIB=~/lib'' in the
above - see perldoc MakeMaker for full details), you will need to ensure
that the PERL5LIB environment variable is set to include the location, or
add a line to your scripts explicitly naming the library location:
use lib '/local/path/to/lib';
To import and use the App::Config module the following line should appear in your Perl script:
use App::Config;
App::Config is implemented using object-oriented methods. A new App::Config
object is created and initialised using the App::Config->new() method.
This returns a reference to a new App::Config object.
my $cfg = App::Config->new();
This will create a reference to a new App::Config with all configuration options set to their default values. You can initialise the object by passing a hash array reference containing configuration options:
$cfg = App::Config->new( {
CASE => 1,
FILEPARSE => \&my_parser,
ERROR => \&my_error,
} );
The following configuration options may be specified. Some of these use default values as may be specified in the GLOBAL configuration option.
cfg_file() and is passed a reference to
the App::Config object and the name of the file to parse. The routine
should update any variable values directly. The return value is expected
to be 1 to indicate success or 0 to indicate failure. This value is
returned directly from cfg_file();
Pseudo-Code Example:
$cfg = App::Config->new( { FILEPARSE => \&my_parser } );
sub my_parser {
my $cfg = shift;
my $file = shift;
# open file, read lines, etc.
# ...
$cfg->set($variable, $value); # set variable value
# close file, etc.
return 1;
}
cfg_file() routine reads the file and passes each line
to the LINEPARSE function, where defined.
Four parameters are passed to the LINEPARSE function:
The function should return 1 to indicate that the line has been successfully parsed, or 0 to indicate that no action was taken and the default line parser should now be used for this line.
Note that cfg_file() does some elementary
pre-processing before calling the LINEPARSE function.
See READING A CONFIGURATION FILE for more details.
cmd_line() and is passed a reference
to the App::Config object and a reference to a list of command line
arguments (usually @ARGV).
The function is required to set variable values directly and return 1 or 0 to indicate success or failure, as is described in the FILEPARSE section above.
cmd_line() and is passed a reference
to the App::Config object through which variable values can be manipulated.
Other parameters passed are the command line argument in question (e.g.
"-v"), the name of the variable to which it corresponds (e.g. "verbose")
and a reference to the remaining argument list. The function is expected
to modify the argument list if necessary, shifting off additional parameters
where required.
A pseudo-code example is shown:
my $cfg = App::Config->new( { ARGPARSE => \&my_arg_parse, } );
sub my_arg_parse {
my $cfg = shift;
my $arg = shift;
my $var = shift;
my $argvref = shift;
VAR: {
$var eq 'verbose' && do {
$cfg->set($var, 1);
last VAR;
};
# this time, look at $arg instead of $var
$arg eq '-f' && do {
$cfg->set($var, shift(@$argvref)); # should error check
last VAR;
};
# not interested in anything else
# (let default parser have a go)
return 0;
}
# we processed it so return 1
return 1;
}
cmd_line() routine where it is split into whitespace
separated tokens and parsed along with the rest of the command line options.
Environment variable options are processed before any real command line
options.
Note that the variable is split on whitespace and does not take into account quoted whitespace. Thus 'foo ``bar baz'' qux' will be split into the tokens 'foo', '``bar', 'baz''' and 'qux'. This will be fixed in a future release.
From the Unix shell:
$ SPLATOPTS="-z -f foobar"
Perl App::Config usage:
my $cfg = App::Config->new( { CMDENV => "SPLATOPTS" } );
$cfg->cmd_line(\@ARGV); # parses ("-z", "-f", "foobar", @ARGV)
my $cfg = App::Config->new( { ENDOFARGS => "STOP" } );
@args = qw(-f -g -h STOP -i -am -ignored);
$cfg->cmd_line(\@args);
# @args now contains qw(-i -am -ignored)
The CMDARG global option, when set to any true value, specifies that the command line option for any variable should be of the form ``-variable''. Any aliases specified for a variable can also be used in this way. e.g.
my $cfg = App::Config->new({
GLOBAL => { ARGCOUNT => 1, CMDARG => 1 }
});
$cfg->define("foo", {
ALIAS => 'bar'
});
The GLOBAL ARGCOUNT parameter specifies that the foo variable expects an
argument. An ARGCOUNT option specified in the define() method call would
override this default. The GLOBAL CMDARG option specifies that the 'foo'
variable should be specified on the command line as '-foo'. The ALIAS
name for foo can also be specified as such: '-bar'.
The define() function is used to pre-declare a variable and specify
its configuration.
$cfg->define("foo");
In the simple example above, a new variable called ``foo'' is defined. A reference to a hash array may also be passed to specify configuration information for the variable:
$cfg->define("foo", {
DEFAULT => 99,
ALIAS => 'metavar1',
});
The following configuration options may be specified
set(), cfg_file() or
cmd_line().
$cfg->define("foo", {
ALIAS => 'metavar1',
});
or
$cfg->define("bar", {
ALIAS => [ 'metavar2', 'metalrod', 'boozer' ],
});
In the first example, $cfg->set("metavar1") (or any other
variable-related function) is equivalent to $cfg->set("foo").
Likewise for the second example, with all 3 aliases defined.
-v is a common flag
indicating verbose mode. The 'verbose' variable might be defined as
such:
$cfg->define("verbose", {
CMDARG => '-v',
});
If the cmd_line() function detects -v in the command line arguments,
it will update the 'verbose' value. See also the ARGCOUNT option below
which influences the variable values that are set by the command line
processing function.
A variable may have more than one related command line argument. These can be specified by passing a reference to an array of arguments:
$cfg->define("verbose", {
CMDARG => [ '-v', '-V' ],
});
If the GLOBAL CMDARG variable is set (see GLOBAL in the DESCRIPTION manpage above) then the default CMDARG for each variable will be its name (and any aliases) prefixed by a dash, e.g. '-verbose'. Any CMADRG value specifically set will override this default.
"-f filename").
The ARGCOUNT value is used to determine if an additional argument is
expected (ARGCOUNT => 1) or not (ARGCOUNT => 0).
When ARGCOUNT is 1, cfg_file() passes the rest of the config line (after
the opening variable name has been removed) as the argument value and
cmd_line() passes the next argument from the command line argument
list (usually @ARGV). When ARGCOUNT is 0, both functions pass the value
1 to set the variable to a true state. The default ARGCOUNT value is 0.
If the GLOBAL ARGCOUNT variable is set (see GLOBAL in the DESCRIPTION manpage above) then this value will be used as the default ARGCOUNT for each variable unless otherwise specified.
NOTE: Although any non-zero value can be used to indicate the presence of an additional argument, this option may be extended in the future to handle multiple arguments. The behaviour associated with any value other than 1 or 0 may change in subsequent versions.
If the GLOBAL EXPAND variable is set (see GLOBAL in <DESCRIPTION> above) then this value will be used as the default EXPAND for each variable unless otherwise specified.
Items are expanded according to the following rules:
cfg_file() and
cmd_line().
If VALIDATE is defined as a simple string, it is applied as a regular expression to the value read from the config file or command line. If the regex matches, the value is set. If not, a warning message is generated.
VALIDATE may also be defined as a reference to a sub-routine which takes as its arguments the name of the variable and its intended value. The sub-routine should return 1 or 0 to indicate that the value is valid or invalid, respectively. An invalid value will cause a warning error message to be generated.
If the GLOBAL VALIDATE variable is set (see GLOBAL in the DESCRIPTION manpage above) then this value will be used as the default VALIDATE for each variable unless otherwise specified.
The ACTION routine may be used, for example, to post-process variable data, update the value of some other dependant variable, generate a warning message, etc.
Example:
sub my_notify {
my $cfg = shift;
my $var = shift;
my $val = shift;
print "$variable set to $value\n";
}
Be aware that calling $cfg->set() to update the variable from within
the ACTION function will cause a recursive loop as the ACTION function is
repeatedly called. This is probably a bug, certainly a limitation.
App::Config defines two methods to manipulate variable values:
set($variable, $value);
get($variable);
Both functions take the variable name as the first parameter and set()
takes an additional parameter which is the new value for the variable.
set() returns 1 or 0 to indicate successful or unsuccessful update of the
variable value. If there is an ACTION routine associated with the named
variable, the value returned will be passed back from set(). The
get() function returns the current value of the variable.
Once defined, variables may be accessed directly as object methods where the method name is the same as the variable name. i.e.
$cfg->set("verbose", 1);
is equivalent to
$cfg->verbose(1);
Without parameters, the current value of the variable is returned. If a parameter is specified, the variable is set to that value and the original value (before modification) is returned.
$cfg->age(28);
$cfg->age(29); # sets 'age' to 29, returns 28
App::Config can be used to read configuration files and automatically update variable values based on the contents of the file.
$cfg->cfg_file("$HOME/.myapprc");
The cfg_file() function reads each line of the specified configuration
file and processes them according to the following rules:
'=' character (surrounding whitespace is ignored).
The following example demonstrates a typical configuration file:
# simple flag (same as " verbose 1" or "verbose = 1")
verbose
# the following lines are all equivalent
file /tmp/foobar
file = /tmp/foobar
file=/tmp/foo
By specify CMDARG values for defined variables, the cmd_line() function
can be used to read the command line parameters and automatically set
variables.
When an command line argument matches a CMDARG value, the variable it
relates to is updated. If the variable has an ARGCOUNT of 0, it will be
assigned the value 1 (i.e. the flag is set). A variable with an ARGCOUNT
of 1 will be set with the next value in the arguments. Users familiar with
getopt(3C) will recognise this as equivalent to adding a colon after an
option letter (e.g. "f:"). An error is generated if the argument starts
with a '-'. The special option ``--'' may be used to delimit the end of the
options. cmd_line() stops processing if it finds this option.
Example variable definition:
$cfg->define("verbose", {
CMDARG => '-v',
ARGCOUNT => 0, # default anyway
});
$cfg->define("file", {
CMDARG => '-f',
ARGCOUNT => 1, # expects an argument
});
Command-line options:
-v -f foobar
Variable values after calling cmd_line(\@ARGV):
verbose: 1
file: foobar
The following list represents known limitations or bugs in App::Config or ways in which it may be improved in the future. Please contact the author if you have any suggestions or comments.
set()
method. This causes the ACTION function to be re-executed, starting a
recursive loop.
"-v(erbose)") and handle different command line
characters other than '-' (e.g. +flag @file). This may also tie in
with long (--) and short (-) options and defining recognised 'classes' of
options.
-I/usr/include
-I/user/abw/include.
cfg_file() and/or cmd_line().
env_vars() function.
Andy Wardley, <abw@cre.canon.co.uk>
Web Technology Group, Canon Research Centre Europe Ltd.
App::Config is based in part on the ConfigReader module, v0.5, by Andrew Wilcox (currently untraceable).
Thanks to all the people who have reported bugs and made suggestions. Special thanks to those who sent patches:
$Revision: 1.9 $
Copyright (C) 1997,98 Canon Research Centre Europe Ltd. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the term of the Perl Artistic License.
printf(3C)printf() function, for a description of
the format parameter to the ERROR routine.
http://www.cre.canon.co.uk/perl/
|
App::Config - Perl5 extension for managing global application configuration information. |