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

FreeBSD Manual Pages

  
 
  

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

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

SYNOPSIS
	   use Data::ICal;

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

	   my $vtodo = Data::ICal::Entry::Todo->new();
	   $vtodo->add_properties(
	       # ... 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
	   $calendar->add_entry($vtodo);
	   print $calendar->as_string;

DESCRIPTION
       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
       events.)

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

METHODS
   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:

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

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

   ical_entry_type
       Returns "VCALENDAR", its	iCalendar entry	name.

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

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

	     prodid version

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

	     calscale method

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

BUGS AND LIMITATIONS
       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
       "bug-data-ical@rt.cpan.org", or through the web interface at
       <http://rt.cpan.org>.

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

NAME | SYNOPSIS | DESCRIPTION | METHODS | DEPENDENCIES | BUGS AND LIMITATIONS | AUTHOR | LICENCE AND COPYRIGHT

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

home | help