Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Data::ICal::Entry(3)  User Contributed Perl Documentation Data::ICal::Entry(3)

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	);

DESCRIPTION
       A Data::ICal::Entry object represents a single entry in an iCalendar
       file.  (Note that the iCalendar RFC refers to entries as	"components".)
       iCalendar defines several types of entries, such	as events and to-do
       lists; each of these corresponds	to a subclass of Data::ICal::Entry
       (though only to-do lists	and events are currently implemented).
       Data::ICal::Entry should	be treated as an abstract base class --	all
       objects created should be of its	subclasses.  The entire	calendar
       itself (the Data::ICal object) is also represented as a
       Data::ICal::Entry object.

       Each entry has an entry type (such as "VCALENDAR" or "VEVENT"), a
       series of "properties", and possibly some sub-entries.  (Only the root
       Data::ICal object can have sub-entries, except for alarm	entries
       contained in events and to-dos (not yet implemented).)

METHODS
   new
       Creates a new entry object with no properties or	sub-entries.

   as_string [ crlf => "CRLF" ]
       Returns the entry as an appropriately formatted string (with trailing
       newline).

       Properties are returned in alphabetical order, with multiple properties
       of the same name	returned in the	order added.  (Property	order is
       unimportant in iCalendar, and this makes	testing	easier.)

       If any mandatory	property is missing, issues a warning.

       The string to use as a newline can optionally be	specified by giving
       the 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.

   add_entry $entry
       Adds an entry to	this entry.  (According	to the standard, 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.)

       Returns true if the entry was successfully added, and false otherwise
       (perhaps	because	you tried to add an entry of an	invalid	type, but this
       check hasn't been implemented yet).

   add_entries $entry1,	[$entry2, ...]
       Convenience function to call "add_entry"	several	times with a list of
       entries.

   entries
       Returns a reference to the array	of subentries of this entry.

   properties
       Returns a reference to the hash of properties of	this entry.  The keys
       are property names and the values are array references containing
       Data::ICal::Property objects.

   property
       Given a property	name returns a reference to the	array 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 does not
       begin with "X-",	issues a warning.

       If the property is known	to be unique, replaces the original property.

       To specify parameters for the property, let $propval be a two-element
       array reference where the first element is the property value and the
       second element is a hash	reference.  The	keys of	the hash are parameter
       names; the values should	be either strings or array references of
       strings,	depending on whether the parameter should have one or multiple
       (to be comma-separated) values.

       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 "add_property" on them in the
       order given, so that unique properties given later in the call will
       take precedence over those given	earlier.  (This	is unrelated to	the
       order of	properties when	the entry is rendered as a string, though.)

       Parameters for the properties are specified in the same way as in
       "add_property".

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

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

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

   optional_repeatable_properties
       Subclasses should override this method (which returns an	empty list by
       default)	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.

   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").

   vcal10 [$bool]
       Gets or sets a boolean saying whether this entry	should be interpreted
       as vCalendar 1.0	(as opposed to iCalendar 2.0).	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.

   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.  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.

   auto_uid [$bool]
       Gets or sets a boolean saying whether this entry	should automatically
       generate	its own	persistently unique UIDs.  Defaults to false.
       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.

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

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

   parse_object
       Translate a Text::vFile::asData sub object into the appropriate
       Data::iCal::Event subtype.

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.

perl v5.32.1			  2020-01-03		  Data::ICal::Entry(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | AUTHOR | LICENCE AND COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Data::ICal::Entry&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help