XML::GRDDL(3pm)

📦
version 0.004 · 3 versions
, in debian bookworm, ubuntu jammy, ubuntu noble

✨ NAME ✨

XML::GRDDL — transform XML and XHTML to RDF 💫

okay so bestie, this is the XML::GRDDL(3pm) page and honestly? it's giving magic. you feed it XML or XHTML, it hands you back RDF. that's the whole vibe. no cap. 🦋

🎀 SYNOPSIS 🎀

so there's two ways to run this. high-level, where you just want the data and you're not tryna micromanage:

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

and low-level, where you want ✨control✨:

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.
}

lowkey obsessed with how clean that is. 💅

💜 DESCRIPTION 💜

GRDDL is a W3C Recommendation for extracting RDF data from arbitrary XML and XHTML via a transformation — typically written in XSLT. if you want the full tea, it's at <http://www.w3.org/TR/grddl/>. go read it, i'll wait. 🫶

This module implements GRDDL in Perl. bestie it gives you both:

  • a low-level interface, where you generate a list of transformations associated with the document being processed, so you can selectively run whichever ones you want — main character energy, you choose;
  • a high-level interface, where a single RDF model comes back to you, and it's literally the union of the RDF graphs generated by applying all available transformations. one model. slay.

🌸 Constructor

  • XML::GRDDL->new — The constructor accepts no parameters and returns an XML::GRDDL object. that's it. no options, no drama, no config. iconic behaviour fr fr.

🦋 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. and ngl, $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. so like, everything stays in its own lane. 🙈

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. versatility? we have it. 💅

XML::GRDDL is a good HTTP citizen: Referer headers are included in requests, and appropriate Accept headers supplied. and if you wanna be an even better citizen, the author recommends 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. not us being self-aware and delegating to the specialists 💀

😭 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. so it's giving "one layer only bestie", we're working on it. 🙈

🌈 SEE ALSO 🌈

👑 AUTHOR 👑

Toby Inkster <tobyink@cpan.org>. legend behaviour honestly. 🫶

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.

(read that one dramatically, bestie. it's the legal equivalent of "no promises, we're all just vibing" 😭)

and that's the whole page! this one's from perl v5.32.1, dated 2021-09-19, and it's the XML::GRDDL(3pm) manual. mwah, go transform something. 💅✨

📦 where this page comes from