NAME
Pgreet - General purpose shared methods for Penguin Greetings.
SYNOPSIS
$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
);DESCRIPTION
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.
INITIALIZATION
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');METHODS
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.
STATE FILE FORMAT
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
Copyright (c) 2003, 2004 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.7