Data::...::Entry(3pm)

💖 Data::...::Entry(3pm) — aka Data::ICal::Entry 💖

okay bestie, this is the manual page for Data::ICal::Entry(3pm) and I need you to focus because this one is literally the main character of iCalendar-land. no cap. 🗓️✨

---

🌈 NAME 🌈

Data::ICal::Entry — Represents an entry in an iCalendar file 🎀

---

🦋 SYNOPSIS 🦋

my $vtodo = Data::ICal::Entry::Todo->new();
$vtodo->add_property(
# ... see Data::ICal::Entry::Todo documentation
);
$vtodo->add_properties( ... );

$calendar->add_entry($vtodo);

$event->add_entry($alarm);
$event->add_entries($alarm1, ...);

# or all in one go
my $vtodo = Data::ICal::Entry::Todo->new( \%props, \@entries );

look at that. so clean. so iconic. 🫶

---

💅 DESCRIPTION 💅

so a Data::ICal::Entry object represents a single entry in an iCalendar file. quick side note from the original text: the iCalendar RFC calls entries "components" instead — same thing, different name, the RFC just woke up and chose violence with its vocabulary. 🫠

iCalendar defines several types of entries, like events and to-do lists. each one of those corresponds to a subclass of Data::ICal::Entry — although, ngl, only to-do lists and events are currently implemented. so don't come for me about the others. 😭

Treat Data::ICal::Entry as an abstract base class. every object you actually create should be one of its subclasses, okay? don't be out here making raw base-class objects, that's not the vibe.

and plot twist: the entire calendar itself (the Data::ICal object) is also represented as a Data::ICal::Entry object. it's giving recursion, but make it fashion. 👑

every entry has:

• an entry type (like "VCALENDAR" or "VEVENT")
• a series of "properties"
• and possibly some sub-entries

and about those sub-entries: only the root Data::ICal object can have sub-entries — with the exception of alarm entries contained in events and to-dos. and guess what bestie, that alarm thing is (not yet implemented). 💀

---

✨ METHODS ✨

🌸 new

Creates a new entry object with no properties and no sub-entries. blank slate. brand new baby entry. fresh start energy. 🐣

🌸 as_string [ crlf => "CRLF" ]

Returns the entry as an appropriately formatted string (with a trailing newline). 📝

properties come back in alphabetical order — and when there are multiple properties with the same name, they come back in the order they were added. btw property order is genuinely unimportant in iCalendar, it's just that alphabetical makes testing easier. be grateful, bestie. 🙏

if any mandatory property is missing? it issues a warning. not a crash, just a warning. it's disappointed but it's not gonna ghost you. 😔

the string used as a newline can optionally be specified by giving a "crlf" argument, which defaults to "\x0d\x0a", per RFC 2445 spec. this option is primarily for backwards compatibility with versions of this module before 0.16. respect the elders. 🫡

🌸 add_entry $entry

Adds an entry to this entry. so here's the standard's opinion: this should only be called on either a to-do or event entry with an alarm entry, or on a calendar entry (Data::ICal) with a to-do, event, journal, timezone, or free/busy entry. that's the rule, i don't make them. 📋

Returns true if the entry was successfully added, and false otherwise — maybe because you tried to add an entry of an invalid type, but, tea time: this check hasn't been implemented yet. so don't count on it catching your nonsense. 🍵

🌸 add_entries $entry1, [$entry2, ...]

Convenience function to call "add_entry" several times with a list of entries. it's the "and also these" of methods. 🎀

🌸 entries

Returns a reference to the array</b> of subentries of this entry. 💫

🌸 properties

Returns a reference to the hash</b> of properties of this entry. the keys are property names and the values are array references containing Data::ICal::Property objects. yes, arrays of objects, we love a lil nested situation. 🪆

🌸 property

Given a property name, returns a reference to the array</b> of Data::ICal::Property objects. 🔥

🌸 add_property $propname => $propval

Creates a new Data::ICal::Property object with name $propname and value $propval and adds it to the event. 💖

• If the property is not known to exist for that object type, and it does not begin with "X-", it issues a warning.
• If the property is known to be unique, it replaces the original property. out with the old, in with the new. 💅

to specify parameters for the property, let $propval be a two-element array reference where:

1. the first element is the property value
2. the second element is a hash reference

the keys of that hash are parameter names, and the values should be either strings or array references of strings — depending on whether the parameter should have one value or multiple values (multiple = comma-separated). 🧚

