.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "XML::Atom::Microformats 3pm" .TH XML::Atom::Microformats 3pm "2021-09-11" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" XML::Atom::Microformats \- parse microformats in Atom content .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& 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 ); .Ve .SH "DESCRIPTION" .IX Header "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. .PP The general pattern of usage is to create an XML::Atom::Microformats object (which corresponds to an Atom 1.0 feed) using the \&\f(CW\*(C`new_feed\*(C'\fR method; tell it which types of Microformat you expect to find there; then ask for the data, as a Perl hashref, a \s-1JSON\s0 string, or an RDF::Trine model. .SS "Constructor" .IX Subsection "Constructor" .ie n .IP """XML::Atom::Microformats\->new_feed($xml, $base_url)""" 4 .el .IP "\f(CWXML::Atom::Microformats\->new_feed($xml, $base_url)\fR" 4 .IX Item "XML::Atom::Microformats->new_feed($xml, $base_url)" Constructs a feed object. .Sp \&\f(CW$xml\fR is the Atom source (string) or an XML::LibXML::Document. .Sp \&\f(CW$base_url\fR is the feed \s-1URL,\s0 important for resolving relative \s-1URL\s0 references. .SS "Profile Management Methods" .IX Subsection "Profile Management Methods" HTML::Microformats uses \s-1HTML\s0 profiles (i.e. the profile attribute on the \&\s-1HTML\s0 element) to detect which Microformats are used on a page. Any microformats which do not have a profile \s-1URI\s0 declared will not be parsed. .PP XML::Atom::Microformats uses a similar mechanism. Because Atom does not have a element, Atom is used instead: .PP .Vb 1 \& .Ve .PP These links can be used on a per-entry basis, or for the whole feed. .PP 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. .ie n .IP """add_profile(@profiles)""" 4 .el .IP "\f(CWadd_profile(@profiles)\fR" 4 .IX Item "add_profile(@profiles)" Using \f(CW\*(C`add_profile\*(C'\fR you can add one or more profile URIs, and they are treated as if they were found on the document. .Sp For example: .Sp .Vb 1 \& $feed\->add_profile(\*(Aqhttp://microformats.org/profile/rel\-tag\*(Aq) .Ve .Sp This is useful for adding profile URIs declared outside the document itself (e.g. in \s-1HTTP\s0 headers). .ie n .IP """entry_add_profile($entryid, @profiles)""" 4 .el .IP "\f(CWentry_add_profile($entryid, @profiles)\fR" 4 .IX Item "entry_add_profile($entryid, @profiles)" \&\f(CW\*(C`entry_add_profile\*(C'\fR 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 \s-1ID.\s0 .ie n .IP """assume_profile(@microformats)""" 4 .el .IP "\f(CWassume_profile(@microformats)\fR" 4 .IX Item "assume_profile(@microformats)" For example: .Sp .Vb 1 \& $feed\->assume_profile(qw(hCard adr geo)) .Ve .Sp This method acts similarly to \f(CW\*(C`add_profile\*(C'\fR 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. .ie n .IP """entry_assume_profile($entryid, @profiles)""" 4 .el .IP "\f(CWentry_assume_profile($entryid, @profiles)\fR" 4 .IX Item "entry_assume_profile($entryid, @profiles)" \&\f(CW\*(C`entry_assume_profile\*(C'\fR 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 \s-1ID.\s0 .ie n .IP """assume_all_profiles""" 4 .el .IP "\f(CWassume_all_profiles\fR" 4 .IX Item "assume_all_profiles" This method is equivalent to calling \f(CW\*(C`assume_profile\*(C'\fR for all known microformats. .ie n .IP """entry_assume_all_profiles($entryid)""" 4 .el .IP "\f(CWentry_assume_all_profiles($entryid)\fR" 4 .IX Item "entry_assume_all_profiles($entryid)" This method is equivalent to calling \f(CW\*(C`entry_assume_profile\*(C'\fR for all known microformats. .SS "Parsing Methods" .IX Subsection "Parsing Methods" You can probably skip this section. The \f(CW\*(C`data\*(C'\fR, \f(CW\*(C`json\*(C'\fR and \&\f(CW\*(C`model\*(C'\fR methods will automatically do this for you. .ie n .IP """parse_microformats""" 4 .el .IP "\f(CWparse_microformats\fR" 4 .IX Item "parse_microformats" Scans through the feed, finding microformat objects. .Sp On subsequent calls, does nothing (as everything is already parsed). .ie n .IP """clear_microformats""" 4 .el .IP "\f(CWclear_microformats\fR" 4 .IX Item "clear_microformats" Forgets information gleaned by \f(CW\*(C`parse_microformats\*(C'\fR and thus allows \&\f(CW\*(C`parse_microformats\*(C'\fR to be run again. This is useful if you've added some profiles between runs of \f(CW\*(C`parse_microformats\*(C'\fR. .SS "Data Retrieval Methods" .IX Subsection "Data Retrieval Methods" These methods allow you to retrieve the feed's data, and do things with it. .ie n .IP """objects($format)""" 4 .el .IP "\f(CWobjects($format)\fR" 4 .IX Item "objects($format)" \&\f(CW$format\fR is, for example, 'hCard', 'adr' or 'RelTag'. .Sp Returns a list of objects of that type. (If called in scalar context, returns an arrayref.) .Sp Each object is, for example, an HTML::Microformat::hCard object, or an HTML::Microformat::RelTag object, etc. See the relevent documentation for details. .ie n .IP """entry_objects($entryid, $format)""" 4 .el .IP "\f(CWentry_objects($entryid, $format)\fR" 4 .IX Item "entry_objects($entryid, $format)" \&\f(CW\*(C`entry_objects\*(C'\fR is a variant to allow you to fetch data for one specific entry within the feed, if you know that entry's \s-1ID.\s0 .ie n .IP """all_objects""" 4 .el .IP "\f(CWall_objects\fR" 4 .IX Item "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. .Sp Each object is, for example, an HTML::Microformat::hCard object, or an HTML::Microformat::RelTag object, etc. See the relevent documentation for details. .ie n .IP """entry_all_objects($entryid)""" 4 .el .IP "\f(CWentry_all_objects($entryid)\fR" 4 .IX Item "entry_all_objects($entryid)" \&\f(CW\*(C`entry_all_objects\*(C'\fR is a variant to allow you to fetch data for one specific entry within the feed, if you know that entry's \s-1ID.\s0 .ie n .IP """json(%opts)""" 4 .el .IP "\f(CWjson(%opts)\fR" 4 .IX Item "json(%opts)" Returns data roughly equivalent to the \f(CW\*(C`all_objects\*(C'\fR method, but as a \s-1JSON\s0 string. .Sp \&\f(CW%opts\fR is a hash of options, suitable for passing to the \s-1JSON\s0 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. .Sp .Vb 1 \& print $feed\->json( pretty=>1, canonical=>1, utf8=>0 ); .Ve .ie n .IP """entry_json($entryid, %opts)""" 4 .el .IP "\f(CWentry_json($entryid, %opts)\fR" 4 .IX Item "entry_json($entryid, %opts)" \&\f(CW\*(C`entry_json\*(C'\fR is a variant to allow you to fetch data for one specific entry within the feed, if you know that entry's \s-1ID.\s0 .ie n .IP """model(%opts)""" 4 .el .IP "\f(CWmodel(%opts)\fR" 4 .IX Item "model(%opts)" Returns data as an RDF::Trine::Model, suitable for serialising as \&\s-1RDF\s0 or running \s-1SPARQL\s0 queries. Quads are used (rather than triples) which allows you to trace statements to the entries from which they came. .Sp \&\f(CW$opts\fR{'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 \&\f(CW\*(C`entry_model\*(C'\fR method. .Sp If RDF::RDFa::Parser 1.096 or above is installed, then \&\f(CW$opts\fR{'atomowl'} will automatically pull in DataRSS data too. .ie n .IP """entry_model($entryid, %opts)""" 4 .el .IP "\f(CWentry_model($entryid, %opts)\fR" 4 .IX Item "entry_model($entryid, %opts)" \&\f(CW\*(C`entry_model\*(C'\fR is a variant to allow you to fetch data for one specific entry within the feed, if you know that entry's \s-1ID.\s0 .ie n .IP """add_to_model($model, %opts)""" 4 .el .IP "\f(CWadd_to_model($model, %opts)\fR" 4 .IX Item "add_to_model($model, %opts)" Adds data to an existing RDF::Trine::Model. Otherwise, the same as \f(CW\*(C`model\*(C'\fR. .ie n .IP """entry_add_to_model($entry, $model, %opts)""" 4 .el .IP "\f(CWentry_add_to_model($entry, $model, %opts)\fR" 4 .IX Item "entry_add_to_model($entry, $model, %opts)" Adds data to an existing RDF::Trine::Model. Otherwise, the same as \f(CW\*(C`entry_model\*(C'\fR. .SH "BUGS" .IX Header "BUGS" Please report any bugs to . .SH "SEE ALSO" .IX Header "SEE ALSO" HTML::Microformats, XML::Atom::OWL, XML::Atom::FromOWL, RDF::RDFa::Parser. .PP , . .SH "AUTHOR" .IX Header "AUTHOR" Toby Inkster . .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2010\-2012 Toby Inkster .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "DISCLAIMER OF WARRANTIES" .IX Header "DISCLAIMER OF WARRANTIES" \&\s-1THIS PACKAGE IS PROVIDED \*(L"AS IS\*(R" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.\s0