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

WARNING

    THIS VERSION IS BORKED. THIS IS A DEVELOPMENT RELEASE ONLY.
    
SYNOPSIS
        use Date::ICal;

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

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

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

        $ical->epoch( time+60 ); # Set the time a minute ahead

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 );

    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.

  _parse_ical

        $self->_parse_ical;

    "_parse_ical" is an internal method (although I suppose you could call
    it externally if you really wanted to) which repopulates other
    attributes based on the ical field. This should be called by various
    methods if an attribute is undefined.

  _format_ical

        $self->_format_ical;

    This is an internal method used to rebuild the ical string when one
    component, such as the "second" or "month" field has been changed.

  _epoch_from_ical

        $self->_epoch_from_ical;

    This is an internal method used to determine the epoch time from the
    ical value.

  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.

TODO
    - IMPORTANT: rework internal storage to Julian dates and times
    - add support for initializing dates
    - add timezone support, including moving between timezones
    - add arithmetic methods: add, subtract, ...
    - 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