Provided by: libtext-vcard-perl_3.07-1_all
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.