XRD::Parser(3pm)

1XRD::Parser(3)        User Contributed Perl Documentation       XRD::Parser(3)
2
3
4

NAME

6       XRD::Parser - parse XRD and host-meta files into RDF::Trine models
7

SYNOPSIS

9         use RDF::Query;
10         use XRD::Parser;
11
12         my $parser = XRD::Parser->new(undef, "http://example.com/foo.xrd");
13         my $results = RDF::Query->new(
14           "SELECT * WHERE {?who <http://spec.example.net/auth/1.0> ?auth.}")
15           ->execute($parser->graph);
16
17         while (my $result = $results->next)
18         {
19           print $result->{'auth'}->uri . "\n";
20         }
21
22       or maybe:
23
24         my $data = XRD::Parser->hostmeta('gmail.com')
25                                 ->graph
26                                   ->as_hashref;
27

DESCRIPTION

29       While XRD has a rather different history, it turns out it can mostly be
30       thought of as a serialisation format for a limited subset of RDF.
31
32       This package ignores the order of <Link> elements, as RDF is a graph
33       format with no concept of statements coming in an "order". The XRD spec
34       says that grokking the order of <Link> elements is only a SHOULD. That
35       said, if you're concerned about the order of <Link> elements, the
36       callback routines allowed by this package may be of use.
37
38       This package aims to be roughly compatible with RDF::RDFa::Parser's
39       interface.
40
41   Constructors
42       "$p = XRD::Parser->new($content, $uri, [\%options], [$store])"
43           This method creates a new XRD::Parser object and returns it.
44
45           The $content variable may contain an XML string, or a
46           XML::LibXML::Document.  If a string, the document is parsed using
47           XML::LibXML::Parser, which may throw an exception. XRD::Parser does
48           not catch the exception.
49
50           $uri the base URI of the content; it is used to resolve any
51           relative URIs found in the XRD document.
52
53           Options [default in brackets]:
54
55           •       default_subject - If no <Subject> element. [undef]
56
57           •       link_prop - How to handle <Property> in <Link>?  0=skip,
58                   1=reify, 2=subproperty, 3=both. [0]
59
60           •       loose_mime - Accept text/plain, text/html and
61                   application/octet-stream media types. [0]
62
63           •       tdb_service - Use thing-described-by.org when possible. [0]
64
65           $storage is an RDF::Trine::Storage object. If undef, then a new
66           temporary store is created.
67
68       "$p = XRD::Parser->new_from_url($url, [\%options], [$storage])"
69           $url is a URL to fetch and parse.
70
71           This function can also be called as "new_from_uri". Same thing.
72
73       "$p = XRD::Parser->hostmeta($uri)"
74           This method creates a new XRD::Parser object and returns it.
75
76           The parameter may be a URI (from which the hostname will be
77           extracted) or just a bare host name (e.g. "example.com"). The
78           resource "/.well-known/host-meta" will then be fetched from that
79           host using an appropriate HTTP Accept header, and the parser object
80           returned.
81
82   Public Methods
83       "$p->uri($uri)"
84           Returns the base URI of the document being parsed. This will
85           usually be the same as the base URI provided to the constructor.
86
87           Optionally it may be passed a parameter - an absolute or relative
88           URI - in which case it returns the same URI which it was passed as
89           a parameter, but as an absolute URI, resolved relative to the
90           document's base URI.
91
92           This seems like two unrelated functions, but if you consider the
93           consequence of passing a relative URI consisting of a zero-length
94           string, it in fact makes sense.
95
96       "$p->dom"
97           Returns the parsed XML::LibXML::Document.
98
99       "$p->graph"
100           This method will return an RDF::Trine::Model object with all
101           statements of the full graph.
102
103           This method will automatically call "consume" first, if it has not
104           already been called.
105
106       $p->set_callbacks(\%callbacks)
107           Set callback functions for the parser to call on certain events.
108           These are only necessary if you want to do something especially
109           unusual.
110
111             $p->set_callbacks({
112               'pretriple_resource' => sub { ... } ,
113               'pretriple_literal'  => sub { ... } ,
114               'ontriple'           => undef ,
115               });
116
117           Either of the two pretriple callbacks can be set to the string
118           'print' instead of a coderef.  This enables built-in callbacks for
119           printing Turtle to STDOUT.
120
121           For details of the callback functions, see the section CALLBACKS.
122           "set_callbacks" must be used before "consume". "set_callbacks"
123           itself returns a reference to the parser object itself.
124
125           NOTE: the behaviour of this function was changed in version 0.05.
126
127       "$p->consume"
128           This method processes the input DOM and sends the resulting triples
129           to the callback functions (if any).
130
131           It called again, does nothing.
132
133           Returns the parser object itself.
134
135   Utility Functions
136       "$host_uri = XRD::Parser::host_uri($uri)"
137           Returns a URI representing the host. These crop up often in graphs
138           gleaned from host-meta files.
139
140           $uri can be an absolute URI like 'http://example.net/foo#bar' or a
141           host name like 'example.com'.
142
143       "$uri = XRD::Parser::template_uri($relationship_uri)"
144           Returns a URI representing not a normal relationship, but the
145           relationship between a host and a template URI literal.
146
147       "$hostmeta_uri = XRD::Parser::hostmeta_location($host)"
148           The parameter may be a URI (from which the hostname will be
149           extracted) or just a bare host name (e.g. "example.com"). The
150           location for a host-meta file relevant to the host of that URI will
151           be calculated.
152
153           If called in list context, returns an 'https' URI and an 'http' URI
154           as a list.
155

