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'
);
# 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'
,
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 for making this module possible by donating a significant amount of developer time.