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);
use RDF::TrineShortcuts qw(rdf_query);
my $results = rdf_query($sparql, $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-2011 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.