| 1 |
NAME |
| 2 |
XML::GRDDL - transform XML and XHTML to RDF |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
High-level interface: |
| 6 |
|
| 7 |
my $grddl = XML::GRDDL->new; |
| 8 |
my $model = $grddl->data($xmldoc, $baseuri); |
| 9 |
# $model is an RDF::Trine::Model |
| 10 |
|
| 11 |
Low-level interface: |
| 12 |
|
| 13 |
my $grddl = XML::GRDDL->new; |
| 14 |
my @transformations = $grddl->discover($xmldoc, $baseuri); |
| 15 |
foreach my $t (@transformations) |
| 16 |
{ |
| 17 |
# $t is an XML::GRDDL::Transformation |
| 18 |
my ($output, $mediatype) = $t->transform($xmldoc); |
| 19 |
# $output is a string of type $mediatype. |
| 20 |
} |
| 21 |
|
| 22 |
DESCRIPTION |
| 23 |
GRDDL is a W3C Recommendation for extracting RDF data from arbitrary XML |
| 24 |
and XHTML via a transformation, typically written in XSLT. See |
| 25 |
<http://www.w3.org/TR/grddl/> for more details. |
| 26 |
|
| 27 |
This module implements GRDDL in Perl. It offers both a low level |
| 28 |
interface, allowing you to generate a list of transformations associated |
| 29 |
with the document being processed, and thus the ability to selectively |
| 30 |
run the transformation; and a high-level interface where a single RDF |
| 31 |
model is returned representing the union of the RDF graphs generated by |
| 32 |
applying all available transformations. |
| 33 |
|
| 34 |
Constructor |
| 35 |
"XML::GRDDL->new" |
| 36 |
The constructor accepts no parameters and returns an XML::GRDDL |
| 37 |
object. |
| 38 |
|
| 39 |
Methods |
| 40 |
"$grddl->discover($xml, $base, %options)" |
| 41 |
Processes the document to discover the transformations associated |
| 42 |
with it. $xml is the raw XML source of the document, or an |
| 43 |
XML::LibXML::Document object. ($xml cannot be "tag soup" HTML, |
| 44 |
though you should be able to use HTML::HTML5::Parser to parse tag |
| 45 |
soup into an XML::LibXML::Document.) $base is the base URI for |
| 46 |
resolving relative references. |
| 47 |
|
| 48 |
Returns a list of XML::GRDDL::Transformation objects. |
| 49 |
|
| 50 |
Options include: |
| 51 |
|
| 52 |
* force_rel - boolean; interpret XHTML rel="transformation" even |
| 53 |
in the absence of the GRDDL profile. |
| 54 |
|
| 55 |
* strings - boolean; return a list of plain strings instead of |
| 56 |
blessed objects. |
| 57 |
|
| 58 |
"$grddl->data($xml, $base, %options)" |
| 59 |
Processes the document, discovers the transformations associated |
| 60 |
with it, applies the transformations and merges the results into a |
| 61 |
single RDF model. $xml and $base are as per "discover". |
| 62 |
|
| 63 |
Returns an RDF::Trine::Model containing the data. Statement contexts |
| 64 |
(a.k.a. named graphs / quads) are used to distinguish between data |
| 65 |
from the result of each transformation. |
| 66 |
|
| 67 |
Options include: |
| 68 |
|
| 69 |
* force_rel - boolean; interpret XHTML rel="transformation" even |
| 70 |
in the absence of the GRDDL profile. |
| 71 |
|
| 72 |
* metadata - boolean; include provenance information in the |
| 73 |
default graph (a.k.a. nil context). |
| 74 |
|
| 75 |
"$grddl->ua( [$ua] )" |
| 76 |
Get/set the user agent used for HTTP requests. $ua, if supplied, |
| 77 |
must be an LWP::UserAgent. |
| 78 |
|
| 79 |
Constants |
| 80 |
These constants may be exported upon request. |
| 81 |
|
| 82 |
"GRDDL_NS" |
| 83 |
"XHTML_NS" |
| 84 |
|
| 85 |
FEATURES |
| 86 |
XML::GRDDL supports transformations written in XSLT 1.0, and in |
| 87 |
RDF-EASE. |
| 88 |
|
| 89 |
XML::GRDDL is a good HTTP citizen: Referer headers are included in |
| 90 |
requests, and appropriate Accept headers supplied. To be an even better |
| 91 |
citizen, I recommend changing the User-Agent header to advertise the |
| 92 |
name of the application: |
| 93 |
|
| 94 |
$grddl->ua->default_header(user_agent => 'MyApp/1.0 '); |
| 95 |
|
| 96 |
Provenance information for GRDDL transformations is returned using the |
| 97 |
GRDDL vocabulary at <http://www.w3.org/2003/g/data-view#>. |
| 98 |
|
| 99 |
Certain XHTML profiles and XML namespaces known not to contain any |
| 100 |
transformations, or to contain useless transformations are skipped. See |
| 101 |
XML::GRDDL::Namespace and XML::GRDDL::Profile for details. In particular |
| 102 |
profiles for RDFa and many Microformats are skipped, as |
| 103 |
RDF::RDFa::Parser and HTML::Microformats will typically yield far |
| 104 |
superior results. |
| 105 |
|
| 106 |
BUGS |
| 107 |
Please report any bugs to <http://rt.cpan.org/>. |
| 108 |
|
| 109 |
Known limitations: |
| 110 |
|
| 111 |
* Recursive GRDDL doesn't work yet. |
| 112 |
|
| 113 |
That is, the profile documents and namespace documents linked to |
| 114 |
from your primary document cannot themselves rely on GRDDL. |
| 115 |
|
| 116 |
SEE ALSO |
| 117 |
XML::GRDDL::Transformation, XML::GRDDL::Namespace, XML::GRDDL::Profile, |
| 118 |
XML::GRDDL::Transformation::RDF_EASE::Functional, XML::Saxon::XSLT2. |
| 119 |
|
| 120 |
HTML::HTML5::Parser, RDF::RDFa::Parser, HTML::Microformats. |
| 121 |
|
| 122 |
JSON::GRDDL. |
| 123 |
|
| 124 |
<http://www.w3.org/TR/grddl/>. |
| 125 |
|
| 126 |
<http://www.perlrdf.org/>. |
| 127 |
|
| 128 |
This module is derived from Swignition |
| 129 |
<http://buzzword.org.uk/swignition/>. |
| 130 |
|
| 131 |
AUTHOR |
| 132 |
Toby Inkster <[email protected]>. |
| 133 |
|
| 134 |
COPYRIGHT AND LICENCE |
| 135 |
Copyright 2008-2012 Toby Inkster |
| 136 |
|
| 137 |
This library is free software; you can redistribute it and/or modify it |
| 138 |
under the same terms as Perl itself. |
| 139 |
|
| 140 |
DISCLAIMER OF WARRANTIES |
| 141 |
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED |
| 142 |
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF |
| 143 |
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. |
| 144 |
|