Debian Codegraph @

README

raw
1 NAME
2 RDF::RDFa::Parser - flexible RDFa parser
3
4 SYNOPSIS
5 If you're wanting to work with an RDF::Trine::Model that can be queried
6 with SPARQL, etc:
7
8 use RDF::RDFa::Parser;
9 my $url = 'http://example.com/document.html';
10 my $options = RDF::RDFa::Parser::Config->new('xhtml', '1.1');
11 my $rdfa = RDF::RDFa::Parser->new_from_url($url, $options);
12 my $model = $rdfa->graph;
13
14 For dealing with local data:
15
16 use RDF::RDFa::Parser;
17 my $base_url = 'http://example.com/document.html';
18 my $options = RDF::RDFa::Parser::Config->new('xhtml', '1.1');
19 my $rdfa = RDF::RDFa::Parser->new($markup, $base_url, $options);
20 my $model = $rdfa->graph;
21
22 A simple set of operations for working with Open Graph Protocol data:
23
24 use RDF::RDFa::Parser;
25 my $url = 'http://www.rottentomatoes.com/m/net/';
26 my $options = RDF::RDFa::Parser::Config->tagsoup;
27 my $rdfa = RDF::RDFa::Parser->new_from_url($url, $options);
28 print $rdfa->opengraph('title') . "\n";
29 print $rdfa->opengraph('image') . "\n";
30
31 DESCRIPTION
32 RDF::TrineX::Parser::RDFa provides a saner interface for this module. If
33 you are new to parsing RDFa with Perl, then that's the best place to
34 start.
35
36 Forthcoming API Changes
37 Some of the logic regarding host language and RDFa version guessing is
38 likely to be removed from RDF::RDFa::Parser and
39 RDF::RDFa::Parser::Config, and shifted into RDF::TrineX::Parser::RDFa
40 instead.
41
42 Constructors
43 "$p = RDF::RDFa::Parser->new($markup, $base, [$config], [$storage])"
44 This method creates a new RDF::RDFa::Parser object and returns it.
45
46 The $markup variable may contain an XHTML/XML string, or a
47 XML::LibXML::Document. If a string, the document is parsed using
48 XML::LibXML::Parser or HTML::HTML5::Parser, depending on the
49 configuration in $config. XML well-formedness errors will cause the
50 function to die.
51
52 $base is a URL used to resolve relative links found in the document.
53
54 $config optionally holds an RDF::RDFa::Parser::Config object which
55 determines the set of rules used to parse the RDFa. It defaults to
56 XHTML+RDFa 1.1.
57
58 Advanced usage note: $storage optionally holds an RDF::Trine::Store
59 object. If undef, then a new temporary store is created.
60
61 "$p = RDF::RDFa::Parser->new_from_url($url, [$config], [$storage])"
62 "$p = RDF::RDFa::Parser->new_from_uri($url, [$config], [$storage])"
63 $url is a URL to fetch and parse, or an HTTP::Response object.
64
65 $config optionally holds an RDF::RDFa::Parser::Config object which
66 determines the set of rules used to parse the RDFa. The default is
67 to determine the configuration by looking at the HTTP response
68 Content-Type header; it's probably sensible to keep the default.
69
70 $storage optionally holds an RDF::Trine::Store object. If undef,
71 then a new temporary store is created.
72
73 This function can also be called as "new_from_url" or
74 "new_from_uri". Same thing.
75
76 "$p = RDF::RDFa::Parser->new_from_response($response, [$config],
77 [$storage])"
78 $response is an "HTTP::Response" object.
79
80 Otherwise the same as "new_from_url".
81
82 Public Methods
83 "$p->graph"
84 This will return an RDF::Trine::Model containing all the RDFa data
85 found on the page.
86
87 Advanced usage note: If passed a graph URI as a parameter, will
88 return a single named graph from within the page. This feature is
89 only useful if you're using named graphs.
90
91 "$p->graphs"
92 Advanced usage only.
93
94 Will return a hashref of all named graphs, where the graph name is a
95 key and the value is a RDF::Trine::Model tied to a temporary
96 storage.
97
98 This method is only useful if you're using named graphs.
99
100 "$p->opengraph([$property])"
101 If $property is provided, will return the value or list of values
102 (if called in list context) for that Open Graph Protocol property.
103 (In pure RDF terms, it returns the non-bnode objects of triples
104 where the subject is the document base URI; and the predicate is
105 $property, with non-URI $property strings taken as having the
106 implicit prefix 'http://ogp.me/ns#'. There is no distinction between
107 literal and non-literal values; literal datatypes and languages are
108 dropped.)
109
110 If $property is omitted, returns a list of possible properties.
111
112 Example:
113
114 foreach my $property (sort $p->opengraph)
115 {
116 print "$property :\n";
117 foreach my $val (sort $p->opengraph($property))
118 {
119 print " * $val\n";
120 }
121 }
122
123 See also: <http://opengraphprotocol.org/>.
124
125 "$p->dom"
126 Returns the parsed XML::LibXML::Document.
127
128 "$p->uri( [$other_uri] )"
129 Returns the base URI of the document being parsed. This will usually
130 be the same as the base URI provided to the constructor, but may
131 differ if the document contains a <base> HTML element.
132
133 Optionally it may be passed a parameter - an absolute or relative
134 URI - in which case it returns the same URI which it was passed as a
135 parameter, but as an absolute URI, resolved relative to the
136 document's base URI.
137
138 This seems like two unrelated functions, but if you consider the
139 consequence of passing a relative URI consisting of a zero-length
140 string, it in fact makes sense.
141
142 "$p->errors"
143 Returns a list of errors and warnings that occurred during parsing.
144
145 "$p->processor_graph"
146 As per "$p->errors" but returns data as an RDF model.
147
148 "$p->output_graph"
149 An alias for "graph", but does not accept a parameter.
150
151 "$p->processor_and_output_graph"
152 Union of the above two graphs.
153
154 "$p->consume"
155 Advanced usage only.
156
157 The document is parsed for RDFa. As of RDF::RDFa::Parser 1.09x, this
158 is called automatically when needed; you probably don't need to
159 touch it unless you're doing interesting things with callbacks.
160
161 Calling "$p->consume(survive => 1)" will avoid crashing (e.g. when
162 the markup provided cannot be parsed), and instead make more errors
163 available in "$p->errors".
164
165 "$p->set_callbacks(\%callbacks)"
166 Advanced usage only.
167
168 Set callback functions for the parser to call on certain events.
169 These are only necessary if you want to do something especially
170 unusual.
171
172 $p->set_callbacks({
173 'pretriple_resource' => sub { ... } ,
174 'pretriple_literal' => sub { ... } ,
175 'ontriple' => undef ,
176 'onprefix' => \&some_function ,
177 });
178
179 Either of the two pretriple callbacks can be set to the string
180 'print' instead of a coderef. This enables built-in callbacks for
181 printing Turtle to STDOUT.
182
183 For details of the callback functions, see the section CALLBACKS. If
184 used, "set_callbacks" must be called *before* "consume".
185 "set_callbacks" returns a reference to the parser object itself.
186
187 "$p->element_subjects"
188 Advanced usage only.
189
190 Gets/sets a hashref of { xpath => RDF::Trine::Node } mappings.
191
192 This is not touched during normal RDFa parsing, only being used by
193 the @role and @cite features where RDF resources (i.e. URIs and
194 blank nodes) are needed to represent XML elements themselves.
195
196 CALLBACKS
197 Several callback functions are provided. These may be set using the
198 "set_callbacks" function, which takes a hashref of keys pointing to
199 coderefs. The keys are named for the event to fire the callback on.
200
201 ontriple
202 This is called once a triple is ready to be added to the graph. (After
203 the pretriple callbacks.) The parameters passed to the callback function
204 are:
205
206 * A reference to the "RDF::RDFa::Parser" object
207
208 * A hashref of relevant "XML::LibXML::Element" objects (subject,
209 predicate, object, graph, current)
210
211 * An RDF::Trine::Statement object.
212
213 The callback should return 1 to tell the parser to skip this triple (not
214 add it to the graph); return 0 otherwise. The callback may modify the
215 RDF::Trine::Statement object.
216
217 onprefix
218 This is called when a new CURIE prefix is discovered. The parameters
219 passed to the callback function are:
220
221 * A reference to the "RDF::RDFa::Parser" object
222
223 * A reference to the "XML::LibXML::Element" being parsed
224
225 * The prefix (string, e.g. "foaf")
226
227 * The expanded URI (string, e.g. "http://xmlns.com/foaf/0.1/")
228
229 The return value of this callback is currently ignored, but you should
230 return 0 in case future versions of this module assign significance to
231 the return value.
232
233 ontoken
234 This is called when a CURIE or term has been expanded. The parameters
235 are:
236
237 * A reference to the "RDF::RDFa::Parser" object
238
239 * A reference to the "XML::LibXML::Element" being parsed
240
241 * The CURIE or token as a string (e.g. "foaf:name" or "Stylesheet")
242
243 * The fully expanded URI
244
245 The callback function must return a fully expanded URI, or if it wants
246 the CURIE to be ignored, undef.
247
248 onerror
249 This is called when an error occurs:
250
251 * A reference to the "RDF::RDFa::Parser" object
252
253 * The error level (RDF::RDFa::Parser::ERR_ERROR or
254 RDF::RDFa::Parser::ERR_WARNING)
255
256 * An error code
257
258 * An error message
259
260 * A hash of other information
261
262 The return value of this callback is currently ignored, but you should
263 return 0 in case future versions of this module assign significance to
264 the return value.
265
266 If you do not define an onerror callback, then errors will be output via
267 STDERR and warnings will be silent. Either way, you can retrieve errors
268 after parsing using the "errors" method.
269
270 pretriple_resource
271 This callback is deprecated - use ontriple instead.
272
273 This is called when a triple has been found, but before preparing the
274 triple for adding to the model. It is only called for triples with a
275 non-literal object value.
276
277 The parameters passed to the callback function are:
278
279 * A reference to the "RDF::RDFa::Parser" object
280
281 * A reference to the "XML::LibXML::Element" being parsed
282
283 * Subject URI or bnode (string)
284
285 * Predicate URI (string)
286
287 * Object URI or bnode (string)
288
289 * Graph URI or bnode (string or undef)
290
291 The callback should return 1 to tell the parser to skip this triple (not
292 add it to the graph); return 0 otherwise.
293
294 pretriple_literal
295 This callback is deprecated - use ontriple instead.
296
297 This is the equivalent of pretriple_resource, but is only called for
298 triples with a literal object value.
299
300 The parameters passed to the callback function are:
301
302 * A reference to the "RDF::RDFa::Parser" object
303
304 * A reference to the "XML::LibXML::Element" being parsed
305
306 * Subject URI or bnode (string)
307
308 * Predicate URI (string)
309
310 * Object literal (string)
311
312 * Datatype URI (string or undef)
313
314 * Language (string or undef)
315
316 * Graph URI or bnode (string or undef)
317
318 Beware: sometimes both a datatype *and* a language will be passed. This
319 goes beyond the normal RDF data model.)
320
321 The callback should return 1 to tell the parser to skip this triple (not
322 add it to the graph); return 0 otherwise.
323
324 FEATURES
325 Most features are configurable using RDF::RDFa::Parser::Config.
326
327 RDFa Versions
328 RDF::RDFa::Parser supports RDFa versions 1.0 and 1.1.
329
330 1.1 is currently a moving target; support is experimental.
331
332 1.1 is the default, but this can be configured using
333 RDF::RDFa::Parser::Config.
334
335 Host Languages
336 RDF::RDFa::Parser supports various different RDFa host languages:
337
338 * XHTML
339
340 As per the XHTML+RDFa 1.0 and XHTML+RDFa 1.1 specifications.
341
342 * HTML 4
343
344 Uses an HTML5 (sic) parser; uses @lang instead of @xml:lang; keeps
345 prefixes and terms case-insensitive; recognises the @rel relations
346 defined in the HTML 4 specification. Otherwise the same as XHTML.
347
348 * HTML5
349
350 Uses an HTML5 parser; uses @lang as well as @xml:lang; keeps
351 prefixes and terms case-insensitive; recognises the @rel relations
352 defined in the HTML5 draft specification. Otherwise the same as
353 XHTML.
354
355 * XML
356
357 This is implemented as per the RDFa Core 1.1 specification. There is
358 also support for "RDFa Core 1.0", for which no specification exists,
359 but has been reverse-engineered by applying the differences between
360 XHTML+RDFa 1.1 and RDFa Core 1.1 to the XHTML+RDFa 1.0
361 specification.
362
363 Embedded chunks of RDF/XML within XML are supported.
364
365 * SVG
366
367 For now, a synonym for XML.
368
369 * Atom
370
371 The <feed> and <entry> elements are treated specially, setting a new
372 subject; IANA-registered rel keywords are recognised.
373
374 By passing "atom_parser=>1" as a Config option, you can also handle
375 Atom's native semantics. (Uses XML::Atom::OWL. If this module is not
376 installed, this option is silently ignored.)
377
378 Otherwise, the same as XML.
379
380 * DataRSS
381
382 Defines some default prefixes. Otherwise, the same as Atom.
383
384 * OpenDocument XML
385
386 That is, XML content formatted along the lines of 'content.xml' in
387 OpenDocument files.
388
389 Supports OpenDocument bookmarked ranges used as typed or plain
390 object literals (though not XML literals); expects RDFa attributes
391 in the XHTML namespace instead of in no namespace. Otherwise, the
392 same as XML.
393
394 * OpenDocument
395
396 That is, a ZIP file containing OpenDocument XML files.
397 RDF::RDFa::Parser will do all the unzipping and combining for you,
398 so you don't have to. The unregistered "jar:" URI scheme is used to
399 refer to files within the ZIP.
400
401 Embedded RDF/XML
402 Though a rarely used feature, XHTML allows other XML markup languages to
403 be directly embedded into it. In particular, chunks of RDF/XML can be
404 included in XHTML. While this is not common in XHTML, it's seen quite
405 often in SVG and other XML markup languages.
406
407 When RDF::RDFa::Parser encounters a chunk of RDF/XML in a document it's
408 parsing (i.e. an element called 'RDF' with namespace
409 'http://www.w3.org/1999/02/22-rdf-syntax-ns#'), there are three
410 different courses of action it can take:
411
412 0. Continue straight through it.
413 This is the behaviour that XHTML+RDFa seems to suggest is the right
414 option. It should mostly not do any harm: triples encoded in RDF/XML
415 will be generally ignored (though the chunk itself could
416 theoretically end up as part of an XML literal). It will waste a bit
417 of time though.
418
419 1. Parse the RDF/XML.
420 The parser will parse the RDF/XML properly. If named graphs are
421 enabled, any triples will be added to a separate graph. This is the
422 behaviour that SVG Tiny 1.2 seems to suggest is the correct thing to
423 do.
424
425 2. Skip the chunk.
426 This will skip over the RDF element entirely, and thus save you a
427 bit of time.
428
429 You can decide which path to take by setting the 'embedded_rdfxml'
430 Config option. For HTML and XHTML, you probably want to set
431 embedded_rdfxml to '0' (the default) or '2' (a little faster). For other
432 XML markup languages (e.g. SVG or Atom), then you probably want to set
433 it to '1'.
434
435 (There's also an option '3' which controls how embedded RDF/XML
436 interacts with named graphs, but this is only really intended for
437 internal use, parsing OpenDocument.)
438
439 Named Graphs
440 The parser has support for named graphs within a single RDFa document.
441 To switch this on, use the 'graph' Config option.
442
443 See also <http://buzzword.org.uk/2009/rdfa4/spec>.
444
445 The name of the attribute which indicates graph URIs is by default
446 'graph', but can be changed using the 'graph_attr' Config option. This
447 option accepts Clark Notation to specify a namespaced attribute. By
448 default, the attribute value is interpreted as like the 'about'
449 attribute (i.e. CURIEs, URIs, etc), but if you set the 'graph_type'
450 Config option to 'id', it will be treated as setting a fragment
451 identifier (like the 'id' attribute).
452
453 The 'graph_default' Config option allows you to set the default graph
454 URI/bnode identifier.
455
456 Once you're using named graphs, the "graphs" method becomes useful: it
457 returns a hashref of { graph_uri => trine_model } pairs. The optional
458 parameter to the "graph" method also becomes useful.
459
460 OpenDocument (ZIP) host language support makes internal use of named
461 graphs, so if you're parsing OpenDocument, tinker with the graph Config
462 options at your own risk!
463
464 Auto Config
465 RDF::RDFa::Parser has a lot of different Config options to play with.
466 Sometimes it might be useful to allow the page being parsed to control
467 some of these options. If you switch on the 'auto_config' Config option,
468 pages can do this.
469
470 A page can set options using a specially crafted <meta> tag:
471
472 <meta name="http://search.cpan.org/dist/RDF-RDFa-Parser/#auto_config"
473 content="xhtml_lang=1&amp;xml_lang=0" />
474
475 Note that the "content" attribute is an
476 application/x-www-form-urlencoded string (which must then be
477 HTML-escaped of course). Semicolons may be used instead of ampersands,
478 as these tend to look nicer:
479
480 <meta name="http://search.cpan.org/dist/RDF-RDFa-Parser/#auto_config"
481 content="xhtml_lang=1;xml_lang=0" />
482
483 It's possible to use auto config outside XHTML (e.g. in Atom or SVG)
484 using namespaces:
485
486 <xhtml:meta xmlns:xhtml="http://www.w3.org/1999/xhtml"
487 name="http://search.cpan.org/dist/RDF-RDFa-Parser/#auto_config"
488 content="xhtml_lang=0;xml_base=2;atom_elements=1" />
489
490 Any Config option may be given using auto config, except 'use_rtnlx',
491 'dom_parser', and of course 'auto_config' itself.
492
493 Profiles
494 Support for Profiles (an experimental RDFa 1.1 feature) was added in
495 version 1.09_00, but dropped after version 1.096, because the feature
496 was removed from draft specs.
497
498 BUGS
499 RDF::RDFa::Parser 0.21 passed all approved tests in the XHTML+RDFa test
500 suite at the time of its release.
501
502 RDF::RDFa::Parser 0.22 (used in conjunction with HTML::HTML5::Parser
503 0.01 and HTML::HTML5::Sanity 0.01) additionally passes all approved
504 tests in the HTML4+RDFa and HTML5+RDFa test suites at the time of its
505 release; except test cases 0113 and 0121, which the author of this
506 module believes mandate incorrect HTML parsing.
507
508 RDF::RDFa::Parser 1.096_01 passes all approved tests on the default
509 graph (not the processor graph) in the RDFa 1.1 test suite for language
510 versions 1.0 and host languages xhtml1, html4 and html5, with the
511 following exceptions which are skipped:
512
513 * 0140 - wilful violation, pending proof that the test is backed up by
514 the spec.
515
516 * 0198 - an XML canonicalisation test that may be dropped in the
517 future.
518
519 * 0212 - wilful violation, as passing this test would require
520 regressing on the old RDFa 1.0 test suite.
521
522 * 0251 to 0256 pass with RDFa 1.1 and are skipped in RDFa 1.0 because
523 they use RDFa-1.1-specific syntax.
524
525 * 0256 is additionally skipped in HTML4 mode, as the author believes
526 xml:lang should be ignored in HTML versions prior to HTML5.
527
528 * 0303 - wilful violation, as this feature is simply awful.
529
530 Please report any bugs to <http://rt.cpan.org/>.
531
532 Common gotchas:
533
534 * Are you using the XML catalogue?
535
536 RDF::RDFa::Parser maintains a locally cached version of the
537 XHTML+RDFa DTD. This will normally be within your Perl module
538 directory, in a subdirectory named
539 "auto/share/dist/RDF-RDFa-Parser/catalogue/". If this is
540 missing, the parser should still work, but will be very slow.
541
542 SEE ALSO
543 RDF::TrineX::Parser::RDFa provides a saner interface for this module.
544
545 RDF::RDFa::Parser::Config.
546
547 XML::LibXML, RDF::Trine, HTML::HTML5::Parser, HTML::HTML5::Sanity,
548 RDF::RDFa::Generator, RDF::RDFa::Linter.
549
550 <http://www.perlrdf.org/>, <http://rdfa.info>.
551
552 AUTHOR
553 Toby Inkster <[email protected]>.
554
555 ACKNOWLEDGEMENTS
556 Kjetil Kjernsmo <[email protected]> wrote much of the stuff for building
557 RDF::Trine models. Neubert Joachim taught me to use XML catalogues,
558 which massively speeds up parsing of XHTML files that have DTDs.
559
560 COPYRIGHT AND LICENCE
561 Copyright 2008-2012 Toby Inkster
562
563 This is free software; you can redistribute it and/or modify it under
564 the same terms as the Perl 5 programming language system itself.
565
566 DISCLAIMER OF WARRANTIES
567 THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
568 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
569 MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
570