NAME
Text::vCard - a package to parse, edit and create vCards (RFC 2426)
IMPORTANT
The API is currently subject to change, so don't rely on it being the same in the next version! Some documented functionality is still under development as well, basically have a look if your interested but give me a few weeks to get a finished version out!
SYNOPSIS
use Text::vCard;
my $loader = Text::vCard->loader( source => "xmas_card_list.vcf" );
while (my $vcard = $loader->next) {
$vcard->....;
}or even sexier
while (my $vcard = <$loader> ) {
$vcard->...;
}See Text::vFile for more options, such as parsing a string.
DESCRIPTION
Still under active development.
GENERAL METHODS
split_value()
my @list = $vcard->split_value($value);
my $list_ref = $vcard->split_value($value);This method splits a value on non-escaped commas; into an array, or array ref (depending on calling context) it is useful as some methods (e.g. org and nickname) will return the string non-seperated.
name()
my $name = $vcard->name();This method returns the Text::vCard::Part::Name object if available, it returns undef if not.
LIST METHODS
Accessing lists of elements, if no elements exist then undef is returned.
my @list = $vcard->method();
my $list_array_ref = $vcard->method();Return all of a specific element.
my @list_of_type = $vcard->method('type');
my @types = qw(home work pref);
my @list_of_type = $vcard->method(\@types);Supplied with a scalar or an array ref the methods return a list of specific elements of a type. If any of the elements is the prefered element it will be returned as the first element of the list.
foreach my $object (@list) {
$object->value();
$object->value($new_value);
$object->is_type('fax');
$object->add_type('home');
$object->remove_type('work');
}Go through each object, then call what ever methods you want.
addresses()
This method returns an array or array ref containing Text::vCard::Part::Address objects.
tels()
This method returns an array or array ref containing Text::vCard::Part::Basic objects.
lables()
This method returns an array or array ref containing Text::vCard::Part::Basic objects.
emails()
This method returns an array or array ref containing Text::vCard::Part::Basic objects.
SINGLETYPE METHODS
The following list of methods can be accessed as follows:
my $value = $vcard->method();Undef will be returned if a value does not exists.
and can set a new value as follows:
$vcard->method($value);fn()
This method retrieves or sets the full name of the person associated with the card
bday()
This method retrieves or sets the birthday of the person associated with the card.
mailer()
This method retrieves or sets the type of email software the person associated with the card uses.
title()
This method retrieves or sets the title of the person associated with the card.
role()
This method retrieves or sets the role of the person associated with the card based on the X.520 Business Category explanatory attribute
note()
This method retrieves or sets a note for the person associated with the card
prodid()
This method retrieves or sets the product identifier that created the vCard
rev()
This method retrieves or sets the revision (e.g. verson) of the vcard, of the format date-time or just date.
sort-string()
This method retrieves or sets the family name or given name text to be used for national-language-specific sorting of the fn and name types for the person associated with the card.
url()
This method retrieves or sets a single url associated with the card.
version()
This method retrieves or sets the version of the vCard format used to create the for the card.
class()
This method retrieves or sets the access classification for the vCard object
TYPED SINGLE ELEMENTS METHODS
Accessing lists of elements
my $object = $vcard->method();
$object->value();
$object->value($new_value);
$object->is_type('fax');
$object->add_type('home');
$object->remove_type('work');tz()
Time Zone
uid()
Unique Identifier
MULTIPLETEXT METHODS
my $value = $vcard->method();
$vcard->method($value);
$vcard->method(\@value);The following methods will return a string, containing a list of values which are comma seperated. They can be altered by passing in a scalar or an array refernce (this is joined with commas internally and set as the new value).
nickname()
Nicknames associated with the person.
org()
Organisations associated with the person.
categories()
Categories associated with the person.
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()
#=head1 ADDING ELEMENTS #my $address = $vcard->address_new({ # 'street' => 'The Street', #});
AUTHOR
Leo Lapworth, LLAP@cuckoo.org
COPYRIGHT
Copyright (c) 2003 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.
ACKNOWLEDGEMENTS
Jay J. Lawrence for being a fantastic person to bounce ideas off and for creating Text::vFile from our discussions.
SEE ALSO
Text::vFile::Base, Text::vFile, Text::vCard::Part::Address, Text::vCard::Part::Name, Text::vCard::Part::Basic, Text::vCard::Part::Binary, Text::vCard::Part::Geo