/ 
Pgreet-0.9.0
River stage zero No dependents
/ Pgreet::Config

NAME

Pgreet::Config - Configuration object for Penguin Greetings.

SYNOPSIS

# Bootstrap Initialization:
$Pg_config = new Pgreet::Config($config_file);
$Pg_config->add_error_obj($Pg_error);

# Normal Initialization:
$Pg_config = new Pgreet::Config($config_file,
                                $Pg_error,
                                $Pg_default_config
                               );
# Access methods:
$Pg_config->access('config_parameter');
$Pg_config->access('config_parameter', $Value_to_set_parameter_to);
$Pg_config->get_hash();
$Pg_config->put_hash();

# Other Misc. methods:
$Pg_default_config->is_valid_site($site);
$Pg_default_config->expand_config_file($site);
$card_conf->scalar_to_array();

DESCRIPTION

The module Pgreet::Config is the Penguin Greetings interface to configuration information. It, in turn, uses the CPAN module Config::General to actually access the configuration files. This module provides methods to maintain the configuration of the parameters needed to operate the Penguin Greetings applications, the configuration of primary and secondary sites and the configuration related to the ecards themselves. This module can either construct a default object in a bootstrap mode or create objects for secondary sites that merge new information into the primary site's setup.

BOOTSTRAPPED INITIALIZATION

One of the main purposes of these modules was to provide a consistent interface to error handling. However, the error handling module requires configuration information in order to deal with some error conditions. Therefore when when this method is first called, there is no error handling apparatus yet available. To cope with this, the first attempt to construct a Pgreet::Config object simply tries to open a configuration file and read it's contents. If it fails, the constructor returns a false value. If the returned value is false, the calling program must cope as best it can:

unless ($Pg_default_config = new Pgreet::Config($config_file)) {
        die;
       }

When bootstrapping, the constructor to Pgreet::Config is given one argument: the complete path to the configuration file. The constructor always needs at least this one argument. If the configuration object is successfully constructed, it can then be used to create a new error object (illustrated for example by the call below:)

$Pg_error = new Pgreet::Error($Pg_default_config, 'CGIApp');

Once this is done, an error object must be immediately added to the configuration object. If an error occurs without an error object attached to the configuration object, it will crash in about as inelegant a manner as is possible.

$Pg_default_config->add_error_obj($Pg_error);

Once this is done, the bootstrapped configuration object may be used in the manner presented below.

NORMAL CONSTRUCTION

Once an Error object is constructed, successive Penguin Greeting configuration objects can be created directly by providing two arguments the complete path to the configuration file, and the error object. For example, creating a configuration object to hold card configuration data would be as follows:

$card_conf = new Pgreet::Config($card_conf_file, $Pg_error);

There is a third possible way to use the constructor object. If one is defining a configuration object that is using an existing object for default information (for example defining a secondary ecard site) then three arguments are expected in constructing the object:

$Pg_config = new Pgreet::Config($config_file,
                                $Pg_error,
                                $Pg_default_config
                               );

When used in this way, the values in the configuration file are merged with the values already in the default object $Pg_default_config via the internal method _merge_configs. Note that certain values cannot be overridden from the default configuration. Those values are: PID_file, PID_path, batch_pause, tmpdir, today_pause, data_file_prefix, state_file_prefix, delete_state, scheduled_email_queue, pgreet_uid, pgreet_gid, SMTP_server, user_access, User_Pgreets and flush_on_cycle. Attempting to change these values will cause an error to be generated via the attached Penguin Greetings error object.

METHODS

add_error_obj()

This method attaches a Penguin Greetings error object to a configuration object that has been "bootstrapped" into existence. Usage:

$Pg_default_config->add_error_obj($Pg_error);
access()

This is the bread'n'butter method for this object. It can be used in one of two ways. If given one parameter, it retrieves the value of the configuration variable (or returns undef.) A sample use is below:

$Pg_config->access('config_parameter');

The second syntax is use to set a configuration variable. In this case a second parameter is the value that the configuration variable should be set to:

$Pg_config->access('config_parameter', $Value_to_set_parameter_to);
get_hash()

This method can be used to get the entire hash reference that is the Config::General representation of the configuration file. This is used only for example to pass that hash to the Embperl templates for content developers to use. Usage requires no parameters:

$Pg_config->get_hash();
put_hash()

This method is the complement of the get_hash method. It is only used internally to this object, but could be used for meatball surgery of the configuration parameters. It requires one parameter:

$Pg_config->put_hash($new_hash);
is_valid_site()

This predicate method is used to see if a site exists in the list of secondary ecard sites recorded in the primary Penguin Greetings configuration. It takes a name of a site as a parameter:

$Pg_default_config->is_valid_site($site);
expand_config_file()

This method is used to expand directory paths for the configuration files of secondary ecard sites that are specified relative to a particular UNIX user on the system. It takes the site name as an argument and returns a full UNIX path name with any tilde '~' replaced by the full path to the users home directory.

$Pg_default_config->expand_config_file($site);
scalar_to_array()

This method is specific to user created configuration files that may contain ambiguous situations of scalars and arrays mixed together. It goes through the hash reference looking for occurrences of the pseudo configuration item: Force_to_array. It then looks for all instances of the listed fields in that configuration item, and if it finds one of those fields containing a single scalar item, it replaces with with an array reference containing that scalar item. The purpose of this is to simplify the creation of Embperl foreach loops which might otherwise be handed a scalar instead of an array of one item to loop through. This method takes no arguments and should only be called on card configuration information.

$card_conf->scalar_to_array();
Internal methods

There are four methods used internally by Pgreet::Config that should never be of interest to those working on the application layer of Penguin Greetings. they are listed here for completeness:

$self->_read_config_file($config_file);
$self->_merge_configs($default_config_hash, $config_hash);
$self->_int_scalar_to_array($new_hash);
$self->_swap_arrays_for_scalars($config_piece);

COPYRIGHT

Copyright (c) 2003 Edouard Lagache

This software is released under the GNU General Public License, Version 2. For more information, see the COPYING file included with this software or visit: http://www.gnu.org/copyleft/gpl.html

BUGS

No known bugs at this time.

AUTHOR

Edouard Lagache <pgreetdev@canebas.org>

VERSION

0.9.0

SEE ALSO

Config::General, Pgreet, Pgreet::Error