NAME

Data::Microformat::hCard - A module to parse and create hCards

VERSION

This documentation refers to Data::Microformat::hCard version 0.03.

SYNOPSIS

        use Data::Microformat::hCard;

        my $card = Data::Microformat::hCard->parse($a_web_page);

        print "The nickname we found in this hCard was:\n";
        print $card->nickname."\n";

        # To create a new hCard:
        my $new_card = Data::Microformat::hCard->new;
        $new_card->fn("Brendan O'Connor");
        $new_card->nickname("USSJoin");

        my $new_email = Data::Microformat::hCard::type->new;
        $new_email->kind("email");
        $new_email->type("Perl");
        $new_email->value("perl@ussjoin.com");
        $new_card->email($new_email);

        print "Here's the new hCard I've just made:\n";
        print $new_card->to_hcard."\n";

DESCRIPTION

Overview

This module exists both to parse existing hCards from web pages, and to create new hCards so that they can be put onto the Internet.

To use it to parse an existing hCard (or hCards), simply give it the content of the page containing them (there is no need to first eliminate extraneous content, as the module will handle that itself):

        my $card = Data::Microformat::hCard->parse($content);

If you would like to get all the hCards on the webpage, simply ask using an array:

        my @cards = Data::Microformat::hCard->parse($content);
        

The module respects nested hCards using the parsing rules defined in the spec, so if one hCard contains another, it will return one hCard with the other held in the relevant subpart, rather than two top-level hCards.

To create a new hCard, first create the new object:

        my $card = Data::Microformat::hCard->new;
        

Then use the helper methods to add any data you would like. When you're ready to output the hCard, simply write

        my $output = $card->to_hcard;

And $output will be filled with an hCard representation, using <div> tags exclusively with the relevant class names.

If you would like to have the parser determine the representative hCard for a page, simply pass the page's URL as an additional parameter to the parse or from_tree methods, and the appropriate property will be found if it can be determined.

For information on precisely what types of strings are intended for each hCard property, it is recommended to consult the vCARD specification, RFC 2426.

The Helper Methods

Each module in Data::Microformat provides two methods, singular_fields and plural_fields. These methods list the fields on that object that can have exactly one value, or multiple values, respectively. Their documentation also tries to provide some hint as to what the field might be used for.

To set a value in a field, simply write

        $object->field_name($value);

For instance,

        $my_hcard->nickname("Happy");

To get a value, for either singular or plural fields, you may write

        my $value = $object->field_name;

For plural fields, to get all the values, just make the call in array context; for instance,

        my @values = $my_hcard->nickname;
        

A plural value with multiple values set will return just the first one when called in scalar context.

SUBROUTINES/METHODS

Data::Microformat::organization->from_tree($tree [, $source_url])

This method overrides but provides the same functionality as the method of the same name in Data::Microformat, with the optional addition of $source_url. If present, this latter term will trigger a search to find the "representative hCard" for the given page, using the specifications for representative hCard parsing; a card's status of representative or not can be found by calling the is_representative method on it.

$card->is_representative

This method returns 1 if the card is known to be a "representative hCard," and 0 otherwise. Note that for the representative hCard to have been determined, the URL for the source webpage must have been passed to the parse or from_tree method that created the hCard.

class_name

The hCard class name for an hCard; to wit, "vcard."

singular_fields

This is a method to list all the fields on an hCard that can hold exactly one value.

They are as follows:

bday

The birthday of the hCard.

class

The class of the hCard, such as "public" or "private."

fn

The familiar name of the hCard.

geo

The geolocation of the hCard, which should be a Data::Microformat::geo object.

n

The name of the hCard, which should be a Data::Microformat::hCard::name object.

sort_string

The sorting string of the hCard.

uid

The globally unique identifier for the hCard.

tz

The time zone for the hCard.

plural_fields

This is a method to list all the fields on an hCard that can hold multiple values.

They are as follows:

adr

The address of the hCard.

agent

The agent, which can be either a string or an hCard itself.

category

The category of the hCard.

email

The cemail attached to the hCard, which should be a Data::Microformat::hCard::type object.

key

The key (especially, the encryption key) of the hCard.

label

The label of the hCard.

logo

The logo of the hCard; usually a URI for the logo.

mailer

The mailer for the hCard.

nickname

The nickname for the hCard.

note

The note for the hCard.

org

The organization for the hCard, which should be a Data::Microformat::hCard::organization object.

photo

The photo of the hCard; usually a URI for the photo.

rev

The revision of the hCard.

role

The role of the hCard.

sound

The sound of the hCard; usually a URI for the sound.

tel

The telephone number of the hCard, which should be a Data::Microformat::hCard::type object.

title

The title of the hCard.

url

The URL for the hCard.

DEPENDENCIES

This module relies upon the following other modules:

Data::Microformat::adr

Data::Microformat::geo

They are distributed in the same distribution as this module.

BUGS

Please report any bugs or feature requests to bug-data-microformat at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Data-Microformat. I will be notified,and then you'll automatically be notified of progress on your bug as I make changes.

AUTHOR

Brendan O'Connor, <perl at ussjoin.com>

COPYRIGHT

Copyright 2008, Six Apart Ltd. All rights reserved.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

cpanm Data::Microformat

perl -MCPAN -e shell
install Data::Microformat