--- name: "XML::Atom::Microformats" section: "3pm" platform: "linux" package: "libxml-atom-microformats-perl" version: "0.004-4" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/XML::Atom::Microformats" --- # XML::Atom::Microformats(3pm) parse microformats in Atom content ## 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 \ elements (note: not \) 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 \ 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 \ element, Atom \ is used instead: ``` ``` 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 \. ## SEE ALSO HTML::Microformats, XML::Atom::OWL, XML::Atom::FromOWL, RDF::RDFa::Parser. \, \. ## AUTHOR Toby Inkster \. ## 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.