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

NAME

6       Data::ICal::Entry - Represents an entry in an iCalendar file
7

SYNOPSIS

9           my $vtodo = Data::ICal::Entry::Todo->new();
10           $vtodo->add_property(
11           # ... see Data::ICal::Entry::Todo documentation
12           );
13           $vtodo->add_properties( ... );
14
15           $calendar->add_entry($vtodo);
16
17           $event->add_entry($alarm);
18           $event->add_entries($alarm1, ...);
19
20           # or all in one go
21           my $vtodo = Data::ICal::Entry::Todo->new( \%props, \@entries );
22

DESCRIPTION

24       A Data::ICal::Entry object represents a single entry in an iCalendar
25       file.  (Note that the iCalendar RFC refers to entries as "components".)
26       iCalendar defines several types of entries, such as events and to-do
27       lists; each of these corresponds to a subclass of Data::ICal::Entry
28       (though only to-do lists and events are currently implemented).
29       Data::ICal::Entry should be treated as an abstract base class -- all
30       objects created should be of its subclasses.  The entire calendar
31       itself (the Data::ICal object) is also represented as a
32       Data::ICal::Entry object.
33
34       Each entry has an entry type (such as "VCALENDAR" or "VEVENT"), a
35       series of "properties", and possibly some sub-entries.  (Only the root
36       Data::ICal object can have sub-entries, except for alarm entries
37       contained in events and to-dos (not yet implemented).)
38

METHODS

