NAME

XML::FOAFKnows::FromvCard - Perl module to create simple foaf:knows records from vCards

SYNOPSIS

use XML::FOAFKnows::FromvCard;
# read a vCard file into $data
my $formatter = XML::FOAFKnows::FromvCard->format($data);
print $formatter->fragment;

DESCRIPTION

This module takes a vCard string parses it using Text::vCard and attempts to make foaf:knows records from it. It's scope is limited to that, it is not intended to be a full vCard to RDF conversion module, it just wants to make reasonable knows records of your contacts.

It is also conservative in what it outputs. If a vCard contains a "CONFIDENTIAL" class, it will write nothing, and unless a there is a "PUBLIC" class, it will only output the SHA1-hashed mailbox, a nick if it exists and a homepage if it exists. A discussion of these issues will appear in this module later.

METHODS

This module conforms with the Formatter API specification, version 0.95. It is not in the Formatter namespace, however, because it doesn't what Formatters generally do, namely reformat all data from one format to another. Since it does conform, it can be used in most of the same contexts as a formatter.

format($string, [(seeAlso = $seeAlsoUri, uri => $myUri, email => $myEmail) )>

The format function that you call to initialise the converter. It takes the plain text as a string argument and returns an object of this class. In the present implementation, it does pretty much all the parsing and building of the output, so this is the only really expensive call of this module.

In addition to the string, it can take a hash containing seeAlso, uri and email keys. If you want to build a full document, you might want to specify seeAlso to an URL to the rest of your FOAF and you should specify one of uri or email to identify you as a person. The former should be your canonical URI, the latter the email address you want to use to identify yourself.

document([$charset])

This will return a full RDF document. The FOAF knows records will be wrapped in a Person element, which has to represent you somehow, see above.

fragment

This will return the FOAF knows records.

links

Will return all links found the input plain text string as an arrayref. The arrayref will for each element contain keys url and title, the former containing the URL, the latter the full name of the person if it exists.

title

Is meaningless for vCards, so will return undef.

BUGS/TODO

This is presently an alpha release. It should do most things OK, but it is only tested on my own KAddressbook files, and works there. On other files, it may not produce good results, in fact, it may even croak on data it doesn't understand.

Also, it is problematic to produce a full FOAF document, since the vCard has no concept at all of who knows all these folks. I have tried to approach this by allowing the URI of the person to be entered, but I don't know if this is workable.

Feedback is very much appreciated.

SEE ALSO

Text::vCard, Formatter, http://www.foaf-project.org/

SUBVERSION REPOSITORY

This module is currently maintained in a Subversion repository. The trunk can be checked out anonymously using e.g.:

svn checkout http://svn.kjernsmo.net/XML-FOAFKnows-FromvCard/trunk/ FOAFKnows

AUTHOR

Kjetil Kjernsmo, <kjetilk@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2005 by Kjetil Kjernsmo

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.