NAME
    XRD::Parser - Parse XRD files into RDF::Trine models

VERSION
    0.03

SYNOPSIS
      use RDF::Query;
      use XRD::Parser;
  
      my $parser = XRD::Parser->new(undef, "http://example.com/foo.xrd");
      $parser->consume;
  
      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->{'auth'}->uri . "\n";
      }

DESCRIPTION
    While XRD has a rather different history, it turns out it can mostly be
    thought of as a serialisation format for a limited subset of RDF.

    This package ignores the order of <Link> elements, as RDF is a graph
    format with no concept of statements coming in an "order". The XRD spec
    says that grokking the order of <Link> elements is only a SHOULD. That
    said, if you're concerned about the order of <Link> elements, the callback
    routines allowed by this package may be of use.

    This package aims to be roughly compatible with RDF::RDFa::Parser's
    interface.

    $p = XRD::Parser->new($content, $uri, \%options, $store);
            This method creates a new XRD::Parser object and returns it.

            The $content variable may contain an XML 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.

            $uri the supposed URI of the content; it is used to resolve any
            relative URIs found in the XRD document. Also, if $content is
            empty, then XRD::Parser will attempt to retrieve $uri using
            LWP::Simple.

            Options [default in brackets]:

              * tdb_service     - thing-described-by.org when possible. [0]

            $storage is an RDF::Trine::Storage object. If undef, then a new
            temporary store is created.

    $p = XRD::Parser->hostmeta($uri);
            This method creates a new XRD::Parser object and returns it.

            The parameter may be a URI (from which the hostname will be
            extracted) or just a bare host name (e.g. "example.com"). The
            resource "/.well-known/host-meta" will then be fetched from that
            host using an appropriate HTTP Accept header, and the parser
            object returned.

    $p->uri Returns the base URI of the document being parsed. This will
            usually be the same as the base URI provided to the constructor.

            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.

            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.

    $p->dom Returns the parsed XML::LibXML::Document.

    $p->set_callbacks(\&func1, \&func2)
            Set callbacks for handling RDF triples extracted from the
            document. The first function is called when a triple is generated
            taking the form of (*resource*, *resource*, *resource*). The
            second function is called when a triple is generated taking the
            form of (*resource*, *resource*, *literal*).

            The parameters passed to the first callback function are:

            *   A reference to the "XRD::Parser" object

            *   A reference to the "XML::LibXML element" being parsed

            *   Subject URI or bnode

            *   Predicate URI

            *   Object URI or bnode

            The parameters passed to the second callback function are:

            *   A reference to the "XRD::Parser" object

            *   A reference to the "XML::LibXML element" being parsed

            *   Subject URI or bnode

            *   Predicate URI

            *   Object literal

            *   Datatype URI (possibly undef or '')

            *   Language (possibly undef or '')

            In place of either or both functions you can use the string
            'print' which sets the callback to a built-in function which
            prints the triples to STDOUT as Turtle. Either or both can be set
            to undef, in which case, no callback is called when a triple is
            found.

            Beware that for literal callbacks, sometimes both a datatype *and*
            a language will be passed. (This goes beyond the normal RDF data
            model.)

            "set_callbacks" (if used) must be used *before* "consume".

    $p->consume;
            This method processes the input DOM and sends the resulting
            triples to the callback functions (if any).

    $p->graph()
            This method will return an RDF::Trine::Model object with all
            statements of the full graph.

            It makes sense to call "consume" before calling "graph". Otherwise
            you'll just get an empty graph.

SEE ALSO
    RDF::Trine, RDF::Query, RDF::RDFa::Parser.

    <http://www.perlrdf.org/>.

AUTHOR
    Toby Inkster, <tobyink@cpan.org>

COPYRIGHT AND LICENSE
    Copyright (C) 2009 by Toby Inkster

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself, either Perl version 5.8.1 or, at your
    option, any later version of Perl 5 you may have available.

