SYNOPSIS
my
$config
= Package::Configure->new();
my
$value1
=
$config
->setting1();
#get
$config
->setting1(
'a new value for setting 1'
);
#set
DESCRIPTION
Package::Configure - Access package configuration values from command-line options (Getopt::Long style), previously specified cached settings, or default values. This package is a kindred spirit to the GNU automake and autoconf tools.
When a Package::Configure object is instantiated, the following happens:
1. A. If F<pkg_config.cache>
exists
, load it into L</ini()> accessor as a
Config::IniFiles object.
B. Otherwise,
if
F<pkg_config.in>
exists
, load that.
C. Otherwise, load nothing.
2. If a configuration file was loaded, process commandline arguments
Using Getopt::Long, overriding configuration setings
with
those provided
from Getopt::Long.
3. A. If C<--help> was
given
as a Makefile.PL argument, render the configuration
as a usage document to STDOUT and
exit
(0).
-otherwise-
B. If a configuration file was loaded, and C<--interactive> was
given
as a
Makefile.PL argument, query the user on STDOUT/STDIN
for
new configuration
values
.
4. Variable
values
may also be accessed using C<
$config
-E<gt>my_setting_name()>
to get the current value, or C<
$config
-E<gt>my_setting_name(
'a new value'
)> to
update the value of the variable.
5. When the object is destroyed (by falling out of scope, being undefined, etc),
the current state of the object is written to F<pkg_config.cache>.
CONFIGURATION FILES pkg_config.in AND pkg_config.cache
The configuration files are in INI format, and are parsed using Config::IniFiles. You should be familiar with the INI format and Config::IniFiles.
RESERVED VARIABLES
These variables have a built-in function and are reserved for use by Package::Configure.
* help * interactive
Run Makefile.PL --help
for a display of what parameters are available, and Makefile.PL --interactive
for an interactive query for values of said parameters.
DECLARING CONFIGURATION VARIABLES
Package::Configure recognizes variables in the following INI sections:
for single value parameters:
* [option integer] * [option float] * [option string] * [option dir] * [option file]
for multi value parameters:
* [option integers] * [option floats] * [option strings] * [option dirs] * [option files]
Comments on sections/parameters are recognized and displayed when Makefile.PL is run with the --help
option.
Typechecking is performed on the integer, float, dir, and file sections, see "validate_type()".
for scripts:
* [PL_FILES] * [EXE_FILES]
thes sections are special -- they are passed to ExtUtils::MakeMaker to determine which scripts are processed at make-time (PL_FILES), and which are installed (EXE_FILES). See ExtUtils::MakeMaker for details on how that system works.
SETTING VARIABLE VALUES
See Config::IniFiles
Default values can be set in pkg_config.in, as well as collected from the command-line using Getopt::Long-style options, or with interactive question/answer.
The Getopt::Long parameters available are created dynamically from the variable names in pkg_config.in or pkg_config.cache (preferred if present).
EDITING CONFIGURATION FILE
See Config::IniFiles for a description of the configuration file format.
COMMAND-LINE OPTIONS
For a script called script.pl, valid executions of the script might be:
script.pl --color red --number 9
script.pl
Argument names are identical to those in pkg_config.in or pkg_config.cache.
INTERACTIVE QUERY
A few runs of script.pl --interactive
might look like the following:
[14:38]aday
@asti
:~/cvsroot/Package-Tools> /usr/bin/perl ./script.pl --interactive
color - what is your favorite color? (currently:
"blue"
)? red
number - what is your favorite number? (currently:
"2"
)? 9
[14:38]aday
@asti
:~/cvsroot/Package-Tools> /usr/bin/perl ./script.pl --interactive
color - what is your favorite color? (currently:
"red"
)? yellow
number - what is your favorite number? (currently:
"9"
)? 8
[14:38]aday
@asti
:~/cvsroot/Package-Tools> /usr/bin/perl ./script.pl --interactive --color 6 --number orange
Value
"orange"
invalid
for
option number (number expected)
color - what is your favorite color? (currently:
"6"
)? orange
number - what is your favorite number? (currently:
"8"
)? 6
AUTHOR
Allen Day, <allenday@ucla.edu>
METHODS
AUTOLOAD()
FIXME internal method, undocumented
new()
Usage :
$config
= Package::Configure->new();
Function: constructs a new object, reads variables and their
default
/cached
values
from state files F<pkg_config.in> and F<pkg_config.cache>.
Also handles command-line arguments by delegating to Getopt::Long.
Returns : a Package::Configure object
Args : none.
validate_type()
Usage :
$obj
->validate_type(
'type'
,
'thing_to_check'
);
Function: attempts to validate a value as a particular type
valid
values
for
argument 1 are: integer, float, string, dir, file.
Returns : 1 on success
Args : anonymous list:
argument 1: type to validate against
argument 2: value to validate
validate_configuration()
Usage :
$obj
->validate_configuration();
Function: internal method. attempts to validate
values
from the configuration file by calling L</validate_type()>
on
each
.
Returns : n/a
Args : none
process_interactive()
Usage :
$obj
->process_interactive();
Function: iterates over [option *] and [EXE_FILES] sections from
configuration file and prompts user
for
new
values
.
values
are validated using L</validate_type()>
before
being
accepted. lists of
values
are accepted and
split
using
L<Text::ParseWords::shellwords>
Returns : n/a
Args : none
process_options()
Usage :
$config
->process_options();
Function: Internal method that processes command-line options.
show_help()
Usage :
$obj
->show_help();
Function: render configuration file sections/parameters
with
descriptions to STDOUT. program exits and call does
not
return
.
Returns :
exit
code on program termination
Args : exits 0 (success)
ini()
Usage :
$obj
->ini(
$newval
)
Function: holds a Config::IniFiles instance
Returns : value of ini (a
scalar
)
Args : on set, new value (a
scalar
or
undef
, optional)
interactive()
Usage :
$obj
->interactive(
$newval
)
Function: flag
for
whether or not the user should be interactively
queried
for
configuration
values
.
Returns : value of interactive (a
scalar
)
Args : on set, new value (a
scalar
or
undef
, optional)
DESTROY()
called when the object is destroyed. writes object's variables' states to pkg_config.cache to be read at next instantiation.