Examples of setting parameters:

# Add a property with a parameter of VALUE set to 'DATE'
$event->add_property( rdate => [ $date, { VALUE => 'DATE' } ] );

🌸 add_properties $propname1 => $propval1, [$propname2 => $propname2, ...]

Convenience function to call "add_property" several times with a list of properties. 🎁

this method is guaranteed to call "add_property" on them in the order given — so unique properties given later in the call will take precedence over the ones given earlier. so yes, order matters here. but!! and this is important: this is unrelated to the order of properties when the entry is rendered as a string, ok? don't mix those two up. 🙈

parameters for the properties are specified in exactly the same way as in "add_property". consistency is the vibe. ✨

🌸 mandatory_unique_properties

Subclasses should override this method to provide a list of lower case strings identifying the properties which must appear exactly once in the subclass's entry type. default returns an empty list. 📭

🌸 mandatory_repeatable_properties

Subclasses should override this method to provide a list of lower case strings identifying the properties which must appear at least once in the subclass's entry type. default returns an empty list. 📭

🌸 optional_unique_properties

Subclasses should override this method to provide a list of lower case strings identifying the properties which must appear at most once in the subclass's entry type. default returns an empty list. 📭

🌸 optional_repeatable_properties

Subclasses should override this method to provide a list of lower case strings identifying the properties which may appear zero, one, or more times in the subclass's entry type. default returns an empty list. 📭

🌸 is_property $name

Returns a boolean value indicating whether or not the property $name is known to the class — that is, if it's listed in "(mandatory/optional)_(unique/repeatable)_properties". ✅❌

🌸 is_mandatory $name

Returns a boolean value indicating whether or not the property $name is known to the class as mandatory — that is, if it's listed in "mandatory_(unique/repeatable)_properties". 🫡

🌸 is_optional $name

Returns a boolean value indicating whether or not the property $name is known to the class as optional — that is, if it's listed in "optional_(unique/repeatable)_properties". 🍃

🌸 is_unique $name

Returns a boolean value indicating whether or not the property $name is known to the class as unique — that is, if it's listed in "(mandatory/optional)_unique_properties". 💎

🌸 is_repeatable $name

Returns a boolean value indicating whether or not the property $name is known to the class as repeatable — that is, if it's listed in "(mandatory/optional)_repeatable_properties". 🔁

🌸 ical_entry_type

Subclasses should override this method to provide the identifying type name of the entry — such as "VCALENDAR" or "VTODO". it's the entry's whole identity, honestly. 🪪

🌸 vcal10 [$bool]

Gets or sets a boolean saying whether this entry should be interpreted as vCalendar 1.0 (as opposed to iCalendar 2.0). 🕰️

ngl, generally you can just set this on your main Data::ICal object when you construct it — "add_entry" automatically makes sure that sub-entries end up with the same value as their parents. family resemblance, but for booleans. 💞

🌸 rfc_strict [$bool]

Gets or sets a boolean saying whether this entry will complain about missing UIDs as per RFC2446. Defaults to false, for backwards compatibility. 📜

same deal as above: generally you can just set this on your main Data::ICal object when you construct it, and "add_entry" automatically makes sure that sub-entries end up with the same value as their parents. 🫶

🌸 auto_uid [$bool]

Gets or sets a boolean saying whether this entry should automatically generate its own persistently unique UIDs. Defaults to false. 🆔

and yeah, same pattern, bestie: generally you can just set this on your main Data::ICal object when you construct it, and "add_entry" automatically makes sure that sub-entries end up with the same value as their parents. the parents handle it. it's giving delegation. 👑

🌸 header

Returns the header line for the entry (including the trailing newline). 🎬

🌸 footer

Returns the footer line for the entry (including the trailing newline). 🎀

🌸 parse_object

Translate a Text::vFile::asData sub object into the appropriate Data::iCal::Event subtype. translating, but make it vibes. 🔄

---

👑 AUTHOR 👑

Best Practical Solutions, LLC <modules@bestpractical.com> ✉️

---

💜 LICENCE AND COPYRIGHT 💜

Copyright (c) 2005 - 2020, Best Practical Solutions, LLC. All rights reserved. 📅

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic. 🌈

---

and that's the whole page, bestie!! no notes, we ate. 🍽️💅

this was perl v5.36.0, dated 2022-10-14, and the page itself is Data::...::Entry(3pm) — go build something iconic with it 🦋✨💖