NAME

       vCard - Read, write, and edit vCards

SYNOPSIS

           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

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.  It provides a more intuitive user interface.

       To handle an address book with several vCard entries in it, start with vCard::AddressBook
       and then come back to this module.

       Note that the vCard RFC requires version() and full_name().  This module does not check or
       warn if these conditions have not been met.

ENCODING AND UTF-8

       See the 'ENCODING AND UTF-8' section of vCard::AddressBook.

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.

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

   as_string()
       Returns the vCard as a string.

   as_file($filename)
       Write data in vCard format to $filename.

       Dies if not successful.

SIMPLE GETTERS/SETTERS

       These methods accept and return strings.

   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.

   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()
   timezone()

COMPLEX GETTERS/SETTERS

       These methods accept and return array references rather than simple strings.

   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.