vCard:...ssBook(3pm)

💖 vCard::AddressBook 💖

okay bestie, so this is vCard:...ssBook(3pm) — yes the name is giving truncated-but-iconic, it's just vCard::AddressBook and it lives in the User Contributed Perl Documentation section (that's the 3pm vibe, iykyk). Let me tell you everything. 🎀

---

✨ NAME ✨

vCard::AddressBook — read, write, and edit vCard address books. that's it, that's the whole job, and she does it flawlessly. 💅

---

✨ SYNOPSIS ✨

the whole vibe, in code:

use vCard::AddressBook;

# create the object
my $address_book = vCard::AddressBook->new();

# these methods load vCard formatted data
$address_book->load_file('/path/file.vcf');
$address_book->load_string($string);

my $vcard = $address_book->add_vcard; # returns a vCard object
$vcard->full_name('Bruce Banner, PhD');
$vcard->family_names(['Banner']);
$vcard->given_names(['Bruce']);
$vcard->email_addresses([
    { type => ['work'], address => 'bbanner@ssh.secret.army.mil' },
    { type => ['home'], address => 'bbanner@timewarner.com'      },
]);

# $address_book->vcards() returns an arrayref of vCard objects
foreach my $vcard (@{ $address_book->vcards() }) {
    print $vcard->full_name() . "\n";
    print $vcard->email_addresses->[0]->{address} . "\n";
}

# these methods output data in vCard format
my $file   = $address_book->as_file('/path/file.vcf'); # write to a file
my $string = $address_book->as_string();

💀 not Bruce Banner catching strays in the docs. anyway. no cap, this is exactly how you use it.

---

✨ DESCRIPTION ✨

so a vCard is basically a digital business card. simple as that. vCard and vCard::AddressBook together hand you an API for parsing, editing, and creating vCards. 🫶

and here's the tea: this module is built on top of Text::vCard and Text::vCard::AddressBook, and it exists purely to give you a more intuitive user interface. like, the nicer wrapper. the glow-up. the main character version. 👑

---

✨ ENCODING AND UTF-8 ✨

🌸 Constructor Arguments 🌸

the encoding_in and encoding_out constructor parameters let you read and write vCard files with any encoding. examples of valid values are 'UTF-8', 'Latin1', and 'none'. 🌈

both parameters default to 'UTF-8', and honestly that 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 parameter. like, at all. 🎀

🌸 MIME encodings 🌸

vCard RFC 6350 only allows UTF-8 — but it still permits 8bit MIME encoding schemes such as Quoted-Printable and Base64, and this module supports those. slay. ✨

🌸 Getting and setting values on a vCard object 🌸

if you set values on a vCard object, they must be decoded values. the only exception to this rule is if you are messing around with the 'encoding_out' constructor arg. (messing around, bestie. you've been warned. 🙈)

when you get values from a vCard object, they will be decoded values. that's the deal. 💖

---

✨ METHODS ✨

• add_vcard() — creates a new vCard object and adds it to the address book. returns a vCard object. 👑
• load_file($filename) — load and parse the contents of $filename. returns $self so the method can be chained. (chaining? iconic behaviour. 💅)
• load_string($string) — load and parse the contents of $string. this method assumes that $string is decoded (but not MIME decoded). returns $self so the method can be chained. 🦋
• as_file($filename) — write all the vCards to $filename. files are written as UTF-8 by default. dies if not successful. 😭 so maybe wrap her in an eval if you're feeling fragile.
• as_string() — returns all the vCards as a single string. 🎀

---

✨ AUTHOR ✨

Eric Johnson (kablamo), github ~!at!~ iijo dot org

---

✨ ACKNOWLEDGEMENTS ✨

thanks to Foxtons <http://foxtons.co.uk> for making this module possible by donating a significant amount of developer time. absolute legends, no notes. 🫶👑

---

and that's the whole page, bestie. this was perl v5.34.0, dated 2022-06-28, and it's the vCard:...ssBook(3pm) page — go forth and organize your contacts. periodt. 💖✨🎀