NAME

       XML::GRDDL - transform XML and XHTML to RDF

SYNOPSIS

       High-level interface:

        my $grddl = XML::GRDDL->new;
        my $model = $grddl->data($xmldoc, $baseuri);
        # $model is an RDF::Trine::Model

       Low-level interface:

        my $grddl = XML::GRDDL->new;
        my @transformations = $grddl->discover($xmldoc, $baseuri);
        foreach my $t (@transformations)
        {
          # $t is an XML::GRDDL::Transformation
          my ($output, $mediatype) = $t->transform($xmldoc);
          # $output is a string of type $mediatype.
        }

DESCRIPTION

       GRDDL is a W3C Recommendation for extracting RDF data from arbitrary XML and XHTML via a transformation,
       typically written in XSLT. See <http://www.w3.org/TR/grddl/> for more details.

       This module implements GRDDL in Perl. It offers both a low level interface, allowing you to generate a
       list of transformations associated with the document being processed, and thus the ability to selectively
       run the transformation; and a high-level interface where a single RDF model is returned representing the
       union of the RDF graphs generated by applying all available transformations.

   Constructor
       "XML::GRDDL->new"
           The constructor accepts no parameters and returns an XML::GRDDL object.

   Methods
       "$grddl->discover($xml, $base, %options)"
           Processes the document to discover the transformations associated with it. $xml is the raw XML source
           of  the  document,  or  an  XML::LibXML::Document object. ($xml cannot be "tag soup" HTML, though you
           should be able to use HTML::HTML5::Parser to parse tag soup into an XML::LibXML::Document.) $base  is
           the base URI for resolving relative references.

           Returns a list of XML::GRDDL::Transformation objects.

           Options include:

           •   force_rel  -  boolean;  interpret  XHTML  rel="transformation"  even  in the absence of the GRDDL
               profile.

           •   strings - boolean; return a list of plain strings instead of blessed objects.

       "$grddl->data($xml, $base, %options)"
           Processes the document, discovers the transformations associated with it, applies the transformations
           and merges the results into a single RDF model. $xml and $base are as per "discover".

           Returns an RDF::Trine::Model containing the data. Statement contexts (a.k.a. named  graphs  /  quads)
           are used to distinguish between data from the result of each transformation.

           Options include:

           •   force_rel  -  boolean;  interpret  XHTML  rel="transformation"  even  in the absence of the GRDDL
               profile.

           •   metadata - boolean; include provenance information in the default graph (a.k.a. nil context).

       "$grddl->ua( [$ua] )"
           Get/set the user agent used for HTTP requests. $ua, if supplied, must be an LWP::UserAgent.

   Constants
       These constants may be exported upon request.

       "GRDDL_NS"
       "XHTML_NS"

FEATURES

       XML::GRDDL supports transformations written in XSLT 1.0, and in RDF-EASE.

       XML::GRDDL is a good HTTP citizen: Referer headers are  included  in  requests,  and  appropriate  Accept
       headers  supplied.  To be an even better citizen, I recommend changing the User-Agent header to advertise
       the name of the application:

        $grddl->ua->default_header(user_agent => 'MyApp/1.0 ');

       Provenance  information  for  GRDDL  transformations  is  returned  using   the   GRDDL   vocabulary   at
       <http://www.w3.org/2003/g/data-view#>.

       Certain XHTML profiles and XML namespaces known not to contain any transformations, or to contain useless
       transformations are skipped. See XML::GRDDL::Namespace and XML::GRDDL::Profile for details. In particular
       profiles  for  RDFa  and  many Microformats are skipped, as RDF::RDFa::Parser and HTML::Microformats will
       typically yield far superior results.

BUGS

       Please report any bugs to <http://rt.cpan.org/>.

       Known limitations:

       •   Recursive GRDDL doesn't work yet.

           That is, the profile documents and namespace documents linked to from your  primary  document  cannot
           themselves rely on GRDDL.

SEE ALSO

       XML::GRDDL::Transformation,                  XML::GRDDL::Namespace,                  XML::GRDDL::Profile,
       XML::GRDDL::Transformation::RDF_EASE::Functional, XML::Saxon::XSLT2.

       HTML::HTML5::Parser, RDF::RDFa::Parser, HTML::Microformats.

       JSON::GRDDL.

       <http://www.w3.org/TR/grddl/>.

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

       This module is derived from Swignition <http://buzzword.org.uk/swignition/>.

AUTHOR

       Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

       Copyright 2008-2012 Toby Inkster

       This library is free software; you can redistribute it and/or modify it under  the  same  terms  as  Perl
       itself.

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.

perl v5.32.1                                       2021-09-19                                    XML::GRDDL(3pm)