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.

cpanm Package::Install

perl -MCPAN -e shell
install Package::Install