.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" 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 .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . 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 "Data::ICal 3pm" .TH Data::ICal 3pm "2020-01-06" "perl v5.30.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" Data::ICal \- Generates iCalendar (RFC 2445) calendar files .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Data::ICal; \& \& my $calendar = Data::ICal\->new(); \& \& my $vtodo = Data::ICal::Entry::Todo\->new(); \& $vtodo\->add_properties( \& # ... see Data::ICal::Entry::Todo documentation \& ); \& \& # ... or \& $calendar = Data::ICal\->new(filename => \*(Aqfoo.ics\*(Aq); # parse existing file \& $calendar = Data::ICal\->new(data => \*(AqBEGIN:VCALENDAR...\*(Aq); # parse from scalar \& $calendar\->add_entry($vtodo); \& print $calendar\->as_string; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" A Data::ICal object represents a \f(CW\*(C`VCALENDAR\*(C'\fR object as defined in the iCalendar protocol (\s-1RFC 2445, MIME\s0 type \*(L"text/calendar\*(R"), as implemented in many popular calendaring programs such as Apple's iCal. .PP Each Data::ICal object is a collection of \*(L"entries\*(R", which are objects of a subclass of Data::ICal::Entry. The types of entries defined by iCalendar (which refers to them as \*(L"components\*(R") include events, to-do items, journal entries, free/busy time indicators, and time zone descriptors; in addition, events and to-do items can contain alarm entries. (Currently, Data::ICal only implements to-do items and events.) .PP Data::ICal is a subclass of Data::ICal::Entry; see its manpage for more methods applicable to Data::ICal. .SH "METHODS" .IX Header "METHODS" .ie n .SS "new [ data => $data, ] [ filename => $file ], [ calname => $string ], [ vcal10 => $bool ], [ rfc_strict => $bool ], [ auto_uid => $bool ]" .el .SS "new [ data => \f(CW$data\fP, ] [ filename => \f(CW$file\fP ], [ calname => \f(CW$string\fP ], [ vcal10 => \f(CW$bool\fP ], [ rfc_strict => \f(CW$bool\fP ], [ auto_uid => \f(CW$bool\fP ]" .IX Subsection "new [ data => $data, ] [ filename => $file ], [ calname => $string ], [ vcal10 => $bool ], [ rfc_strict => $bool ], [ auto_uid => $bool ]" Creates a new Data::ICal object. .PP If it is given a filename or data argument is passed, then this parses the content of the file or string into the object. If the \f(CW\*(C`vcal10\*(C'\fR flag is passed, parses it according to vCalendar 1.0, not iCalendar 2.0; this in particular impacts the parsing of continuation lines in quoted-printable sections. .PP If a calname is passed, sets x\-wr-calname to the given string. Although not specified in \s-1RFC2445,\s0 most calendar software respects x\-wr-calname as the displayed name of the calendar. .PP If the \f(CW\*(C`rfc_strict\*(C'\fR flag is set to true, will require Data::ICal to include UIDs, as per \s-1RFC2445:\s0 .PP .Vb 3 \& 4.8.4.7 Unique Identifier \& ... The property MUST be specified in the "VEVENT", "VTODO", \& "VJOURNAL" or "VFREEBUSY" calendar components" .Ve .PP If the \f(CW\*(C`auto_uid\*(C'\fR flag is set to true, will automatically generate a default \s-1UID\s0 for each type which requires it, based on the RFC-suggested algorithm. Explicitly-set \s-1UID\s0 attributes will override this auto-generated value. .PP If a filename or data argument is not passed, this just sets the object's \f(CW\*(C`VERSION\*(C'\fR and \f(CW\*(C`PRODID\*(C'\fR properties to \*(L"2.0\*(R" (or \*(L"1.0\*(R" if the \&\f(CW\*(C`vcal10\*(C'\fR flag is passed) and the value of the \f(CW\*(C`product_id\*(C'\fR method respectively. .PP Returns a false value upon failure to open or parse the file or data; this false value is a Class::ReturnValue object and can be queried as to its \&\f(CW\*(C`error_message\*(C'\fR. .ie n .SS "parse [ data => $data, ] [ filename => $file, ]" .el .SS "parse [ data => \f(CW$data\fP, ] [ filename => \f(CW$file\fP, ]" .IX Subsection "parse [ data => $data, ] [ filename => $file, ]" Parse a \f(CW\*(C`.ics\*(C'\fR file or string containing one, and populate \f(CW$self\fR with its contents. .PP Should only be called once on a given object, and will be automatically called by \f(CW\*(C`new\*(C'\fR if you provide arguments to \f(CW\*(C`new\*(C'\fR. .PP Returns \f(CW$self\fR on success. Returns a false value upon failure to open or parse the file or data; this false value is a Class::ReturnValue object and can be queried as to its \&\f(CW\*(C`error_message\*(C'\fR. .SS "ical_entry_type" .IX Subsection "ical_entry_type" Returns \f(CW\*(C`VCALENDAR\*(C'\fR, its iCalendar entry name. .SS "product_id" .IX Subsection "product_id" Returns the product \s-1ID\s0 used in the calendar's \f(CW\*(C`PRODID\*(C'\fR property; you may wish to override this in a subclass for your own application. .SS "mandatory_unique_properties" .IX Subsection "mandatory_unique_properties" According to the iCalendar standard, the following properties must be specified exactly one time for a calendar: .PP .Vb 1 \& prodid version .Ve .SS "optional_unique_properties" .IX Subsection "optional_unique_properties" According to the iCalendar standard, the following properties may be specified at most one time for a calendar: .PP .Vb 1 \& calscale method .Ve .SH "DEPENDENCIES" .IX Header "DEPENDENCIES" Data::ICal requires Class::Accessor, Text::vFile::asData, MIME::QuotedPrint, and Class::ReturnValue. .SH "BUGS AND LIMITATIONS" .IX Header "BUGS AND LIMITATIONS" Data::ICal does not support time zone daylight or standard entries, so time zone components are basically useless. .PP While Data::ICal tries to check which properties are required and repeatable, this only works in simple cases; it does not check for properties that must either both exist or both not exist, or for mutually exclusive properties. .PP Data::ICal does not check to see if property parameter names are known in general or allowed on the particular property. .PP Data::ICal does not check to see if nested entries are nested properly (alarms in todos and events only, everything else in calendars only). .PP The only property encoding supported by Data::ICal is quoted printable. .PP Please report any bugs or feature requests to \&\f(CW\*(C`bug\-data\-ical@rt.cpan.org\*(C'\fR, or through the web interface at . .SH "AUTHOR" .IX Header "AUTHOR" Best Practical Solutions, \s-1LLC\s0 .SH "LICENCE AND COPYRIGHT" .IX Header "LICENCE AND COPYRIGHT" Copyright (c) 2005 \- 2020, Best Practical Solutions, \s-1LLC.\s0 All rights reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.