NAME

Liz - Elizabeth Mattijsen's Perl Extensions


SYNOPSIS

 use Liz;
 use Liz qw(Contents WriteContents Gzip Gunzip Pwd);

 $contents = Contents( $filename );
 $zip = Gzip( $contents );
 WriteContents( "$filename.gz",$zip );
 $unzip = Gunzip( $zip );
 $pwd = Pwd();


SUBROUTINES/METHODS

The following subroutines can either be imported with the use command into your own program, or used as methods by adding ``Liz'' to your @ISA.


LastModified

Return the last modified date/time of one or more file. Filename specifications can be relative or absolute. A ``//'' at the beginning of a filename, indicates a filename specification relative to the document root as specified by the environment variable $ENV{'DOCUMENT_ROOT'}.

Input Parameters

 1..N filename specification
Output Parameters

 1    last modified date/time as Unix time (seconds since 1 Jan. 1970)
      (returns undef if none of the files was found.


Contents

Return the contents of a file as a single string. Reads from STDIN if no file is speCified. Return undef if not successful. If called as a method, store the contents in the field CONTENTS.

Note that 'DATA' can be specified as a special file to read all data after the __END__ in a Perl-script. And that it is also possible to specify a pipe to obtain the output of a command in the form ``command |''.

Input Parameters

 1 path of file to obtain contents of
 2 flag: delete file after reading
   (default: keep file)
Output Parameters

 1 contents of file as a single string
   (undef: error reading file or pipe)


WriteContents

Write a value to a file. Performs the opposite function to Contents. If called as a method, uses the contents of the field CONTENTS to write to the file, unless another value is specified.

Also makes sure that the file's modification and access date are set to the current time on the local machine, instead of the local time of the machine on which the file-system resides. This should prevent a lot of synchronization problems when the time on a mounted file-system is not exactly the same as the system on which the process runs.

Input Parameters

 1 path of file to save in
 2 scalar value to be saved
   (default: NULL or field CONTENTS if called as a method)


CheckEmailAddress

Check whether a given email address is syntactically correct. Can be called as a method or as a subroutine.

Listens to method Nederlands to return Dutch language error messages.

Input Parameters

 1 email address to check
Output Parameters

 1 error found (undef if no error found)
Example

 if ($error = Liz::Calc::EmailAddress( $email )) {
   die "Error in email address: $error\n";
 }


Gzip

Gzip one or more values and return the gzipped values. The opposite function is performed by Gunzip.

Input Parameters

 1..N one or more values to be gzipped
Output Parameters

 1..N the Gzipped values
Note

Creates a temporary file. The location of this temporary file can be adapted by setting the directory where this process can create and delete files with the TMP class method.

Does not change anything in the object when called as a method.


Gunzip

Gunzip one or more values and return the original values. The opposite action is performed by Gzip.

Does not change anything in the object when called as a method.

Input Parameters

 1..N one or more values to be gunzipped
Output Parameters

 1..N the original values
Note

Creates a temporary file. The location of this temporary file can be adapted by setting the directory where this process can create and delete files with the TMP class method.


Hash2Scalars

Unhash the keys and values of a reference to a hash table into the caller's (or any other) namespace as variables. It performs the function opposite to Scalars2Hash.

Input Parameters

 1 reference to hash table
 2 namespace to write variables in
   (default: caller's namespace)


Scalars2Hash

Convert a number of variables into a reference to a hash table. It performs the opposite function to Hash2Scalars.

Input Parameters

 1    namespace to read variables from
      (default: caller's namespace)
 2    the existing reference to hash to add the variables to (optional)
      (default: create new hash)
 3..N variable names to be read into the hash
Output Parameters

 1    reference to hash table containing the variables
Example

 $foo = 'foo';
 $bar = 'bar';
 $hashref = Scalars2Hash( '',qw($foo $bar) );
 foreach (keys %{$hashref}) {
   print "$_ = '$$hashref{$_}'\n";
 }
Example

# Get existing hash from the bookstore # Add scalars to the this hash # Store the scalars with the bookstore

 $data = $bookstore->Data;
 $data = Scalars2Hash( '',$data,qw($mickey $minni $donald) );
 $bookstore->Data( $data );

# Now, $mickey,$minni and $donald are stored in the hash, along with # anything that was present before this operation


Host2IP

Convert a host name to an IP-number. Performs the opposite function to IP2Host. Can also be called as a method.

Input Parameters

 1..N host name (e.g. 'www.xxlink.nl')
Output Parameters

 1..N IP-number (e.g. '193.79.208.1')
Example

 $IP = Liz::Host2IP( 'www.xxLINK.nl' );
 $IP = $object->Host2IP( 'cnn.com' );


IP2Host

Convert an IP-number to a host name. Performs the opposite function to Host2IP. Can also be called as a method.

Input Parameters

 1..N IP-number (e.g. '193.79.208.1')
Output Parameters

 1..N host name (e.g. 'www.xxlink.nl')
     (returns the IP-number if DNS-lookup failed)
Example

 $hostname = Liz::IP2Host( '193.79.208.1' );
 $hostname = $object->IP2Host( '193.79.209.200' );


Pwd

Return the current directory. Mainly intended as a compatibility unit for use on non-Unix platforms that do not have backticks and 'pwd'.

Does not change anything in the object when called as a method.

Output Parameters

 1 current directory


PackIP

Pack an IP-number into a 4-byte integer value. Call routine UnpackIP to retrieve the original IP number. Can also be called as a method.

Input Parameters

 1..N IP-number as string in the form "123.234.12.34"
Output Parameters

 1..N IP-number as packed 4-byte integer


UnpackIP

Unpack an IP-number from a 4-byte integer value. Call routine PackIP to pack an IP-number into an integer value. Can also be called as a method.

Input Parameters

 1..N IP-number as packed 4-byte integer
Output Parameters

 1..N IP-number as string in the form "123.234.12.34"


Timestamp2Date

Return a printable date from a (MySQL) timestamp. Can either be called as a method, or directly as a subroutine with Liz::Timestamp2Date().

Input Parameters

 1    "strftime" format to be applied to date string (optional)
      (default: '%e %B %Y %R', e.g. 17 May 1998 11:57)
 2..N timestamp or unix time value or method to apply on object to obtain timestamp
      (default: the current date and time)
Output Parameters

 1..N printable strings
Example

 ($created,$updated) = $news->Timestamp2Date( '',qw(Created Updated) );
 $updated = $object->Timestamp2Date( '',$updated );
 $published = Liz::Timestamp2Date( '',$published );
Example

 $libris->Nederlands;
 print "Het is nu ".$libris->Timestamp2Date."\n";
Format Options

 %a  locale's abbreviated weekday name
 %A  locale's full weekday name
 %b  locale's abbreviated month name
 %B  locale's full month name
 %c  locale's appropriate date and time representation
 %C  locale's date and time representation as produced by date(1)
 %d  day of month [1,31]; single digits are preceded by 0
 %D  date as %m/%d/%y
 %e  day of month [1,31]; single digits are preceded by a space
 %h  locale's abbreviated month name
 %H  hour (24-hour clock) [0,23]; single digits are  preceded by 0
 %I  hour (12-hour clock) [1,12]; single digits are  preceded by 0
 %j  day number of year [1,366]; single digits  are  preceded by 0
 %k  hour (24-hour clock) [0,23]; single digits are  preceded by a blank
 %l  hour (12-hour clock) [1,12]; single digits are  preceded by a blank
 %m  month number [1,12]; single digits are preceded by a blank
 %M  minute [0,59]; leading zero  is  permitted  but  not required
 %n  insert a newline
 %p  locale's equivalent of either a.m. or p.m.
 %r  appropriate time representation in 12-hour clock format with %p
 %R  time as %H:%M
 %S  seconds [0,61]
 %t  insert a tab
 %T  time as %H:%M:%S
 %u  weekday as a decimal number [1,7], with 1 representing Monday
 %U  week number of year as a decimal number [0,53], with Sunday as the
     first day of week 1
 %V  week number of the year as a decimal number [01,53], with Monday
     as the first day of the week.  If the week containing 1 January
     has four or more days in the new year, then it is considered
     week 1; otherwise, it is week 53 of the previous year, and the
     next week is week 1.
 %w  weekday as a decimal number [0,6], with 0 representing Sunday
 %W  week number of year as a decimal number [0,53], with Monday as
     the first day of week 1
 %x  locale's appropriate date representation
 %X  locale's appropriate time representation
 %y  year within century [0,99]
 %Y  year, including the century (for example 1993)
 %Z  time zone name or abberviation, or no bytes if no timezone
     information exists
Note

Negative unix time values indicate GMT (gmtime()) time-values as opposed to normal (localtime()) time-values.


Int2SysTime

Return the system time value of the integer values supplied. Can either be called as a method, or directly as a subroutine within Liz::Int2SysTime().

Input Parameters

 1 year (1970...)
   (1900 is added for values <1900)
 2 month (January=1, February=2, etc)
   (default: 1)
 3 day
   (default: 1)
 4 hour
   (default: 0)
 5 minute
   (default: 0)
 6 second
   (default: 0)
Output Parameters

 1 system time value, compatible with time() function
Example

 $time = $object->Int2SysTime( 1999,09,29,18,25 );
 $time = Liz::Int2SysTime( 2000 );
Note

This is nothing more than a sensible frontend to POSIX::mktime.


Int2Timestamp

Return the (MySQL) timestamp of the integer values supplied. Can either be called as a method, or directly as a subroutine within Liz::Int2Timestamp().

Method Timestamp2Int performs the opposite function.

Input Parameters

 1 year (1970...)
   (1900 is added for values <1900)
 2 month (January=1, February=2, etc)
   (default: 1)
 3 day
   (default: 1)
 4 hour
   (default: 0)
 5 minute
   (default: 0)
 6 second
   (default: 0)
Output Parameters

 1 timestamp
Note

If no input parameters are specified at all, a timestamp of the current date and time will be returned.

Example

 $timestamp = $object->Int2Timestamp2Int( $year,$month,day );
 $timestamp = Liz::Int2Timestamp($year,$month,$day,$hour,$minute,$second);


Timestamp2Int

Return the integer parts of a (MySQL) timestamp. Can either be called as a method, or directly as a subroutine with Liz::Timestamp2Int().

Method Int2Timestamp performs the opposite function.

Input Parameters

 1 timestamp or method to apply on object to obtain timestamp
   (default: now)
Output Parameters

 1 year (1970...)
 2 month (January=1, February=2, etc)
 3 day
 4 hour
 5 minute
 6 second
Example

 ($year,$month,$day) = $object->Timestamp2Int( 'Updated' );
 ($year,$month,$day) = $object->Timestamp2Int( $updated );
 ($year,$month,$day) = Liz::Timestamp2Int( $updated );


SysTime2Int

Convert a time value to its parts. Assume the current time if none specified. Can either be called as a method or as a subroutine.

Input Parameters

 1 time in system time format or method to be called
   (default: now)
 2 flag: type of timestamp:
   (default = 0 = GMT, 1 = local time)
Output Parameters

 1 year (1970...)
 2 month (January=1, February=2, etc)
 3 day
 4 hour
 5 minute
 6 second
Example

 ($year,$month,$day) = $object->SysTime2Int( 'Time' );
 ($year,$month,$day) = $object->SysTime2Int( $updated );
 ($year,$month,$day) = Liz::SysTime2Int( $updated );
Note

This is nothing more than a sensible front-end for localtime() and gmtime().


SysTime2Midnight

Convert a time value to the time value of midnight on that day. Assume the current time if none specified. Can either be called as a method or as a subroutine.

Input Parameters

 1 time in system time format or method to be called
   (default: now)
 2 flag: type of timestamp:
   (default = 0 = GMT, 1 = local time)
Output Parameters

 1 time of midnight in system time format
Example

 ($midnight) = $object->SysTime2Midnight( 'Time' );
 ($midnight) = $object->SysTime2Midnight( $updated );
 ($midnight) = Liz::SysTime2Midnight( $updated );
Note

This is nothing more than a sensible front-end for SysTime2Int and Int2SysTime together.


SysTime2SecondsFromGMT

Return the number of seconds the system of away from GMT for a given point in time, or for the current time. Can be called either as a method or as a subroutine.

Input Parameters

 1 system time value for which to calculate time difference
   (default: now)
Output Parameters

 1 number of seconds away from GMT
Example

 $away = Liz::SysTime2SecondsFromGMT;
Example

 $away = $object->SysTime2SecondsFromGMT;


SysTime2Timestamp

Construct a mySQL-compatible timestamp from time in system time format. This subroutine is probably obsolete, now that Liz::Timestamp2Date also accepts system (Unix) time format values.

Input Parameters

 1 time in system time format ie. the number of seconds since 1970
   (default: now)
 2 flag: type of timestamp:
   (default = 0 = GMT, 1 = local time)
Output Parameters

 1 timestamp (in format YYYYMMDDHHMMSS)
Example

 # get the system time
 $the_time = time;
 # convert to timestamp
 $timestamp = Liz::SysTime2Timestamp( $the_time );
 # now use the constructed timestamp in a MySQL Liz::SQL statement


LANGUAGE METHODS

Some support for different languages is supported in Liz.pm compatible objects.


Deutsch

Set to have output occur in the German language. Returns the object itself, for handy in-liners.


English

Set to have output occur in the English language. Returns the object itself, for handy in-liners.


Francais

Set to have output occur in the French language. Returns the object itself, for handy in-liners.


Nederlands

Set to have output occur in the Dutch language. Returns the object itself, for handy in-liners.


INHERIT METHODS

The following methods are mainly intended to be inherited by adding ``Liz'' in the @ISA list of other modules.


allow

Specify which methods can be AUTOLOADed. This to prevent AUTOLOAD to allow everything, thus causing hard to trace typos in method names.

This method is intended to be called as a either a class method of your Module, or as an object method for your objects.

If this method is never called, all methods are allowed to be AUTOLOADed.

Input Parameters

 1..N names of methods for which to allow AUTOLOADing
Example

 # Only allow Changed, Score and Name as AUTOLOADed methods for this module
 Module->allow( qw(Changed Score Name) );

 # Only allow these methods to be AUTOLOADed for this object
 $object->allow( qw(Address City Street Zip Country) );

 # Allow the default module methods, as well as these methods for the object
 $object->allow( qw(#module Address City Street Zip Country) );
Note

The special name ``#module'' can be used as the first name in a row to indicate the defaults that were set for the module when specifying allowed methods for an object. The special name ``#object'' can be used to indicate to indicate inclusion of previously specified values for the object.

Note

If the first parameter ends with '::', then it is considered to be the name of the module from which the ``allow'' specification is to be copied.


AllowedMethod

Returns whether the specified method is allowed for the object.

Input Parameters

 1..N name(s) of method(s) to check
Output Parameters

 1    flag whether all methods are allowed on the object
Example

 if ($record->AllowedMethod( 'Telex' )) {
   print "Method Telex allowed\n";
 }


CONTENT METHODS

The following methods are standard methods that change contents of objects. They are usually used by the users of the module in which Liz::SQL is incorporated.


AppendString

Return/Set the string that will be added when appending values with Variable or AUTOLOADed content methods.

Example

 $object->AppendString( ', ' );


FirstName

Specify or return the first name of the object. Deletes the SORTNAME key if a new first name is specified.

Input Parameters

 1 new Firstname
   (default: no change)
Output Parameters

 1 current/old firstname 
Example

 $object->FirstName ( 'Elizabeth' );
 $firstname = $object->FirstName;


FullName

Return the FullName of the object, or construct it from the given parameters. The FullName is constructed from the FIRSTNAME, PREFIX and NAME fields, with only one space between them. Can be called both as a method or as a subroutine.

Input Parameters

 1 first name
   (default: field "FIRSTNAME')
 2 prefix
   (default: field "PREFIX")
 3 (last)name
   (default: field "NAME")
Output Parameters

 1 current FullName
Example

 $fullname = $contact->FullName;
Example

 $fullname = Liz::FullName( $firstname,$prefix,$name );


IP

Specify or return the IP-number of the object. IP-numbers are stored as packed 4-byte integers, therefore a special method is needed.

Input Parameters

 1 new IP-number of object
Output Parameters

 1 current/previous IP-number of object


Limit

Limit the length of a string to a specified length, replacing the last 3 bytes that would fit with '...' if the string does not fit. Can be called as either a subroutine or as a method.

Input Parameters

 1 string (adapts directly if called in a void context)
 2 maximum length
Output Parameters

 1 possibly adapted string
Example

 $string = $contact->Limit( $string,32 );
Example $string = Liz::Limit( $string,32 );
Example

 Liz::Limit( $string,32 );


Name

Specify or return the name of the object. Deletes the SORTNAME key if a new name is specified.

Input Parameters

 1 new value for name property
   (default: no change)
Output Parameters

 1 current/old value for name
Example

 $object->Name( 'Belgium' );
 $name = $object->Name;


Password

Specify or return the password of the object. Passwords are stored encrypted so that a special method is necessary. Can either be called as a method or as a subroutine.

Input Parameters

 1 new value for password property
   (default: no change)
Output Parameters

 1 current/old (encrypted) value for password
   (always returns current encrypted value if called as a subroutine)
Example

 $object->Password( 'catamaran' );
 $password = $object->Password;

or:

 my( $password ) = Liz::Password( 'catamaran' );


SortName

Specify or return the sortname of the object. This can be either a HN object, or any of its inherited objects.

Input Parameters

 1 new value for sortname property
   (default: no change)
Output Parameters

 1 current/old value for sortname
Note

This method should be called after method FirstName or Name, because those methods will reset the SORTNAME key of the object.

Example

 $object->Name( 'The Netherlands' );
 $object->SortName( 'netherlands' );
 $sortname = $object->SortName;


UserName

Specify or return the username of the object. Usernames can only consist of one word and lowercase alphanumeric characters only.

Input Parameters

 1 new value for username property
   (default: no change)
Output Parameters

 1 current/old value for username
Example

 $object->UserName( 'liz' );
 $username = $object->UserName;
Note

The field ``NAME'' is used to store the username into the object.


Option

Return the contents of an option from an email header. Can be used both as a method or as a subroutine.

If the option can occur more than once in an email header, then method OptionList should be used instead.

Input Parameters

 1 option to retrieve contents of
 2 email (or other Option: Tag) header
   (default: field HEADER in object)
Output Parameters

 1 contents of option (undef if not found)
 2 possibly adapted header with the option removed
Example

 $to = $self->Option( 'To' );
 $from = Liz::Option( 'From',$header );
 ($subject,$header) = $self->Option(


OptionList

Return the contents of an option from an email header. Can be used both as a method or as a subroutine. Similar to method Option, but always returns all options as a list, (or as a reference to a list in a scalar context) rather than just the first occurrence.

Input Parameters

 1 option to retrieve contents of
 2 email (or other Option: Tag) header
   (default: field HEADER in object)
Output Parameters

 1..N contents of options found
Example

 foreach ($self->OptionList( 'Received' )) {
   print "Received: $_\n";
 }
Example

 $received = $self->OptionList( 'Received' );
 foreach (@{$received}) {
   print "Received: $_\n";
 }


AUTOLOADed content methods

Called when a method is not found. In the Liz module we assume that if the method does not exist, it is assumed that the method is setting or returning an uppercased key of the object that was available.

Call method allow to specify which keys can be obtained or changed by AUTOLOADing.

Input Parameters

 1 value to set
   (default: no change)
 2 flag: mark the object as changed if value was specified
   -1 = mark as changed if changed, add to CHANGEDLIST
    0 = mark as chanegd if changed (default)
    1 = do NOT mark as changed, even if changed
Output Parameters

 1 old/current value 
Example

 $object->Score( 100 );    # set value of key 'SCORE'
 $score = $object->Score;  # obtain value of key 'SCORE'


Get

Return the values of the specified methods on the indicated object, or set variables in the caller's namespace when called in a void context.

Set variables associated with all allowable methods on the object when no methods are specified in a void context.

If a method is supposed to return a list (as indicated by the fact that the name ends in ``IDs''), then either a reference to that list is returned if the result is retrieved in variables, or the list by that name (but without the trailing ``s'') will be set in the caller's namespace.

The complement of the Set method.

Input Parameters

 1..N the names of the methods to be executed on the object
      (default in void context: all methods known to be allowed on the object)
Output Parameters

 1..N list with values returned by the methods
Example

 ($name,$sortname) = $object->Get( qw(Name SortName) );

 $object->Get( qw(Summary Text) );
 print "summary = $summary, text = $text\n";
Example

 $object->Get( qw(ZippoIDs) );
 foreach (@zippoID) {
   print "ID=$_\n";
 }
Example

 $object->Get;


GetFields

Return the values of the specified fields to the associated value in the object.

Use method SetFields to set the values of one or more fields in the object.

Can also be used as a subroutine: the first parameter should then be the reference to the hash with the fields.

Input Parameters

 1..N name of field of which to return the value
Output Parameters

 1..N values associated with the field
Example

 ($ID,$table,$categoryset) = $self->GetFields( qw(ID TABLE CATEGORYSET) );
 ($ID,$table,$categoryset) = Liz::GetFields( $object,qw(ID TABLE CATEGORYSET) );


ReRef

Return a reference to a hash, list or scalar. It performs the opposite function to UnRef.

Input Parameters

 1 string of originally reffed hash, list or scalar
Output Parameters

 1 reference to hash, list or scalar


Set

Set the values of the specified methods on the indicated object using variables and lists from the caller's namespace. The complement of the Get method.

If a method is supposed to read in a list from the caller's namespace, then the list with the same name, but without the trailing ``s'', will be read and placed in the object.

Input Parameters

 1..N the names of the methods to be executed on the object
      (default: all allowable methods on the object)
Output Parameters

 1    the object itself, handy for oneliners
Example

 print "summary = $summary, text = $text\n";
 $object->Set( qw(Summary Text) );
Example

 @zippoID = (1,2,3);
 @zappoID = (4,5,6);
 $object->Set( qw(ZippoIDs ZappoIDs) );
Example

 $name = 'Elizabeth Mattijsen';
 $email = 'liz@xxLINK.nl';
 $object->Set;


SetFields

Set the values of the specified fields to the associated value in the object. Handy for additional initializations of an object and therefore usually only used internally.

Use method GetFields to obtain values of one or more fields in the object.

Can also be used as a subroutine: the first parameter should then be the reference to the hash with the fields.

Input Parameters

  odd name of field to be set
 even value to be placed in field
Example

 $self->SetFields(
  'ID',$ID,
  'TABLE',$table,
  'CATEGORYSET',$categoryset );
Example

 Liz::SetFields( $object,
  'ID',$ID,
  'TABLE',$table,
  'CATEGORYSET',$categoryset );


UnRef

Change a reference to a hash, list or scalar into a flat-file text. Performs the opposite function of ReRef.

Input Parameters

 1 reference to a hash, list or scalar
Output Parameters

 1 flat-file text


Variable

Set or return the value of a key associated with an object. Intended to be used by methods internal to a module only.

Input Parameters

 1 key to set or obtain value of
 2 value to set
   (default: no change)
 3 flag: mark the object as changed if value was specified
   -1 = mark as changed if changed, add to CHANGEDLIST
    0 = mark as changed if changed (default)
    1 = do NOT mark as changed, even if changed
Output Parameters

 1 old/current value 
Example

 # create method Changed to return value of key 'CHANGED'
 sub Changed { $_[0]->Variable('CHANGED' ) }
 # create method Score to set/return value of key 'SCORE'
 sub Score { $_[0]->Variable('SCORE',$_[1]) ) }
Note

The value to be set may also be a reference to a hash, list or a scalar. The values of the hash, list or scalar will be encoded in the object (suitable for storage in a text field in a database). If such a value is requested again, it will be returned as it was passed: as a reference to a hash, list or scalar.

This feature is very handy in the case one wants to store more than one ``field'' in a database of which the fields have already been defined. The reference is then in fact a ``sub-field'' definition that can be different for each record in the database.

Note that the append feature can not be used when the value set has been a reference.


List

Set or return the list of values of a key associated with an object. Intended to be used by methods internal to a module only. Specifically intended for storing strings of categories of the Liz::CategorySet module.

Input Parameters

 1    key to set or obtain values of
 2..N new values to set
      (default: no change)
Output Parameters

 1..N old/current values
Note

Does not ever mark the as changed. Also never removes the ID-field.

Example

 sub Interests { Liz::List( shift,'INTERESTS',@_ ) }

 $member->Interests( @interests );
 @interests = $member->Interests;


OBJECT INHERITANCE METHODS

The following methods are used mainly when handling objects within objects, and the updating of these objects to the database.


Inherit

Inherit a number of values from another object.

Input Parameters

 1    object or class to copy from
 2..N keys to copy
Example

 $self->Inherit( $class,qw(DBH DEBUG TMP) );
 $self->Inherit( $hn,qw(DBH DEBUG TMP) );


MissingValues

Check the specified variables from the caller's namespace and return the list of names of the variables that were not set. Can also be used for any other namespace as specified by the field ``NAMESPACE''.

Input Parameters

 1..N hash of variable names (including type prefix) and showable names
Output Parameters

 1..N showable names of variables that were not set
Example

 print "summary = $summary, text = $text\n";
 <LOOP "$object->MissingValues( qw($summary Summary $text Text) )>
 <ENDLOOP>


DEBUGGING AND ASSOCIATED METHODS


Debug

Specify or return the current debug setting.

If called as a class method, sets or returns the defaults with which new objects will be created. If called as an object method, only changes or returns the value for that object.

The default is: 0 (off).

Input Parameters

 1 new debug level
   (default: no change)
Output Parameters

 1 current/old debug level
Example

 HN->Debug( 1 );
 $object->Debug( 0 );
 $debug = $object->Debug;


Error

Return the last error message associated with the object.

Output Parameters

 1 last error message
Example

 $error = $object->Error;


TMP

Specify or return the directory in which temporary files are stored.

If called as a class method, sets or returns the defaults with which new objects will be created. If called as an object method, only changes or returns the value for that object.

The default is: '/tmp'.

Input Parameters

 1 new directory to be used to store temporary files
   (default: no change)
Output Parameters

 1 current/old directory setting
Example

 HN->TMP( '/export/home/local/tmp' );
 $object->TMP( '/export/home/local/tmp' );
 $TMP = $object->TMP;


Dump

Return some or all keys in dump format associated with the object. Recurse for all the keys that are a reference to a hash, list or a scalar.

Because the first parameter of a subroutine called as a method is always the object, it is also possible to call Dump as a subroutine. The object of which to dump the keys, must then be specified as the first parameter.

Input Parameters

 1    spaces to prefix at the initial level (optional)
      (default: none)
 2..N keys to be dumped
      (default: all keys in the object)
Example

 print $object->Dump;
 WriteContents( $filename,$object->Dump( qw(ERROR ID NAME SORTNAME) );
Example

 $text = Liz::Dump( $object,'  ' );


ExpandValue

Subroutine for expanding a value to a readable format for reporting. It is usually used by other modules or methods, most notably the Dump method and the Liz::Perl error reporting functions.

Currently performs the following checks for now:

 - if the value is an IP-number, then a reverse lookup is attempted and added if successful
 - if the value is numerically 0, the string "0" is returned
 - if the value is empty, the string "(null)" is returned
 - if the value is undefined, the string "(undef)" is returned
 - if the value contains TAB characters, they are expanded to "\t"
 - if the value contains Carriage Return characters, they are expanded to "\r"
 - if the value contains null bytes, they are expanded to "\0"
 - if the value is longer than X bytes, then it will be shortened to X bytes

Other checks and conversions may be added in the future.

Input Parameters

 1 value to expand
 2 maximum number of bytes for a value
   (default: 255)
Output Parameters

 1 expanded value
Example

 print Liz::ExpandValue( $value );
 $text .= "$key=".Liz::ExpandValue($value)."\n";


OBTAINING DATA FROM CGI SCRIPTS

The Liz module allows you to obtain data from scripts, even file uploads, into the namespace of your choice. And then share them between namespaces at will.


GetPostData

Reads in GET or POST data, converts it to unescaped text, and stores the values obtained in variables within the namespace indicated. If more than one value is received per variable, the array with the same name contains all values received.

If just a value was passed in a GET operation, then the variable ``$query'' will be set.

If a file was passed in a POST operation, the original filename is stored in a variable with the same name as the contents, but with the string ``_filename'' postfixed, so ``$banner_filename'' would contain the name of the file of which the contents is stored in ``$banner''.

If an image was clicked to submit the data, then the variable $action will be set to the name of the image if there is no variable by that name already. The X and Y position where the image was clicked, are available in the variable with the same name as the image postfixed with ``_x'' and ``_y''.

It is possible to access the ``raw'' data with the variable $GETPOSTDATA which is set in the namespace specified. It contains a reference to the actual data, use ``$$GETPOSTDATA'' to get at the actual contents.

Input Parameters

 1 namespace in which to read values into variables
   (default: caller's namespace)
 2 Apache::Request object or URLencoded string to parse
   (default: result from posting)
Output Parameters

 1 error found (undef if no error found)


GetCookies

Reads the environment variables HTTP_COOKIE (or a specified string), converts it to unescaped text, and stores the values obtained in a hash by the name '%cookiejar' within the namespace indicated.

Input Parameters

 1 namespace in which to read values into variables
   (default: caller's namespace)
 2 URLencoded string to parse
   (default: result from posting)
 3 name of hash to store cookies in
   (default: 'cookiejar')
Output Parameters

 1 error found (undef if no error found)


Share

Share variables, routines and globs between namespaces.

Input Parameters

 1 first variable to be shared (namespace defaults to caller's)
 2 namespace and name to share with (name defaults to from)
 ...


AUTHOR

Elizabeth Mattijsen ( lizperl@INC.nl )

with contributions by:

- Sjoerd Lawende (sjoerd@xxLINK.nl)


COPYRIGHT

(C) 1996-2000 International Network Consultants


HISTORY

Version 2.27, 1 May 2000

Added ``-'' as valid character in a domein-name in subroutine/method CheckEmailAddress.

Version 2.26, 28 March 2000

Added ``touch'' to WriteContents so that a file on a mounted NFS-system will always have the last modified/access times in sync with the local system.

Added daylight saving time hack to SysTime2SecondsFromGMT to quickly fix problem. Apparently mktime does not take daylight saving time into account.

Version 2.25, 5 January 2000

Fixed problem with SysTime2Int: the default was not being set.

Version 2.24, 29 December 1999

Added new method/subroutine SysTime2Midnight to convert a system time value to its value at midnight of that day.

Version 2.23, 28 December 1999

Added new method/subroutine SysTime2Int, which is a sensible front-end for localtime() and gmtime().

Version 2.22, 20 December 1999

Fixed problem in Int2SysTime when a year < 1900 would be specified.

Version 2.21, 3 December 1999

Put module name between quotes to fix obscure bug in Perl 5.005x under ModPerl in subroutines Contents and WriteContents.

Version 2.20, 12 November 1999

Added subroutine/method Limit to limit strings to a certain length.

Version 2.19, 31 September 1999

Subroutine/Method Contents now returns undef if the file or pipre could not be read.

Version 2.18, 19 September 1999

Method/Subroutine CheckEmailAddress now also checks for a correct top level domain if Liz::Calc::ISO2Country is also available.

Version 2.17, 14 September 1999

Method SortName now makes any new value lowercase and alphanumeric only.

Version 2.16, 31 August 1999

Method SysTime2Timestamp now optionally returns a timestamp in local time, rather than GMT as before.

New subroutine/method SysTime2SecondsFromGMT added. Returns the time difference here and GMT in seconds.

Version 2.15, 29 August 1999

New method/subroutine Int2SysTime added: convert from integer values to a Unix time value.

Subroutine/Method Timestamp2Date now does not need an empty first parameter anymore if the default format is needed.

Subroutines/Methods Host2IP and IP2Host now also accept and return a list of Ip-numbers or host names.

Subroutines PackIP and UnpackIP now accept and return lists when appropriate, and can now also be called as methods.

Version 2.14, 24 August 1999

Documented the ``inherit from module'' feature in method allow.

Version 2.13, 11 August 1999

Added extra parameter to subroutine ExpandValue so that you can specify the maximum length of the expanded value.

Version 2.12, 8 August 1999

New method/subroutine FullName added: return the full name specification of a given firstname, prefix and (last)name.

Version 2.11, 30 July 1999

Fixed problem in Timestamp2Date that would cause literal strings to fail (introduced in version 2.10).

Version 2.10, 28 July 1999

Method/subroutine Timestamp2Date now defaults to the current date and time.

Version 2.09, 24 July 1999

Added method AllowedMethod which will return a flag indicating whether all methods specified are allowed for the given object.

Version 2.08, 13 July 1999

Fixed problem in Contents which was introduced in 1.71, which would cause any pipes to simply not work.

Version 2.07, 2 July 1999

Added setting of variable $GETPOSTDATA in specified namespace in method/subroutine GetPostData.

Version 2.06, 30 June 1999

New method/subroutine CheckEmailAddress added: check whether an email address is syntactically correct.

Version 2.05, 13 May 1999

Changed method Set so that it will default to all allowable methods.

Changed method Get so that it will default to all allowable methods when called in a void context without any parameters.

Version 2.04, 12 May 1999

Fixed problem that would change the global ALLOWED variable of the module reading from, when using methode allow as a class method and while specifying just the module name.

Version 2.03, 10 May 1999

Method allow now also allows a specification of a package (in the form Main::Sub) to indicate using all allowable methods from that package.

Version 2.02, 9 May 1999

Subroutine GetPostData now also allows ; as a seperator in GET query strings.

Cleaned up various m# and s# that were not made constant yet, when they could.

General source cleanup, now using indented source format.

Version 2.01, 28 April 1999

Upgraded subroutine GetPostData to handle input from Apache::Request objects also.

Version 2.00, 14 April 1999

Fixed problem with referencing undefined $ENV{'DOCUMENT_ROOT'}.

Version 1.99, 12 April 1999

Method/Subroutine Dump now calls the proper Liz::Perl Print routine when called in a void context from a Liz::Perl script. This will ensure dumps will be automatically buffered also.

Version 1.98, 5 April 1999

Subroutine ExpandValue now also expands TAB, CR and null bytes to something visible.

Version 1.97, 2 April 1999

New subroutines/methods SetFields and GetFields added. Allow setting and retrieving fields in an object by using lists.

Version 1.96, 31 March 1999

Adapted method Inherit so it does not copy non-existing keys.

New method ExpandValue added: expands a value so that it can be sensibly used for reporting. Adapted method Dump so that all values are now properly expanded.

Method/Subroutine Dump now automatically adds hostname information to IP-number values.

Moved subroutines Host2IP and IP2Host here from the Liz::Calc module. Added support for being called as a method. Added some examples in the documentation.

Improved performance within ModPerl environment by changing all regular expressions to include the ``o'' attribute (for constant matching string) where appropriate.

Version 1.95, 30 March 1999

Method Dump now also allows the number of spaces at the beginning of each line to be specified.

Version 1.94, 24 March 1999

New subroutine/method OptionList added: return list of options in a header, similar to Option.

Version 1.93, 18 March 1999

Adapted Option so that it can also be called as a subroutine. No also optionally returns the header with the requested option removed.

Adapted Gzip so that the zipped version of the value is stored on the filesystem, as opposed to the unzipped (presumably larger) version.

Fixed problem in WriteContents that would not allow writing to a pipe.

Version 1.92, 12 March 1999

Moved methods/subroutines Int2Timestamp and Timestamp2Int here from the Liz::SQL module. This made much more sense than leaving it in the Liz::SQL module as method/subroutine Timestamp2Date also moved here.

Version 1.91, 9 March 1999

New subroutine GetCookies added: obtain information about cookies into a hash in a manner similar to GetPostData.

Moved method/subroutine Timestamp2Date here from the Liz::SQL module. This made much more sense than leaving it in the Liz::SQL module, since Unix timestamps are valid input parameters.

Moved language methods Nederlands, Francais, Deutsch and English here from the Liz::SQL module also. They also make much more sense here. Also moved internal conversion subroutines ConvertNL, ConvertFR, ConvertDE and SetLanguage here.

Version 1.90, 3 February 1999

Method Dump now also prints out seperate messages for empty lists and undefined scalars.

Fixed problem with matching of last option in a header with subroutine/method Option.

Version 1.89, 22 January 1999

Method Dump now prints the dump automatically when called within a void context, and puts <PRE> </PRE> around it if that is done from within a Liz::Perl environment.

Version 1.88, 20 January 1999

Fixed problem with use of uninitialized values in allow.

Version 1.87, 12 January 1999

Method Dump augmented: now recurses for all references to hashes, lists and scalars.

New method List: allows for transparent storing of lists in an object, similar to Variable.

Version 1.86, 10 January 1999

Methods Set and Get now support methods that require or return a list: these methods are recognised by the name which should end in ``IDs''.

Version 1.85, 6 January 1999

Removed AddScalars2Hash. Function is now taken over by Scalars2Hash.

Subroutine Scalars2Hash now allows for the specification of a reference to an existing hash to which the values should be added.

Version 1.84, 6 January 1999

Added binmode() to WriteContents so that GIF-files can also be written properly.

Version 1.83, 5 January 1999

Fixed problems in AddScalars2Hash and Hash2Scalars introduced yesterday.

Version 1.82, 4 January 1999

Added AddScalars2Hash.

Version 1.81, 1 January 1999

Moved ImageDimensions to GetImageDimesions in Liz::Calc.

Version 1.80, 30 December 1998

Created a platform independend version of GetImageDimensions called ImageDimensions. This sub is currently beta, but will be finished next year. :-)

Version 1.79, 11 November 1998

Reduced UserName to a shell around Name. It's use was too unclear and apparently not necessary anymore.

Version 1.78, 6 October 1998

Reduced memory footprint by fully qualifing global variables.

Version 1.77, 28 September 1998

Fixed problem in special method FirstName.

Version 1.76, 12 September 1998

Method Get now also handles the case when only one variable is used in a scalar context to obtain the value.

Version 1.75, 17 August 1998

Methods/Subroutines Contents and WriteContents now accept the '//filename' notation to indicate files relative to the document root as defined by the environment variable ``DOCUMENT_ROOT''.

Version 1.74, 11 August 1998

Fixed problem in Variable introduced on August 5.

Version 1.73, 5 August 1998

New method/subroutine UnRef added: return reference to hash, list or scalar of original values.

New method/subroutine ReRef added: change a reference to hash, list or scalar into flat-file text.

Version 1.72, 30 July 1998

Subroutine GetPostData now also allows the URLEncoded string with parameters to be directly specified. This can be handy in those cases were people actually used that format as a database format.

Version 1.71, 25 July 1998

Subroutines Contents and WriteContents upgraded to use IO::File so that there will never be a potential filehandle clash problem.

Subroutine/Method Pwd now uses the Cwd::getcwd routine for maximum portability.

Version 1.7, 18 July 1998

New subroutine LastModified added: returns the last modified date and time of one or more files.

Version 1.61, 10 July 1998

Method Password can now also be called as a subroutine.

Version 1.6, 8 July 1998

New subroutine Scalars2Hash added: turns a list of variables into a reference to a hash table in which the names of the variables are the keys.

New subroutine Hash2Scalars added: turns a reference to a hash table into variables in the indicated namespace in which the keys become the names of the variables.

Method Variable now also accepts (and returns!) references to hash tables, lists and scalars.

Version 1.52, 26 June 1998

Method Inherit now performs more error checks to prevent it from crashing scripts on incorrect input.

Version 1.51, 13 June 1998

Method Set no returns the object itself: handy for oneliners.

Version 1.5, 4 June 1998

Method Option moved here from the Liz::Mail module.

Version 1.4, 1 June 1998

Method UserName now stores the name in the ``NAME'' field, instead of the ``USERNAME'' field.

Version 1.3, 27 May 1998

Method Inherit now does not mark objects as changed anymore.

Version 1.2, 26 May 1998

New method Set added: set values in the object by executing the associated methods.

Moved several content methods over from Liz::SQL:

 L<FirstName>
 L<IP>
 L<Name>
 L<Password>
 L<SortName>
 L<UserName>

Fixed problem in method AppendString,

Version 1.1, 25 May 1998

Method Inherit now marks object as changed.

Method/Routine SysTime2Timestamp moved here from the Liz::SQL.pm module.

Routines PackIP and UnpackIP added.

Version 1.0, 17 May 1998

Rebuilt Liz.pm basically from scratch. Now for the first time it is really a module. But a module intended to inherit from, not to create any objects of itself.

Support for AppendString added: now an extra string will be prefixed when adding values to already existing fields.

Version 0.2, 11 February 1998

Added routine _SetVariable as a basic routine for true Perl modules.

Version 0.1, 2 February 1998

First version of this true Perl module, based on routines developed for the LizPerl library.