File Coverage

blib/lib/Text/vCard/Precisely.pm
Criterion Covered Total %
statement 14 14 100.0
branch 2 2 100.0
condition n/a
subroutine 4 4 100.0
pod 0 1 0.0
total 20 21 95.2


line stmt bran cond sub pod time code
1             package Text::vCard::Precisely;
2              
3             our $VERSION = '0.27';
4              
5 2     2   1469 use Moose;
  2         481340  
  2         14  
6 2     2   13485 use Moose::Util::TypeConstraints;
  2         5  
  2         18  
7              
8             extends 'Text::vCard::Precisely::V3';
9              
10             enum 'Version' => [qw( 3.0 4.0 )];
11             has version => ( is => 'ro', isa => 'Version', default => '3.0', required => 1 );
12              
13             sub BUILD {
14 10     10 0 19 my $self = shift;
15 10 100       273 return Text::vCard::Precisely::V3->new(@_) unless $self->version() eq '4.0';
16              
17 1         612 require Text::vCard::Precisely::V4;
18 1         30 our @ISA = 'Text::vCard::Precisely::V4';
19 1         38 return Text::vCard::Precisely::V4->new(@_);
20             }
21              
22             __PACKAGE__->meta->make_immutable;
23 2     2   4271 no Moose;
  2         4  
  2         10  
