.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "XRD::Parser 3pm"
.TH XRD::Parser 3pm "2012-09-11" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
XRD::Parser \- parse XRD and host\-meta files into RDF::Trine models
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use RDF::Query;
\&  use XRD::Parser;
\&  
\&  my $parser = XRD::Parser\->new(undef, "http://example.com/foo.xrd");
\&  my $results = RDF::Query\->new(
\&    "SELECT * WHERE {?who <http://spec.example.net/auth/1.0> ?auth.}")
\&    \->execute($parser\->graph);
\&        
\&  while (my $result = $results\->next)
\&  {
\&    print $result\->{\*(Aqauth\*(Aq}\->uri . "\en";
\&  }
.Ve
.PP
or maybe:
.PP
.Vb 3
\&  my $data = XRD::Parser\->hostmeta(\*(Aqgmail.com\*(Aq)
\&                          \->graph
\&                            \->as_hashref;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
While \s-1XRD\s0 has a rather different history, it turns out it can mostly
be thought of as a serialisation format for a limited subset of
\&\s-1RDF.\s0
.PP
This package ignores the order of <Link> elements, as \s-1RDF\s0 is a graph
format with no concept of statements coming in an \*(L"order\*(R". The \s-1XRD\s0 spec
says that grokking the order of <Link> elements is only a \s-1SHOULD.\s0 That
said, if you're concerned about the order of <Link> elements, the
callback routines allowed by this package may be of use.
.PP
This package aims to be roughly compatible with RDF::RDFa::Parser's
interface.
.SS "Constructors"
.IX Subsection "Constructors"
.ie n .IP """$p = XRD::Parser\->new($content, $uri, [\e%options], [$store])""" 4
.el .IP "\f(CW$p = XRD::Parser\->new($content, $uri, [\e%options], [$store])\fR" 4
.IX Item "$p = XRD::Parser->new($content, $uri, [%options], [$store])"
This method creates a new XRD::Parser object and returns it.
.Sp
The \f(CW$content\fR variable may contain an \s-1XML\s0 string, or a XML::LibXML::Document.
If a string, the document is parsed using XML::LibXML::Parser, which may throw an
exception. XRD::Parser does not catch the exception.
.Sp
\&\f(CW$uri\fR the base \s-1URI\s0 of the content; it is used to resolve any relative URIs found
in the \s-1XRD\s0 document.
.Sp
Options [default in brackets]:
.RS 4
.IP "\(bu" 8
\&\fBdefault_subject\fR \- If no <Subject> element. [undef]
.IP "\(bu" 8
\&\fBlink_prop\fR \- How to handle <Property> in <Link>?
0=skip, 1=reify, 2=subproperty, 3=both. [0]
.IP "\(bu" 8
\&\fBloose_mime\fR \- Accept text/plain, text/html and
application/octet\-stream media types. [0]
.IP "\(bu" 8
\&\fBtdb_service\fR \- Use thing\-described\-by.org when possible. [0]
.RE
.RS 4
.Sp
\&\f(CW$storage\fR is an RDF::Trine::Storage object. If undef, then a new
temporary store is created.
.RE
.ie n .IP """$p = XRD::Parser\->new_from_url($url, [\e%options], [$storage])""" 4
.el .IP "\f(CW$p = XRD::Parser\->new_from_url($url, [\e%options], [$storage])\fR" 4
.IX Item "$p = XRD::Parser->new_from_url($url, [%options], [$storage])"
\&\f(CW$url\fR is a \s-1URL\s0 to fetch and parse.
.Sp
This function can also be called as \f(CW\*(C`new_from_uri\*(C'\fR. Same thing.
.ie n .IP """$p = XRD::Parser\->hostmeta($uri)""" 4
.el .IP "\f(CW$p = XRD::Parser\->hostmeta($uri)\fR" 4
.IX Item "$p = XRD::Parser->hostmeta($uri)"
This method creates a new XRD::Parser object and returns it.
.Sp
The parameter may be a \s-1URI \s0(from which the hostname will be extracted) or
just a bare host name (e.g. \*(L"example.com\*(R"). The resource
\&\*(L"/.well\-known/host\-meta\*(R" will then be fetched from that host using an
appropriate \s-1HTTP\s0 Accept header, and the parser object returned.
.SS "Public Methods"
.IX Subsection "Public Methods"
.ie n .IP """$p\->uri($uri)""" 4
.el .IP "\f(CW$p\->uri($uri)\fR" 4
.IX Item "$p->uri($uri)"
Returns the base \s-1URI\s0 of the document being parsed. This will usually be the
same as the base \s-1URI\s0 provided to the constructor.
.Sp
Optionally it may be passed a parameter \- an absolute or relative \s-1URI \-\s0 in
which case it returns the same \s-1URI\s0 which it was passed as a parameter, but
as an absolute \s-1URI,\s0 resolved relative to the document's base \s-1URI.\s0
.Sp
This seems like two unrelated functions, but if you consider the consequence
of passing a relative \s-1URI\s0 consisting of a zero-length string, it in fact makes
sense.
.ie n .IP """$p\->dom""" 4
.el .IP "\f(CW$p\->dom\fR" 4
.IX Item "$p->dom"
Returns the parsed XML::LibXML::Document.
.ie n .IP """$p\->graph""" 4
.el .IP "\f(CW$p\->graph\fR" 4
.IX Item "$p->graph"
This method will return an RDF::Trine::Model object with all
statements of the full graph.
.Sp
This method will automatically call \f(CW\*(C`consume\*(C'\fR first, if it has not
already been called.
.ie n .IP "$p\->set_callbacks(\e%callbacks)" 4
.el .IP "\f(CW$p\fR\->set_callbacks(\e%callbacks)" 4
.IX Item "$p->set_callbacks(%callbacks)"
Set callback functions for the parser to call on certain events. These are only necessary if
you want to do something especially unusual.
.Sp
.Vb 5
\&  $p\->set_callbacks({
\&    \*(Aqpretriple_resource\*(Aq => sub { ... } ,
\&    \*(Aqpretriple_literal\*(Aq  => sub { ... } ,
\&    \*(Aqontriple\*(Aq           => undef ,
\&    });
.Ve
.Sp
Either of the two pretriple callbacks can be set to the string 'print' instead of a coderef.
This enables built-in callbacks for printing Turtle to \s-1STDOUT.\s0
.Sp
For details of the callback functions, see the section \s-1CALLBACKS. \s0\f(CW\*(C`set_callbacks\*(C'\fR must
be used \fIbefore\fR \f(CW\*(C`consume\*(C'\fR. \f(CW\*(C`set_callbacks\*(C'\fR itself returns a reference to the parser
object itself.
.Sp
\&\fI\s-1NOTE:\s0\fR the behaviour of this function was changed in version 0.05.
.ie n .IP """$p\->consume""" 4
.el .IP "\f(CW$p\->consume\fR" 4
.IX Item "$p->consume"
This method processes the input \s-1DOM\s0 and sends the resulting triples to 
the callback functions (if any).
.Sp
It called again, does nothing.
.Sp
Returns the parser object itself.
.SS "Utility Functions"
.IX Subsection "Utility Functions"
.ie n .IP """$host_uri = XRD::Parser::host_uri($uri)""" 4
.el .IP "\f(CW$host_uri = XRD::Parser::host_uri($uri)\fR" 4
.IX Item "$host_uri = XRD::Parser::host_uri($uri)"
Returns a \s-1URI\s0 representing the host. These crop up often in graphs gleaned
from host-meta files.
.Sp
\&\f(CW$uri\fR can be an absolute \s-1URI\s0 like 'http://example.net/foo#bar' or a host
name like 'example.com'.
.ie n .IP """$uri = XRD::Parser::template_uri($relationship_uri)""" 4
.el .IP "\f(CW$uri = XRD::Parser::template_uri($relationship_uri)\fR" 4
.IX Item "$uri = XRD::Parser::template_uri($relationship_uri)"
Returns a \s-1URI\s0 representing not a normal relationship, but the
relationship between a host and a template \s-1URI\s0 literal.
.ie n .IP """$hostmeta_uri = XRD::Parser::hostmeta_location($host)""" 4
.el .IP "\f(CW$hostmeta_uri = XRD::Parser::hostmeta_location($host)\fR" 4
.IX Item "$hostmeta_uri = XRD::Parser::hostmeta_location($host)"
The parameter may be a \s-1URI \s0(from which the hostname will be extracted) or
just a bare host name (e.g. \*(L"example.com\*(R"). The location for a host-meta file
relevant to the host of that \s-1URI\s0 will be calculated.
.Sp
If called in list context, returns an 'https' \s-1URI\s0 and an 'http' \s-1URI\s0 as a list.
.SH "CALLBACKS"
.IX Header "CALLBACKS"
Several callback functions are provided. These may be set using the \f(CW\*(C`set_callbacks\*(C'\fR function,
which taskes a hashref of keys pointing to coderefs. The keys are named for the event to fire the
callback on.
.SS "pretriple_resource"
.IX Subsection "pretriple_resource"
This is called when a triple has been found, but before preparing the triple for
adding to the model. It is only called for triples with a non-literal object value.
.PP
The parameters passed to the callback function are:
.IP "\(bu" 4
A reference to the \f(CW\*(C`XRD::Parser\*(C'\fR object
.IP "\(bu" 4
A reference to the \f(CW\*(C`XML::LibXML::Element\*(C'\fR being parsed
.IP "\(bu" 4
Subject \s-1URI\s0 or bnode (string)
.IP "\(bu" 4
Predicate \s-1URI \s0(string)
.IP "\(bu" 4
Object \s-1URI\s0 or bnode (string)
.PP
The callback should return 1 to tell the parser to skip this triple (not add it to
the graph); return 0 otherwise.
.SS "pretriple_literal"
.IX Subsection "pretriple_literal"
This is the equivalent of pretriple_resource, but is only called for triples with a
literal object value.
.PP
The parameters passed to the callback function are:
.IP "\(bu" 4
A reference to the \f(CW\*(C`XRD::Parser\*(C'\fR object
.IP "\(bu" 4
A reference to the \f(CW\*(C`XML::LibXML::Element\*(C'\fR being parsed
.IP "\(bu" 4
Subject \s-1URI\s0 or bnode (string)
.IP "\(bu" 4
Predicate \s-1URI \s0(string)
.IP "\(bu" 4
Object literal (string)
.IP "\(bu" 4
Datatype \s-1URI \s0(string or undef)
.IP "\(bu" 4
Language (string or undef)
.PP
The callback should return 1 to tell the parser to skip this triple (not add it to
the graph); return 0 otherwise.
.SS "ontriple"
.IX Subsection "ontriple"
This is called once a triple is ready to be added to the graph. (After the pretriple
callbacks.) The parameters passed to the callback function are:
.IP "\(bu" 4
A reference to the \f(CW\*(C`XRD::Parser\*(C'\fR object
.IP "\(bu" 4
A reference to the \f(CW\*(C`XML::LibXML::Element\*(C'\fR being parsed
.IP "\(bu" 4
An RDF::Trine::Statement object.
.PP
The callback should return 1 to tell the parser to skip this triple (not add it to
the graph); return 0 otherwise. The callback may modify the RDF::Trine::Statement
object.
.SH "WHY RDF?"
.IX Header "WHY RDF?"
It abstracts away the structure of the \s-1XRD\s0 file, exposing just the meaning
of its contents. Two \s-1XRD\s0 files with the same meaning should end up producing
more or less the same \s-1RDF\s0 data, even if they differ significantly at the
syntactic level.
.PP
If you care about the syntax of an \s-1XRD\s0 file, then use XML::LibXML.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
RDF::Trine, RDF::Query, RDF::RDFa::Parser.
.PP
<http://www.perlrdf.org/>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Toby Inkster, <tobyink@cpan.org>
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
Copyright (C) 2009\-2012 by Toby Inkster
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "DISCLAIMER OF WARRANTIES"
.IX Header "DISCLAIMER OF WARRANTIES"
\&\s-1THIS PACKAGE IS PROVIDED \*(L"AS IS\*(R" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.\s0