Date::Handler is a container for dates that holds all the methods to transform itself from Timezone to Timezone and format itself. This module idea comes from an original version written by dLux (Szabó, Balázs) <dlux@kapu.hu> in his module Class::Date.

Date::Handler is implemented in pure Perl using POSIX modules, it encapsulates the environnement variable TZ for it's time zone management so you don't have to play with it externally in the implementation. Date::Handler also supports localisation using POSIX where available.

It uses operator overloading and Delta date objects to calculates time differences.

A useful way of using Date::Handler in your code is to implement that a class that ISA Date::Handler. This way you can overload methods through the inheritance tree and change the object's behaviour to your needs.

Here is a small example of an overloaded class that specifies a default timezone different than the machine's timezone.

Date::Handler contains a feature by witch a date handler object can use intuitive month calculation. This means that Date::Handler will compensate for month overflows during delta operations.

For example, if you have a date handler that is 2002/01/30, and you add to it a delta of 1 month, standard Date::Handler object will give you a new object that is 2002/03/02. This is because POSIX will compensate for the month overflow and add 2 days to the date because February does not have a 29 or 30th in 2002. Date::Handler can compensate for that by using the INTUITIVE_MONTH_CALCULATIONS constant. (this is turned off by default).

This constant can be turned on during overloading (inheritance):

use constant INTUITIVE_MONTH_CALCULATIONS => 1;

Turning this constant on will tell Date::Handler to follow track of month overflow during operations. This will make it so that adding a month to 2002/01/30 will bring you to 2002/02/28. Adding another month to this will bring you (with intuition) to 2002/03/30, because Date::Handler keeps track of the "intuitive" day of the month.

Using INTUITIVE_MONTH_CALCULATIONS will also make it possible to pass an "intuitive_day" key to the new() constructor in order to simulate a previous addition.

In this example, the start date of 2002/02/28 with intuitive_day set to 30 will make it so that adding 1 month to the date will bring us to march 30th. Note that INTUITIVE_MONTH_CALCULATIONS will only affect month/day calculations and no time modifications will be applied.

Date::Handler provides a facility called INTUITIVE_DST_ADJUSTMENTS. This is implemented via an inherited constant, like the other options above. When INTUITIVE_DST_ADJUSTMENTS are turned on, Date::Handler will compensate for day light savings changes. For example, 2002/04/07 1AM + 1 day would give you 2002/04/08 1AM instead of 2AM. Note that INTUITIVE_DST_ADJUSTMENTS will not apply this compensation when the exact "turn over" date/time is detected. For example, 2002/04/06 2AM + 1 day would give you 2002/04/07 3AM because we don't compensate for this specific case.

Date::Handler provides yet another facility to add intuitive date calculations. By using INTUITIVE_TIME_CALCULATIONS (via inherited constant), Date::Handler will "remember" that it compensated for a DST adjustment and try to compensate for it.

For example, 2002/04/06 2AM + 1day would give you 2002/04/07 3AM. Adding a day to this date under INTUITIVE_TIME_CALCULATIONS would give you 2002/04/08 2AM because Date::Handler remembers it compensated for day light savings.

Combining INTUITIVE_DST_ADJUSTMENTS, INTUITIVE_MONTH_CALCULATIONS and INTUITIVE_TIME_CALCULATIONS will give a behaviour closer to the way humans expect the module to react.

This can be very useful to make date calculations a little more "humanized".

The intuitive "hour" can be faked by passing it to the new() constructor:

Date::Handler supports locales using POSIX setlocale() functions. The allowed values for the locale are listed (on most unix system) using the `locale -a` command. The Date::Handler defaults to "en_US" for it's locale when no locale are passed to the constructor. The constant DEFAULT_LOCALE can be overloaded to change this behaviour. Special note that the locales "english" and "en" are not implemented on most linux (Red Hat here) systems. You need to use the locale en_US, en_GB etc etc.

Date::Handler supports time zones using POSIX tzset() and tzname() functions. The allowed values for the time_zone key are listed (on linux systems) by look at the /usr/share/zoneinfo directory. The Date::Handler default to "GMT" for it's time zone when to time_zone key are passed to the constructor. The constant DEFAULT_TIME_ZONE can be overloaded to change this behaviour.

Date::Handler's formatting is provided by POSIX's strfmtime() function. The allowed parameters to the TimeFormat() method can be listed (on most unix system) using `man strftime`. By default, Date::Handler uses the format string '%c' to represent itself in most cases. The constant DEFAULT_FORMAT_STRING can be overloaded to change this behaviour.

To go forward or backward in time with a date object, you can use the Date::Handler::Delta objects. These objects represent a time lapse represented in months and seconds. Since Date::Handler uses operator overloading, you can 'apply' a Delta object on an absolute date simply by using '+' and '-'.

Example:

#A Delta of 1 year.
my $delta = new Date::Handler::Delta([1,0,0,0,0,0]);
my $date = new Date::Handler({ date => time } );
#$newdate is now one year in the furure.
my $newdate = $date+$delta;

Refer to the Date::Handler::Delta(1) documentation for more on Deltas.