---
name: "Data::ICal"
section: "3pm"
platform: "linux"
package: "libdata-ical-perl"
version: "0.24+dfsg-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Data::ICal"
---

# Data::ICal(3pm)

Generates iCalendar (RFC 2445) calendar files

## NAME

Data::ICal - Generates iCalendar (RFC 2445) calendar files

## SYNOPSIS

```
    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 => 'foo.ics'); # parse existing file
    $calendar = Data::ICal->new(data => 'BEGIN:VCALENDAR...'); # parse from scalar
    $calendar->add_entry($vtodo);
    print $calendar->as_string;
```

## DESCRIPTION

A Data::ICal object represents a `"VCALENDAR"` object as defined in the iCalendar protocol (RFC 2445, MIME type "text/calendar"), as implemented in many popular calendaring programs such as Apple's iCal.

Each Data::ICal object is a collection of "entries", which are objects of a subclass of Data::ICal::Entry.  The types of entries defined by iCalendar (which refers to them as "components") 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.)

Data::ICal is a subclass of Data::ICal::Entry; see its manpage for more methods applicable to Data::ICal.

## METHODS

### new \[ data =\> $data, \] \[ filename =\> $file \], \[ calname =\> $string \], \[ vcal10 =\> $bool \], \[ rfc\_strict =\> $bool \], \[ auto\_uid =\> $bool \]

Creates a new Data::ICal object.

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 `"vcal10"` 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.

If a calname is passed, sets x-wr-calname to the given string.  Although not specified in RFC2445, most calendar software respects x-wr-calname as the displayed name of the calendar.

If the `"rfc_strict"` flag is set to true, will require Data::ICal to include UIDs, as per RFC2445:

```
    4.8.4.7 Unique Identifier
    ... The property MUST be specified in the "VEVENT", "VTODO",
    "VJOURNAL" or "VFREEBUSY" calendar components"
```

If the `"auto_uid"` flag is set to true, will automatically generate a default UID for each type which requires it, based on the RFC-suggested algorithm.  Explicitly-set UID attributes will override this auto-generated value.

If a filename or data argument is not passed, this just sets the object's `"VERSION"` and `"PRODID"` properties to "2.0" (or "1.0" if the `"vcal10"` flag is passed) and the value of the `"product_id"` method respectively.

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 `"error_message"`.

### parse \[ data =\> $data, \] \[ filename =\> $file, \]

Parse a `".ics"` file or string containing one, and populate `$self` with its contents.

Should only be called once on a given object, and will be automatically called by `"new"` if you provide arguments to `"new"`.

Returns `$self` 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 `"error_message"`.

### ical\_entry\_type

Returns `"VCALENDAR"`, its iCalendar entry name.

### product\_id

Returns the product ID used in the calendar's `"PRODID"` property; you may wish to override this in a subclass for your own application.

### mandatory\_unique\_properties

According to the iCalendar standard, the following properties must be specified exactly one time for a calendar:

```
      prodid version
```

### optional\_unique\_properties

According to the iCalendar standard, the following properties may be specified at most one time for a calendar:

```
      calscale method
```

## DEPENDENCIES

Data::ICal requires Class::Accessor, Text::vFile::asData, MIME::QuotedPrint, and Class::ReturnValue.

## BUGS AND LIMITATIONS

Data::ICal does not support time zone daylight or standard entries, so time zone components are basically useless.

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.

Data::ICal does not check to see if property parameter names are known in general or allowed on the particular property.

Data::ICal does not check to see if nested entries are nested properly (alarms in todos and events only, everything else in calendars only).

The only property encoding supported by Data::ICal is quoted printable.

Please report any bugs or feature requests to `"bug-data-ical@rt.cpan.org"`, or through the web interface at \<http://rt.cpan.org\>.

## AUTHOR

Best Practical Solutions, LLC \<modules@bestpractical.com\>

## LICENCE AND COPYRIGHT

Copyright (c) 2005 - 2020, Best Practical Solutions, LLC.  All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.