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

FreeBSD Manual Pages

  
 
  

home | help
DateTime::Format::ICalUser Contributed Perl DocumentaDateTime::Format::ICal(3)

NAME
       DateTime::Format::ICal -	Parse and format iCal datetime and duration
       strings

SYNOPSIS
	 use DateTime::Format::ICal;

	 my $dt	= DateTime::Format::ICal->parse_datetime( '20030117T032900Z' );

	 my $dur = DateTime::Format::ICal->parse_duration( '+P3WT4H55S'	);

	 # 20030117T032900Z
	 DateTime::Format::ICal->format_datetime($dt);

	 # +P3WT4H55S
	 DateTime::Format::ICal->format_duration($dur);

DESCRIPTION
       This module understands the ICal	date/time and duration formats,	as
       defined in RFC 2445.  It	can be used to parse these formats in order to
       create the appropriate objects.

METHODS
       This class offers the following methods.

       o   parse_datetime($string)

	   Given an iCal datetime string, this method will return a new
	   "DateTime" object.

	   If given an improperly formatted string, this method	may die.

       o   parse_duration($string)

	   Given an iCal duration string, this method will return a new
	   "DateTime::Duration"	object.

	   If given an improperly formatted string, this method	may die.

       o   parse_period($string)

	   Given an iCal period	string,	this method will return	a new
	   "DateTime::Span" object.

	   If given an improperly formatted string, this method	may die.

       o   parse_recurrence( recurrence	=> $string, ...	)

	   Given an iCal recurrence description, this method uses
	   "DateTime::Event::ICal" to create a "DateTime::Set" object
	   representing	that recurrence.  Any parameters given to this method
	   beside "recurrence" will be passed directly to the
	   "DateTime::Event::ICal->recur" method.

	   If given an improperly formatted string, this method	may die.

	   This	method accepts optional	parameters "dtstart" and "dtend".
	   These parameters must be "DateTime" objects.

	   The iCal spec requires that "dtstart" always	be included in the
	   recurrence set, unless this is an "exrule" statement.  Since	we
	   don't know what kind	of statement is	being parsed, we do not
	   include "dtstart" in	the recurrence set.

       o   format_datetime($datetime)

	   Given a "DateTime" object, this methods returns an iCal datetime
	   string.

	   The iCal spec requires that datetimes be formatted either as
	   floating times (no time zone), UTC (with a 'Z' suffix) or with a
	   time	zone id	at the beginning ('TZID=America/Chicago;...').	If
	   this	method is asked	to format a "DateTime" object that has an
	   offset-only time zone, then the object will be converted to the UTC
	   time	zone internally	before formatting.

	   For example,	this code:

	       my $dt =	DateTime->new( year => 1900, hour => 15, time_zone => '-0100' );

	       print $ical->format_datetime($dt);

	   will	print the string "19000101T160000Z".

       o   format_duration($duration)

	   Given a "DateTime::Duration"	object,	this methods returns an	iCal
	   duration string.

	   The iCal standard does not allow for	months or years	in a duration,
	   so if a duration for	which "delta_months()" is not zero is given,
	   then	this method will die.

       o   format_period($span)

	   Given a "DateTime::Span" object, this methods returns an iCal
	   period string, using	the format "DateTime/DateTime".

       o   format_period_with_duration($span)

	   Given a "DateTime::Span" object, this methods returns an iCal
	   period string, using	the format "DateTime/Duration".

       o   format_recurrence($arg [,$arg...] )

	   This	method returns a list of strings containing ICal statements.
	   In scalar context it	returns	a single string	which may contain
	   embedded newlines.

	   The argument	can be a "DateTime" list, a "DateTime::Span" list, a
	   "DateTime::Set", or a "DateTime::SpanSet".

	   ICal	"DATE" values are not supported. Whenever a date value is
	   found, a "DATE-TIME"	is generated.

	   If a	recurrence has an associated "DTSTART" or "DTEND", those
	   values must be formatted using "format_datetime()".	The
	   "format_recurrence()" method	will not do this for you.

	   If a	"union"	or "complement"	of recurrences is being	formatted,
	   they	are assumed to have the	same "DTSTART" value.

	   Only	"union"	and "complement" operations are	supported for
	   recurrences.	 This is a limitation of the ICal specification.

	   If given a set it cannot format, this method	may die.

	   Only	"DateTime::Set::ICal" objects are formattable.	A set may
	   change class	after some set operations:

	       $recurrence = $recurrence->union( $dt_set );
	       # Ok - $recurrence still	is a DT::Set::ICal

	       $recurrence = $dt_set->union( $recurrence );
	       # Not Ok! - $recurrence is a DT::Set now

	   The only unbounded recurrences currently supported are the ones
	   generated by	the "DateTime::Event::ICal" module.

	   You can add ICal formatting support to a custom recurrence by using
	   the "DateTime::Set::ICal" module:

	       $custom_recurrence =
		   DateTime::Set::ICal->from_recurrence
		       ( recurrence =>
			 sub { $_[0]->truncate(	to => 'month' )->add( months =>	1 ) }
		       );
	       $custom_recurrence->set_ical( include =>	[ 'FREQ=MONTHLY' ] );

SUPPORT
       Support for this	module is provided via the datetime@perl.org email
       list.  See http://lists.perl.org/ for more details.

AUTHORS
       Dave Rolsky <autarch@urth.org> and Flavio Soibelmann Glock
       <fglock@pucrs.br>

       Some of the code	in this	module comes from Rich Bowen's "Date::ICal"
       module.

COPYRIGHT
       Copyright (c) 2003 David	Rolsky.	 All rights reserved.  This program is
       free software; you can redistribute it and/or modify it under the same
       terms as	Perl itself.

       The full	text of	the license can	be found in the	LICENSE	file included
       with this module.

SEE ALSO
       datetime@perl.org mailing list

       http://datetime.perl.org/

perl v5.32.1			  2021-02-28	     DateTime::Format::ICal(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | SUPPORT | AUTHORS | COPYRIGHT | SEE ALSO

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

home | help