NAME
App::CELL::Config -- load, store, and dispense meta parameters, core parameters, and site parameters
VERSION
Version 0.127
SYNOPSIS
use App::CELL::Config;
# 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 package variables, $meta, $core, and $site, which are references to hashes holding the names, values, and other information related to the configuration parameters loaded from files in the App::CELL distro sharedir and the site configuration directory, if any. These values are loaded by the App::CELL::Load module.
PACKAGE VARIABLES
$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
config
The config method provides clients access to site configuration parameters. A simple logic is applied: if the parameter is defined in 'site', we're done: that is the value. If the parameter is not defined in 'site', check 'core' and use that value, if available.
If neither 'site' nor 'core' has a definition for the parameter, undef is returned.
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 mutable. Use this function to set or change them. Takes two arguments: parameter name and new value. If the parameter didn't exist before, it will be created. Returns 'ok' status object.
TO_DO: check value to make sure it's a scalar.
set_core
Sets core parameter, provided it doesn't already exist. Wrapper.
set_site
Sets site parameter, provided it doesn't already exist. Wrapper.
_set_core_site
Core and site parameters are immutable. This function can be used to set them, provided they don't already exist. Takes three arguments: param type, param name and new value. If the parameter didn't exist before, it will be created. Returns 'ok' status object on success, or error object on failure.