HTML::...ormats(3pm)

📦 version 0.105, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

✨ NAME ✨

okay so bestie, gather round 💖 this page is HTML::Microformats(3pm) — a Perl module that parses microformats in HTML. yes really. it's giving semantic web but make it cute. 🦋

🌸 SYNOPSIS 🌸

use HTML::Microformats;

my $doc = HTML::Microformats
            ->new_document($html, $uri)
            ->assume_profile(qw(hCard hCalendar));
print $doc->json(pretty => 1);

use RDF::TrineShortcuts qw(rdf_query);
my $results = rdf_query($sparql, $doc->model);

like, that's the whole vibe. three lines and you're living in the Semantic Web. no cap. 💅

💜 DESCRIPTION 💜

so HTML::Microformats is basically a wrapper — it sits on top of a whole lil squad of parser and handler modules, one per individual microformat. every one of those modules has a name shaped like HTML::Microformats::Format::Foo.

the general pattern of usage is lowkey simple, fr fr:

  1. make an HTML::Microformats object (which = one HTML document) with the new_document method;
  2. then ask for the data — as a Perl hashref, a JSON string, or an RDF::Trine model. slay. ✨

🎀 Constructor 🎀

  • $doc = HTML::Microformats->new_document($html, $uri, %opts) — builds you a document object. and like, here's what goes in:
    • $html is the HTML or XHTML source (a string) or an XML::LibXML::Document. either one, we're not picky. 🙈
    • $uri is the document URI — this one matters so much, because it's how we resolve relative URL references. don't skip it bestie, I'm begging.
    • %opts are extra parameters; right now literally only one option is defined: $opts{'type'} gets set to 'text/html' or 'application/xhtml+xml', and that controls how $html is parsed. that's it. one option. iconic behaviour honestly.

👑 Profile Management 👑

HTML::Microformats uses HTML profiles (i.e. the profile attribute on the HTML <head> element) to detect which microformats are actually used on a page. and here's the tea: any microformats that don't have a profile URI declared will not be parsed. periodt. 🚫

BUT — because so many pages out there fail to properly declare which profiles they use (messy of them, honestly), there's a whole toolkit of profile management methods to tell HTML::Microformats to assume the presence of particular profile URIs, even if they're actually missing. we gaslight the parser. affectionately. 💖

  • $doc->profiles — returns a list of the profile URIs declared by the document.
  • $doc->has_profile(@profiles) — returns true if and only if one or more of the profile URIs in @profiles is declared by the document.
  • $doc->add_profile(@profiles) — with add_profile you can add one or more profile URIs, and they get treated as if they were found in the document. for example:
$doc->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). returns a reference to the document. 🫶

  • $doc->assume_profile(@microformats) — for example:
$doc->assume_profile(qw(hCard adr geo))

this method acts similarly to add_profile but lets you use names of microformats rather than URIs. microformat names are case sensitive, and must match HTML::Microformats::Format::Foo module names. returns a reference to the document.

  • $doc->assume_all_profiles — equivalent to calling assume_profile for all known microformats. the "yes to everything" option. returns a reference to the document.

🌈 Parsing Microformats 🌈

