view release on metacpan or  search on metacpan

README  view on Meta::CPAN

NAME
    Date::ICal - Perl extension for ICalendar date objects.

VERSION
    $Revision: 682 $

SYNOPSIS
        use Date::ICal;

        $ical = Date::ICal->new( ical => '19971024T120000' );
        $ical = Date::ICal->new( epoch => time );
        $ical = Date::ICal->new( year => 1964,
            month => 10, day => 16, hour => 16,
            min => 12, sec => 47 );

        $hour = $ical->hour;
        $year = $ical->year;

        $ical_string = $ical->ical;
        $epoch_time = $ical->epoch;

        $ical2 = $ical + $duration;

    (Where $duration is either a duration string, like 'P2W3DT7H9M', or a
    Date::ICal::Duration (qv) object.

        $ical += 'P6DT12H';

        $duration = $ical - $ical2;
        $ical3 = $ical - $duration;

DESCRIPTION
    Date::ICal talks the ICal date format, and is intended to be a base
    class for other date/calendar modules that know about ICal time format
    also.

AUTHOR
    Rich Bowen, and the Reefknot team. Alas, Reefknot is no more. See
    <https://github.com/houseabsolute/DateTime.pm/wiki> for more modern and
    accurate modules.

    Last touched by $Author: michal-josef-spacek $

METHODS
    Date::ICal has the following methods available:

  new
    A new Date::ICal object can be created with any valid ICal string:

        my $ical = Date::ICal->new( ical => '19971024T120000' );
        # will default to the timezone specified in $TZ, see below

    Or with any epoch time:

        my $ical = Date::ICal->new( epoch => time );

    Or, better still, create it with components

        my $date = Date::ICal->new( 
                               day => 25, 
                               month => 10, 
                               year => 1066,
                               hour => 7,
                               min => 15,
                               sec => 47
                               );

    If you call new without any arguments, you'll get a Date::ICal object
    that is set to the time right now.

        my $ical = Date::ICal->new();

    If you already have an object in Date::ICal, or some other subclass
    thereof, you can create a new Date::ICal (or subclass) object using that
    object to start with. This is particularly useful for converting from
    one calendar to another:

       # Direct conversion from Discordian to ISO dates
       my $disco = Date::Discordian->new( disco => '12 Chaos, YOLD 3177' );
       my $iso = Date::ISO->new( $disco );
       print $iso->iso;

    new() handles timezones. It defaults times to UTC (Greenwich Mean Time,
    also called Zulu). If you want to set up a time that's in the US
    "Pacific" timezone, which is GMT-8, use something like:

        my $ical = Date::ICal->new( ical => '19971024T120000',
                                    offset => "-0800");

    Note that as of version 1.44, new() tries to be intelligent about
    figuring out your local time zone. If you enter a time that's not
    *explicitly* in UTC, it looks at the environment variable $TZ, if it
    exists, to determine your local offset. If $TZ isn't set, new() will
    complain.

  ical
        $ical_string = $ical->ical;

    Retrieves, or sets, the date on the object, using any valid ICal
    date/time string. Output is in UTC (ends with a "Z") by default. To get
    output in localtime relative to the current machine, do:

        $ical_string = $ical->ical( localtime => 1 );

    To get output relative to an arbitrary offset, do:

        $ical_string = $ical->ical( offset => '+0545' );

  epoch
        $epoch_time = $ical->epoch;
    
        $ical->epoch( 98687431 );

    Sets, or retrieves, the epoch time represented by the object, if it is
    representable as such. (Dates before 1971 or after 2038 will not have an
    epoch representation.)

    Internals note: The ICal representation of the date is considered the
    only authoritative one. This means that we may need to reconstruct the
    epoch time from the ICal representation if we are not sure that they are
    in synch. We'll need to do clever things to keep track of when the two
    may not be in synch. And, of course, the same will go for any subclasses
    of this class.

  offset_to_seconds
        $seconds_plus_or_minus = offset_to_seconds($offset);

    Changes -0600 to -21600. Not object method, no side-effects.

  offset_from_seconds
        $seconds_plus_or_minus = offset_from_seconds($offset_in_seconds);

    Changes -18000 (seconds) to -0600 (hours, minutes). Not object method,
    no side-effects.

  offset