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.

  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" and "until" will be passed directly to the DateTime::Event::ICal->recur method. If "until" is given as an iCal format datetime, it will be parsed and turned into an object first.

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

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

SUPPORT

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

AUTHOR

Dave Rolsky <autarch@urth.org>

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/