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.

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

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

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

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

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

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

       •   format_period($span)

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

       •   format_period_with_duration($span)

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

       •   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/