1Data::ICal(3)         User Contributed Perl Documentation        Data::ICal(3)
2
3
4

NAME

6       Data::ICal - Generates iCalendar (RFC 2445) calendar files
7

SYNOPSIS

9           use Data::ICal;
10
11           my $calendar = Data::ICal->new();
12
13           my $vtodo = Data::ICal::Entry::Todo->new();
14           $vtodo->add_properties(
15               # ... see Data::ICal::Entry::Todo documentation
16           );
17
18           # ... or
19           $calendar = Data::ICal->new(filename => 'foo.ics'); # parse existing file
20           $calendar = Data::ICal->new(data => 'BEGIN:VCALENDAR...'); # parse from scalar
21           $calendar->add_entry($vtodo);
22           print $calendar->as_string;
23

DESCRIPTION

25       A Data::ICal object represents a "VCALENDAR" object as defined in the
26       iCalendar protocol (RFC 2445, MIME type "text/calendar"), as
27       implemented in many popular calendaring programs such as Apple's iCal.
28
29       Each Data::ICal object is a collection of "entries", which are objects
30       of a subclass of Data::ICal::Entry.  The types of entries defined by
31       iCalendar (which refers to them as "components") include events, to-do
32       items, journal entries, free/busy time indicators, and time zone
33       descriptors; in addition, events and to-do items can contain alarm
34       entries.  (Currently, Data::ICal only implements to-do items and
35       events.)
36
37       Data::ICal is a subclass of Data::ICal::Entry; see its manpage for more
38       methods applicable to Data::ICal.
39

METHODS

41   new [ data => $data, ] [ filename => $file ], [ calname => $string ], [
42       vcal10 => $bool ], [ rfc_strict => $bool ], [ auto_uid => $bool ]
43       Creates a new Data::ICal object.
44
45       If it is given a filename or data argument is passed, then this parses
46       the content of the file or string into the object.  If the "vcal10"
47       flag is passed, parses it according to vCalendar 1.0, not iCalendar
48       2.0; this in particular impacts the parsing of continuation lines in
49       quoted-printable sections.
50
51       If a calname is passed, sets x-wr-calname to the given string.
52       Although not specified in RFC2445, most calendar software respects
53       x-wr-calname as the displayed name of the calendar.
54
55       If the "rfc_strict" flag is set to true, will require Data::ICal to
56       include UIDs, as per RFC2445:
57
58           4.8.4.7 Unique Identifier
59           ... The property MUST be specified in the "VEVENT", "VTODO",
60           "VJOURNAL" or "VFREEBUSY" calendar components"
61
62       If the "auto_uid" flag is set to true, will automatically generate a
63       default UID for each type which requires it, based on the RFC-suggested
64       algorithm.  Explicitly-set UID attributes will override this auto-
65       generated value.
66
67       If a filename or data argument is not passed, this just sets the
68       object's "VERSION" and "PRODID" properties to "2.0" (or "1.0" if the
69       "vcal10" flag is passed) and the value of the "product_id" method
70       respectively.
71
72       Returns a false value upon failure to open or parse the file or data;
73       this false value is a Class::ReturnValue object and can be queried as
74       to its "error_message".
75
76   parse [ data => $data, ] [ filename => $file, ]
77       Parse a ".ics" file or string containing one, and populate $self with
78       its contents.
79
80       Should only be called once on a given object, and will be automatically
81       called by "new" if you provide arguments to "new".
82
83       Returns $self on success.  Returns a false value upon failure to open
84       or parse the file or data; this false value is a Class::ReturnValue
85       object and can be queried as to its "error_message".
86
87   ical_entry_type
88       Returns "VCALENDAR", its iCalendar entry name.
89
90   product_id
91       Returns the product ID used in the calendar's "PRODID" property; you
92       may wish to override this in a subclass for your own application.
93
94   mandatory_unique_properties
95       According to the iCalendar standard, the following properties must be
96       specified exactly one time for a calendar:
97
98             prodid version
99
100   optional_unique_properties
101       According to the iCalendar standard, the following properties may be
102       specified at most one time for a calendar:
103
104             calscale method
105

DEPENDENCIES

107       Data::ICal requires Class::Accessor, Text::vFile::asData,
108       MIME::QuotedPrint, and Class::ReturnValue.
109

BUGS AND LIMITATIONS

111       Data::ICal does not support time zone daylight or standard entries, so
112       time zone components are basically useless.
113
114       While Data::ICal tries to check which properties are required and
115       repeatable, this only works in simple cases; it does not check for
116       properties that must either both exist or both not exist, or for
117       mutually exclusive properties.
118
119       Data::ICal does not check to see if property parameter names are known
120       in general or allowed on the particular property.
121
122       Data::ICal does not check to see if nested entries are nested properly
123       (alarms in todos and events only, everything else in calendars only).
124
125       The only property encoding supported by Data::ICal is quoted printable.
126
127       Please report any bugs or feature requests to
128       "bug-data-ical@rt.cpan.org", or through the web interface at
129       <http://rt.cpan.org>.
130

AUTHOR

132       Best Practical Solutions, LLC <modules@bestpractical.com>
133

135       Copyright (c) 2005 - 2020, Best Practical Solutions, LLC.  All rights
136       reserved.
137
138       This module is free software; you can redistribute it and/or modify it
139       under the same terms as Perl itself. See perlartistic.
140
141
142
143perl v5.36.0                      2023-01-20                     Data::ICal(3)
Impressum