Text::vCard(3) User Contributed Perl Documentation Text::vCard(3)NAMEText::vCard - a package to edit and create a single vCard (RFC 2426)
WARNING
You probably want to start with Text::vCard::Addressbook, then this
module.
This is not backwards compatable with 1.0 or earlier versions!
Version 1.1 was a complete rewrite/restructure, this should not happen
again.
SYNOPSIS
use Text::vCard;
my $cards = Text::vCard->new({
'asData_node' => $objects_node_from_asData,
});
DESCRIPTION
A vCard is an electronic business card.
This package is for a single vCard (person / record / set of address
information). It provides an API to editing and creating vCards, or
supplied a specific piece of the Text::vFile::asData results it
generates a vCard with that content.
You should really use Text::vCard::Addressbook as this handles creating
vCards from an existing file for you.
METHODSnew()
use Text::vCard;
my $new_vcard = Text::vCard->new();
my $existing_vcard = Text::vCard->new({
'asData_node' => $objects_node_from_asData,
});
add_node()
my $address = $vcard->add_node({ 'node_type' => 'ADR', });
This creates a new address in the vCard which you can then call the
address methods on. See below for what options are available.
The node_type parameter must conform to the vCard spec format (e.g. ADR
not address)
get()
The following method allows you to extract the contents from the vCard.
# get all elements
$nodes = $vcard->get('tel');
# Just get the home address
my $nodes = $vcard->get({
'node_type' => 'addresses',
'types' => 'home',
});
# get all phone number that matches serveral types
my @types = qw(work home);
my $nodes = $vcard->get({
'node_type' => 'tel',
'types' => \@types,
});
Either an array or array ref is returned, containing Text::vCard::Node
objects. If there are no results of 'node_type' undef is returned.
Supplied with a scalar or an array ref the methods return a list of
nodes of a type, where relevant. If any of the elements is the prefered
element it will be returned as the first element of the list.
get_simple_type()
The following method is a convenience wrapper for accessing simple
elements.
$value = $vcard->get_simple_type('email', ['internet', 'work']);
If multiple elements match, then only the first is returned. If the
object isn't found, or doesn't have a simple value, then undef is
returned.
The argument type may be ommitted, it can be a scalar, or it can be an
array reference if multiple types are selected.
nodes
my $addresses = $vcard->get({ 'node_type' => 'address' });
my $first_address = $addresses->[0];
# get the value
print $first_address->street();
# set the value
$first_address->street('Barney Rubble');
# See if it is part of a group
if($first_address->group()) {
print 'Group: ' . $first_address->group();
}
According to the RFC the following 'simple' nodes should only have one
element, this is not enforced by this module, so for example you can
have multiple URL's if you wish.
simple nodes
For simple nodes, you can also access the first node in the following
way:
my $fn = $vcard->fullname();
# or setting
$vcard->fullname('new name');
The node will be automatically created if it does not exist and you
supplied a value. undef is returned if the node does not exist. Simple
nodes can be called as all upper or all lowercase method names.
vCard Spec: 'simple' Alias
----------------------------
FN fullname
BDAY birthday
MAILER
TZ timezone
TITLE
ROLE
NOTE
PRODID
REV
SORT-STRING
UID
URL
CLASS
EMAIL
NICKNAME
PHOTO
version (lowercase only)
more complex vCard nodes
vCard Spec Alias Methods on object
-------------------------------------
N name (depreciated as conflicts with rfc, use moniker)
N moniker 'family','given','middle','prefixes','suffixes'
ADR addresses 'po_box','extended','street','city','region','post_code','country'
GEO 'lat','long'
TEL phones
LABELS
ORG 'name','unit' (unit is a special case and will return an array reference)
my $addresses = $vcard->get({ 'node_type' => 'addresses' });
foreach my $address (@{$addresses}) {
print $address->street();
}
# Setting values on an address element
$addresses->[0]->street('The burrows');
$addresses->[0]->region('Wimbeldon common');
# Checking an address is a specific type
$addresses->[0]->is_type('fax');
$addresses->[0]->add_types('home');
$addresses->[0]->remove_types('work');
get_group()
my $group_name = 'item1';
my $node_type = 'X-ABLABEL';
my $of_group = $vcard->get_group($group_name,$node_type);
foreach my $label (@{$of_group}) {
print $label->value();
}
This method takes one or two arguments. The group name (accessable on
any node object by using $node->group() - not all nodes will have a
group, indeed most vcards do not seem to use it) and optionally the
types of node you with to have returned.
Either an array or array reference is returned depending on the calling
context, if there are no matches it will be empty.
BINARY METHODS
These methods allow access to what are potentially binary values such
as a photo or sound file.
API still to be finalised.
photo()sound()key()logo()
get_lookup
This method is used internally to lookup those nodes which have
multiple elements, e.g. GEO has lat and long, N (name) has family,
given, middle etc.
If you wish to extend this package (for custom attributes), overload
this method in your code
sub my_lookup {
return \%my_lookup;
}
*Text::vCard::get_lookup = \&my_lookup;
This has not been tested yet.
get_of_type()
my $list = $vcard->get_of_type($node_type,\@types);
It is probably easier just to use the get() method, which inturn calls
this method.
AUTHOR
Leo Lapworth, LLAP@cuckoo.org
BUGS
None that I'm aware of - export may not encode correctly.
Repository (git)
http://github.com/ranguard/text-vcard,
git://github.com/ranguard/text-vcard.git
COPYRIGHT
Copyright (c) 2005-2010 Leo Lapworth. All rights reserved. This
program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
SEE ALSO
Text::vCard::Address, Text::vCard::Node
perl v5.14.1 2010-01-28 Text::vCard(3)
