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

       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.

SEE ALSO

       Text::vCard, Text::vCard::Node