vCard(3pm)

💌 vCard — like, the Perl module, bestie

okay so this is vCard(3pm), from the User Contributed Perl Documentation section of the manual, and it's genuinely one of the cutest little modules out there. it's a Perl thing. it reads, writes, and edits vCards. let's go 🎀

---

✨ NAME ✨

vCard — read, write, and edit vCards. that's it. that's the whole vibe. 💅

---

🌸 SYNOPSIS 🌸

here's the whole flow, no gatekeeping:

    use vCard;

    # create the object
    my $vcard = vCard->new;

    # these methods load vCard data
    # (see method documentation for details)
    $vcard->load_file($filename);
    $vcard->load_string($string);
    $vcard->load_hashref($hashref);

    # simple getters/setters
    $vcard->full_name('Bruce Banner, PhD');
    $vcard->title('Research Scientist');
    $vcard->photo('http://example.com/bbanner.gif');

    # complex getters/setters
    $vcard->phones([
        { type => ['work', 'text'], number => '651-290-1234', preferred => 1 },
        { type => ['home'],         number => '651-290-1111' }
    ]);
    $vcard->email_addresses([
        { type => ['work'], address => 'bbanner@ssh.secret.army.mil' },
        { type => ['home'], address => 'bbanner@timewarner.com'      },
    ]);

    # these methods output data in vCard format
    my $file   = $vcard->as_file($filename); # writes to $filename
    my $string = $vcard->as_string;          # returns a string

like... it's giving "I have a business card and it's digital". obsessed. 🔥

---

🦋 DESCRIPTION 🦋

A vCard is a digital business card. periodt. 💳✨

vCard and vCard::AddressBook team up to give you an API for parsing, editing, and creating vCards. bestie duo fr fr.

This module is built on top of Text::vCard. It just... provides a more intuitive user interface. the way that it's the glow-up version 😌

If you're dealing with an address book that has several vCard entries in it, start with vCard::AddressBook and then come back to this module. iykyk.

⚠️ heads up babes: the vCard RFC requires version() and full_name(). This module does not check or warn if these conditions have not been met. so like, do your part. 🙈

---

🌈 ENCODING AND UTF-8 🌈

See the 'ENCODING AND UTF-8' section of vCard::AddressBook. it's all over there, go look 💜

---

💖 METHODS 💖

🎀 load_hashref($hashref)

$hashref should look like this:

    full_name    => 'Bruce Banner, PhD',
    given_names  => ['Bruce'],
    family_names => ['Banner'],
    title        => 'Research Scientist',
    photo        => 'http://example.com/bbanner.gif',
    phones       => [
        { type => ['work'], number => '651-290-1234', preferred => 1 },
        { type => ['cell'], number => '651-290-1111' },
    ],
    addresses => [
        { type => ['work'], ... },
        { type => ['home'], ... },
    ],
    email_addresses => [
        { type => ['work'], address => 'bbanner@shh.secret.army.mil' },
        { type => ['home'], address => 'bbanner@timewarner.com' },
    ],

Returns $self in case you feel like chaining. 🔗 slay.

🎀 load_file($filename)

Returns $self in case you feel like chaining. 🔗

🎀 load_string($string)

Returns $self in case you feel like chaining. 🔗

This method assumes $string is decoded (but not MIME decoded). noted. 📝

🎀 as_string()

Returns the vCard as a string. 💫

🎀 as_file($filename)

Write data in vCard format to $filename. 💾

💀 Dies if not successful. like, it will simply pass away.

---

💅 SIMPLE GETTERS/SETTERS 💅

These methods accept and return strings. simple. clean. iconic. ✨

• version() — Version number of the vcard. Defaults to '4.0'
• full_name() — A person's entire name as they would like to see it displayed. (their name, their rules 💖)
• title() — A person's position or job.
• photo() — This should be a link. Accepts a string or a URI object. This method always returns a URI object.
  • TODO: handle binary images using the data uri schema
• birthday() — yeah. it's the birthday. 🎂
• timezone() — the timezone, bestie. 🕐

---

👑 COMPLEX GETTERS/SETTERS 👑

These methods accept and return array references rather than simple strings. fancy, i know. 🫶

• family_names() — Accepts/returns an arrayref of family names (aka surnames).
• given_names() — Accepts/returns an arrayref.
• other_names() — Accepts/returns an arrayref of names which don't qualify as family_names or given_names.
• honorific_prefixes() — Accepts/returns an arrayref. eg "[ 'Dr.' ]"
• honorific_suffixes() — Accepts/returns an arrayref. eg "[ 'Jr.', 'MD' ]"
• phones() — Accepts/returns an arrayref that looks like:

  [
    { type => ['work'], number => '651-290-1234', preferred => 1 },
    { type => ['cell'], number => '651-290-1111' },
  ]

• addresses() — Accepts/returns an arrayref that looks like:

  [
    { type => ['work'], street => 'Main St', preferred => 0 },
    { type      => ['home'],
      pobox     => 1234,
      extended  => 'asdf',
      street    => 'Army St',
      city      => 'Desert Base',
      region    => '',
      post_code => '',
      country   => 'USA',
      preferred => 1,
    },
  ]

• email_addresses() — Accepts/returns an arrayref that looks like:

  [
    { type => ['work'], address => 'bbanner@ssh.secret.army.mil' },
    { type => ['home'], address => 'bbanner@timewarner.com', preferred => 1 },
  ]

---

⭐ 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 cap. 👑

---

okay and for the lil' sign-off moment: this whole thing is documented for perl v5.34.0 and dated 2022-06-28 — so yeah, that's the vCard(3pm) era we're living in. go forth and make digital business cards, bestie. mwah 💋🎀✨