.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Text::vFile::asData 3pm"
.TH Text::vFile::asData 3pm "2021-01-01" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Text::vFile::asData \- parse vFile formatted files into data structures
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&  use Text::vFile::asData;
\&  open my $fh, "foo.ics"
\&    or die "couldn\*(Aqt open ics: $!";
\&  my $data = Text::vFile::asData\->new\->parse( $fh );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Text::vFile::asData reads vFile format files, such as vCard (\s-1RFC 2426\s0) and
vCalendar (\s-1RFC 2445\s0).
.SH "DATA STRUCTURE"
.IX Header "DATA STRUCTURE"
A vFile contains one or more objects, delimited by \s-1BEGIN\s0 and \s-1END\s0 tags.
.PP
.Vb 3
\&  BEGIN:VCARD
\&  ...
\&  END:VCARD
.Ve
.PP
Objects may contain sub-objects;
.PP
.Vb 7
\&  BEGIN:VCALENDAR
\&  ...
\&  BEGIN:VEVENT
\&  ...
\&  END:VEVENT
\&  ...
\&  ENV:VCALENDAR
.Ve
.PP
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:
.PP
.Vb 1
\&  DTSTART;VALUE=DATE:19970317
.Ve
.PP
identifies a property with the name, \f(CW\*(C`DSTART\*(C'\fR, the parameter
\&\f(CW\*(C`VALUE\*(C'\fR, which has the value \f(CW\*(C`DATE\*(C'\fR, and the property's value is
\&\f(CW19970317\fR.  Those of you with an \s-1XML\s0 bent might find this more
recognisable as:
.PP
.Vb 1
\&  <dtstart value="date">19970317</dtstart>
.Ve
.PP
The return value from the \f(CW\*(C`parse()\*(C'\fR method is a hash ref.
.PP
The top level key, \f(CW\*(C`objects\*(C'\fR, refers to an array ref.  Each entry in the
array ref is a hash ref with two or three keys.
.PP
The value of the first key, \f(CW\*(C`type\*(C'\fR, is a string corresponding to the
type of the object.  E.g., \f(CW\*(C`VCARD\*(C'\fR, \f(CW\*(C`VEVENT\*(C'\fR, and so on.
.PP
The value of the second key, \f(CW\*(C`properties\*(C'\fR, 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;
.PP
.Vb 5
\&  BEGIN:VEVENT
\&  ATTENDEE;CN="Nik Clayton":mailto:nik@FreeBSD.org
\&  ATTENDEE;CN="Richard Clamp":mailto:richardc@unixbeard.net
\&  ...
\&  END:VEVENT
.Ve
.PP
Each entry in the array ref is a hash ref with one or two keys.
.PP
The first key, \f(CW\*(C`value\*(C'\fR, corresponds to the property's value.
.PP
The second key, \f(CW\*(C`param\*(C'\fR, 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 \f(CW\*(C`preserve_params\*(C'\fR
option there is an additional key populated, called \f(CW\*(C`params\*(C'\fR.  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.)
.PP
The third key in the top level \f(CW\*(C`objects\*(C'\fR hash ref is \f(CW\*(C`objects\*(C'\fR.  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 \f(CW\*(C`objects\*(C'\fR key.  This recursive
structure continues, nesting as deeply as there were sub-objects in
the input file.
.PP
The \f(CW\*(C`bin/v2yaml\*(C'\fR script that comes with this distribution displays the
format of a vFile as \s-1YAML.\s0  \f(CW\*(C`t/03usage.t\*(C'\fR has examples of picking out
the relevant information from the data structure.
.SH "AUTHORS"
.IX Header "AUTHORS"
Richard Clamp <richardc@unixbeard.net> and Nik Clayton <nik@FreeBSD.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2004, 2010, 2013 Richard Clamp and Nik Clayton.  All Rights Reserved.
.PP
This program is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.
.SH "CAVEATS"
.IX Header "CAVEATS"
We don't do any decoding of property values, including descaping
\&\f(CW\*(C`\e,\*(C'\fR, we're still undecided as to whether this is a bug.
.SH "BUGS"
.IX Header "BUGS"
Aside from the \s-1TODO\s0 list items, none known.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Text::vFile \- parses to objects, doesn't handle nested items
.PP
\&\s-1RFC 2426\s0 \- vCard specification
.PP
\&\s-1RFC 2445\s0 \- vCalendar specification