XML::A...formats(3pm)

💖 XML::Atom::Microformats(3pm) 💖

okay bestie, so this is the user-contributed Perl documentation for XML::Atom::Microformats, and it's literally the moment microformats get to hang out inside Atom feeds. let's go 🦋

---

✨ 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 whole functionality of HTML::Microformats over to Atom 1.0 Syndication feeds. it finds microformats embedded in the <content> elements (note: not <summary>, bestie, we do not look there) of Atom entries 👀

the general pattern of usage is:

1. make an XML::Atom::Microformats object (which corresponds to an Atom 1.0 feed) using the new_feed method;
2. tell it which types of Microformat you expect to find in there;
3. ask for the data — as a Perl hashref, a JSON string, or an RDF::Trine model. slay. 🎀

---

🧚 Constructor

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

Constructs a feed object. iconic behavior tbh.

• $xml is the Atom source (a string) or an XML::LibXML::Document.
• $base_url is the feed URL, and it's important for resolving relative URL references. don't skip it, fr fr.

---

🌸 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. no profile, no vibes. 🙈

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. we're just gonna believe in them. main character energy ✨

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). iykyk.

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. 💀 so mind your capitalization.

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. go big or go home 🫶

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. consider this the backstage pass, not the main event. ✨

parse_microformats

Scans through the feed, finding microformat objects.

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

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. a little reset, a little refresh 🌈

---

💜 Data Retrieval Methods

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

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. so you always know where a vibe came from 🔥

$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. noted. no cap.

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/>. bestie, they wanna hear it. 🫶

---

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

like, zero promises. gorgeous of it honestly 💅

---

and that's a wrap, bestie 🦋 this was XML::Atom::Microformats — part of the User Contributed Perl Documentation, version perl v5.32.1, dated 2021-09-11. mwah. 💖✨🎀