Text::vCard(3pm)

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

NAME

6       Text::vCard - Edit and create vCards (RFC 2426)
7

WARNING

9       vCard and vCard::AddressBook are built on top of this module and
10       provide a more intuitive user interface.  Please try those modules
11       first.
12

SYNOPSIS

14         use Text::vCard;
15         my $cards
16             = Text::vCard->new( { 'asData_node' => $objects_node_from_asData, } );
17

DESCRIPTION

19       A vCard is an electronic business card.
20
21       This package is for a single vCard (person / record / set of address
22       information). It provides an API to editing and creating vCards, or
23       supplied a specific piece of the Text::vFile::asData results it
24       generates a vCard with that content.
25
26       You should really use Text::vCard::Addressbook as this handles creating
27       vCards from an existing file for you.
28

METHODS

30   new()
31         use Text::vCard;
32
33         my $new_vcard = Text::vCard->new();
34
35         my $existing_vcard
36             = Text::vCard->new( { 'asData_node' => $objects_node_from_asData, } );
37
38   add_node()
39         my $address = $vcard->add_node( { 'node_type' => 'ADR', } );
40
41       This creates a new address (a Text::vCard::Node object) in the vCard
42       which you can then call the address methods on. See below for what
43       options are available.
44
45       The node_type parameter must conform to the vCard spec format (e.g. ADR
46       not address)
47
48   get()
49       The following method allows you to extract the contents from the vCard.
50
51         # get all elements
52         $nodes = $vcard->get('tel');
53
54         # Just get the home address
55         my $nodes = $vcard->get(
56             {   'node_type' => 'addresses',
57                 'types'     => 'home',
58             }
59         );
60
61         # get all phone number that matches serveral types
62         my @types = qw(work home);
63         my $nodes = $vcard->get(
64             {   'node_type' => 'tel',
65                 'types'     => \@types,
66             }
67         );
68
69       Either an array or array ref is returned, containing Text::vCard::Node
70       objects.  If there are no results of 'node_type' undef is returned.
71
72       Supplied with a scalar or an array ref the methods return a list of
73       nodes of a type, where relevant. If any of the elements is the prefered
74       element it will be returned as the first element of the list.
75
76   get_simple_type()
77       The following method is a convenience wrapper for accessing simple
78       elements.
79
80         $value = $vcard->get_simple_type( 'email', [ 'internet', 'work' ] );
81
82       If multiple elements match, then only the first is returned.  If the
83       object isn't found, or doesn't have a simple value, then undef is
84       returned.
85
86       The argument type may be ommitted, it can be a scalar, or it can be an
87       array reference if multiple types are selected.
88
89   nodes
90         my $addresses = $vcard->get( { 'node_type' => 'address' } );
91
92         my $first_address = $addresses->[0];
93
94         # get the value
95         print $first_address->street();
96
97         # set the value
98         $first_address->street('Barney Rubble');
99
100         # See if it is part of a group
101         if ( $first_address->group() ) {
102             print 'Group: ' . $first_address->group();
103         }
104
105       According to the RFC the following 'simple' nodes should only have one
106       element, this is not enforced by this module, so for example you can
107       have multiple URL's if you wish.
108
109   simple nodes
110       For simple nodes, you can also access the first node in the following
111       way:
112
113         my $fn = $vcard->fullname();
114         # or setting
115         $vcard->fullname('new name');
116
117       The node will be automatically created if it does not exist and you
118       supplied a value.  undef is returned if the node does not exist. Simple
119       nodes can be called as all upper or all lowercase method names.
120
121         vCard Spec: 'simple'    Alias
122         --------------------    --------
123         FN                      fullname
124         BDAY                    birthday
125         MAILER
126         TZ                      timezone
127         TITLE
128         ROLE
129         NOTE
130         PRODID
131         REV
132         SORT-STRING
133         UID
134         URL
135         CLASS
136         EMAIL
137         NICKNAME
138         PHOTO
139         version (lowercase only)
140
141   more complex vCard nodes
142         vCard Spec    Alias           Methods on object
143         ----------    ----------      -----------------
144         N             name (depreciated as conflicts with rfc, use moniker)
145         N             moniker            'family','given','middle','prefixes','suffixes'
146         ADR           addresses       'po_box','extended','street','city','region','post_code','country'
147         GEO                           'lat','long'
148         TEL           phones
149         LABELS
150         ORG                           'name','unit' (unit is a special case and will return an array reference)
151
152         my $addresses = $vcard->get( { 'node_type' => 'addresses' } );
153         foreach my $address ( @{$addresses} ) {
154             print $address->street();
155         }
156
157         # Setting values on an address element
158         $addresses->[0]->street('The burrows');
159         $addresses->[0]->region('Wimbeldon common');
160
161         # Checking an address is a specific type
162         $addresses->[0]->is_type('fax');
163         $addresses->[0]->add_types('home');
164         $addresses->[0]->remove_types('work');
165
166   get_group()
167         my $group_name = 'item1';
168         my $node_type  = 'X-ABLABEL';
169         my $of_group   = $vcard->get_group( $group_name, $node_type );
170         foreach my $label ( @{$of_group} ) {
171             print $label->value();
172         }
173
174       This method takes one or two arguments. The group name (accessable on
175       any node object by using $node->group() - not all nodes will have a
176       group, indeed most vcards do not seem to use it) and optionally the
177       types of node you with to have returned.
178
179       Either an array or array reference is returned depending on the calling
180       context, if there are no matches it will be empty.
181

BINARY METHODS

183       These methods allow access to what are potentially binary values such
184       as a photo or sound file. Binary values will be correctly encoded and
185       decoded to/from base 64.
186
187       API still to be finalised.
188
189   photo()
190   sound()
191   key()
192   logo()
193   get_lookup
194       This method is used internally to lookup those nodes which have
195       multiple elements, e.g. GEO has lat and long, N (name) has family,
196       given, middle etc.
197
198       If you wish to extend this package (for custom attributes), overload
199       this method in your code:
200
201         sub my_lookup {
202             return \%my_lookup;
203         }
204         *Text::vCard::get_lookup = \&my_lookup;
205
206       This has not been tested yet.
207
208   get_of_type()
209         my $list = $vcard->get_of_type( $node_type, \@types );
210
211       It is probably easier just to use the get() method, which inturn calls
212       this method.
213
214   as_string
215       Returns the vCard as a string.
216

AUTHOR

218       Leo Lapworth, LLAP@cuckoo.org Eric Johnson (kablamo), github ~!at!~
219       iijo dot org
220

Repository (git)

222       http://github.com/ranguard/text-vcard,
223       git://github.com/ranguard/text-vcard.git
224

COPYRIGHT

226       Copyright (c) 2005-2010 Leo Lapworth. All rights reserved.  This
227       program is free software; you can redistribute it and/or modify it
228       under the same terms as Perl itself.
229