Debian Codegraph @

README

raw
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