Text::vCard(3pm)

✨ Text::vCard ✨ — bestie, we're doing vCards today 🎀

okay so this is Text::vCard from the perl user-contributed docs, aka Text::vCard(3pm). it's the module for editing and creating vCards, RFC 2426 style. it's giving very "i have 400 contacts and i organize them by vibe". 💅

---

⚠️ WARNING ⚠️

so like, real talk: vCard and vCard::AddressBook are built on top of this module, and they give you a way more intuitive user interface. please try those modules first. this one is the backstage pass, not the front door. 🙈

---

📖 SYNOPSIS 📖

use Text::vCard;
my $cards
    = Text::vCard->new( { 'asData_node' => $objects_node_from_asData, } );

---

💖 DESCRIPTION 💖

a vCard is an electronic business card. iconic, honestly.

this package handles a single vCard (like, one person / one record / one set of address info). it gives you an API for editing and creating vCards — or, if you hand it a specific piece of the Text::vFile::asData results, it'll generate a vCard with that content. no cap. 🌸

ngl, you should really be using Text::vCard::Addressbook, because that one handles creating vCards from an existing file for you. this module is the "i'll do it myself" era.

---

🛠️ METHODS 🛠️

new()

use Text::vCard;

my $new_vcard = Text::vCard->new();

my $existing_vcard
    = Text::vCard->new( { 'asData_node' => $objects_node_from_asData, } );

add_node()

my $address = $vcard->add_node( { 'node_type' => 'ADR', } );

this creates a new address (a Text::vCard::Node object, bestie) inside the vCard, and then you can call the address methods on it. see below for what options are available. ✨

the node_type parameter must conform to the vCard spec format — so like ADR, not address. the spec does not care about your lowercase era. 💀

get()

this method lets you extract the contents from the vCard. it's the little extractor-3000. 🧚

# get all elements
$nodes = $vcard->get('tel');

# Just get the home address
my $nodes = $vcard->get(
    {   'node_type' => 'addresses',
        'types'     => 'home',
    }
);

# get all phone number that matches several types
my @types = qw(work home);
my $nodes = $vcard->get(
    {   'node_type' => 'tel',
        'types'     => \@types,
    }
);

you get back either an array or an array ref (depending on context, iykyk), containing Text::vCard::Node objects. and if there are no results of that 'node_type', undef is returned. ghosted. 👻

supplied with a scalar or an array ref, the methods return a list of nodes of a type, where relevant. and here's the cute part: if any of the elements is the preferred element, it gets returned as the first element of the list. main character energy, first in line. 👑

get_simple_type()

this one is a convenience wrapper for accessing simple elements. it's the shortcut girly. 🎀

$value = $vcard->get_simple_type( 'email', [ 'internet', 'work' ] );

if multiple elements match, then only the first is returned. if the object isn't found, or doesn't have a simple value, then undef is returned. sorry. 😭

the argument type may be omitted, it can be a scalar, or it can be an array reference if multiple types are selected. flexible fr fr.

nodes

my $addresses = $vcard->get( { 'node_type' => 'address' } );

my $first_address = $addresses->[0];

# get the value
print $first_address->street();

# set the value
$first_address->street('Barney Rubble');

# See if it is part of a group
if ( $first_address->group() ) {
    print 'Group: ' . $first_address->group();
}

according to the RFC, the following 'simple' nodes should only have one element. this is not enforced by this module — so for example you can have multiple URL's if you wish. live your truth. 🌈

simple nodes

for simple nodes, you can also access the first node like this:

my $fn = $vcard->fullname();
# or setting
$vcard->fullname('new name');

the node will be automatically created if it does not exist and you supplied a value. and undef is returned if the node does not exist. simple nodes can be called as all upper or all lowercase method names — pick your fighter. 💅

vCard Spec: 'simple'    Alias
--------------------    --------
FN                      fullname
BDAY                    birthday
MAILER
TZ                      timezone
TITLE
ROLE
NOTE
PRODID
REV
SORT-STRING
UID
URL
CLASS
EMAIL
NICKNAME
PHOTO
version (lowercase only)

more complex vCard nodes

vCard Spec    Alias           Methods on object
----------    ----------      -----------------
N             name (depreciated as conflicts with rfc, use moniker)
N             moniker            'family','given','middle','prefixes','suffixes'
ADR           addresses       'po_box','extended','street','city','region','post_code','country'
GEO                           'lat','long'
TEL           phones
LABELS
ORG                           'name','unit' (unit is a special case and will return an array reference)

my $addresses = $vcard->get( { 'node_type' => 'addresses' } );
foreach my $address ( @{$addresses} ) {
    print $address->street();
}

# Setting values on an address element
$addresses->[0]->street('The burrows');
$addresses->[0]->region('Wimbeldon common');

# Checking an address is a specific type
$addresses->[0]->is_type('fax');
$addresses->[0]->add_types('home');
$addresses->[0]->remove_types('work');

get_group()

my $group_name = 'item1';
my $node_type  = 'X-ABLABEL';
my $of_group   = $vcard->get_group( $group_name, $node_type );
foreach my $label ( @{$of_group} ) {
    print $label->value();
}

this method takes one or two arguments: the group name (accessible on any node object by using $node->group() — not all nodes will have a group, indeed most vcards do not seem to use it 🫠) and optionally the types of node you wish to have returned.

you get back either an array or an array reference depending on the calling context. if there are no matches, it'll be empty. no matches, no drama. 🦋

---

🔐 BINARY METHODS 🔐

these methods let you access what are potentially binary values — like a photo or a sound file. binary values will be correctly encoded and decoded to/from base 64. slay, honestly. ⭐

API still to be finalised. (yes, it's giving "we'll finish it later", and that's fine.) 🍓

photo()

sound()

key()

logo()

get_lookup

this method is used internally to look up those nodes which have multiple elements — e.g. GEO has lat and long, N (name) has family, given, middle etc. it's the little address book of the address book. 🔥

if you wish to extend this package (for custom attributes), overload this method in your code:

sub my_lookup {
    return \%my_lookup;
}
*Text::vCard::get_lookup = \&my_lookup;

this has not been tested yet. ⚠️ consider yourself warned, bestie.

get_of_type()

my $list = $vcard->get_of_type( $node_type, \@types );

it is probably easier just to use the get() method, which in turn calls this method. so like... use get(). 💖

as_string

returns the vCard as a string. that's it, that's the whole vibe. 🎀

---

👑 AUTHOR 👑

Leo Lapworth, LLAP@cuckoo.org Eric Johnson (kablamo), github ~!at!~ iijo dot org

Repository (git)

http://github.com/ranguard/text-vcard, git://github.com/ranguard/text-vcard.git

---

📜 COPYRIGHT 📜

Copyright (c) 2005-2010 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.

---

🌈 SEE ALSO 🌈

Text::vCard::Addressbook, Text::vCard::Node, vCard vCard, vCard::AddressBook vCard::AddressBook,

---

okay that's the whole page bestie, go forth and vCard responsibly 🫶

this has been the perl v5.34.0 version of Text::vCard(3pm), dated 2022-06-28 — mwah, no notes, periodt. 💜✨