NAME

Text::vCard::Precisely::V3 - Read, Write and Edit just ONLY vCards 3.0 precisely

SYNOPSIS

 my $vc = Text::vCard::Precisely->new( version => '3.0' );
 # Or you can write like below if you want to be expressly using 3.0:
 #my $vc = Text::vCard::Precisely::V3->new();

 $vc->n([ 'Gump', 'Forrest', , 'Mr', '' ]);
 $vc->fn( 'Forrest Gump' );

 use GD;
 use MIME::Base64;

 my $img = GD->new( ... some param ... )->plot->png;
 my $base64 = MIME::Base64::encode($img);

 $vc->photo([
    { content => 'https://avatars2.githubusercontent.com/u/2944869?v=3&s=400',  media_type => 'image/jpeg' },
    { content => $img, media_type => 'image/png' }, # Now you can set a binary image directly
    { content => $base64, media_type => 'image/png' }, # Also accept the text encoded in Base64
 ]);

 $vc->org('Bubba Gump Shrimp Co.'); # Now you can set/get org!

 $vc->tel({ content => '+1-111-555-1212', types => ['work'], pref => 1 });

 $vc->email({ content => 'forrestgump@example.com', types => ['work'] });

 $vc->adr( {
    types => ['work'],
    pobox     => '109',
    extended  => 'Shrimp Bld.',
    street    => 'Waters Edge',
    city      => 'Baytown',
    region    => 'LA',
    post_code => '30314,
    country   => 'United States of America',
 });

 $vc->url({ content => 'https://twitter.com/worthmine', types => ['twitter'] }); # for URL param

And you can use X-SOCIALPROFILE type if you want like below:

 use Facebook::Graph;
 use Encode;

 my $fb = Facebook::Graph->new(
    app_id => 'your app id',
    secret => 'your secret key',
 );
 $fb->authorize;
 $fb->access>token( $fb->{'app_id'} . '|' . $fb->{'secret'} );
 my $q = $fb->query->find( 'some facebookID' )
 ->select>fields(qw( id name ))
 ->request
 ->as_hashref;

 $vc->socialprofile({ # Now you can set X-Social-Profile but Android ignore it
    content => 'https://www.facebook/' . 'some facebookID',
    types => 'facebook',
    displayname => encode_utf8( $q->{'name'} ),
    userid => $q->{'id'},
 });

 print $vc->as_string();

DESCRIPTION

A vCard is a digital business card. vCard and Text::vFile::asData provide an API for parsing vCards.

This module is forked from Text::vCard because some reason below:

  • Text::vCard doesn't provide full methods based on RFC2426

  • Mac OS X and iOS can't parse vCard4.0 with UTF-8 precisely. they cause some Mojibake

  • Android 4.4.x can't parse vCard4.0

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

Note that the vCard RFC requires FN type. And this module does not check or warn if these conditions have not been met.

Constructors

load_hashref($HashRef)

Accepts a HashRef that looks like below:

 my $hashref = {
    N   => [ 'Gump', 'Forrest', '', 'Mr.', '' ],
    FN  => 'Forrest Gump',
    SORT_STRING => 'Forrest Gump',
    ORG => 'Bubba Gump Shrimp Co.',
    TITLE => 'Shrimp Man',
    PHOTO => { media_type => 'image/gif', content => 'http://www.example.com/dir_photos/my_photo.gif' },
    TEL => [
        { types => ['WORK','VOICE'], content => '(111) 555-1212' },
        { types => ['HOME','VOICE'], content => '(404) 555-1212' },
    ],
    ADR =>[{
        types       => ['work'],
        pref        => 1,
        extended    => 100,
        street      => 'Waters Edge',
        city        => 'Baytown',
        region      => 'LA',
        post_code   => '30314',
        country     => 'United States of America'
    },{
        types       => ['home'],
        extended    => 42,
        street      => 'Plantation St.',
        city        => 'Baytown',
        region      => 'LA',
        post_code   => '30314',
        country     => 'United States of America'
    }],
    URL => 'http://www.example.com/dir_photos/my_photo.gif',
    EMAIL => 'forrestgump@example.com',
    REV => '2008-04-24T19:52:43Z',
 };

