Text::vFile::asData(3pm)

1Text::vFile::asData(3)User Contributed Perl DocumentationText::vFile::asData(3)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

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

DATA STRUCTURE

19       A vFile contains one or more objects, delimited by BEGIN and END tags.
20
21         BEGIN:VCARD
22         ...
23         END:VCARD
24
25       Objects may contain sub-objects;
26
27         BEGIN:VCALENDAR
28         ...
29         BEGIN:VEVENT
30         ...
31         END:VEVENT
32         ...
33         ENV:VCALENDAR
34
35       Each object consists of one or more properties.  Each property consists
36       of a name, zero or more optional parameters, and then a value.  This
37       fragment:
38
39         DTSTART;VALUE=DATE:19970317
40
41       identifies a property with the name, "DSTART", the parameter "VALUE",
42       which has the value "DATE", and the property's value is 19970317.
43       Those of you with an XML bent might find this more recognisable as:
44
45         <dtstart value="date">19970317</dtstart>
46
47       The return value from the "parse()" method is a hash ref.
48
49       The top level key, "objects", refers to an array ref.  Each entry in
50       the array ref is a hash ref with two or three keys.
51
52       The value of the first key, "type", is a string corresponding to the
53       type of the object.  E.g., "VCARD", "VEVENT", and so on.
54
55       The value of the second key, "properties", is a hash ref, with property
56       names as keys, and an array ref of those property values.  It's an
57       array ref, because some properties may appear within an object multiple
58       times with different values.  For example;
59
60         BEGIN:VEVENT
61         ATTENDEE;CN="Nik Clayton":mailto:nik@FreeBSD.org
62         ATTENDEE;CN="Richard Clamp":mailto:richardc@unixbeard.net
63         ...
64         END:VEVENT
65
66       Each entry in the array ref is a hash ref with one or two keys.
67
68       The first key, "value", corresponds to the property's value.
69
70       The second key, "param", contains a hash ref of the property's
71       parameters.  Keys in this hash ref are the parameter's name, the value
72       is the parameter's value.  (If you enable the "preserve_params" option
73       there is an additional key populated, called "params".  It is an array
74       ref of hash refs, each hash ref is the parameter's name and the
75       parameter's value - these are collected in the order they are
76       encountered to prevent hash collisions as seen in some vCard files)
77       line.)
78
79       The third key in the top level "objects" hash ref is "objects".  If it
80       exists, it indicates that sub-objects were found.  The value of this
81       key is an array ref of sub-objects, with identical keys and behaviour
82       to that of the top level "objects" key.  This recursive structure
83       continues, nesting as deeply as there were sub-objects in the input
84       file.
85
86       The "bin/v2yaml" script that comes with this distribution displays the
87       format of a vFile as YAML.  "t/03usage.t" has examples of picking out
88       the relevant information from the data structure.
89

AUTHORS

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

COPYRIGHT

95       Copyright 2004, 2010, 2013 Richard Clamp and Nik Clayton.  All Rights
96       Reserved.
97
98       This program is free software; you can redistribute it and/or modify it
99       under the same terms as Perl itself.
100

CAVEATS

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

BUGS

106       Aside from the TODO list items, none known.
107