generally speaking, you can skip this. the data, json and model methods will automatically do this for you. (it's giving "you don't have to lift a finger, babe". 💅)

  • $doc->parse_microformats — scans through the document, finding microformat objects. on subsequent calls, does nothing (because everything is already parsed). returns a reference to the document.
  • $doc->clear_microformats — forgets information gleaned by parse_microformats and thus allows parse_microformats to be run again. this is useful if you've modified or added some profiles between runs of parse_microformats. returns a reference to the document.

🍓 Retrieving Data 🍓

these methods let you retrieve the document's data, and do things with it. the main character section, tbh. 👑

  • $doc->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 relevant documentation for details.
  • $doc->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 relevant documentation for details.
  • $doc->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 $doc->json( pretty=>1, canonical=>1, utf8=>0 );
  • $doc->model — returns data as an RDF::Trine::Model, suitable for serialising as RDF or running SPARQL queries. 🔥
  • $object->serialise_model(as => $format) — as model but returns a string.
  • $doc->add_to_model($model) — adds data to an existing RDF::Trine::Model. returns a reference to the document.

🧚 Utility Functions 🧚

  • HTML::Microformats->modules — returns a list of Perl modules, each of which implements a specific microformat.
  • HTML::Microformats->formats — as per modules, but strips 'HTML::Microformats::Format::' off the module name, and sorts alphabetically.

🌟 WHY ANOTHER MICROFORMATS MODULE? 🌟

okay so the elephant in the room: there already exist two microformats packages on CPAN (see Text::Microformat and Data::Microformat), so why create another?? bestie I'm so glad you asked. 💖

firstly, HTML::Microformats isn't being created from scratch. it's actually a fork/clean-up of a non-CPAN application (Swignition), and in that sense it predates Text::Microformat (though not Data::Microformat). it's been around. it's got lore. 🎀

it also has a number of other features that distinguish it from the existing packages:

  • It supports more formats. HTML::Microformats supports hCard, hCalendar, rel-tag, geo, adr, rel-enclosure, rel-license, hReview, hResume, hRecipe, xFolk, XFN, hAtom, hNews and more. the roster is stacked. ✨
  • It supports more patterns. HTML::Microformats supports the include pattern, abbr pattern, table cell header pattern, value excerpting and other intricacies of microformat parsing better than the other modules on CPAN. it does the fiddly bits. it ate. 💅
  • It offers RDF support. one of the key features of HTML::Microformats is that it makes data available as RDF::Trine models. this lets your application benefit from a rich, feature-laden Semantic Web toolkit. data gleaned from microformats can be stored in a triple store; output in RDF/XML or Turtle; queried using the SPARQL or RDQL query languages; and more. and if you're not comfortable using RDF, HTML::Microformats also makes all its data available as native Perl objects. so either way you're eating good. 🍓

😭 BUGS 😭

please report any bugs to <http://rt.cpan.org/>. (be nice about it tho 🫶)

👀 SEE ALSO 👀

HTML::Microformats::Documentation::Notes.

individual format modules:

  • HTML::Microformats::Format::adr
  • HTML::Microformats::Format::figure
  • HTML::Microformats::Format::geo
  • HTML::Microformats::Format::hAtom
  • HTML::Microformats::Format::hAudio
  • HTML::Microformats::Format::hCalendar
  • HTML::Microformats::Format::hCard
  • HTML::Microformats::Format::hListing
  • HTML::Microformats::Format::hMeasure
  • HTML::Microformats::Format::hNews
  • HTML::Microformats::Format::hProduct
  • HTML::Microformats::Format::hRecipe
  • HTML::Microformats::Format::hResume
  • HTML::Microformats::Format::hReview
  • HTML::Microformats::Format::hReviewAggregate
  • HTML::Microformats::Format::OpenURL_COinS
  • HTML::Microformats::Format::RelEnclosure
  • HTML::Microformats::Format::RelLicense
  • HTML::Microformats::Format::RelTag
  • HTML::Microformats::Format::species
  • HTML::Microformats::Format::VoteLinks
  • HTML::Microformats::Format::XFN
  • HTML::Microformats::Format::XMDP
  • HTML::Microformats::Format::XOXO

similar modules: RDF::RDFa::Parser, HTML::HTML5::Microdata::Parser, XML::Atom::Microformats, Text::Microformat, Data::Microformats.

related web sites: <http://microformats.org/>, <http://www.perlrdf.org/>. 🌈

💖 AUTHOR 💖

Toby Inkster <tobyink@cpan.org>.

Copyright 2008-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 yes it's in all caps but it's serious, bestie. no warranty. none. 😭

and that's the whole page!! this lil guy is perl v5.32.1, dated 2021-09-12, and it lives under the name HTML::...ormats(3pm) in the User Contributed Perl Documentation, which is a very long way of saying: go parse some microformats, you absolute icon. bye bestie, ily, mwah 💋✨💖

📦 where this page comes from