load_file($file_name)

Accepts a file name

load_string($vCard)

Accepts a vCard string

METHODS

as_string()

Returns the vCard as a string. You have to use Encode::encode_utf8() if your vCard is written in utf8

as_file($filename)

Write data in vCard format to $filename. Dies if not successful.

SIMPLE GETTERS/SETTERS

These methods accept and return strings

version()

returns Version number of the vcard. Defaults to '3.0' and this method is READONLY

rev()

To specify revision information about the current vCard3.0

name(), profile(), mailer(), agent(), class();

These Types will be DEPRECATED in vCard 4.0 and it seems they are useless So just sapport as READONLY methods

COMPLEX GETTERS/SETTERS

They are based on Moose with coercion. So, these methods accept not only ArrayRef[HashRef] but also ArrayRef[Str], single HashRef or single Str. Read source if you were confused.

n()

To specify the components of the name of the object the vCard represents.

tel()

 Accepts/returns an ArrayRef that looks like:

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

adr(), address()

Accepts/returns an ArrayRef that looks like:

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

email()

Accepts/returns an ArrayRef that looks like:

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

or accept the string as email like below

 'bbanner@timewarner.com'

url()

Accepts/returns an ArrayRef that looks like:

 [
    { content => 'https://twitter.com/worthmine', types => ['twitter'] },
    { content => 'https://github.com/worthmine' },
 ]

or accept the string as URL like below

 'https://github.com/worthmine'

photo(), logo()

Accepts/returns an ArrayRef of URLs or Images: Even if they are raw image binary or text encoded in Base64, it does not matter Attention! Mac OS X and iOS ignore the description beeing URL use Base64 encoding or raw image binary if you have to show the image you want

note()

To specify supplemental information or a comment that is associated with the vCard

org(), title(), role(), categories()

To specify additional information for your jobs

fn(), full_name(), fullname()

A person's entire name as they would like to see it displayed

nickname()

To specify the text corresponding to the nickname of the object the vCard represents

geo()

To specify information related to the global positioning of the object the vCard represents

key()

To specify a public key or authentication certificate associated with the object that the vCard represents

label() ToDo: because It's DEPRECATED in 4.0 To specify the formatted text corresponding to delivery address of the object the vCard represents

sort_string()

To specify the family name, given name or organization text to be used for national-language-specific sorting of the FN, N and ORG This method will be DEPRECATED in vCard4.0 Use SORT-AS param instead of it. (Text::vCard::Precisely::V4 supports it)

uid()

To specify a value that represents a globally unique identifier corresponding to the individual or resource associated with the vCard

tz(), timezone()

Both are same method with Alias To specify information related to the time zone of the object the vCard represents utc-offset format is NOT RECOMMENDED in vCard 4.0 TZ can be a URL, but there is no document in RFC2426 or RFC6350 So it just supports some text values

bday(), birthday()

Both are same method with Alias To specify the birth date of the object the vCard represents

prodid()

To specify the identifier for the product that created the vCard object

source()

To identify the source of directory information contained in the content type

sound()

To specify a digital sound content information that annotates some aspect of the vCard This property is often used to specify the proper pronunciation of the name property value of the vCard

socialprofile()

There is no documents about X-SOCIALPROFILE in RFC but it works!

aroud UTF-8

if you want to send precisely the vCard3.0 with UTF-8 characters to the Android4.4.x or before, you have to set Charset param for each values like below:

 ADR;CHARSET=UTF-8:201号室;マンション;通り;市;都道府県;郵便番号;日本

for under perl-5.12.5

This module uses \P{ascii} in regexp so You have to use 5.12.5 and later And this module uses Data::Validate::URI and it has bug on 5.8.x. so I can't support them

SEE ALSO

AUTHOR

Yuki Yoshida(worthmine)

LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as Perl.