---
name: "vCard::AddressBook"
section: "3pm"
platform: "linux"
package: "libtext-vcard-perl"
version: "3.09-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/vCard::AddressBook"
---

# vCard::AddressBook(3pm)

Read, write, and edit vCard address books

## NAME

vCard::AddressBook - Read, write, and edit vCard address books

## SYNOPSIS

```
    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();
```

## DESCRIPTION

A vCard is a digital business card.  vCard and vCard::AddressBook provide an API for parsing, editing, and creating vCards.

This module is built on top of Text::vCard and Text::vCard::AddressBook and provides a more intuitive user interface.

## ENCODING AND UTF-8

### Constructor Arguments

The 'encoding\_in' and 'encoding\_out' constructor parameters allow you to 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 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 parameter.

### 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.

### 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.

When you get values from a vCard object they will be decoded values.

## 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.

### 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.

### 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.