NAME

Date::ICal - Perl extension for ICalendar date objects.

SYNOPSIS

use Date::ICal;

$ical = Date::ICal->new( ical => '19971024T120000' );
$ical = Date::ICal->new( epoch => time );
$ical = Date::ICal->new( year => 1964,
    month => 10, day => 16, hour => 16,
    min => 12, sec => 47, tz => '0530' );

$hour = $ical->hour;
$year = $ical->year;

$ical_string = $ical->ical;
$epoch_time = $ical->epoch;

DESCRIPTION

Date::ICal talks the ICal date format, and is intended to be a base class for other date/calendar modules that know about ICal time format also.

See http://dates.rcbowen.com/unified.txt for details

METHODS

Date::ICal has the following methods available:

new

A new Date::ICal object can be created with any valid ICal string:

my $ical = Date::ICal->new( ical => '19971024T120000' );

Or with any epoch time:

my $ical = Date::ICal->new( epoch => time );

Or, better still, create it with components

my $date = Date::ICal->new( 
                       day => 25, 
                       month => 10, 
                       year => 1066,
                       hour => 7,
                       min => 15,
                       sec => 47
                       );

If you call new without any arguments, you'll get a Date::ICal object that is set to the time right now.

my $ical = Date::ICal->new();

ical

$ical_string = $ical->ical;

$ical->ical( '19981016' );

Retrieves, or sets, the date on the object, using any valid ICal date/time string.

The ICal representation is the one authoritative value in the object, and so if it is changed, it must be able to indicate that the other values are no longer valid. Or set the correctly. Or something. Comments welcomed.

epoch

$epoch_time = $ical->epoch;

$ical->epoch( 98687431 );

Sets, or retrieves, the epoch time represented by the object, if it is representable as such. (Dates before 1971 or after 2038 will not have an epoch representation.)

Internals note: The ICal representation of the date is considered the only authoritative one. This means that we may need to reconstruct the epoch time from the ICal representation if we are not sure that they are in synch. We'll need to do clever things to keep track of when the two may not be in synch. And, of course, the same will go for any subclasses of this class.

#}}}

add#{{{

$date->add( %hash ); # Hash of day, hour, min, etc, values
$date->add( ical => $ical_duration_string );

Adds a duration to a Date::ICal object.

Duration should be passed in as either an ical string, or as a hash of date/time properties.

The result will be normalized. That is, the output time will have meaningful values, rather than being 48:73 pm on the 34th of hexadecember.

$self->add( month=>2 );
$self->add( duration =>'P1W' );

_normal

$self->_normal($attrib,$suggestednewvalue);

This attempts to flatten out of range values to what they should be and adjust
adjcent values accordingly.  For instance passing 'month' and 14 to _normal
would result in the year being incremented and the ical month field being set
to two

_month_length

$self->_month_length();

This utility returns the length of the current ical month.

_alter_period

$self->_alter_period($attrib);

called by add and _normal to do the hard work of flattening the values

add_duration

$self->add_duration('P2W');

Adds a rfc2445 duration to current $self->{ical}

compare

$cmp = $date1->compare($date2);

@dates = sort {$a->compare($b)} @dates;

Compare two Date::ICal objects. Semantics are compatible with sort; returns -1 if $a < $b, 0 if $a == $b, 1 if $a > $b.

day

my $day = $date->day;

Returns the day of the month.

Day is in the range 1..31

month

my $month = $date->month;

Returns the month of the year.

Month is returned as a number in the range 1..12

year

my $year = $date->year;

Returns the year.

hour

my $hour = $date->hour

Returns the hour of the day.

Hour is in the range 0..23

min

my $min = $date->min;

Returns the minute.

Minute is in the range 0..59

sec

my $sec = $date->sec;

Returns the second.

Second is in the range 0..60. The value of 60 is (maybe) needed for leap seconds. But I'm not sure if we're going to go there.

julian

my $jd = $date->jd;

Returns the "Julian day", with the fractional part representing the time of day as a fraction of the seconds in a day. This should not be thought of as a real julian day, because it's not. The module is internally consistent, and that's enough.

This really should be considered an internal method.

TODO

- add timezone support, including moving between timezones

- add gmtime and localtime methods, perhaps?

AUTHOR

Rich Bowen (DrBacchus) rbowen@rcbowen.com

And the rest of the Reefknot team.

SEE ALSO

datetime@perl.org mailing list

http://reefknot.org/

http://dates.rcbowen.com/

Time::Local

Net::ICal

cpanm Date::ICal

perl -MCPAN -e shell
install Date::ICal