24              
25             1;
26              
27             __END__
28              
29             =encoding UTF8
30              
31             =head1 NAME
32              
33             Text::vCard::Precisely - Read, Write and Edit the vCards 3.0 and/or 4.0 precisely
34              
35             =head1 SYNOPSIS
36            
37             use Text::vCard::Precisely;
38             my $vc = Text::vCard::Precisely->new();
39             # Or now you can write like below if you want to use 4.0:
40             my $vc4 = Text::vCard::Precisely->new( version => '4.0' );
41             #or $vc4 = Text::vCard::Precisely::V4->new(); # it's same
42              
43             $vc->n([ 'Gump', 'Forrest', , 'Mr', '' ]);
44             $vc->fn( 'Forrest Gump' );
45              
46             use GD;
47             use MIME::Base64;
48             my $gd = GD::Image->new( 100, 100 );
49             my $black = $gd->colorAllocate( 0, 0, 0 );
50             $gd->rectangle( 0, 0, 99, 99, $black );
51              
52             my $img = $gd->png();
53             my $base64 = MIME::Base64::encode($img);
54              
55             $vc->photo([
56             { content => 'https://avatars2.githubusercontent.com/u/2944869?v=3&s=400', media_type => 'image/jpeg' },
57             { content => $img, media_type => 'image/png' }, # Now you can set a binary image directly
58             { content => $base64, media_type => 'image/png' }, # Also accept the text encoded in Base64
59             ]);
60              
61             $vc->org('Bubba Gump Shrimp Co.'); # Now you can set/get org!
62              
63             $vc->tel({ content => '+1-111-555-1212', types => ['work'], pref => 1 });
64              
65             $vc->email({ content => 'forrestgump@example.com', types => ['work'] });
66              
67             $vc->adr( {
68             types => ['work'],
69             pobox => '109',
70             extended => 'Shrimp Bld.',
71             street => 'Waters Edge',
72             city => 'Baytown',
73             region => 'LA',
74             post_code => '30314',
75             country => 'United States of America',
76             });
77              
78             $vc->url({ content => 'https://twitter.com/worthmine', types => ['twitter'] }); # for URL param
79              
80             print $vc->as_string();
81              
82             =head1 DESCRIPTION
83              
84             A vCard is a digital business card.
85             vCard and L<Text::vFile::asData> provides an API for parsing vCards
86              
87             This module is forked from L<Text::vCard>
88             because some reason below:
89              
90             =over
91              
92             =item
93              
94             Text::vCard B<doesn't provide> full methods based on L<RFC2426|https://tools.ietf.org/html/rfc2426>
95              
96             =item
97              
98             Mac OS X and iOS can't parse vCard4.0 with UTF-8 precisely. they cause some Mojibake
99              
100             =item
101              
102             Android 4.4.x can't parse vCard4.0
103              
104             =back
105              
106             To handle an address book with several vCard entries in it, start with
107             L<Text::vFile::asData> and then come back to this module.
108              
109             Note that the vCard RFC requires C<VERSION> and C<FN>. This module does not check or warn yet if these conditions have not been met
110              
111             =head1 Constructors
112              
113             =head2 load_hashref($HashRef)
114              
115             Accepts a HashRef that looks like below:
116              
117             my $hashref = {
118             N => [ 'Gump', 'Forrest', '', 'Mr.', '' ],
119             FN => 'Forrest Gump',
120             SORT_STRING => 'Forrest Gump',
121             ORG => 'Bubba Gump Shrimp Co.',
122             TITLE => 'Shrimp Man',
123             PHOTO => { media_type => 'image/gif', content => 'http://www.example.com/dir_photos/my_photo.gif' },
124             TEL => [
125             { types => ['WORK','VOICE'], content => '(111) 555-1212' },
126             { types => ['HOME','VOICE'], content => '(404) 555-1212' },
127             ],
128             ADR =>[{
129             types => ['work'],
130             pref => 1,
131             extended => 100,
132             street => 'Waters Edge',
133             city => 'Baytown',
134             region => 'LA',
135             post_code => '30314',
136             country => 'United States of America'
137             },{
138             types => ['home'],
139             extended => 42,
140             street => 'Plantation St.',
141             city => 'Baytown',
142             region => 'LA',
143             post_code => '30314',
144             country => 'United States of America'
145             }],
146             URL => 'http://www.example.com/dir_photos/my_photo.gif',
147             EMAIL => 'forrestgump@example.com',
148             REV => '2008-04-24T19:52:43Z',
149             };
150              
151             =head2 load_file($file_name)
152              
153             Accepts a file name
154              
155             =head2 load_string($vCard)
156              
157             Accepts a vCard string
158              
159             =head1 METHODS
160              
161             =head2 as_string()
162              
163             Returns the vCard as a string.
164             You have to use C<Encode::encode_utf8()> if your vCard is written in utf8
165              
166             =head2 as_file($filename)
167              
168             Write data in vCard format to $filename.
169             Dies if not successful
170              
171             =head1 SIMPLE GETTERS/SETTERS
172              
173             These methods accept and return strings
174              
175             =head2 version()
176              
177             returns Version number of the vcard.
178             Defaults to B<'3.0'> and this method is B<READONLY>
179              
180             =head2 rev()
181              
182             To specify revision information about the current vCard
183              
184             =head2 sort_string()
185              
186             To specify the family name, given name or organization text to be used for
187             national-language-specific sorting of the C<FN>, C<N> and C<ORG>.
188              
189             B<This method is DEPRECATED in vCard4.0> Use C<SORT-AS> param instead of it.
190              
191             =head1 COMPLEX GETTERS/SETTERS
192              
193             They are based on Moose with coercion.
194             So these methods accept not only ArrayRef[HashRef] but also ArrayRef[Str],
195             single HashRef or single Str.
196              
197             Read source if you were confused
198              
199             =head2 n()
200              
201             To specify the components of the name of the object the vCard represents
202              
203             =head2 tel()
204              
205             Accepts/returns an ArrayRef that looks like:
206              
207             [
208             { type => ['work'], content => '651-290-1234', preferred => 1 },
209             { type => ['home'], content => '651-290-1111' },
210             ]
211              
212             After version 0.18, B<content will not be validated as phone numbers>
213             All I<Str> type is accepted.
214              
215             So you have to validate phone numbers with your way.
216              
217             =head2 adr(), address()
218              
219             Accepts/returns an ArrayRef that looks like:
220              
221             [
222             { types => ['work'], street => 'Main St', pref => 1 },
223             { types => ['home'],
224             pobox => 1234,
225             extended => 'asdf',
226             street => 'Army St',
227             city => 'Desert Base',
228             region => '',
229             post_code => '',
230             country => 'USA',
231             pref => 2,
232             },
233             ]
234              
235             =head2 email()
236              
237             Accepts/returns an ArrayRef that looks like:
238              
239             [
240             { type => ['work'], content => 'bbanner@ssh.secret.army.mil' },
241             { type => ['home'], content => 'bbanner@timewarner.com', pref => 1 },
242             ]
243              
244             or accept the string as email like below
245              
246             'bbanner@timewarner.com'
247              
248             =head2 url()
249              
250             Accepts/returns an ArrayRef that looks like:
251              
252             [
253             { content => 'https://twitter.com/worthmine', types => ['twitter'] },
254             { content => 'https://github.com/worthmine' },
255             ]
256              
257             or accept the string as URL like below
258              
259             'https://github.com/worthmine'
260              
261             =head2 photo(), logo()
262              
263             Accepts/returns an ArrayRef of URLs or Images:
264             Even if they are raw image binary or text encoded in Base64, it does not matter
265              
266             B<Attention!> Mac OS X and iOS B<ignore> the description beeing URL
267              
268             use Base64 encoding or raw image binary if you have to show the image you want
269              
270             =head2 note()
271              
272             To specify supplemental information or a comment that is associated with the vCard
273              
274             =head2 org(), title(), role(), categories()
275              
276             To specify additional information for your jobs
277              
278             In these, C<CATEGORIES> may have multiple content with being separated by COMMA.
279             multiple content is expressed by using ArrayRef like this:
280              
281             $vc->categories([qw(Internet Travel)]);
282              
283             =head2 fn(), full_name(), fullname()
284              
285             A person's entire name as they would like to see it displayed
286              
287             =head2 nickname()
288              
289             To specify the text corresponding to the nickname of the object the vCard represents
290              
291             Like C<CATEGORIES>, It ALSO may have multiple content with being separated by COMMA.
292              
293             $vc->nickname([qw(Johny John)]);
294              
295             =head2 geo()
296              
297             To specify information related to the global positioning of the object the vCard represents
298              
299             =head2 key()
300              
301             To specify a public key or authentication certificate associated with the object that the vCard represents
302              
303             =head2 label()
304              
305             ToDo: because B<It's DEPRECATED in vCard4.0>
306              
307             To specify the formatted text corresponding to delivery address of the object the vCard represents
308              
309             =head2 uid()
310              
311             To specify a value that represents a globally unique identifier corresponding to
312             the individual or resource associated with the vCard
313              
314             =head2 tz(), timezone()
315              
316             Both are same method with Alias
317              
318             To specify information related to the time zone of the object the vCard represents
319              
320             utc-offset format is NOT RECOMMENDED from vCard4.0
321              
322             C<TZ> can be a URL, but there is no document in
323             L<RFC2426|https://tools.ietf.org/html/rfc2426>
324             or L<RFC6350|https://tools.ietf.org/html/rfc6350>
325              
326             So it just supports some text values
327              
328             =head2 bday(), birthday()
329              
330             Both are same method with Alias
331              
332             To specify the birth date of the object the vCard represents
333              
334             =head2 prodid()
335              
336             To specify the identifier for the product that created the vCard object
337              
338             =head2 source()
339              
340             To identify the source of directory information contained in the content type
341              
342             =head2 sound()
343              
344             To specify a digital sound content information that annotates some aspect of the vCard
345              
346             This property is often used to specify the proper pronunciation of
347             the name property value of the vCard
348              
349             =head2 socialprofile()
350              
351             There is no documents about C<X-SOCIALPROFILE> in RFC but it works in iOS and Mac OS X!
352              
353             I don't know well about in Android or Windows. Somebody please feedback me
354              
355             =head2 label()
356              
357             B<It's DEPRECATED in vCard4.0> You can use this method Just ONLY in vCard3.0
358              
359             =head1 For operating files with multiple vCards
360              
361             See L<Text::vCard::Precisely::Multiple>
362              
363             =head1 aroud UTF-8
364              
365             If you want to send precisely the vCard with UTF-8 characters to the B<ALMOST>
366             of smartphones, Use 3.0
367              
368             It seems to be TOO EARLY to use 4.0
369              
370             =head1 for under perl-5.12.5
371              
372             This module uses C<\P{ascii}> in regexp so You have to use 5.12.5 and later
373              
374             =head1 SEE ALSO
375              
376             =over
377              
378             =item
379              
380             L<RFC 2426|https://tools.ietf.org/html/rfc2426>
381              
382             =item
383              
384             L<RFC 2425|https://tools.ietf.org/html/rfc2425>
385              
386             =item
387              
388             L<RFC 6350|https://tools.ietf.org/html/rfc6350>
389              
390             =item
391              
392             L<Text::vCard::Precisely::Multiple>
393              
394             =item
395              
396             L<Text::vFile::asData>
397              
398             =back
399              
400             =head1 AUTHOR
401              
402             Yuki Yoshida(L<worthmine|https://github.com/worthmine>)
403              
404             =head1 LICENSE
405              
406             This is free software; you can redistribute it and/or modify it under the same terms as Perl.