Text::vCard::Addressbook(3pm)

1Text::vCard::AddressbooUks(e3r)Contributed Perl DocumentTaetxito:n:vCard::Addressbook(3)
2
3
4

NAME

6       Text::vCard::Addressbook - Parse, edit, and create vCard address books
7       (RFC 2426)
8

WARNING

10       vCard::AddressBook is built on top of this module and provides a more
11       intuitive user interface.  Please try that module first.
12

SYNOPSIS

14         use Text::vCard::Addressbook;
15
16         # To read an existing address book file:
17
18         my $address_book = Text::vCard::Addressbook->new({
19           'source_file'  => '/path/to/address_book.vcf',
20         });
21
22         foreach my $vcard ( $address_book->vcards() ) {
23             print "Got card for " . $vcard->fullname() . "\n";
24         }
25
26         # To create a new address book file:
27
28         my $address_book = Text::vCard::Addressbook->new();
29         my $vcard        = $address_book->add_vcard;
30         $vcard->fullname('Foo Bar');
31         $vcard->EMAIL('foo@bar.com');
32
33         open my $out, '>:encoding(UTF-8)', 'new_address_book.vcf' or die;
34         print $out $address_book->export;
35

DESCRIPTION

37       This package provides an API to reading / editing and creating multiple
38       vCards.  A vCard is an electronic business card. This package has been
39       developed based on rfc2426.
40
41       You will find that many applications (Apple Address book, MS Outlook,
42       Evolution etc) can export and import vCards.
43

ENCODING AND UTF-8

45   Constructor Arguments
46       The 'encoding_in' and 'encoding_out' constructor arguments allow you to
47       read and write vCard files with any encoding.  Examples of valid values
48       are 'UTF-8', 'Latin1', and 'none'.
49
50       Both values default to 'UTF-8' and this should just work for the vast
51       majority of people.  The latest vCard RFC 6350 only allows UTF-8 as an
52       encoding so most people should not need to use either of these
53       constructor arguments.
54
55   MIME encodings
56       vCard RFC 6350 only allows UTF-8 but it still permits 8bit MIME
57       encoding schemes such as Quoted-Printable and Base64 which are
58       supported by this module.
59
60   Manually setting values on a Text::vCard or Text::vCard::Node object
61       If you manually set values on a Text::vCard or Text::vCard::Node object
62       they must be decoded values.  The only exception to this rule is if you
63       are messing around with the 'encoding_out' constructor arg.
64

METHODS FOR LOADING VCARDS

66   load()
67         my $address_book = Text::vCard::Addressbook->load(
68           [ 'foo.vCard', 'Addresses.vcf' ],  # list of files to load
69         );
70
71       This method will croak if it is unable to read in any of the files.
72
73   import_data()
74         $address_book->import_data($string);
75
76       This method imports data directly from a string.  $string is assumed to
77       be decoded (but not MIME decoded).
78
79   new()
80         # Create a new (empty) address book
81         my $address_book = Text::vCard::Addressbook->new();
82
83         # Load vcards from a single file
84         my $address_book = Text::vCard::Addressbook->new({
85           source_file => '/path/to/address_book.vcf'
86         });
87
88         # Load vcards from a a string
89         my $address_book = Text::vCard::Addressbook->new({
90           source_text => $source_text
91         });
92
93       This method will croak if it is unable to read the source_file.
94
95       The constructor accepts 'encoding_in' and 'encoding_out' attributes.
96       The default values for both are 'UTF-8'.  You can set them to 'none' if
97       you don't want your output encoded with Encode::encode().  But be aware
98       the latest vCard RFC 6350 mandates UTF-8.
99

OTHER METHODS

101   add_vcard()
102         my $vcard = $address_book->add_vcard();
103
104       This method creates a new empty Text::vCard object, stores it in the
105       address book and return it so you can add data to it.
106
107   vcards()
108         my $vcards = $address_book->vcards();
109         my @vcards = $address_book->vcards();
110
111       This method returns a reference to an array or an array of vcards in
112       this address book. This could be an empty list if there are no entries
113       in the address book.
114
115   set_encoding()
116       DEPRECATED.  Use the 'encoding_in' and 'encoding_out' constructor
117       arguments.
118
119   export()
120         my $string = $address_book->export()
121
122       This method returns the vcard data as a string in the vcf file format.
123
124       Please note there is no validation, you must ensure that the correct
125       nodes (FN,N,VERSION) are already added to each vcard if you want to
126       comply with RFC 2426.
127

AUTHOR

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

COPYRIGHT

133       Copyright (c) 2003 Leo Lapworth. All rights reserved.  This program is
134       free software; you can redistribute it and/or modify it under the same
135       terms as Perl itself.
136

ACKNOWLEDGEMENTS

138       The authors of Text::vFile::asData for making my life so much easier.
139