1Text::VCardFast(3)    User Contributed Perl Documentation   Text::VCardFast(3)
2
3
4

NAME

6       Text::VCardFast - Perl extension for very fast parsing of VCards
7

SYNOPSIS

9         use Text::VCardFast;
10
11         my $hash = Text::VCard::vcard2hash($card, multival => ['adr', 'org', 'n']);
12         my $card = Text::VCard::hash2vcard($hash, "\r\n");
13

DESCRIPTION

15       Text::VCardFast is designed to parse VCards very quickly compared to
16       pure-perl solutions.  It has a perl and an XS version of the same API,
17       accessible as vcard2hash_pp and vcard2hash_c, with the XS version being
18       preferred.
19
20       Why would you care?  We were writing the calendaring code for
21       fastmail.fm, and it was taking over 6 seconds to draw respond to a
22       request for calendar data, and the bulk was going to the perl
23       middleware layer - and THAT profiled down to the vcard parser.
24
25       Two of us independently wrote better pure perl implementations, leading
26       to about a 5 times speedup in each case.  I figured it was worth
27       checking if XS would be much better.  Here's the benchmark on the v4
28       example from Wikipedia:
29
30           Benchmark: timing 10000 iterations of fastxs, pureperl, vcardasdata...
31               fastxs:  0 wallclock secs ( 0.16 usr +  0.01 sys =  0.17 CPU) @ 58823.53/s (n=10000)
32                       (warning: too few iterations for a reliable count)
33             pureperl:  1 wallclock secs ( 1.04 usr +  0.00 sys =  1.04 CPU) @ 9615.38/s (n=10000)
34           vcardasdata:  8 wallclock secs ( 7.35 usr +  0.00 sys =  7.35 CPU) @ 1360.54/s (n=10000)
35
36       (see bench.pl in the source tarball for the code)
37
38   EXPORT
39         vcard2hash
40         hash2vcard
41
42   API
43       Text::VCard::vcard2hash($card, %options);
44             Options:
45
46             * only_one - A flag which, if true, means parsing will stop after
47               extracting a single VCard from the buffer.  This is very useful
48               in cases where, for example, a disclaimer has been added after
49               a calendar event in an email.
50
51             * multival - A list of entry names which will be considered to have
52               multiple values.  Instead of having a 'value' field in the hash,
53               entries with this key will have a 'values' field containing an
54               arrayref of values - even if there is only one value.
55               The value is split on semicolon, with escaped semicolons decoded
56               correctly within each item.
57
58               Default is the empty list.
59
60             * multiparam - As with values - multiparam is a list of entry names
61               which can have multiple values.  To see the difference here you
62               must consider something like this:
63
64               EMAIL;TYPE="INTERNET,HOME";TYPE=PREF:example@example.com
65
66               If 'multiparam' includes 'TYPE' then the result will be:
67               ['INTERNET', 'HOME', 'PREF'], otherwise it will be:
68               ['INTERNET,HOME', 'PREF'].
69
70               Default is the empty list.
71
72             * barekeys - if set, then a bare parameter will be considered to be
73               a parameter name with an undefined value, rather than a being a
74               value for the parameter type.
75
76               Consider:
77
78               EMAIL;INTERNET;HOME:example@example.com
79
80               barekeys off:
81
82               {
83                 name => 'email',
84                 params => { type => ['INTERNET', 'HOME'] },
85                 value => 'example@example.com',
86               }
87
88               barekeys on:
89
90               {
91                 name => 'email',
92                 params => { internet => [undef], home => [undef] },
93                 value => 'example@example.com',
94               }
95
96               default is barekeys off.
97
98             The input is a scalar containing VFILE text, as per RFC 6350 or the various
99             earlier RFCs it replaces.  If the perl unicode flag is set on the scalar,
100             then it will be propagated to the output values.
101
102             The output is a hash reference containing a single key 'objects', which is
103             an array of all the cards within the source text.
104
105             Each object can have the following keys:
106             * type - the text after BEGIN: and END: of the card (lower cased)
107             * properties - a hash from name to array of instances within the card.
108             * objects - an array of sub cards within the card.
109
110             Properties are a hash with the following keys:
111             * group - optional - if the propery name as 'foo.bar', this will be foo.
112             * name - a copy of the hash key that pointed to this property, so that
113               this hash can be used without keeping the key around too
114             * params - a hash of the parameters on the entry.  This is everything from
115               the ; to the :
116             * value - either a scalar (if not a multival field) or an array of values.
117               This is everything after the :
118
119             Decoding is done where possible, including RFC 6868 handling of ^.
120
121             All names, both entry names and parameter names, are lowercased where the
122             RFC says they are not case significant.  This means that all hash keys are
123             lowercase within this API, as are card types.
124
125             Values, on the other hand, are left in their original case even where the
126             RFC says they are case insignificant - due to the increased complexity of
127             tracking which version what parameters are in effect.
128
129       Text::VCard::hash2vcard($hash, $eol)
130             The inverse operation (as much as possible!)
131
132             Given a hash with an 'objects' key in it, output a scalar string containing
133             the VCARD representation.  Lines are separated with the $eol string given,
134             or the default "\n".  Use "\r\n" for files going to caldav/carddav servers.
135
136             In the inverse of the above case, where names are case insignificant, they
137             are generated in UPPERCASE in the card, for maximum compatibility with
138             other implementations.
139

