Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Perl package to edit and create vCard(s) (RFC 2426)
Perl Perl6
Failed to load latest commit information.
lib Fix bugs in POD examples.
t Added a test for Text::vCard::Node->add_types().
.gitignore ok now doing this for real
.travis.yml install Test::NoTabs on travis
Changes release 3.07
MANIFEST.SKIP Switch to DZilla
README.md release 3.07
TODO
dist.ini release 3.07

README.md

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

Something went wrong with that request. Please try again.