Text::vFile - Generic module which can read and write "vFile" files such as vCard (RFC 2426) and vCalendar (RFC 2445). The result of loading this data is a collection of objects which will grant you easy access to the properties. Then the module can write your objects back to a data file.
use Text::vFile; my $objects = Text::vCard->load( "foo.vCard", "blort.vCard", "whee.vCard" ); foreach my $card (@$objects) { spam ( $card->email('pref') ); } # OR my $reader = Text::vFile->new( source_file => "foo.vCard" ); while ( my $object = $reader->next ) { spam ( $object ); } # OR my $reader = Text::vFile->new( source_text => $vcard_data ); while ( my $vcard = <$reader> ) { spam ( $vcard ); }
The way this processor works is that it reads the vFile line by line.
1 - BEGIN:(.*) tag
$1 is looked up in classMap; class is loaded; new object of this class is created ie/ $Text::vFile::classMap{'VCARD'}="Text::vCard"; $object=$classMap{'VCARD'}->new; n.b. classMap is a package variable for Text::vFile
2 - All lines are read and stored until a BEGIN tag (goto 1) or END tag (goto 3) is reached
3 - END:(.*) tag
Signals that all entry data has been obtained and now the rows of data are processed
4 - Data is concatenated - thanks to Text::iCal for the strategy; the tag label and data are obtained
5 - The data handler is identified via $object->varHandler->{$label}
There are some generic handlers for common data types such as simple strings, dates, etc. More elaborate data types such as N, ADR, etc. need special treatment and are declared explititly in classes as "load_XXX" such as "load_N"
You should be able to override and extend the processing by taking Text::vFile::Base.pm as your example and adjusting as necessary.
The resulting data structure is a bit bulky - but is such that it can express vFile data completely and reliably
$VAR1 = bless( { 'EMAIL' => [ { 'attr' => { 'email' => [ 'HOME' ], 'type' => [] }, 'sequence' => 1, 'type' => { 'internet' => 1 }, 'value' => 'email\\@domain.com' } ], 'TITLE' => { 'value' => 'Job Title' }, 'X-ICQ' => [ { 'attr' => { 'type' => [ 'WORK', 'pref' ] }, 'sequence' => 11, 'type' => { 'pref' => 1, 'work' => 1 }, 'value' => '12341234' } ], '_lines' => [ 'VERSION:2.1', 'N:Person;Test,Given;;;', 'FN:Test Person', .... ] }, "Text::vCard");
Loads the vFiles found in filenames supplied and returns all found items an array of objects.
Loads the vFiles found in the strings passed in and returns all found items as objects.
Sets this filename to be the source of vfile data. Only one filename, can contain many vfile entries.
Sets this scalar to be the source of vfile data. Can contain many vfile.
Create a new vfile loader. You will need to set its source to either a source_file or source_text. Then use the next method to get each next object.
Gets next object from vfile
Returns true if loader is at end of data for current source.
Called when a line cannot be successfully decoded
For technical support please email to jlawrenc@cpan.org ... for faster service please include "Text::vFile" and "help" in your subject line.
Jay J. Lawrence - jlawrenc@cpan.org Infonium Inc., Canada http://www.infonium.ca/
Copyright (c) 2003 Jay J. Lawrence, Infonium Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
Leo - for a very productive exchange on how this should work plus suffering through a few growing pains. Net::iCal - whose loading code inspired me for mine
RFC 2425, 2426, 2445
To install Text::vFile, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Text::vFile
CPAN shell
perl -MCPAN -e shell install Text::vFile
For more information on module installation, please visit the detailed CPAN module installation guide.