Pgreet - General purpose shared methods for Penguin Greetings.

  $Pg_obj = new Pgreet($Pg_config, $Pg_error, 'daemon');

  $Pg_obj->store_state($data_hash_ref, $Complete_path_to_StateFilName);

  $data_hash_ref = $Pg_obj->read_state($data_hash_ref,
                                       $Complete_path_to_StateFilName
                                      );

The Perl module: Pgreet (Pgreet.pm) provides shared functionality for the Penguin Greetings application that is not provided by any specific submodule. Presently, it provide consistent access to the intermediate state files between the CGI Application and Penguin Greetings daemon.

This module depends on the Pgreet::Error and Pgreet::Config modules to provide error handling and configuration information respectively. The normal initialization sequence would be to first create a Penguin Greetings configuration object and then a Penguin Greetings error object using declarations similar to what is shown below:

  $Pg_config = new Pgreet::Config($config_file)

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

Once these two objects exist, the Pgreet object may be constructed. The required arguments are the Penguin Greetings config object (below $Pg_config,) the Penguin Greetings error object (below $Pg_error,) and the type of application that is creating the Pgreet object. There are three recognized types: daemon (for a application daemon like pgreetd,) CGIApp (for a CGI application, Speedy CGI application, etc. like pgreet.pl.cgi,) and App (for a command line application like PgTemplateTest.) These are used to determine how input/output will be dealt with for example.

  $Pg_obj = new Pgreet($Pg_config, $Pg_error, 'CGIApp');

There are two methods in Pgreet. They provide a consistent interface to reading and writing the temporary state files used to communicate between the CGI application and the system daemon. To store data, use the store_state method. It takes a hash reference of items to store and complete path to a file.

  $Pg_obj->store_state($data_hash_ref, $Complete_path_to_StateFilName);

To retrieve data from a state file, use the method read_state. It takes the same two arguments: a hash reference and the path to the file to read. The method returns the hash reference so that it may be called in a more functional-programming style if desired (shown below.)

  $data_hash_ref = $Pg_obj->read_state($data_hash_ref,
                                       $Complete_path_to_StateFilName
                                      );

Because errors are handled by the Penguin Greetings Error object, these methods will not return error conditions but will produce error conditions consistent with the Error object.

The state file format is very simple minded. Items are in a key-data format that is tab-delimited. All tabs in the data is converted to spaces to avoid ambiguity. The only exception (and the reason for these special methods) is the message text of the ecard. It is listed separately line by line. The reason for this special handing is limitations in the length of fields in other implementations of state file transition. An example of a state file is shown below

  # pgreet intermediate state file - autogenerated.
  # Created on: Fri Jul 25 10:27:53 2003

  recipient_email	user@miscserver.org
  password	testpassword	
  copy_for_you	yes
  recipient_name	Jane & John Doe
  sender_name	Jane & John Doe
  sender_email	user@miscserver.org
  card	St_Gabriel_new_day
  site	PgSaint
  state_file	pgreet-state-84760f0946f1ead86770d156e3ac4e7f.txt
  EOV
  MESSAGE:
  This is a test message.  This is a test message.  This is a test message.
  This is a test message.

The line EOV indicates that all tab-separated values have been provided. The next line MESSAGE: is the start of the message text. The message text continues until the end of the file.

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

No known bugs at this time.

Edouard Lagache <pgreetdev@canebas.org>

1.0.0

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