.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 >0, 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
.\" ========================================================================
.\"
.IX Title "XML::Atom::OWL 3pm"
.TH XML::Atom::OWL 3pm 2024-03-09 "perl v5.38.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
XML::Atom::OWL \- parse an Atom file into RDF
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& use XML::Atom::OWL;
\& 
\& $parser = XML::Atom::OWL\->new($xml, $baseuri);
\& $graph  = $parser\->graph;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This has a pretty similar interface to RDF::RDFa::Parser.
.SS Constructor
.IX Subsection "Constructor"
.ie n .IP """new($xml, $baseuri, \e%options, $storage)""" 4
.el .IP "\f(CWnew($xml, $baseuri, \e%options, $storage)\fR" 4
.IX Item "new($xml, $baseuri, %options, $storage)"
This method creates a new XML::Atom::OWL object and returns it.
.Sp
The \f(CW$xml\fR variable may contain an XML (Atom) string, or an
XML::LibXML::Document object. If a string, the document is parsed
using XML::LibXML, which will throw an exception if it is not
well-formed. XML::Atom::OWL does not catch the exception.
.Sp
The base URI is used to resolve relative URIs found in the document.
.Sp
Currently only one option is defined, 'no_fetch_content_src', a boolean
indicating whether <content src> URLs should be automatically fetched
and added to the model as if inline content had been provided. They are
fetched by default, but it's pretty rare for feeds to include this attribute.
.Sp
\&\f(CW$storage\fR is an RDF::Trine::Storage object. If undef, then a new
temporary store is created.
.SS "Public Methods"
.IX Subsection "Public Methods"
.ie n .IP """uri""" 4
.el .IP \f(CWuri\fR 4
.IX Item "uri"
Returns the base URI of the document being parsed. This will usually be the
same as the base URI provided to the constructor.
.Sp
Optionally it may be passed a parameter \- an absolute or relative URI \- in
which case it returns the same URI which it was passed as a parameter, but
as an absolute URI, resolved relative to the document's base URI.
.Sp
This seems like two unrelated functions, but if you consider the consequence
of passing a relative URI consisting of a zero-length string, it in fact makes
sense.
.ie n .IP """dom""" 4
.el .IP \f(CWdom\fR 4
.IX Item "dom"
Returns the parsed XML::LibXML::Document.
.ie n .IP """graph""" 4
.el .IP \f(CWgraph\fR 4
.IX Item "graph"
This method will return an RDF::Trine::Model object with all
statements of the full graph.
.Sp
This method automatically calls \f(CW\*(C`consume\*(C'\fR.
.ie n .IP """root_identifier""" 4
.el .IP \f(CWroot_identifier\fR 4
.IX Item "root_identifier"
Returns the blank node or URI for the root element of the Atom
document as an RDF::Trine::Node
.Sp
Calls \f(CW\*(C`consume\*(C'\fR automatically.
.ie n .IP set_callbacks(\e%callbacks) 4
.el .IP \f(CWset_callbacks(\e%callbacks)\fR 4
.IX Item "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
For details of the callback functions, see the section CALLBACKS. \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.
.ie n .IP """consume""" 4
.el .IP \f(CWconsume\fR 4
.IX Item "consume"
The document is parsed. Triples extracted from the document are passed
to the callbacks as each one is found; triples are made available in the
model returned by the \f(CW\*(C`graph\*(C'\fR method.
.Sp
This function returns the parser object itself, making it easy to
abbreviate several of XML::Atom::OWL's functions:
.Sp
.Vb 2
\&  my $iterator = XML::Atom::OWL\->new(undef, $uri)
\&                 \->consume\->graph\->as_stream;
.Ve
.Sp
You probably only need to call this explicitly if you're using callbacks.
.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`XML::Atom::OWL\*(C'\fR object
.IP \(bu 4
A reference to the \f(CW\*(C`XML::LibXML::Element\*(C'\fR being parsed
.IP \(bu 4
Subject URI or bnode (string)
.IP \(bu 4
Predicate URI (string)
.IP \(bu 4
Object URI or bnode (string)
.IP \(bu 4
Graph URI or bnode (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 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`XML::Atom::OWL\*(C'\fR object
.IP \(bu 4
A reference to the \f(CW\*(C`XML::LibXML::Element\*(C'\fR being parsed
.IP \(bu 4
Subject URI or bnode (string)
.IP \(bu 4
Predicate URI (string)
.IP \(bu 4
Object literal (string)
.IP \(bu 4
Datatype URI (string or undef)
.IP \(bu 4
Language (string or undef)
.IP \(bu 4
Graph URI or bnode (string or undef)
.PP
Beware: sometimes both a datatype \fIand\fR a language will be passed. 
This goes beyond the normal RDF data model.)
.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`XML::Atom::OWL\*(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 BUGS
.IX Header "BUGS"
Please report any bugs to <http://rt.cpan.org/>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
RDF::Trine, XML::Atom::FromOWL.
.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 2010\-2011 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"
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.