VERSION

This document describes version 0.14 released 1st September 2006.

SYNOPSIS

        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;

DEPENDENCIES

Tie::File

DESCRIPTION

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.

FILE LOCKING

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;

DATES

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.

How Tie::iCal interprets iCal files

Tie::iCal interprets files by mapping iCal components into Perl hash keys and iCal content lines into various Perl arrays and hashes.

Components

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'}]

Subcomponents

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.

Content Lines

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', ..], ... ]

BUGS

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.

AUTHOR

Blair Sutton, <mailto:[email protected]>, <http://www.numeninest.com/>

COPYRIGHT

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.

RELATED TO Tie::iCal…

perl, Tie::File, Date::ICal