Text::vFile::asData(3)User Contributed Perl DocumentatioText::vFile::asData(3)NAMEText::vFile::asData - parse vFile formatted files into data structures
SYNOPSIS
use Text::vFile::asData;
open my $fh, "foo.ics"
or die "couldn't open ics: $!";
my $data = Text::vFile::asData->new->parse( $fh );
DESCRIPTIONText::vFile::asData reads vFile format files, such as vCard (RFC 2426)
and vCalendar (RFC 2445).
DATA STRUCTURE
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.
AUTHORS
Richard Clamp <richardc@unixbeard.net> and Nik Clayton
<nik@FreeBSD.org>
COPYRIGHT
Copyright 2004, 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.
CAVEATS
We don't do any decoding of property values, including descaping "\,",
we're still undecided as to whether this is a bug.
BUGS
Aside from the TODO list items, none known.
SEE ALSO
Text::vFile - parses to objects, doesn't handle nested items
RFC 2426 - vCard specification
RFC 2445 - vCalendar specification
perl v5.14.1 2010-08-25 Text::vFile::asData(3)
