Tie ical files to perl hashes.
This document describes version 0.14 released 1st September 2006.
use Tie::iCal;
tie %my_events, 'Tie::iCal', "mycalendar.ics" or die "Failed to tie file!\n";
tie %your_events, 'Tie::iCal', "yourcalendar.ics" or die "Failed to tie file!\n";
$my_events{"A-NEW-UNIQUE-ID"} = [
'VEVENT',
{
'SUMMARY' => 'Bastille Day Party',
'DTSTAMP' => '19970714T170000Z',
'DTEND' => '19970715T035959Z',
}
];
tie %our_events, 'Tie::iCal', "ourcalendar.ics" or die "Failed to tie file!\n";
# assuming %my_events and %your_events
# have no common keys (unless that's your intention)
#
while (my($uid,$event) = each(%my_events)) {
$our_events{$uid} = $event;
}
while (my($uid,$event) = each(%your_events)) {
$our_events{$uid} = $event;
}
untie %our_events;
untie %your_events;
untie %my_events;
Tie::File
Tie::iCal represents an \s-1RFC2445\s0 iCalendar file as a Perl hash. Each key in the hash represents an iCalendar component like \s-1VEVENT\s0, \s-1VTODO\s0 or \s-1VJOURNAL\s0. Each component in the file must have a unique \s-1UID\s0 property as specified in the \s-1RFC\s0 2445. A file containing non-unique UIDs can be converted to have only unique UIDs (see samples/uniquify.pl).
The module makes very little effort in understanding what each iCalendar property means and concentrates on the format of the iCalendar file only.
The Tie::iCal object returned by tie can also be used to access the underlying Tie::File object. This is accessible via the 'A' class variable. This may be useful for file locking.
my $ical = tie %events, 'Tie::iCal', "mycalendar.ics"; $ical->{A}->flock;
The iCalendar specification uses a special format for dates. This module makes no effort in trying to interpret dates in this format. You should look at the Date::ICal module that can convert between Unix epoch dates and iCalendar date strings.
Tie::iCal interprets files by mapping iCal components into Perl hash keys and iCal content lines into various Perl arrays and hashes.
An iCal component such as \s-1VEVENT\s0, \s-1VTODO\s0 or \s-1VJOURNAL\s0 maps to a hash key:-
BEGIN:VEVENT UID:a_unique_uid NAME1:VALUE1 .. END:VEVENT
corresponds to
$events{'a_unique_uid'} = ['VEVENT', {'NAME1' => 'VALUE1'}]
An iCal subcomponent such as \s-1VALARM\s0 maps to a list of hash keys:-
BEGIN:VALARM TRIGGER;VALUE=DURATION:-PT1S TRIGGER;VALUE=DURATION:-PT1S END:VALARM BEGIN:VALARM X-TIE-ICAL;VALUE=ANOTHER:HERE X-TIE-ICAL:HERE2 X-TIE-ICAL-NAME:HERE2 END:VALARM
corresponds to
'VALARM' => [ { 'TRIGGER' => [ [{'VALUE' => 'DURATION'},'-PT1S'], [{'VALUE' => 'DURATION'},'-PT1S'] ] }, { 'X-TIE-ICAL' => [ [{'VALUE' => 'ANOTHER'},'HERE'], ['HERE2'] ], 'X-TIE-ICAL-NAME' => 'HERE2' } ]
To see how individual content lines are formed see below.
Once unfolded, a content line may look like:-
NAME;PARAM1=PVAL1;PARAM2=PVAL2;...:VALUE1,VALUE2,...
having an equivalent perl data structure like: -
'NAME' => [{'PARAM1'=>'PVAL1', 'PARAM2'=>'PVAL2', ..}, 'VALUE1', 'VALUE2', ..]
or
NAME:VALUE1,VALUE2,...
having an equivalent perl data structure like: -
'NAME' => ['VALUE1', 'VALUE2', ..]
or
NAME:VALUE
having an equivalent perl data structure like: -
'NAME' => 'VALUE'
An blank value is mapped from
NAME:
to
'NAME' => ''
Multiple contentlines with same name, i.e. \s-1FREEBUSY\s0, \s-1ATTENDEE:-\s0
NAME;PARAM10=PVAL10;PARAM20=PVAL20;...:VALUE10,VALUE20,... NAME;PARAM11=PVAL11;PARAM21=PVAL21;...:VALUE11,VALUE21,... ...
having an equivalent perl data structure like: -
'NAME' => [ [{'PARAM10'=>'PVAL10', 'PARAM20'=>'PVAL20', ..}, 'VALUE10', 'VALUE20', ..], [{'PARAM11'=>'PVAL11', 'PARAM21'=>'PVAL21', ..}, 'VALUE11', 'VALUE21', ..], ... ]
or
NAME:VALUE10,VALUE20,... NAME:VALUE11,VALUE21,... ...
having an equivalent perl data structure like: -
'NAME' => [ ['VALUE10', 'VALUE20', ..], ['VALUE11', 'VALUE21', ..], ... ]
or in a mixed form, i.e.
NAME:VALUE10,VALUE20,... NAME;PARAM11=PVAL11;PARAM21=PVAL21:VALUE11,VALUE21,... NAME:VALUE12,VALUE22,... ...
having an equivalent perl data structure like: -
'NAME' => [ ['VALUE10', 'VALUE20', ..], [{'PARAM11'=>'PVAL11', 'PARAM21'=>'PVAL21', ..}, 'VALUE11', 'VALUE21', ..], ['VALUE12', 'VALUE22', ..], ... ]
Property names are assumed not to be folded, i.e.
DESCR IPTION:blah blah..
\s-1RRULE\s0 property does not support parameters.
Property names that begin with \s-1UID\s0 can potentially confuse this module.
Subcomponents such as \s-1VALARM\s0 must exist after any \s-1UID\s0 property.
Deleting events individually may leave non-RFC2445 compliant empty \s-1VCALENDAR\s0 objects.
Blair Sutton, <mailto:[email protected]>, <http://www.numeninest.com/>
Copyright (c) 2006 Blair Sutton. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
perl, Tie::File, Date::ICal