| 1 |
NAME |
| 2 |
HTML::HTML5::Microdata::Parser - fairly experimental parser for HTML |
| 3 |
'microdata' |
| 4 |
|
| 5 |
SYNOPSIS |
| 6 |
use HTML::HTML5::Microdata::Parser; |
| 7 |
|
| 8 |
my $parser = HTML::HTML5::Microdata::Parser->new($html, $baseURI); |
| 9 |
my $graph = $parser->graph; |
| 10 |
|
| 11 |
DESCRIPTION |
| 12 |
This package aims to have a roughly compatible API to RDF::RDFa::Parser. |
| 13 |
|
| 14 |
Microdata is an experimental metadata format, not in wide use. Use this |
| 15 |
module at your own risk. |
| 16 |
|
| 17 |
$p = HTML::HTML5::Microdata::Parser->new($html, $baseuri, \%options, |
| 18 |
$storage) |
| 19 |
This method creates a new HTML::HTML5::Microdata::Parser object |
| 20 |
and returns it. |
| 21 |
|
| 22 |
The $xhtml variable may contain an XHTML/XML string, or a |
| 23 |
XML::LibXML::Document. If a string, the document is parsed using |
| 24 |
HTML::HTML5::Parser and HTML::HTML5::Sanity, which may throw an |
| 25 |
exception. HTML::HTML5::Microdata::Parser does not catch the |
| 26 |
exception. |
| 27 |
|
| 28 |
The base URI is used to resolve relative URIs found in the |
| 29 |
document. |
| 30 |
|
| 31 |
Options [default in brackets]: |
| 32 |
|
| 33 |
* alt_stylesheet - Magic rel="alternate stylesheet". [1] |
| 34 |
* auto_config - See section "Auto Config" [0] |
| 35 |
* mhe_lang - Process <meta http-equiv=Content-Language>. |
| 36 |
[1] |
| 37 |
* prefix_empty - URI prefix for itemprops of untyped items. |
| 38 |
[undef] |
| 39 |
* strategy - URI generation strategy for itemprops of |
| 40 |
typed items. [HTML::HTML5::Microdata:: |
| 41 |
Strategy::Heuristic] |
| 42 |
* tdb_service - thing-described-by.org when possible. [0] |
| 43 |
* xhtml_base - Process <base href> element. [1] |
| 44 |
* xhtml_lang - Process @lang. [1] |
| 45 |
* xhtml_meta - Process <meta>. [0] |
| 46 |
* xhtml_cite - Process @cite. [0] |
| 47 |
* xhtml_rel - Process @rel. [0] |
| 48 |
* xhtml_time - Process <time> element more nicely. [0] |
| 49 |
* xhtml_title - Process <title> element. [0] |
| 50 |
* xml_lang - Process @xml:lang. [1] |
| 51 |
|
| 52 |
$storage is an RDF::Trine::Storage object. If undef, then a new |
| 53 |
temporary store is created. |
| 54 |
|
| 55 |
$p->xhtml |
| 56 |
Returns the HTML source of the document being parsed. |
| 57 |
|
| 58 |
$p->uri Returns the base URI of the document being parsed. This will |
| 59 |
usually be the same as the base URI provided to the constructor, |
| 60 |
but may differ if the document contains a <base> HTML element. |
| 61 |
|
| 62 |
Optionally it may be passed a parameter - an absolute or |
| 63 |
relative URI - in which case it returns the same URI which it |
| 64 |
was passed as a parameter, but as an absolute URI, resolved |
| 65 |
relative to the document's base URI. |
| 66 |
|
| 67 |
This seems like two unrelated functions, but if you consider the |
| 68 |
consequence of passing a relative URI consisting of a |
| 69 |
zero-length string, it in fact makes sense. |
| 70 |
|
| 71 |
$p->dom Returns the parsed XML::LibXML::Document. |
| 72 |
|
| 73 |
$p->set_callbacks(\%callbacks) |
| 74 |
Set callback functions for the parser to call on certain events. |
| 75 |
These are only necessary if you want to do something especially |
| 76 |
unusual. |
| 77 |
|
| 78 |
$p->set_callbacks({ |
| 79 |
'pretriple_resource' => sub { ... } , |
| 80 |
'pretriple_literal' => sub { ... } , |
| 81 |
'ontriple' => undef , |
| 82 |
}); |
| 83 |
|
| 84 |
Either of the two pretriple callbacks can be set to the string |
| 85 |
'print' instead of a coderef. This enables built-in callbacks |
| 86 |
for printing Turtle to STDOUT. |
| 87 |
|
| 88 |
For details of the callback functions, see the section |
| 89 |
CALLBACKS. "set_callbacks" must be used *before* "consume". |
| 90 |
"set_callbacks" itself returns a reference to the parser object |
| 91 |
itself. |
| 92 |
|
| 93 |
$p->consume |
| 94 |
The document is parsed for Microdata. Nothing of interest is |
| 95 |
returned by this function, but the triples extracted from the |
| 96 |
document are passed to the callbacks as each one is found. |
| 97 |
|
| 98 |
The "graph" method automatically calls "consume", so normally |
| 99 |
you don't need to call it manually. If you're using callback |
| 100 |
functions, it may be useful though. |
| 101 |
|
| 102 |
$p->consume_microdata_item($element) |
| 103 |
You almost certainly do not want to use this method. |
| 104 |
|
| 105 |
It will consume a single Microdata item, assuming that $element |
| 106 |
is an element that does or should have the @itemscope attribute |
| 107 |
set. Returns the URI or blank node identifier for the item. |
| 108 |
|
| 109 |
This method is exposed mostly for the benefit of |
| 110 |
HTML::HTML5::Microdata::ToRDFa. |
| 111 |
|
| 112 |
$p->graph() |
| 113 |
This method will return an RDF::Trine::Model object with all |
| 114 |
statements of the full graph. |
| 115 |
|
| 116 |
$p->graphs() |
| 117 |
Provided for RDF::RDFa::Parser compatibility. |
| 118 |
|
| 119 |
CALLBACKS |
| 120 |
Several callback functions are provided. These may be set using the |
| 121 |
"set_callbacks" function, which taskes a hashref of keys pointing to |
| 122 |
coderefs. The keys are named for the event to fire the callback on. |
| 123 |
|
| 124 |
pretriple_resource |
| 125 |
This is called when a triple has been found, but before preparing the |
| 126 |
triple for adding to the model. It is only called for triples with a |
| 127 |
non-literal object value. |
| 128 |
|
| 129 |
The parameters passed to the callback function are: |
| 130 |
|
| 131 |
* A reference to the "HTML::HTML5::Microdata::Parser" object |
| 132 |
|
| 133 |
* A reference to the "XML::LibXML::Element" being parsed |
| 134 |
|
| 135 |
* Subject URI or bnode (string) |
| 136 |
|
| 137 |
* Predicate URI (string) |
| 138 |
|
| 139 |
* Object URI or bnode (string) |
| 140 |
|
| 141 |
The callback should return 1 to tell the parser to skip this triple (not |
| 142 |
add it to the graph); return 0 otherwise. |
| 143 |
|
| 144 |
pretriple_literal |
| 145 |
This is the equivalent of pretriple_resource, but is only called for |
| 146 |
triples with a literal object value. |
| 147 |
|
| 148 |
The parameters passed to the callback function are: |
| 149 |
|
| 150 |
* A reference to the "HTML::HTML5::Microdata::Parser" object |
| 151 |
|
| 152 |
* A reference to the "XML::LibXML::Element" being parsed |
| 153 |
|
| 154 |
* Subject URI or bnode (string) |
| 155 |
|
| 156 |
* Predicate URI (string) |
| 157 |
|
| 158 |
* Object literal (string) |
| 159 |
|
| 160 |
* Datatype URI (string or undef) |
| 161 |
|
| 162 |
* Language (string or undef) |
| 163 |
|
| 164 |
Beware: sometimes both a datatype *and* a language will be passed. This |
| 165 |
goes beyond the normal RDF data model.) |
| 166 |
|
| 167 |
The callback should return 1 to tell the parser to skip this triple (not |
| 168 |
add it to the graph); return 0 otherwise. |
| 169 |
|
| 170 |
ontriple |
| 171 |
This is called once a triple is ready to be added to the graph. (After |
| 172 |
the pretriple callbacks.) The parameters passed to the callback function |
| 173 |
are: |
| 174 |
|
| 175 |
* A reference to the "HTML::HTML5::Microdata::Parser" object |
| 176 |
|
| 177 |
* A reference to the "XML::LibXML::Element" being parsed |
| 178 |
|
| 179 |
* An RDF::Trine::Statement object. |
| 180 |
|
| 181 |
The callback should return 1 to tell the parser to skip this triple (not |
| 182 |
add it to the graph); return 0 otherwise. The callback may modify the |
| 183 |
RDF::Trine::Statement object. |
| 184 |
|
| 185 |
ITEMPROP URI GENERATION STRATEGY |
| 186 |
The "itemprop" attribute does not need to be a full URI. |
| 187 |
|
| 188 |
<div itemscope itemtype="http://example.com/Person"> |
| 189 |
<span itemprop="phoneNumber">01234 567 890</span> |
| 190 |
</div> |
| 191 |
|
| 192 |
The "strategy" option passed to the constructor tells the parser how to |
| 193 |
convert "phoneNumber" in the above example into a URI. This can be a |
| 194 |
callback function, or an object or class that provides a "generate_uri" |
| 195 |
method. |
| 196 |
|
| 197 |
Three strategies are bundled with this distribution: |
| 198 |
|
| 199 |
* HTML::HTML5::Microdata::Strategy::Basic - don't attempt to convert |
| 200 |
to a URI |
| 201 |
|
| 202 |
* HTML::HTML5::Microdata::Strategy::Heuristic - smart strategy, the |
| 203 |
default |
| 204 |
|
| 205 |
* HTML::HTML5::Microdata::Strategy::Microdata0 - official strategy of |
| 206 |
early Microdata drafts |
| 207 |
|
| 208 |
AUTO CONFIG |
| 209 |
HTML::HTML5::Microdata::Parser has a lot of different options that can |
| 210 |
be switched on and off. Sometimes it might be useful to allow the page |
| 211 |
being parsed to control some of the options. If you switch on the |
| 212 |
'auto_config' option, pages can do this. |
| 213 |
|
| 214 |
A page can set options using a specially crafted <meta> tag: |
| 215 |
|
| 216 |
<meta name="http://search.cpan.org/dist/HTML-HTML5-Microdata-Parser/#auto_config" |
| 217 |
content="alt_stylesheet=0&prefix_empty=http://example.net/" /> |
| 218 |
|
| 219 |
Note that the "content" attribute is an |
| 220 |
application/x-www-form-urlencoded string (which must then be |
| 221 |
HTML-escaped of course). Semicolons may be used instead of ampersands, |
| 222 |
as these tend to look nicer: |
| 223 |
|
| 224 |
<meta name="http://search.cpan.org/dist/HTML-HTML5-Microdata-Parser/#auto_config" |
| 225 |
content="alt_stylesheet=0;prefix_empty=http://example.net/" /> |
| 226 |
|
| 227 |
Any option allowed in the constructor may be given using auto config, |
| 228 |
except 'auto_config' itself. |
| 229 |
|
| 230 |
SEE ALSO |
| 231 |
XML::LibXML, RDF::Trine, RDF::RDFa::Parser, HTML::HTML5::Parser, |
| 232 |
HTML::HTML5::Sanity. |
| 233 |
|
| 234 |
<http://www.perlrdf.org/>. |
| 235 |
|
| 236 |
AUTHOR |
| 237 |
Toby Inkster <[email protected]>. |
| 238 |
|
| 239 |
COPYRIGHT AND LICENCE |
| 240 |
Copyright (C) 2009-2011 by Toby Inkster |
| 241 |
|
| 242 |
This library is free software; you can redistribute it and/or modify it |
| 243 |
under the same terms as Perl itself. |
| 244 |
|
| 245 |
DISCLAIMER OF WARRANTIES |
| 246 |
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED |
| 247 |
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF |
| 248 |
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. |
| 249 |
|