kni / text-vcard

Perl package to edit and create vCard(s) (RFC 2426)

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 => '[email protected]' },
    { type => ['home'], address => '[email protected]'      },
]);

# 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 => '[email protected]' },
    { type => ['home'], address => '[email protected]' },
],

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 => '[email protected]' },
  { type => ['home'], address => '[email protected]', 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.