NAME

Text::vCard::Addressbook - Parse, edit, and create vCard address books (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

ACKNOWLEDGEMENTS

The authors of Text::vFile::asData for making my life so much easier.