.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DateTime::Event::ICal 3"
.TH DateTime::Event::ICal 3 2024-09-01 "perl v5.40.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
DateTime::Event::ICal \- Perl DateTime extension for computing rfc2445 recurrences.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\& use DateTime;
\& use DateTime::Event::ICal;
\&
\& my $dt = DateTime\->new( year   => 2000,
\&                         month  => 6,
\&                         day    => 20,
\&                       );
\&
\& my $set = DateTime::Event::ICal\->recur( 
\&      dtstart => $dt,
\&      freq =>    \*(Aqdaily\*(Aq,
\&      bymonth => [ 10, 12 ],
\&      byhour =>  [ 10 ]
\& );
\&
\& my $dt_next = $set\->next( $dt );
\&
\& my $dt_previous = $set\->previous( $dt );
\&
\& my $bool = $set\->contains( $dt );
\&
\& my @days = $set\->as_list( start => $dt1, end => $dt2 );
\&
\& my $iter = $set\->iterator;
\&
\& while ( my $dt = $iter\->next ) {
\&     print \*(Aq \*(Aq, $dt\->datetime;
\& }
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module provides convenience methods that let you easily create
\&\f(CW\*(C`DateTime::Set\*(C'\fR objects for rfc2445 style recurrences.
.SH USAGE
.IX Header "USAGE"
.IP recur 4
.IX Item "recur"
This method returns a DateTime::Set object representing the
given recurrence.
.Sp
.Vb 1
\&  my $set = DateTime::Event::ICal\->recur( %args );
.Ve
.Sp
This method takes parameters which correspond to the rule parts
specified in section 4.3.10 of RFC 2445.  Rather than rewrite that RFC
here, you are encouraged to read that first if you want to understand
what all these parameters represent.
.RS 4
.IP \(bu 4
dtstart
.Sp
A DateTime object, which is the start date.
.Sp
This datetime is not included in the recurrence, unless it satisfies
the recurrence's rules.
.Sp
A set can thus be used for creating exclusion rules (rfc2445
\&\f(CW\*(C`exrule\*(C'\fR), which don't include \f(CW\*(C`dtstart\*(C'\fR.
.IP \(bu 4
until
.Sp
A DateTime object which specifies the recurrence's end date.  Can also
be specified as "dtend".
.IP \(bu 4
count
.Sp
A positive number which indicate the total number of recurrences.
Giving both a "count" and an "until" parameter is pointless, though it
is currently allowed.
.IP \(bu 4
freq
.Sp
One of:
.Sp
.Vb 2
\&   "yearly", "monthly", "weekly", "daily",
\&   "hourly", "minutely", "secondly"
.Ve
.Sp
See the \f(CW\*(C`DateTime::Event::Recurrence\*(C'\fR documentation for more details
on what these mean.
.IP \(bu 4
interval
.Sp
The interval between recurrences.  This is a multiplier for the value
specified by "freq".  It defaults to 1.
.Sp
So if you specify a "freq" of "yearly" and an "interval" of 3, that
means a recurrence that occurs every three years.
.IP \(bu 4
wkst
.Sp
Week start day.  This can be one of: "mo", "tu", "we", "th", "fr",
"sa", "su".  The default is Monday ("mo").
.Sp
\&\fBNote: this parameter is not yet implemented\fR
.IP \(bu 4
bysecond => [ list ], byminute => [ list ], byhour => [ list ]
.Sp
This should be one or more positive or numbers, specified as a scalar
or array reference.  Each number represents a second/minute/hour.
.Sp
See RFC 2445, section 4.3.10 for more details.
.IP \(bu 4
byday => [ list ]
.Sp
This should be a scalar or array reference containing days of the
week, specified as "mo", "tu", "we", "th", "fr", "sa", "su"
.Sp
The day of week may have a prefix:
.Sp
.Vb 2
\& "1tu",  # the first tuesday of month or year
\& "\-2we"  # the second to last wednesday of month or year
.Ve
.Sp
See RFC 2445, section 4.3.10 for more details.
.IP \(bu 4
bymonthday => [ list ], byyearday => [ list ]
.Sp
A scalar or array reference containing positive or negative numbers,
but not zero.  For "bymonthday", the allowed ranges are \-31 to \-1.
For "byyearday", the allowed ranges are \-366 to \-1, and 1 to 366.
.Sp
Day \-1 is last day of month or year.
.Sp
See RFC 2445, section 4.3.10 for more details.
.IP \(bu 4
byweekno => [ list ]
.Sp
A scalar or array reference containing positive or negative numbers,
but not zero.  The allowed ranges are \-53 to \-1, and 1 to 53.
.Sp
The first week of year is week 1.
.Sp
The default week start day is Monday.
.Sp
Week \-1 is the last week of year.
.Sp
See RFC 2445, section 4.3.10 for more details.
.IP \(bu 4
bymonth => [ list ]
.Sp
A scalar or array reference containing positive or negative numbers,
from \-12 to \-1 and 1 to 12.
.Sp
Month \-1 is December.
.Sp
See RFC 2445, section 4.3.10 for more details.
.IP \(bu 4
bysetpos => [ list ]
.Sp
This can be either a scalar or an array reference of positive and
negative numbers from \-366 to \-1, and 1 to 366.  This parameter is
used in conjunction with one of the other "by..." parameters.
.Sp
See RFC 2445, section 4.3.10 for more details.
.RE
.RS 4
.RE
.SH AUTHOR
.IX Header "AUTHOR"
Flavio Soibelmann Glock
fglock@gmail.com
.SH CREDITS
.IX Header "CREDITS"
The API was developed with help from the people
in the datetime@perl.org list.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (c) 2003 Flavio Soibelmann Glock.  
All rights reserved.  This program
is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.
.PP
The full text of the license can be found in the LICENSE file included
with this module.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
datetime@perl.org mailing list
.PP
DateTime Web page <http://datetime.perl.org/>
.PP
The DateTime module.
.PP
DateTime::Event::Recurrence \- simple rule-based recurrences.
.PP
DateTime::Format::ICal \- can parse rfc2445 recurrences.
.PP
DateTime::Set \- recurrences defined by callback subroutines.
.PP
DateTime::Event::Cron \- recurrences defined by "cron" rules.
.PP
DateTime::SpanSet
.PP
RFC2445 <http://www.ietf.org/rfc/rfc2445.txt> \-
Internet Calendaring and Scheduling Core Object Specification.