Text::vFile::asData - parse vFile formatted files into data structures

       Richard Clamp <richardc@unixbeard.net> and Nik Clayton <nik@FreeBSD.org>

       Aside from the TODO list items, none known.

       We don't do any decoding of property values, including descaping "\,", we're still undecided as to
       whether this is a bug.

       Copyright 2004, 2010, 2013 Richard Clamp and Nik Clayton.  All Rights Reserved.

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

       A vFile contains one or more objects, delimited by BEGIN and END tags.

         BEGIN:VCARD
         ...
         END:VCARD

       Objects may contain sub-objects;

         BEGIN:VCALENDAR
         ...
         BEGIN:VEVENT
         ...
         END:VEVENT
         ...
         ENV:VCALENDAR

       Each object consists of one or more properties.  Each property consists of a name, zero or more optional
       parameters, and then a value.  This fragment:

         DTSTART;VALUE=DATE:19970317

       identifies a property with the name, "DSTART", the parameter "VALUE", which has the value "DATE", and the
       property's value is 19970317.  Those of you with an XML bent might find this more recognisable as:

         <dtstart value="date">19970317</dtstart>

       The return value from the "parse()" method is a hash ref.

       The top level key, "objects", refers to an array ref.  Each entry in the array ref is a hash ref with two
       or three keys.

       The value of the first key, "type", is a string corresponding to the type of the object.  E.g., "VCARD",
       "VEVENT", and so on.

       The value of the second key, "properties", is a hash ref, with property names as keys, and an array ref
       of those property values.  It's an array ref, because some properties may appear within an object
       multiple times with different values.  For example;

         BEGIN:VEVENT
         ATTENDEE;CN="Nik Clayton":mailto:nik@FreeBSD.org
         ATTENDEE;CN="Richard Clamp":mailto:richardc@unixbeard.net
         ...
         END:VEVENT

       Each entry in the array ref is a hash ref with one or two keys.

       The first key, "value", corresponds to the property's value.

       The second key, "param", contains a hash ref of the property's parameters.  Keys in this hash ref are the
       parameter's name, the value is the parameter's value.  (If you enable the "preserve_params" option there
       is an additional key populated, called "params".  It is an array ref of hash refs, each hash ref is the
       parameter's name and the parameter's value - these are collected in the order they are encountered to
       prevent hash collisions as seen in some vCard files) line.)

       The third key in the top level "objects" hash ref is "objects".  If it exists, it indicates that sub-
       objects were found.  The value of this key is an array ref of sub-objects, with identical keys and
       behaviour to that of the top level "objects" key.  This recursive structure continues, nesting as deeply
       as there were sub-objects in the input file.

       The "bin/v2yaml" script that comes with this distribution displays the format of a vFile as YAML.
       "t/03usage.t" has examples of picking out the relevant information from the data structure.

       Text::vFile::asData reads vFile format files, such as vCard (RFC 2426) and vCalendar (RFC 2445).

       Text::vFile::asData - parse vFile formatted files into data structures

       Text::vFile - parses to objects, doesn't handle nested items

       RFC 2426 - vCard specification

       RFC 2445 - vCalendar specification

perl v5.34.0                                       2022-06-28                           Text::vFile::asData(3pm)

         use Text::vFile::asData;
         open my $fh, "foo.ics"
           or die "couldn't open ics: $!";
         my $data = Text::vFile::asData->new->parse( $fh );