NAME¶
vCard - Read, write, and edit vCards
SYNOPSIS¶
use vCard;
# create the object
my $vcard = vCard->new;
# these methods load vCard data
# (see method documentation for details)
$vcard->load_file($filename);
$vcard->load_string($string);
$vcard->load_hashref($hashref);
# simple getters/setters
$vcard->full_name('Bruce Banner, PhD');
$vcard->title('Research Scientist');
$vcard->photo('http://example.com/bbanner.gif');
# complex getters/setters
$vcard->phones({
{ type => ['work', 'text'], number => '651-290-1234', preferred => 1 },
{ type => ['home'], number => '651-290-1111' }
});
$vcard->email_addresses({
{ type => ['work'], address => 'bbanner@ssh.secret.army.mil' },
{ type => ['home'], address => 'bbanner@timewarner.com' },
});
# these methods output data in vCard format
my $file = $vcard->as_file($filename); # writes to $filename
my $string = $vcard->as_string; # returns a string
DESCRIPTION¶
A vCard is a digital business card. vCard and vCard::AddressBook provide an API
for parsing, editing, and creating vCards.
This module is built on top of Text::vCard. It provides a more intuitive user
interface.
To handle an address book with several vCard entries in it, start with
vCard::AddressBook and then come back to this module.
Note that the vCard RFC requires
version() and
full_name(). This
module does not check or warn if these conditions have not been met.
ENCODING AND UTF-8¶
See the 'ENCODING AND UTF-8' section of vCard::AddressBook.
METHODS¶
load_hashref($hashref)¶
$hashref should look like this:
full_name => 'Bruce Banner, PhD',
given_names => ['Bruce'],
family_names => ['Banner'],
title => 'Research Scientist',
photo => 'http://example.com/bbanner.gif',
phones => [
{ type => ['work'], number => '651-290-1234', preferred => 1 },
{ type => ['cell'], number => '651-290-1111' },
},
addresses => [
{ type => ['work'], ... },
{ type => ['home'], ... },
],
email_addresses => [
{ type => ['work'], address => 'bbanner@shh.secret.army.mil' },
{ type => ['home'], address => 'bbanner@timewarner.com' },
],
Returns $self in case you feel like chaining.
load_file($filename)¶
Returns $self in case you feel like chaining.
load_string($string)¶
Returns $self in case you feel like chaining. This method assumes $string is
decoded (but not MIME decoded).
as_string()¶
Returns the vCard as a string.
as_file($filename)¶
Write data in vCard format to $filename.
Dies if not successful.
SIMPLE GETTERS/SETTERS¶
These methods accept and return strings.
version()¶
Version number of the vcard. Defaults to '4.0'
full_name()¶
A person's entire name as they would like to see it displayed.
title()¶
A person's position or job.
photo()¶
This should be a link. Accepts a string or a URI object. This method always
returns a URI object.
TODO: handle binary images using the data uri schema
birthday()¶
timezone()¶
COMPLEX GETTERS/SETTERS¶
These methods accept and return array references rather than simple strings.
family_names()¶
Accepts/returns an arrayref of family names (aka surnames).
given_names()¶
Accepts/returns an arrayref.
other_names()¶
Accepts/returns an arrayref of names which don't qualify as family_names or
given_names.
honorific_prefixes()¶
Accepts/returns an arrayref. eg "[ 'Dr.' ]"
honorific_suffixes()¶
Accepts/returns an arrayref. eg "[ 'Jr.', 'MD' ]"
phones()¶
Accepts/returns an arrayref that looks like:
[
{ type => ['work'], number => '651-290-1234', preferred => 1 },
{ type => ['cell'], number => '651-290-1111' },
]
addresses()¶
Accepts/returns an arrayref that looks like:
[
{ type => ['work'], street => 'Main St', preferred => 0 },
{ type => ['home'],
pobox => 1234,
extended => 'asdf',
street => 'Army St',
city => 'Desert Base',
region => '',
post_code => '',
country => 'USA',
preferred => 1,
},
]
email_addresses()¶
Accepts/returns an arrayref that looks like:
[
{ type => ['work'], address => 'bbanner@ssh.secret.army.mil' },
{ type => ['home'], address => 'bbanner@timewarner.com', preferred => 1 },
]
AUTHOR¶
Eric Johnson (kablamo), github ~!at!~ iijo dot org
ACKNOWLEDGEMENTS¶
Thanks to Foxtons <
http://foxtons.co.uk> for making this module possible
by donating a significant amount of developer time.