The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
App-CELL-0.069
River stage one • 5 direct dependents • 5 total dependents
/ App::CELL::Load

NAME

App::CELL::Load -- find and load configuration files

VERSION

Version 0.069

SYNOPSIS

    use App::CELL::Load;

    # assemble a list of configuration files (full paths) of a given type
    # under the given directory
    my @metafiles = App::CELL::Load::find_files( '/etc/CELL', 'meta' );
   
    # 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::Load module is to provide configuration file finding and loading functionality to the App::CELL::Config and App::CELL::Message modules.

find_files

Takes two arguments: full directory path and config file type.

Always returns an array reference. On "failure", the array reference will be empty.

How it works: first, the function checks a state variable to see if the "work" of walking the configuration directory has already been done. If so, then the function simply returns the corresponding array reference from its cache (the state hash %resultlist). If this is the first invocation, the function walks the directory (and all its subdirectories) to find files matching one of the four regular expressions corresponding to the four types of configuration files('meta', 'core', 'site', 'message'). For each matching file, the full path is pushed onto the corresponding array in the cache.

parse_message_file

This function is where message files are parsed. It takes a PARAMHASH consisting of:

File - filename (full path)
Dest - hash reference (where to store the message templates).

Returns: number of stanzas successfully parsed and loaded

parse_config_file

Parses a configuration file and adds the parameters found to the hashref provided. If a parameter already exists in the hashref, a warning is generated, the existing parameter is not overwritten, and processing continues.

This function doesn't care what type of configuration parameters are in the file, except that they must be scalar values. In other words, the value can be a number, a string, or a reference to an array, a hash, or a subroutine.

The technique used in the eval, derived from Request Tracker, can be described as follows: a local typeglob "set" is defined, containing a reference to an anonymous subroutine. Subsequently, a config file consisting of calls to this "set" subroutine is required.

If even one call to set fails to compile, the entire file will be rejected and no configuration parameters from that file will be loaded.

The parse_config_file function takes a PARAMHASH consisting of:

File - filename (full path)
Dest - hash reference (where to store the message templates).

Returns: number of configuration parameters parsed/loaded

(IMPORTANT NOTE: If even one call to set fails to compile, the entire file will be rejected and no configuration parameters from that file will be loaded.)

_conf_from_config

This function takes a target hashref (which points to one of the 'meta', 'core', or 'site' package hashes in App::CELL::Config), a config parameter (i.e. a string), config value, config file name, and line number.

Let's imagine that the configuration parameter is "FOO_BAR". The function first checks if a key named "FOO_BAR" already exists in the package hash (which is passed into the function as %ARGS{'Dest'}). If there isn't one, it creates that key. If there is one, it leaves it untouched and triggers a warning.

Although the arguments are passed to the function in the form of a PARAMHASH, the function converts them into ordinary private variables. This was necessary to avoid extreme notational ugliness.