Debian Codegraph @

README

raw
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&amp;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