NAME
Text::vCard::Addressbook - a package to parse, edit and create multiple vCards (RFC 2426)
WARNING
vCard::AddressBook is built on top of this module and provides a more intuitive user interface. Please try that module first.
SYNOPSIS
use Text::vCard::Addressbook;
# To read an existing address book file:
my $address_book = Text::vCard::Addressbook->new({
'source_file' => '/path/to/address_book.vcf',
});
foreach my $vcard ( $address_book->vcards() ) {
print "Got card for " . $vcard->fullname() . "\n";
}
# To create a new address book file:
my $address_book = Text::vCard::Addressbook->new();
my $vcard = $address_book->add_vcard;
$vcard->fullname('Foo Bar');
$vcard->EMAIL('foo@bar.com');
open my $out, '>:encoding(UTF-8)', 'new_address_book.vcf' or die;
print $out $address_book->export;DESCRIPTION
This package provides an API to reading / editing and creating multiple vCards. A vCard is an electronic business card. This package has been developed based on rfc2426.
You will find that many applications (Apple Address book, MS Outlook, Evolution etc) can export and import vCards.
ENCODING AND UTF-8
Constructor Arguments
The 'encoding_in' and 'encoding_out' constructor arguments allow you to read and write vCard files with any encoding. Examples of valid values are 'UTF-8', 'Latin1', and 'none'.
Both values default to 'UTF-8' and this should just work for the vast majority of people. The latest vCard RFC 6350 only allows UTF-8 as an encoding so most people should not need to use either of these constructor arguments.
MIME encodings
vCard RFC 6350 only allows UTF-8 but it still permits 8bit MIME encoding schemes such as Quoted-Printable and Base64 which are supported by this module.
Manually setting values on a Text::vCard or Text::vCard::Node object
If you manually set values on a Text::vCard or Text::vCard::Node object they must be decoded values. The only exception to this rule is if you are messing around with the 'encoding_out' constructor arg.
METHODS FOR LOADING VCARDS
load()
my $address_book = Text::vCard::Addressbook->load(
[ 'foo.vCard', 'Addresses.vcf' ], # list of files to load
);This method will croak if it is unable to read in any of the files.
import_data()
$address_book->import_data($string);This method imports data directly from a string. $string is assumed to be decoded (but not MIME decoded).
new()
# Create a new (empty) address book
my $address_book = Text::vCard::Addressbook->new();
# Load vcards from a single file
my $address_book = Text::vCard::Addressbook->new({
source_file => '/path/to/address_book.vcf'
});
# Load vcards from a a string
my $address_book = Text::vCard::Addressbook->new({
source_text => $source_text
});This method will croak if it is unable to read the source_file.
The constructor accepts 'encoding_in' and 'encoding_out' attributes. The default values for both are 'UTF-8'. You can set them to 'none' if you don't want your output encoded with Encode::encode(). But be aware the latest vCard RFC 6350 mandates UTF-8.
OTHER METHODS
add_vcard()
my $vcard = $address_book->add_vcard();This method creates a new empty Text::vCard object, stores it in the address book and return it so you can add data to it.
vcards()
my $vcards = $address_book->vcards();
my @vcards = $address_book->vcards();This method returns a reference to an array or an array of vcards in this address book. This could be an empty list if there are no entries in the address book.
set_encoding()
DEPRECATED. Use the 'encoding_in' and 'encoding_out' constructor arguments.
export()
my $string = $address_book->export()This method returns the vcard data as a string in the vcf file format.
Please note there is no validation, you must ensure that the correct nodes (FN,N,VERSION) are already added to each vcard if you want to comply with RFC 2426.
AUTHOR
Leo Lapworth, LLAP@cuckoo.org Eric Johnson (kablamo), github ~!at!~ iijo dot 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
The authors of Text::vFile::asData for making my life so much easier.