NAME

Data::ICal::DateTime - convenience methods for using Data::ICal with DateTime

SYNPOSIS

    # performs mixin voodoo
    use Data::ICal::DateTime; 
    my $cal = Data::ICal->new( filename => 'example.ics');


    my $date1 = DateTime->new( year => 2005, month => 7, day => 01 );
    my $date2 = DateTime->new( year => 2005, month => 7, day => 07 );
    my $span  = DateTime::Span->from_datetimes( start => $date1, end => $date2 );

    my @events = $cal->events();           # all VEVENTS
    my @week   = $cal->events($span);      # just in that week
    my @week   = $cal->events($span,'day');# explode long events into days 

    my $event = Data::ICal::Entry::Event->new();
    
    $event->start($start);                 # $start is a DateTime object
    $event->end($end);                     # so is $end

    $event->duration($duration);           # $duration is DateTime::Duration 
    $event->recurrence($recurrence);       # $reccurence is a DateTime list, 
                                           # a DateTime::Span list,  
                                           # a DateTime::Set, 
                                           # or a DateTime::SpanSet
 
    $event->start;                         # returns a DateTime object
    $event->end;                           # ditto
    $event->duration;                      # returns a DateTime::Duration
    $event->recurrence;                    # returns a DateTime::Set
    $event->period;                        # returns a DateTime::Span object
    $event->rdate;                         # returns a DateTime::Set
    $event->exrule;                        # returns a DateTime::Set
    $event->exdate;                        # returns a DateTime::Set
    $event->explode($span);                # returns an array of sub events
                                           # (if this is recurring);
    $event->explode($span,'week');         # if any events are longer than a 
                                           # week then split them up
    $event->is_in($span);                  # whether this event falls within a 
                                           # Set, Span, or SetSpan


    $cal->add($event);

methods

DESCRIPTION

METHODS

events [span] [period]

Provides a Data::ICal object with a method to return all events.

If a DateTime::Set, DateTime::Span or DateTime::SpanSet object is passed then only the events that occur within that set will be returned including expansion of all recurring events. All events will be normalised to have a dtstart and dtend rather than any other method of determining their start and stop time.

Additionally you can pass a period string which can be one of the following

    year month week day hour 
    minute second nanosecond

This will explode an event into as many sub events as needed e.g a period of 'day' will explode a 2-day event into 2 one day events with the second starting just after the first

start [new]

Returns a DateTime object representing the start time of this event.

May return undef.

If passed a DateTime object will set that to be the new start time.

end

Returns a DateTime object representing the end time of this event.

May return undef.

If passed a DateTime object will set that to be the new end time.

duration

Returns a DateTime::Duration object representing the duration of this event.

May return undef.

If passed a DateTime::Duration object will set that to be the new duration.

period

Returns a DateTime::Span object representing the period of this event.

May return undef.

If passed a DateTime::Span object will set that to be the new period.

recurrence

Returns a DateTime::Set object representing the union of all the RRULEs in this object.

May return undef.

If passed one or more DateTime lists, DateTime::Span lists, DateTime::Sets, or DateTime::SpanSets then set the recurrence rules to be those.

rdate

Returns a DateTime::Set object representing the set of all RDATEs in the object.

May return undef.

exrule

Returns a DateTime::Set object representing the union of all the EXRULEs in this object.

May return undef.

If passed one or more DateTime lists, DateTime::Span lists, DateTime::Sets, or DateTime::SpanSets then set the recurrence rules to be those.

exdate

Returns a DateTime::Set object representing the set of all RDATEs in the object.

May return undef.

summary

Returns a string representing the summary of this event.

This string may contain embedded new lines and other escaped characters.

It may be useful to do

    my $summ = $event->summary || '';
    evel "\$summ = \"$summ\";";

May return undef.

description

Returns a string representing the summary of this event.

This string may contain embedded new lines and other escaped characters.

It may be useful to do

    my $desc = $event->description || '';
    evel "\$desc = \"$desc\";";

May return undef.

explode <span> [period]

Takes DateTime::Set, DateTime::Span or DateTime::SpanSet and returns an array of events.

If this is not a recurring event, and it falls with the span, then it will return one event with the dtstart and dtend properties set and no other time information.

If this is a recurring event then it will return all times that this recurs within the span. All returned events will have the dtstart and dtend properties set and no other time information.

If period is optionally passed then events longer than period will be exploded into multiple events.

period can be any of the following

    year month week day hour
    minute second nanosecond

is_in <span>

Takes DateTime::Set, DateTime::Span or DateTime::SpanSet and returns whether this event can fall within that time frame.

AUTHOR

Simon Wistow <simon@thegestalt.org>

COPYING

Copyright, 2005 Simon Wistow

Distributed under the same terms as Perl itself.

BUGS

Potential timezone problems?

No tests for

    EXRULE
    EXDATE
    RDATE

SEE ALSO

DateTime, DateTime::Set, Data::ICal, Text::vFile::asData

cpanm Data::ICal::DateTime

perl -MCPAN -e shell
install Data::ICal::DateTime