The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Pgreet-1.0.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($new_hash);

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

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, and calling application will be terminated via the Pgreet::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();
chk_params()

This method applies a set of tests to configuration variables for the Penguin Greetings main configuration files (not the card configuration files which are developer defined.) The tests are a series of "sanity checks" that insure that the values allow Penguin Greetings to function at all and are implemented using String::Checker.

The method returns a hash reference. If any errors are encountered the hash keys will be the configuration variables that had failed the tests and the hash value will be a list reference of String::Checker expectations that failed.

In order to provide meaningful tests, some additional expectations are defined: is_directory - is this an existing directory on system?, num_min - is this value less than supplied number?, existing_uid is this an existing UID on this system?, and existing_gid is this an existing GID on this system? These names are turned in the array reference. The Penguin Greetings utility PgreetConfTest has a translation table of these expectations to provide "human-friendly" diagnostics for administrators.

choose_localized_site()

This method takes a site name that is expected to be the prefix for a number of sites localized in different languages. It then uses the CPAN module: I18N::AcceptLanguage to match among the options provided in the Localize configuration parameters which available sites among those sites with multiple language support best fits the user's language profile as represented by their HTTP_ACCEPT_LANGUAGE environmental string. If no acceptable match is found, it returns the default site is specified. If no default is provided, it will create a warning and return the argument supplied. If there is no Localize lookup for the site name it is just returned assuming that this is a non-localized site.

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);
  $self->_chk_params_helper($to_test, \%check_configs, $test_results);

COPYRIGHT

Copyright (c) 2003-2005 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

1.0.0

SEE ALSO

Config::General, Pgreet, Pgreet::Error, Pgreet::CGIUtils