NAME
App::CELL::Config -- load, store, and dispense meta parameters, core parameters, and site parameters
VERSION
Version 0.066
SYNOPSIS
use App::CELL::Config;
# load meta, core, and site parameters from files
my $status = App::CELL::Config::init();
return $status unless $status->ok;
# get a parameter value (returns value or undef)
my $value = App::CELL::Config::get_param( 'meta', 'MY_PARAM' );
my $value = App::CELL::Config::get_param( 'core', 'MY_PARAM' );
my $value = App::CELL::Config::get_param( 'site', 'MY_PARAM' );
# set a meta parameter
App::CELL::Config::set_meta( 'MY_PARAM', 42 );DESCRIPTION
The purpose of the App::CELL::Config module is to maintain and provide access to three blessed hashrefs: $meta, $core, and $site, which hold the names, values, and other information related to the configuration parameters loaded from files in the site configuration directory.
$meta
Holds parameter values loaded from files with names of the format [...]_MetaConfig.pm. These "meta parameters" are by definition changeable.
$core
Holds parameter values loaded from files whose names match [...]_Config.pm. Sometimes referred to as "core parameters", these are intended to be set by the application programmer to provide default values for site parameters.
$site
Holds parameter values loaded from files of the format [...]_SiteConfig.pm -- referred to as "site parameters". These are intended to be set by the site administrator.
HOW PARAMETERS ARE INITIALIZED
Like message templates, the meta, core, and site parameters are initialized by require-ing files in the configuration directory. As described above, files in this directory are processed according to their filenames.
The actual directory path is determined by consulting the CELL_CONFIGDIR environment variable, the file .cell/CELL.conf in the user's HOME directory, or the file /etc/sysconfig/perl-CELL, in that order -- whichever is found first, "wins".
CELL's configuration parameters are modelled after those of Request Tracker. Configuration files are special Perl modules that are loaded at run-time. The modules should be in the CELL package and should consist of a series of calls to the set function (which is provided by CELL and will not collide with your application's function of the same name).
CELL configuration files are straightforward and simple to create and maintain, while still managing to provide power and flexibility. For details, see the CELL_MetaConfig.pm module in the CELL distribution.
PUBLIC FUNCTIONS AND METHODS
init
Re-entrant initialization function.
On first call, initializes all three site configuration hashes by performing the following actions:
- 0. checks meta parameter CELL_CONFIG_INITIALIZED -- returns "OK" status if true.
- 1. get CELL_CONFIGDIR configuration parameter by consulting (a) the environment, (b)
~/.cell/CELL.conf, and (c)/etc/sysconfig/perl-CELL, in that order, and if none of these options is viable, default to/etc/CELL. - 2. load meta parameters and their default values from files whose names match
[...]_MetaConfig.pm-- store these in$meta - 3. load core parameters and their default values from files whose names match
[...]_Config.pm-- store these in$core - 4. load site parameters and their default values from files whose names match
[...]_SiteConfig.pm-- store these in$site
Takes: nothing, returns status object. To be called like this:
my $status = App::CELL::Config::init();Sets CELL_SITECONF_DIR and CELL_CONFIG_INITIALIZED meta parameters.
get_siteconfdir
Look in various places (in a pre-defined order) for the site configuration directory. Stop as soon as we come up with a plausible candidate. On success, returns a string containing an absolute directory path. On failure, returns undef.
_import_cellconf
Takes cellconf candidate (full path). Returns site configuration directory on success, undef on failure.
_is_viable
Run viability checks on siteconf candidate. Siteconf candidate _must_ pass these checks; otherwise, we give up.
get_param
Basic function providing access to values of site configuration parameters (i.e. the values stored in the %meta, %core, and %site module variables). Takes two arguments: type ('meta', 'core', or 'site') and parameter name. Returns parameter value on success, undef on failure (i.e. when parameter is not defined).
my $value = App::CELL::Config::get_param( 'meta', 'META_MY_PARAM' );set_meta
By definition, meta parameters are changeable. Use this function to change them. Takes two arguments: parameter name and new value. If the parameter didn't exist before, it will be created. Returns a true value.