gitpan / data-microformat Goto Github PK

Data-Microformat

SYNOPSIS

Overview

This module handles four existing specifications from Microformats.org:

* hCard - http://microformats.org/wiki/hcard
* adr   - http://microformats.org/wiki/adr
* geo   - http://microformats.org/wiki/geo
* hFeed - http://microformats.org/wiki/hatom

Each of them can be used on their own (hCard uses adr and geo to parse
addresses and geolocations, but adr and geo have no dependencies on any others,
and hCard doesn't need either unless the corresponding elements appear in an
hCard), though the primary appearance of adr and geo "in the wild" is as
subparts of hCards.

This module exists both to parse existing microformats from webpages, and
create new HTML representations of microformats.

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'd like instead to get a plain
text representation, write

	my $text = $card->to_text;

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 set 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.

INSTALLATION

To install this module, run the following commands:

	perl Makefile.PL
	make
	make test
	make install

SUPPORT AND DOCUMENTATION

After installing, you can find documentation for this module with the
perldoc command.

    perldoc Data::Microformat

You can also look for information at:

    RT, CPAN's request tracker
        http://rt.cpan.org/NoAuth/Bugs.html?Dist=Data-Microformat

    AnnoCPAN, Annotated CPAN documentation
        http://annocpan.org/dist/Data-Microformat

    CPAN Ratings
        http://cpanratings.perl.org/d/Data-Microformat

    Search CPAN
        http://search.cpan.org/dist/Data-Microformat


AUTHOR

Brendan O'Connor <perl -at- ussjoin -dot- com>

COPYRIGHT AND LICENSE

Copyright (C) 2008 Six Apart Ltd. All rights reserved.

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