1iCal::Parser(3)       User Contributed Perl Documentation      iCal::Parser(3)
2
3
4

NAME

6       iCal::Parser - Parse iCalendar files into a data structure
7

SYNOPSIS

9         use iCal::Parser;
10
11         my $parser=iCal::Parser->new();
12         my $hash=$parser->parse($file);
13
14         $parser->parse($another_file);
15         my $combined=$parser->calendar;
16
17         my $combined=iCal::Parser->new->parse(@files);
18         my $combined=iCal::Parser->new->parse_files(@files);
19         my $combined=iCal::Parser->new->parse_strings(@strings);
20

DESCRIPTION

22       This module processes iCalendar (vCalendar 2.0) files as specified in
23       RFC 2445 into a data structure.  It handles recurrences ("RRULE"s),
24       exclusions ("EXDATE"s), event updates (events with a "RECURRENCE-ID"),
25       and nested data structures ("ATTENDEES" and "VALARM"s). It currently
26       ignores the "VTIMEZONE", "VJOURNAL" and "VFREEBUSY" entry types.
27
28       The data structure returned is a hash like the following:
29
30           {
31             calendars=>[\%cal, ...],
32             events=>{yyyy=>{mm=>{dd}=>{UID=>\%event}}
33             todos=>[\%todo, ...]
34           }
35
36       That is, it contains an array of calendar hashes, a hash of events key
37       by "year=>month=>day=>eventUID", and an array of todos.
38
39       Calendars, events and todos are "rolled up" version os the hashes
40       returned from Text::vFile::asData, with dates replaced by "DateTime"
41       objects.
42
43       During parsing, events in the input calendar are expanded out into
44       multiple events, one per day covered by the event, as follows:
45
46       •   If the event is a one day "all day" event (in ical, the event is
47           24hrs long, starts at midnight on the day and ends a midnight of
48           the next day), it contains no "hour" field and the "allday" field
49           is set to 1.
50
51       •   If the event is a recurrence ("RRULE"), one event per day is
52           created as per the "RRULE" specification.
53
54       •   If the event spans more than one day (the start and end dates are
55           on different days, but does not contain an "RRULE"), it is expanded
56           into multiple events, the first events end time is set to midnight,
57           subsequent events are set to start at midnight and end at midnight
58           the following day (same as an "allday" event, but the "allday"
59           field is not set), and the last days event is set to run from
60           midnight to the end time of the original multi-day event.
61
62       •   If the event is an update (it contains a "RECURRENCE-ID"), the
63           original event is updated. If the referenced event does not exist
64           (e.g., it was deleted after the update), then the event is added as
65           a new event.
66
67       An example of each hash is below.
68
69   Calendar Hash
70           {
71               'X-WR-CALNAME' => 'Test',
72               'index' => 1,
73               'X-WR-RELCALID' => '7CCE8555-3516-11D9-8A43-000D93C45D90',
74               'PRODID' => '-//Apple Computer\\, Inc//iCal 1.5//EN',
75               'CALSCALE' => 'GREGORIAN',
76               'X-WR-TIMEZONE' => 'America/New_York',
77               'X-WR-CALDESC' => 'My Test Calendar',
78               'VERSION' => '2.0'
79           }
80
81   Event Hash
82       Note that "hours" and "allday" are mutually exclusive in the actual
83       data.  The "idref" field contains the "id" of the calendar the event
84       came from, which is useful if the hash was created from multiple
85       calendars.
86
87           {
88               'SUMMARY' => 'overnight',
89               'hours' => '15.00',
90               'allday' => 1,
91               'UID' => '95CCBF98-3685-11D9-8CA5-000D93C45D90',
92               'idref' => '7CCE8555-3516-11D9-8A43-000D93C45D90',
93               'DTSTAMP' => \%DateTime,
94               'DTEND' => \%DateTime,
95               'DTSTART' => \%DateTime
96               'ATTENDEE' => [
97                  {
98                     'CN' => 'Jay',
99                     'value' => 'mailto:jayl@my.server'
100                  },
101                 ],
102                 'VALARM' => [
103                   {
104                     'when' => \%DateTime,
105                     'SUMMARY' => 'Alarm notification',
106                     'ACTION' => 'EMAIL',
107                     'DESCRIPTION' => 'This is an event reminder',
108                     'ATTENDEE' => [
109                        {
110                          'value' => 'mailto:cpan@my.server'
111                        }
112                     ]
113                  }
114                ],
115           }
116
117   Todo Hash
118           {
119               'URL' => 'mailto:me',
120               'SUMMARY' => 'todo 1',
121               'UID' => 'B78E68F2-35E7-11D9-9E64-000D93C45D90',
122               'idref' => '7CCE8555-3516-11D9-8A43-000D93C45D90',
123               'STATUS' => 'COMPLETED',
124               'COMPLETED' => \%DateTime,
125               'DTSTAMP' => \%DateTime,
126               'PRIORITY' => '9',
127               'DTSTART' => \%DateTime,
128               'DUE' => \%DateTime,
129               'DESCRIPTION' => 'not much',
130               'VALARM' => [
131                  {
132                     'when' => \%DateTime,
133                     'ATTACH' => 'file://localhost/my-file',
134                     'ACTION' => 'PROCEDURE'
135                  }
136               ],
137           },
138

Methods

140   new(%opt_args)
141       Optional Arguments
142
143       start {yyymmdd|DateTime}
144           Only include events on or after "yyymmdd". Defaults to Jan of this
145           year.
146
147       end {yyyymmdd|DateTime}
148           Only include events before "yyymmdd".
149
150       no_events
151           Don't include events in the output (todos only).
152
153       no_todos
154           Don't include todos in the output (events only).
155
156       months n
157           DateTime::Sets (used for calculating recurrences) are limited to
158           approximately 200 entries. If an "end" date is not specified, the
159           "to" date is set to the "start" date plus this many months.  The
160           default is 60.
161
162       tz (string|DateTime::TimeZone)
163           Use tz as timezone for date values.  The default is 'local', which
164           will adjust the parsed dates to the current timezone.
165
166       debug
167           Set to non-zero for some debugging output during processing.
168
169   parse({file|file_handle}+)
170       Parse the input files or opened file handles and return the generated
171       hash.
172
173       This function can be called mutitple times and the calendars will be
174       merge into the hash, each event tagged with the unique id of its
175       calendar.
176
177   parse_files({file|file_handle}+)
178       Alias for parse()
179
180   parse_strings(string+)
181       Parse the input strings (each assumed to be a valid iCalendar) and
182       return the generated hash.
183

AUTHOR

185       Rick Frankel, cpan@rickster.com
186
188       This program is free software; you can redistribute it and/or modify it
189       under the same terms as Perl itself.
190
191       The full text of the license can be found in the LICENSE file included
192       with this module.
193

SEE ALSO

195       Text::vFile::asData, DateTime::Set, DateTime::Span, iCal::Parser::SAX
196
197
198
199perl v5.36.0                      2023-01-20                   iCal::Parser(3)
Impressum