CALLBACKS

157       Several callback functions are provided. These may be set using the
158       "set_callbacks" function, which taskes a hashref of keys pointing to
159       coderefs. The keys are named for the event to fire the callback on.
160
161   pretriple_resource
162       This is called when a triple has been found, but before preparing the
163       triple for adding to the model. It is only called for triples with a
164       non-literal object value.
165
166       The parameters passed to the callback function are:
167
168       •   A reference to the "XRD::Parser" object
169
170       •   A reference to the "XML::LibXML::Element" being parsed
171
172       •   Subject URI or bnode (string)
173
174       •   Predicate URI (string)
175
176       •   Object URI or bnode (string)
177
178       The callback should return 1 to tell the parser to skip this triple
179       (not add it to the graph); return 0 otherwise.
180
181   pretriple_literal
182       This is the equivalent of pretriple_resource, but is only called for
183       triples with a literal object value.
184
185       The parameters passed to the callback function are:
186
187       •   A reference to the "XRD::Parser" object
188
189       •   A reference to the "XML::LibXML::Element" being parsed
190
191       •   Subject URI or bnode (string)
192
193       •   Predicate URI (string)
194
195       •   Object literal (string)
196
197       •   Datatype URI (string or undef)
198
199       •   Language (string or undef)
200
201       The callback should return 1 to tell the parser to skip this triple
202       (not add it to the graph); return 0 otherwise.
203
204   ontriple
205       This is called once a triple is ready to be added to the graph. (After
206       the pretriple callbacks.) The parameters passed to the callback
207       function are:
208
209       •   A reference to the "XRD::Parser" object
210
211       •   A reference to the "XML::LibXML::Element" being parsed
212
213       •   An RDF::Trine::Statement object.
214
215       The callback should return 1 to tell the parser to skip this triple
216       (not add it to the graph); return 0 otherwise. The callback may modify
217       the RDF::Trine::Statement object.
218

WHY RDF?

220       It abstracts away the structure of the XRD file, exposing just the
221       meaning of its contents. Two XRD files with the same meaning should end
222       up producing more or less the same RDF data, even if they differ
223       significantly at the syntactic level.
224
225       If you care about the syntax of an XRD file, then use XML::LibXML.
226

AUTHOR

233       Toby Inkster, <tobyink@cpan.org>
234

COPYRIGHT AND LICENCE

236       Copyright (C) 2009-2012 by Toby Inkster
237
238       This library is free software; you can redistribute it and/or modify it
239       under the same terms as Perl itself.
240

DISCLAIMER OF WARRANTIES

242       THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
243       WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
244       MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
245
246
247
248perl v5.32.1                      2021-01-27                    XRD::Parser(3)