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

NAME

6       vCard - Read, write, and edit vCards
7

SYNOPSIS

9           use vCard;
10
11           # create the object
12           my $vcard = vCard->new;
13
14           # these methods load vCard data
15           # (see method documentation for details)
16           $vcard->load_file($filename);
17           $vcard->load_string($string);
18           $vcard->load_hashref($hashref);
19
20           # simple getters/setters
21           $vcard->full_name('Bruce Banner, PhD');
22           $vcard->title('Research Scientist');
23           $vcard->photo('http://example.com/bbanner.gif');
24
25           # complex getters/setters
26           $vcard->phones([
27               { type => ['work', 'text'], number => '651-290-1234', preferred => 1 },
28               { type => ['home'],         number => '651-290-1111' }
29           ]);
30           $vcard->email_addresses([
31               { type => ['work'], address => 'bbanner@ssh.secret.army.mil' },
32               { type => ['home'], address => 'bbanner@timewarner.com'      },
33           ]);
34
35           # these methods output data in vCard format
36           my $file   = $vcard->as_file($filename); # writes to $filename
37           my $string = $vcard->as_string;          # returns a string
38

DESCRIPTION

40       A vCard is a digital business card.  vCard and vCard::AddressBook
41       provide an API for parsing, editing, and creating vCards.
42
43       This module is built on top of Text::vCard.  It provides a more
44       intuitive user interface.
45
46       To handle an address book with several vCard entries in it, start with
47       vCard::AddressBook and then come back to this module.
48
49       Note that the vCard RFC requires version() and full_name().  This
50       module does not check or warn if these conditions have not been met.
51

ENCODING AND UTF-8

53       See the 'ENCODING AND UTF-8' section of vCard::AddressBook.
54

METHODS

56   load_hashref($hashref)
57       $hashref should look like this:
58
59           full_name    => 'Bruce Banner, PhD',
60           given_names  => ['Bruce'],
61           family_names => ['Banner'],
62           title        => 'Research Scientist',
63           photo        => 'http://example.com/bbanner.gif',
64           phones       => [
65               { type => ['work'], number => '651-290-1234', preferred => 1 },
66               { type => ['cell'], number => '651-290-1111' },
67           },
68           addresses => [
69               { type => ['work'], ... },
70               { type => ['home'], ... },
71           ],
72           email_addresses => [
73               { type => ['work'], address => 'bbanner@shh.secret.army.mil' },
74               { type => ['home'], address => 'bbanner@timewarner.com' },
75           ],
76
77       Returns $self in case you feel like chaining.
78
79   load_file($filename)
80       Returns $self in case you feel like chaining.
81
82   load_string($string)
83       Returns $self in case you feel like chaining.  This method assumes
84       $string is decoded (but not MIME decoded).
85
86   as_string()
87       Returns the vCard as a string.
88
89   as_file($filename)
90       Write data in vCard format to $filename.
91
92       Dies if not successful.
93

SIMPLE GETTERS/SETTERS

95       These methods accept and return strings.
96
97   version()
98       Version number of the vcard.  Defaults to '4.0'
99
100   full_name()
101       A person's entire name as they would like to see it displayed.
102
103   title()
104       A person's position or job.
105
106   photo()
107       This should be a link. Accepts a string or a URI object.  This method
108       always returns a URI object.
109
110       TODO: handle binary images using the data uri schema
111
112   birthday()
113   timezone()

COMPLEX GETTERS/SETTERS

115       These methods accept and return array references rather than simple
116       strings.
117
118   family_names()
119       Accepts/returns an arrayref of family names (aka surnames).
120
121   given_names()
122       Accepts/returns an arrayref.
123
124   other_names()
125       Accepts/returns an arrayref of names which don't qualify as
126       family_names or given_names.
127
128   honorific_prefixes()
129       Accepts/returns an arrayref.  eg "[ 'Dr.' ]"
130
131   honorific_suffixes()
132       Accepts/returns an arrayref.  eg "[ 'Jr.', 'MD' ]"
133
134   phones()
135       Accepts/returns an arrayref that looks like:
136
137         [
138           { type => ['work'], number => '651-290-1234', preferred => 1 },
139           { type => ['cell'], number => '651-290-1111' },
140         ]
141
142   addresses()
143       Accepts/returns an arrayref that looks like:
144
145         [
146           { type => ['work'], street => 'Main St', preferred => 0 },
147           { type      => ['home'],
148             pobox     => 1234,
149             extended  => 'asdf',
150             street    => 'Army St',
151             city      => 'Desert Base',
152             region    => '',
153             post_code => '',
154             country   => 'USA',
155             preferred => 1,
156           },
157         ]
158
159   email_addresses()
160       Accepts/returns an arrayref that looks like:
161
162         [
163           { type => ['work'], address => 'bbanner@ssh.secret.army.mil' },
164           { type => ['home'], address => 'bbanner@timewarner.com', preferred => 1 },
165         ]
166

AUTHOR

168       Eric Johnson (kablamo), github ~!at!~ iijo dot org
169

ACKNOWLEDGEMENTS

171       Thanks to Foxtons <http://foxtons.co.uk> for making this module
172       possible by donating a significant amount of developer time.
173
174
175
176perl v5.34.0                      2021-07-23                          vCard(3)