Nathan Cutler


App::CELL::Config -- load, store, and dispense meta parameters, core parameters, and site parameters


Version 0.070


    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 );


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.


Holds parameter values loaded from files with names of the format [...] These "meta parameters" are by definition changeable.


Holds parameter values loaded from files whose names match [...] Sometimes referred to as "core parameters", these are intended to be set by the application programmer to provide default values for site parameters.


Holds parameter values loaded from files of the format [...] -- referred to as "site parameters". These are intended to be set by the site administrator.


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 module in the CELL distribution.



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 [...] -- store these in $meta
3. load core parameters and their default values from files whose names match [...] -- store these in $core
4. load site parameters and their default values from files whose names match [...] -- store these in $site

Takes: nothing, returns status object. To be called like this:

    my $status = App::CELL::Config::init();



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.


Takes cellconf candidate (full path). Returns site configuration directory on success, undef on failure.


Run viability checks on siteconf candidate. Siteconf candidate _must_ pass these checks; otherwise, we give up.


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' );


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 'ok' status object.