Text::...ssbook(3pm)

💖 Text::vCard::Addressbook — bestie edition 💖

okay so. this is the Perl module Text::vCard::Addressbook, and it's giving "parse, edit, and create vCard address books (RFC 2426)". yes the whole thing. all the cards. slay.

---

🚨 WARNING 🚨

ngl, vCard::AddressBook is built on top of this module and it gives a way more intuitive user interface. so like, please try that module first?? it's the main character here, this one is the supporting cast. 🙈

---

✨ 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;

like... it literally reads cards, it literally writes cards. we love a versatile icon. 👑

---

🌸 DESCRIPTION 🌸

This package gives you an API for reading / editing and creating multiple vCards. and what is a vCard?? it's an electronic business card, bestie. this package was developed based on rfc2426, no cap.

and the way that so many apps (Apple Address book, MS Outlook, Evolution etc) can export and import vCards?? iconic. you will find that. it's real. 🔥

---

🔤 ENCODING AND UTF-8 🔤

🧚 Constructor Arguments

The 'encoding_in' and 'encoding_out' constructor arguments let you 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 honestly 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. periodt. 💅

📧 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. so like, the vibe is UTF-8 but the MIME schemes are still allowed to come thru. 🎀

🙈 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. that's the one loophole, iykyk.

---

📂 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. like it's not gonna be chill about it. it's gonna croak. 😭

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). important distinction bestie!! 🫶

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. (yes, "a a string" — that's what the original says, i'm not fixing it, it's part of the lore 💀)

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. so like, do what you want but the RFC is watching. 👀

---

🛠️ 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 returns it so you can add data to it. it's giving "here's a blank canvas, go off". ✨

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. and like, empty list is valid!! it's fine!! 🦋

set_encoding()

DEPRECATED. use the 'encoding_in' and 'encoding_out' constructor arguments instead. it's old. it's retired. let it rest. 🪦

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. the module is not your babysitter, bestie, you gotta check yourself. 😤

---

👑 AUTHOR 👑

Leo Lapworth, LLAP@cuckoo.org — and Eric Johnson (kablamo), github ~!at!~ iijo dot org. legends, fr fr. 🫶

---

©️ 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. shoutout, we stan. 💜

---

🔗 SEE ALSO 🔗

• Text::vCard
• Text::vCard::Node

---

and that's the whole page!! 🌈 go forth and card responsibly. this was perl v5.34.0, dated 2022-06-28 — ty for coming to my ted talk, mwah 💅💖