1Text::vCard(3) User Contributed Perl Documentation Text::vCard(3)
2
6 Text::vCard - a package to edit and create a single vCard (RFC 2426)
7
9 You probably want to start with Text::vCard::Addressbook, then this
10 module.
11 This is not backwards compatable with 1.0 or earlier versions!
13 Version 1.1 was a complete rewrite/restructure, this should not happen
15 again.
16
18 use Text::vCard;
19 my $cards = Text::vCard->new({
20 'asData_node' => $objects_node_from_asData,
21 });
22
24 A vCard is an electronic business card.
25 This package is for a single vCard (person / record / set of address
27 information). It provides an API to editing and creating vCards, or
28 supplied a specific piece of the Text::vFile::asData results it
29 generates a vCard with that content.
30 You should really use Text::vCard::Addressbook as this handles creating
32 vCards from an existing file for you.
33
35 new()
36 use Text::vCard;
37 my $new_vcard = Text::vCard->new();
39 my $existing_vcard = Text::vCard->new({
41 'asData_node' => $objects_node_from_asData,
42 });
43 add_node()
45 my $address = $vcard->add_node({ 'node_type' => 'ADR', });
46 This creates a new address in the vCard which you can then call the
48 address methods on. See below for what options are available.
49 The node_type parameter must conform to the vCard spec format (e.g. ADR
51 not address)
52 get()
54 The following method allows you to extract the contents from the vCard.
55 # get all elements
57 $nodes = $vcard->get('tel');
58 # Just get the home address
60 my $nodes = $vcard->get({
61 'node_type' => 'addresses',
62 'types' => 'home',
63 });
64 # get all phone number that matches serveral types
66 my @types = qw(work home);
67 my $nodes = $vcard->get({
68 'node_type' => 'tel',
69 'types' => \@types,
70 });
71 Either an array or array ref is returned, containing Text::vCard::Node
73 objects. If there are no results of 'node_type' undef is returned.
74 Supplied with a scalar or an array ref the methods return a list of
76 nodes of a type, where relevant. If any of the elements is the prefered
77 element it will be returned as the first element of the list.
78 get_simple_type()
80 The following method is a convenience wrapper for accessing simple
81 elements.
82 $value = $vcard->get_simple_type('email', ['internet', 'work']);
84 If multiple elements match, then only the first is returned. If the
86 object isn't found, or doesn't have a simple value, then undef is
87 returned.
88 The argument type may be ommitted, it can be a scalar, or it can be an
90 array reference if multiple types are selected.
91 nodes
93 my $addresses = $vcard->get({ 'node_type' => 'address' });
94 my $first_address = $addresses->[0];
96 # get the value
98 print $first_address->street();
99 # set the value
101 $first_address->street('Barney Rubble');
102 # See if it is part of a group
104 if($first_address->group()) {
105 print 'Group: ' . $first_address->group();
106 }
107 According to the RFC the following 'simple' nodes should only have one
109 element, this is not enforced by this module, so for example you can
110 have multiple URL's if you wish.
111 simple nodes
113 For simple nodes, you can also access the first node in the following
114 way:
115 my $fn = $vcard->fullname();
117 # or setting
118 $vcard->fullname('new name');
119 The node will be automatically created if it does not exist and you
121 supplied a value. undef is returned if the node does not exist. Simple
122 nodes can be called as all upper or all lowercase method names.
123 vCard Spec: 'simple' Alias
125 -------------------- --------
126 FN fullname
127 BDAY birthday
128 MAILER
129 TZ timezone
130 TITLE
131 ROLE
132 NOTE
133 PRODID
134 REV
135 SORT-STRING
136 UID
137 URL
138 CLASS
139 EMAIL
140 NICKNAME
141 PHOTO
142 version (lowercase only)
143 more complex vCard nodes
145 vCard Spec Alias Methods on object
146 ---------- ---------- -----------------
147 N name (depreciated as conflicts with rfc, use moniker)
148 N moniker 'family','given','middle','prefixes','suffixes'
149 ADR addresses 'po_box','extended','street','city','region','post_code','country'
150 GEO 'lat','long'
151 TEL phones
152 LABELS
153 ORG 'name','unit' (unit is a special case and will return an array reference)
154 my $addresses = $vcard->get({ 'node_type' => 'addresses' });
156 foreach my $address (@{$addresses}) {
157 print $address->street();
158 }
159 # Setting values on an address element
161 $addresses->[0]->street('The burrows');
162 $addresses->[0]->region('Wimbeldon common');
163 # Checking an address is a specific type
165 $addresses->[0]->is_type('fax');
166 $addresses->[0]->add_types('home');
167 $addresses->[0]->remove_types('work');
168 get_group()
170 my $group_name = 'item1';
171 my $node_type = 'X-ABLABEL';
172 my $of_group = $vcard->get_group($group_name,$node_type);
173 foreach my $label (@{$of_group}) {
174 print $label->value();
175 }
176 This method takes one or two arguments. The group name (accessable on
178 any node object by using $node->group() - not all nodes will have a
179 group, indeed most vcards do not seem to use it) and optionally the
180 types of node you with to have returned.
181 Either an array or array reference is returned depending on the calling
183 context, if there are no matches it will be empty.
184
186 These methods allow access to what are potentially binary values such
187 as a photo or sound file.
188 API still to be finalised.
190 photo()
192 sound()
193 key()
194 logo()
195 get_lookup
196 This method is used internally to lookup those nodes which have
197 multiple elements, e.g. GEO has lat and long, N (name) has family,
198 given, middle etc.
199 If you wish to extend this package (for custom attributes), overload
201 this method in your code
202 sub my_lookup {
204 return \%my_lookup;
205 }
206 *Text::vCard::get_lookup = \&my_lookup;
207 This has not been tested yet.
209 get_of_type()
211 my $list = $vcard->get_of_type($node_type,\@types);
212 It is probably easier just to use the get() method, which inturn calls
214 this method.
215
217 Leo Lapworth, LLAP@cuckoo.org
218
220 None that I'm aware of - export may not encode correctly.
221
223 http://github.com/ranguard/text-vcard,
224 git://github.com/ranguard/text-vcard.git
225
227 Copyright (c) 2005-2010 Leo Lapworth. All rights reserved. This
228 program is free software; you can redistribute it and/or modify it
229 under the same terms as Perl itself.
230
232 Text::vCard::Address, Text::vCard::Node
233perl v5.12.0 2010-01-28 Text::vCard(3)