DateTime::Format::ICal (3pm)

Parse and format ical datetime and duration strings

  1. Carta.tech
  2. Man Pages
  3. MISSING SECTION
  4. DateTime::Format::ICal: Parse and format ical datetime and duration strings
  1. Carta.tech
  2. Packages
  3. libdatetime-format-ical-perl
  4. 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 \s-1RFC\s0 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 \*(C`DateTime\*(C' 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 \*(C`DateTime::Duration\*(C' 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 \*(C`DateTime::Span\*(C' object. If given an improperly formatted string, this method may die.

  • parse_recurrence( recurrence => $string, ... ) Given an iCal recurrence description, this method uses \*(C`DateTime::Event::ICal\*(C' to create a \*(C`DateTime::Set\*(C' object representing that recurrence. Any parameters given to this method beside \*(L"recurrence\*(R" will be passed directly to the \*(C`DateTime::Event::ICal->recur\*(C' method. If given an improperly formatted string, this method may die. This method accepts optional parameters \*(L"dtstart\*(R" and \*(L"dtend\*(R". These parameters must be \*(C`DateTime\*(C' objects. The iCal spec requires that \*(L"dtstart\*(R" always be included in the recurrence set, unless this is an \*(L"exrule\*(R" statement. Since we don't know what kind of statement is being parsed, we do not include \*(C`dtstart\*(C' in the recurrence set.

  • format_datetime($datetime) Given a \*(C`DateTime\*(C' object, this methods returns an iCal datetime string. The iCal spec requires that datetimes be formatted either as floating times (no time zone), \s-1UTC\s0 (with a 'Z' suffix) or with a time zone id at the beginning ('TZID=America/Chicago;...'). If this method is asked to format a \*(C`DateTime\*(C' object that has an offset-only time zone, then the object will be converted to the \s-1UTC\s0 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 \*(L"19000101T160000Z\*(R".

  • format_duration($duration) Given a \*(C`DateTime::Duration\*(C' 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 \*(C`delta_months()\*(C' is not zero is given, then this method will die.

  • format_period($span) Given a \*(C`DateTime::Span\*(C' object, this methods returns an iCal period string, using the format \*(C`DateTime/DateTime\*(C'.

  • format_period_with_duration($span) Given a \*(C`DateTime::Span\*(C' object, this methods returns an iCal period string, using the format \*(C`DateTime/Duration\*(C'.

  • 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 \*(C`DateTime\*(C' list, a \*(C`DateTime::Span\*(C' list, a \*(C`DateTime::Set\*(C', or a \*(C`DateTime::SpanSet\*(C'. ICal \*(C`DATE\*(C' values are not supported. Whenever a date value is found, a \*(C`DATE-TIME\*(C' is generated. If a recurrence has an associated \*(C`DTSTART\*(C' or \*(C`DTEND\*(C', those values must be formatted using \*(C`format_datetime()\*(C'. The \*(C`format_recurrence()\*(C' method will not do this for you. If a \*(C`union\*(C' or \*(C`complement\*(C' of recurrences is being formatted, they are assumed to have the same \*(C`DTSTART\*(C' value. Only \*(C`union\*(C' and \*(C`complement\*(C' 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 \*(C`DateTime::Set::ICal\*(C' 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 \*(C`DateTime::Event::ICal\*(C' module. You can add ICal formatting support to a custom recurrence by using the \*(C`DateTime::Set::ICal\*(C' 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 [email protected] email list. See http://lists.perl.org/ for more details.

AUTHORS

Dave Rolsky <[email protected]> and Flavio Soibelmann Glock <[email protected]>

Some of the code in this module comes from Rich Bowen's \*(C`Date::ICal\*(C' 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 \s-1LICENSE\s0 file included with this module.

RELATED TO DateTime::Format::ICal…

[email protected] mailing list

http://datetime.perl.org/