EXAMPLES

141         For more examples see the t/cases directory in the tarball, which contains
142         some sample VCARDs and JSON dumps of the hash representation.
143
144         BEGIN:VCARD
145         KEY;PKEY=PVALUE:VALUE
146         KEY2:VALUE2
147         END:VCARD
148
149         {
150         'objects' => [
151           {
152             'type' => 'vcard',
153             'properties' => {
154               'key2' => [
155                 {
156                   'value' => 'VALUE2',
157                   'name' => 'key2'
158                 }
159               ],
160               'key' => [
161                 {
162                   'params' => {
163                     'pkey' => [
164                       'PVALUE'
165                     ]
166                   },
167                   'value' => 'VALUE',
168                   'name' => 'key'
169                 }
170               ]
171             }
172           }
173         ]
174         }
175
176         BEGIN:VCARD
177         BEGIN:SUBCARD
178         KEY:VALUE
179         END:SUBCARD
180         END:VCARD
181
182         {
183         'objects' => [
184           {
185             'objects' => [
186               {
187                 'type' => 'subcard',
188                 'properties' => {
189                   'key' => [
190                     {
191                       'value' => 'VALUE',
192                       'name' => 'key'
193                     }
194                   ]
195                 }
196               }
197             ],
198             'type' => 'vcard',
199             'properties' => {}
200           }
201         ]
202         }
203
204         BEGIN:VCARD
205         GROUP1.KEY:VALUE
206         GROUP1.KEY2:VALUE2
207         GROUP2.KEY:VALUE
208         END:VCARD
209
210         {
211         'objects' => [
212           {
213             'type' => 'vcard',
214             'properties' => {
215               'key2' => [
216                 {
217                   'group' => 'group1',
218                   'value' => 'VALUE2',
219                   'name' => 'key2'
220                 }
221               ],
222               'key' => [
223                 {
224                   'group' => 'group1',
225                   'value' => 'VALUE',
226                   'name' => 'key'
227                 },
228                 {
229                   'group' => 'group2',
230                   'value' => 'VALUE',
231                   'name' => 'key'
232                 }
233               ]
234             }
235           }
236         ]
237         }
238

SEE ALSO

240       There is a similar module Text::VFile::asData on CPAN, but it is much
241       slower and doesn't do as much decoding.
242
243       Code is stored on github at
244
245       https://github.com/brong/Text-VCardFast/
246

AUTHOR

248       Bron Gondwana, <brong@fastmail.fm<gt>
249
251       Copyright (C) 2014 by Bron Gondwana
252
253       This library is free software; you can redistribute it and/or modify it
254       under the same terms as Perl itself, either Perl version 5.14.2 or, at
255       your option, any later version of Perl 5 you may have available.
256
257
258
259perl v5.36.0                      2022-07-22                Text::VCardFast(3)
Impressum