Toby Inkster > XML-Atom-Microformats-0.004 > XML::Atom::Microformats

Download:
XML-Atom-Microformats-0.004.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.004   Source  

NAME ^

XML::Atom::Microformats - parse microformats in Atom content

SYNOPSIS ^

 use XML::Atom::Microformats;
 
 my $feed = XML::Atom::Microformats
    -> new_feed( $xml, $base_uri )
    -> assume_profile( qw(hCard hCalendar) );
 print $feed->json(pretty => 1);
 
 my $results = RDF::Query
    -> new( $sparql )
    -> execute( $feed->model );

DESCRIPTION ^

The XML::Atom::Microformats module brings the functionality of HTML::Microformats to Atom 1.0 Syndication feeds. It finds microformats embedded in the <content> elements (note: not <summary>) of Atom entries.

The general pattern of usage is to create an XML::Atom::Microformats object (which corresponds to an Atom 1.0 feed) using the new_feed method; tell it which types of Microformat you expect to find there; then ask for the data, as a Perl hashref, a JSON string, or an RDF::Trine model.

Constructor

XML::Atom::Microformats->new_feed($xml, $base_url)

Constructs a feed object.

$xml is the Atom source (string) or an XML::LibXML::Document.

$base_url is the feed URL, important for resolving relative URL references.

Profile Management Methods

HTML::Microformats uses HTML profiles (i.e. the profile attribute on the HTML <head> element) to detect which Microformats are used on a page. Any microformats which do not have a profile URI declared will not be parsed.

XML::Atom::Microformats uses a similar mechanism. Because Atom does not have a <head> element, Atom <link> is used instead:

  <link rel="profile" href="http://ufs.cc/x/hcalendar" />

These links can be used on a per-entry basis, or for the whole feed.

Because many feeds fail to properly declare which profiles they use, there are various profile management methods to tell XML::Atom::Microformats to assume the presence of particular profile URIs, even if they're actually missing.

add_profile(@profiles)

Using add_profile you can add one or more profile URIs, and they are treated as if they were found on the document.

For example:

 $feed->add_profile('http://microformats.org/profile/rel-tag')

This is useful for adding profile URIs declared outside the document itself (e.g. in HTTP headers).

entry_add_profile($entryid, @profiles)

entry_add_profile is a variant to allow you to add a profile which applies only to one specific entry within the feed, if you know that entry's ID.

assume_profile(@microformats)

For example:

 $feed->assume_profile(qw(hCard adr geo))

This method acts similarly to add_profile but allows you to use names of microformats rather than URIs. Microformat names are case sensitive, and must match HTML::Microformats::Format::Foo module names.

entry_assume_profile($entryid, @profiles)

entry_assume_profile is a variant to allow you to add a profile which applies only to one specific entry within the feed, if you know that entry's ID.

assume_all_profiles

This method is equivalent to calling assume_profile for all known microformats.

entry_assume_all_profiles($entryid)

This method is equivalent to calling entry_assume_profile for all known microformats.

Parsing Methods

You can probably skip this section. The data, json and model methods will automatically do this for you.

parse_microformats

Scans through the feed, finding microformat objects.

On subsequent calls, does nothing (as everything is already parsed).

clear_microformats

Forgets information gleaned by parse_microformats and thus allows parse_microformats to be run again. This is useful if you've added some profiles between runs of parse_microformats.

Data Retrieval Methods

These methods allow you to retrieve the feed's data, and do things with it.

objects($format)

$format is, for example, 'hCard', 'adr' or 'RelTag'.

Returns a list of objects of that type. (If called in scalar context, returns an arrayref.)

Each object is, for example, an HTML::Microformat::hCard object, or an HTML::Microformat::RelTag object, etc. See the relevent documentation for details.

entry_objects($entryid, $format)

entry_objects is a variant to allow you to fetch data for one specific entry within the feed, if you know that entry's ID.

all_objects

Returns a hashref of data. Each hashref key is the name of a microformat (e.g. 'hCard', 'RelTag', etc), and the values are arrayrefs of objects.

Each object is, for example, an HTML::Microformat::hCard object, or an HTML::Microformat::RelTag object, etc. See the relevent documentation for details.

entry_all_objects($entryid)

entry_all_objects is a variant to allow you to fetch data for one specific entry within the feed, if you know that entry's ID.

json(%opts)

Returns data roughly equivalent to the all_objects method, but as a JSON string.

%opts is a hash of options, suitable for passing to the JSON module's to_json function. The 'convert_blessed' and 'utf8' options are enabled by default, but can be disabled by explicitly setting them to 0, e.g.

  print $feed->json( pretty=>1, canonical=>1, utf8=>0 );
entry_json($entryid, %opts)

entry_json is a variant to allow you to fetch data for one specific entry within the feed, if you know that entry's ID.

model(%opts)

Returns data as an RDF::Trine::Model, suitable for serialising as RDF or running SPARQL queries. Quads are used (rather than triples) which allows you to trace statements to the entries from which they came.

$opts{'atomowl'} is a boolean indicating whether or not to include data from XML::Atom::OWL in the returned model. If enabled, this always includes AtomOWL data for the whole feed (not just for a specific entry), even if you use the entry_model method.

If RDF::RDFa::Parser 1.096 or above is installed, then $opts{'atomowl'} will automatically pull in DataRSS data too.

entry_model($entryid, %opts)

entry_model is a variant to allow you to fetch data for one specific entry within the feed, if you know that entry's ID.

add_to_model($model, %opts)

Adds data to an existing RDF::Trine::Model. Otherwise, the same as model.

entry_add_to_model($entry, $model, %opts)

Adds data to an existing RDF::Trine::Model. Otherwise, the same as entry_model.

BUGS ^

Please report any bugs to http://rt.cpan.org/.

SEE ALSO ^

HTML::Microformats, XML::Atom::OWL, XML::Atom::FromOWL, RDF::RDFa::Parser.

http://microformats.org/, http://www.perlrdf.org/.

AUTHOR ^

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT ^

Copyright 2010-2012 Toby Inkster

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

DISCLAIMER OF WARRANTIES ^

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

syntax highlighting: