1Text::VCardFast(3) User Contributed Perl Documentation Text::VCardFast(3)
2
6 Text::VCardFast - Perl extension for very fast parsing of VCards
7
9 use Text::VCardFast;
10 my $hash = Text::VCard::vcard2hash($card, multival => ['adr', 'org', 'n']);
12 my $card = Text::VCard::hash2vcard($hash, "\r\n");
13
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 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 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 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 (see bench.pl in the source tarball for the code)
37 EXPORT
39 vcard2hash
40 hash2vcard
41 API
43 Text::VCard::vcard2hash($card, %options);
44 Options:
45 * 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 * 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 Default is the empty list.
59 * 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 EMAIL;TYPE="INTERNET,HOME";TYPE=PREF:example@example.com
65 If 'multiparam' includes 'TYPE' then the result will be:
67 ['INTERNET', 'HOME', 'PREF'], otherwise it will be:
68 ['INTERNET,HOME', 'PREF'].
69 Default is the empty list.
71 * 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 Consider:
77 EMAIL;INTERNET;HOME:example@example.com
79 barekeys off:
81 {
83 name => 'email',
84 params => { type => ['INTERNET', 'HOME'] },
85 value => 'example@example.com',
86 }
87 barekeys on:
89 {
91 name => 'email',
92 params => { internet => [undef], home => [undef] },
93 value => 'example@example.com',
94 }
95 default is barekeys off.
97 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 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 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 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 Decoding is done where possible, including RFC 6868 handling of ^.
120 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 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 Text::VCard::hash2vcard($hash, $eol)
130 The inverse operation (as much as possible!)
131 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 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
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 BEGIN:VCARD
145 KEY;PKEY=PVALUE:VALUE
146 KEY2:VALUE2
147 END:VCARD
148 {
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 BEGIN:VCARD
177 BEGIN:SUBCARD
178 KEY:VALUE
179 END:SUBCARD
180 END:VCARD
181 {
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 BEGIN:VCARD
205 GROUP1.KEY:VALUE
206 GROUP1.KEY2:VALUE2
207 GROUP2.KEY:VALUE
208 END:VCARD
209 {
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
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 Code is stored on github at
244 https://github.com/brong/Text-VCardFast/
246
248 Bron Gondwana, <brong@fastmail.fm<gt>
249
251 Copyright (C) 2014 by Bron Gondwana
252 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.
256perl v5.36.0 2022-11-09 Text::VCardFast(3)