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

FreeBSD Manual Pages


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

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

	   use Data::ICal;

	   my $calendar	= Data::ICal->new();

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

	   # ... or
	   $calendar = Data::ICal->new(filename	=> 'foo.ics'); # parse existing	file
	   $calendar = Data::ICal->new(data => 'BEGIN:VCALENDAR...'); #	parse from scalar
	   print $calendar->as_string;

       A Data::ICal object represents a	"VCALENDAR" object as defined in the
       iCalendar protocol (RFC 2445, MIME type "text/calendar"), as
       implemented in many popular calendaring programs	such as	Apple's	iCal.

       Each Data::ICal object is a collection of "entries", which are objects
       of a subclass of	Data::ICal::Entry.  The	types of entries defined by
       iCalendar (which	refers to them as "components")	include	events,	to-do
       items, journal entries, free/busy time indicators, and time zone
       descriptors; in addition, events	and to-do items	can contain alarm
       entries.	 (Currently, Data::ICal	only implements	to-do items and

       Data::ICal is a subclass	of Data::ICal::Entry; see its manpage for more
       methods applicable to Data::ICal.

   new [ data => $data,	] [ filename =>	$file ], [ calname => $string ], [
       vcal10 => $bool ], [ rfc_strict => $bool	], [ auto_uid => $bool ]
       Creates a new Data::ICal	object.

       If it is	given a	filename or data argument is passed, then this parses
       the content of the file or string into the object.  If the "vcal10"
       flag is passed, parses it according to vCalendar	1.0, not iCalendar
       2.0; this in particular impacts the parsing of continuation lines in
       quoted-printable	sections.

       If a calname is passed, sets x-wr-calname to the	given string.
       Although	not specified in RFC2445, most calendar	software respects
       x-wr-calname as the displayed name of the calendar.

       If the "rfc_strict" flag	is set to true,	will require Data::ICal	to
       include UIDs, as	per RFC2445: Unique Identifier
	   ... The property MUST be specified in the "VEVENT", "VTODO",
	   "VJOURNAL" or "VFREEBUSY" calendar components"

       If the "auto_uid" flag is set to	true, will automatically generate a
       default UID for each type which requires	it, based on the RFC-suggested
       algorithm.  Explicitly-set UID attributes will override this auto-
       generated value.

       If a filename or	data argument is not passed, this just sets the
       object's	"VERSION" and "PRODID" properties to "2.0" (or "1.0" if	the
       "vcal10"	flag is	passed)	and the	value of the "product_id" method

       Returns a false value upon failure to open or parse the file or data;
       this false value	is a Class::ReturnValue	object and can be queried as
       to its "error_message".

   parse [ data	=> $data, ] [ filename => $file, ]
       Parse a ".ics" file or string containing	one, and populate $self	with
       its contents.

       Should only be called once on a given object, and will be automatically
       called by "new" if you provide arguments	to "new".

       Returns $self on	success.  Returns a false value	upon failure to	open
       or parse	the file or data; this false value is a	Class::ReturnValue
       object and can be queried as to its "error_message".

       Returns "VCALENDAR", its	iCalendar entry	name.

       Returns the product ID used in the calendar's "PRODID" property;	you
       may wish	to override this in a subclass for your	own application.

       According to the	iCalendar standard, the	following properties must be
       specified exactly one time for a	calendar:

	     prodid version

       According to the	iCalendar standard, the	following properties may be
       specified at most one time for a	calendar:

	     calscale method

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

       Data::ICal does not support time	zone daylight or standard entries, so
       time zone components are	basically useless.

       While Data::ICal	tries to check which properties	are required and
       repeatable, this	only works in simple cases; it does not	check for
       properties that must either both	exist or both not exist, or for
       mutually	exclusive properties.

       Data::ICal does not check to see	if property parameter names are	known
       in general or allowed on	the particular property.

       Data::ICal does not check to see	if nested entries are nested properly
       (alarms in todos	and events only, everything else in calendars only).

       The only	property encoding supported by Data::ICal is quoted printable.

       Please report any bugs or feature requests to
       "", or through the web interface at

       Best Practical Solutions, LLC <>

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

       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(3)


Want to link to this manual page? Use this URL:

home | help