/ 
XML-FOAFKnows-FromvCard-0.6
River stage zero No dependents
/ XML::FOAFKnows::FromvCard

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;

The foafvcard script in the distribution is also a good and more elaborate usage example.

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.

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, attribute => 'CLASS', privacy => 'PRIVATE|PUBLIC') )>

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.

privacy and attribute are privacy options, and they can optionally be set to indicate what level of details should be included in the output. See the discussion in "Privacy Settings" for further details.

You should ensure that the data passed is UTF-8, and has the UTF-8 flag set, as invalid RDF nodeIDs may result if you don't.

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.

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.

Privacy Settings

By default, this module is conservative in what it outputs. FOAF is a very powerful and will give us many interesting applications when we compile data about people. However, people may also feel that their privacy is compromised by having even their name so readily available. You will have to be concerned about the privacy of your friends.

vCards commonly contain an attribute that indicate a privacy level of the vCard. The name of this attribute can be set using the attribute parameter to format and defaults to CLASS.

If this attribute contains a "CONFIDENTIAL" value, this module 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.

You may also set a privacy parameter to format. If set, it will override the above attribute for all vCards in the input. It may be set to PRIVATE or PUBLIC. In the first case, it will make sure only the above minimal information is included, in the latter, it will include many more properties (not defined, as it may change).

If neither the privacy attribute can be found, nor the privacy parameter, it will default to PRIVATE.

Finally, note that even though we are hashing the e-mail addresses, they are not impossible to crack. It is, for many purposes, not infeasible to recover the plaintext e-mail addresses by a dictionary attack, i.e. combine common ISP domains with common names, and compare them with the hash. Hashing is therefore not a 100% guarantee that your friend's cleartext addresses will remain a secret if a determined attacker seeks them.

BUGS/TODO

This is presently a beta release. It should do most things OK, but it has only been tested on vCards from three different sources.

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. One may also report bugs at https://rt.cpan.org/NoAuth/Bugs.html?Dist=XML-FOAFKnows-FromvCard

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.