iCal::Parser 1.14

iCal::Parser is a Perl module to parse iCalendar files into a data structure.

SYNOPSIS

use iCal::Parser

my $parser=iCal::Parser->new();
my $hash=$parser->parse($file);

$parser->parse($another_file);
my $combined=$parser->calendar;

my $combined=iCal::Parser->new->parse(@files);
my $combined=iCal::Parser->new->parse_files(@files);
my $combined=iCal::Parser->new->parse_strings(@strings);

This module processes iCalendar (vCalendar 2.0) files as specified in RFC 2445 into a data structure. It handles recurrences (RRULEs), exclusions (EXDATEs), event updates (events with a RECURRENCE-ID), and nested data structures (ATTENDEES and VALARMs). It currently ignores the VTIMEZONE, VJOURNAL and VFREEBUSY entry types.

The data structure returned is a hash like the following:

{
calendars=>[%cal, ...],
events=>{yyyy=>{mm=>{dd}=>{UID=>%event}}
todos=>[%todo, ...]
}

That is, it contains an array of calendar hashes, a hash of events key by year=>month=>day=>eventUID, and an array of todos.

Calendars, events and todos are "rolled up" version os the hashes returned from Text::vFile::asData, with dates replaced by DateTime objects.

During parsing, events in the input calendar are expanded out into multiple events, one per day covered by the event, as follows:
If the event is a one day "all day" event (in ical, the event is 24hrs long, starts at midnight on the day and ends a midnight of the next day), it contains no hour field and the allday field is set to 1.

If the event is a recurrence (RRULE), one event per day is created as per the RRULE specification.

If the event spans more than one day (the start and end dates are on different days, but does not contain an RRULE), it is expanded into multiple events, the first events end time is set to midnight, subsequent events are set to start at midnight and end at midnight the following day (same as an "allday" event, but the allday field is not set), and the last days event is set to run from midnight to the end time of the original multi-day event.

If the event is an update (it contains a RECURRENCE-ID), the original event is updated. If the referenced event does not exist (e.g., it was deleted after the update), then the event is added as a new event.
An example of each hash is below.