40   new
41       Creates a new entry object with no properties or sub-entries.
42
43   as_string [ crlf => "CRLF" ]
44       Returns the entry as an appropriately formatted string (with trailing
45       newline).
46
47       Properties are returned in alphabetical order, with multiple properties
48       of the same name returned in the order added.  (Property order is
49       unimportant in iCalendar, and this makes testing easier.)
50
51       If any mandatory property is missing, issues a warning.
52
53       The string to use as a newline can optionally be specified by giving
54       the a "crlf" argument, which defaults to "\x0d\x0a", per RFC 2445 spec;
55       this option is primarily for backwards compatibility with versions of
56       this module before 0.16.
57
58   add_entry $entry
59       Adds an entry to this entry.  (According to the standard, this should
60       only be called on either a to-do or event entry with an alarm entry, or
61       on a calendar entry (Data::ICal) with a to-do, event, journal,
62       timezone, or free/busy entry.)
63
64       Returns true if the entry was successfully added, and false otherwise
65       (perhaps because you tried to add an entry of an invalid type, but this
66       check hasn't been implemented yet).
67
68   add_entries $entry1, [$entry2, ...]
69       Convenience function to call "add_entry" several times with a list of
70       entries.
71
72   entries
73       Returns a reference to the array of subentries of this entry.
74
75   properties
76       Returns a reference to the hash of properties of this entry.  The keys
77       are property names and the values are array references containing
78       Data::ICal::Property objects.
79
80   property
81       Given a property name returns a reference to the array of
82       Data::ICal::Property objects.
83
84   add_property $propname => $propval
85       Creates a new Data::ICal::Property object with name $propname and value
86       $propval and adds it to the event.
87
88       If the property is not known to exist for that object type and does not
89       begin with "X-", issues a warning.
90
91       If the property is known to be unique, replaces the original property.
92
93       To specify parameters for the property, let $propval be a two-element
94       array reference where the first element is the property value and the
95       second element is a hash reference.  The keys of the hash are parameter
96       names; the values should be either strings or array references of
97       strings, depending on whether the parameter should have one or multiple
98       (to be comma-separated) values.
99
100       Examples of setting parameters:
101
102        # Add a property with a parameter of VALUE set to 'DATE'
103        $event->add_property( rdate => [ $date, { VALUE => 'DATE' } ] );
104
105   add_properties $propname1 => $propval1, [$propname2 => $propname2, ...]
106       Convenience function to call "add_property" several times with a list
107       of properties.
108
109       This method is guaranteed to call add "add_property" on them in the
110       order given, so that unique properties given later in the call will
111       take precedence over those given earlier.  (This is unrelated to the
112       order of properties when the entry is rendered as a string, though.)
113
114       Parameters for the properties are specified in the same way as in
115       "add_property".
116
117   mandatory_unique_properties
118       Subclasses should override this method (which returns an empty list by
119       default) to provide a list of lower case strings identifying the
120       properties which must appear exactly once in the subclass's entry type.
121
122   mandatory_repeatable_properties
123       Subclasses should override this method (which returns an empty list by
124       default) to provide a list of lower case strings identifying the
125       properties which must appear at least once in the subclass's entry
126       type.
127
128   optional_unique_properties
129       Subclasses should override this method (which returns an empty list by
130       default) to provide a list of lower case strings identifying the
131       properties which must appear at most once in the subclass's entry type.
132
133   optional_repeatable_properties
134       Subclasses should override this method (which returns an empty list by
135       default) to provide a list of lower case strings identifying the
136       properties which may appear zero, one, or more times in the subclass's
137       entry type.
138
139   is_property $name
140       Returns a boolean value indicating whether or not the property $name is
141       known to the class (that is, if it's listed in
142       "(mandatory/optional)_(unique/repeatable)_properties").
143
144   is_mandatory $name
145       Returns a boolean value indicating whether or not the property $name is
146       known to the class as mandatory (that is, if it's listed in
147       "mandatory_(unique/repeatable)_properties").
148
149   is_optional $name
150       Returns a boolean value indicating whether or not the property $name is
151       known to the class as optional (that is, if it's listed in
152       "optional_(unique/repeatable)_properties").
153
154   is_unique $name
155       Returns a boolean value indicating whether or not the property $name is
156       known to the class as unique (that is, if it's listed in
157       "(mandatory/optional)_unique_properties").
158
159   is_repeatable $name
160       Returns a boolean value indicating whether or not the property $name is
161       known to the class as repeatable (that is, if it's listed in
162       "(mandatory/optional)_repeatable_properties").
163
164   ical_entry_type
165       Subclasses should override this method to provide the identifying type
166       name of the entry (such as "VCALENDAR" or "VTODO").
167
168   vcal10 [$bool]
169       Gets or sets a boolean saying whether this entry should be interpreted
170       as vCalendar 1.0 (as opposed to iCalendar 2.0).  Generally, you can
171       just set this on your main Data::ICal object when you construct it;
172       "add_entry" automatically makes sure that sub-entries end up with the
173       same value as their parents.
174
175   rfc_strict [$bool]
176       Gets or sets a boolean saying whether this entry will complain about
177       missing UIDs as per RFC2446. Defaults to false, for backwards
178       compatibility.  Generally, you can just set this on your main
179       Data::ICal object when you construct it; "add_entry" automatically
180       makes sure that sub-entries end up with the same value as their
181       parents.
182
183   auto_uid [$bool]
184       Gets or sets a boolean saying whether this entry should automatically
185       generate its own persistently unique UIDs.  Defaults to false.
186       Generally, you can just set this on your main Data::ICal object when
187       you construct it; "add_entry" automatically makes sure that sub-entries
188       end up with the same value as their parents.
189
190   header
191       Returns the header line for the entry (including trailing newline).
192
193   footer
194       Returns the footer line for the entry (including trailing newline).
195
196   parse_object
197       Translate a Text::vFile::asData sub object into the appropriate
198       Data::iCal::Event subtype.
199

AUTHOR

201       Best Practical Solutions, LLC <modules@bestpractical.com>
202
204       Copyright (c) 2005 - 2020, Best Practical Solutions, LLC.  All rights
205       reserved.
206
207       This module is free software; you can redistribute it and/or modify it
208       under the same terms as Perl itself. See perlartistic.
209
210
211
212perl v5.30.1                      2020-01-29              Data::ICal::Entry(3)
Impressum