Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bestpractical/data-ical


https://github.com/bestpractical/data-ical

Last synced: about 1 month ago
JSON representation

Awesome Lists containing this project

README 

        
NAME

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



INSTALLATION

        perl Makefile.PL

        make

        make test

        make install



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 ], [ vcal10 => $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 filename or data argument is not passed, this just sets its

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



    There is no Data::ICal::Entry::Alarm base class.



    Please report any bugs or feature requests to

    "[email protected]", or through the web interface at

    .



AUTHOR

    Jesse Vincent "" with David Glasser, Simon

    Wistow, and Alex Vandiver



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.



DISCLAIMER OF WARRANTY

    BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY

    FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN

    OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES

    PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER

    EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED

    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE

    ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH

    YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL

    NECESSARY SERVICING, REPAIR, OR CORRECTION.



    IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING

    WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR

    REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE

    TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR

    CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE

    SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING

    RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A

    FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF

    SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH

    DAMAGES.