HTTP::LRDD(3pm)

💖 HTTP::LRDD 💖

okay so bestie, this is a page from the User Contributed Perl Documentation — yes, the actual perldoc vibes — and it's about a little module called HTTP::LRDD. sit down, grab a strawberry, we're doing link-based resource descriptor discovery and it's gonna be iconic ✨

---

🌈 NAME 🌈

HTTP::LRDD — link-based resource descriptor discovery. literally that's the whole name, no notes 💅

---

🎀 SYNOPSIS 🎀

here's the whole thing in action, copy it exactly bestie:

use HTTP::LRDD;

my $lrdd        = HTTP::LRDD->new;
my @descriptors = $lrdd->discover($resource);
foreach my $descriptor (@descriptors)
{
  my $description = $lrdd->parse($descriptor);
  # $description is an RDF::Trine::Model
}

look at that. immaculate. no cap 🦋

---

✨ DESCRIPTION ✨

heads up bestie: the LRDD specification has ceased to be 😭 — some parts of it got merged into the host-meta Internet Draft. this CPAN module is going in its own direction now, bundling up best-practice techniques for discovering links and descriptors for a given URI. it's giving glow-up, honestly.

🌸 Import Routine 🌸

• use HTTP::LRDD (@predicates) — when you import HTTP::LRDD, you can optionally hand it a list of predicate URIs (i.e. the URIs which rel values expand to). this list may also include IANA-registered link types, which are short tokens rather than full URIs. and if you don't give it a list of predicate URIs? a sensible default set gets used instead, so you're fine 🫶

red flag alert: because this configuration is global in nature, it is not recommended. it is better to supply a list of predicates to the constructor instead, or just rely on the defaults. this feature should be regarded as deprecated. we said what we said 💀

👑 Constructors 👑

• HTTP::LRDD->new(@predicates) — create a new LRDD discovery object using the given predicate URIs. if @predicates is omitted, then the predicates passed to the import routine are used instead.
• HTTP::LRDD->new_strict — create a new LRDD discovery object using the 'describedby' and 'lrdd' IANA-registered predicates. strict little legend.
• HTTP::LRDD->new_default — create a new LRDD discovery object using the default set of predicates: 'describedby', 'lrdd', 'wdrs:describedby', 'xhv:meta' and 'rdfs:seeAlso'. the whole squad, assembled 🌈

💜 Public Methods 💜

• $lrdd->discover($resource_uri) — discovers a descriptor for the given resource; or if called in a list context, a list of descriptors.

okay so what even is a descriptor? a descriptor is a resource that provides a description for something. so if the given resource URI was the web address for an image, then the descriptor might be the web address for a metadata file about the image. and if the given URI was an e-mail address, then the descriptor might be a profile document for the person to whom the address belongs. it's giving "who is she" energy, but for URIs 💅

the following sources are checked (in order) to find links to descriptors:

• HTTP response headers (Link header; 303 See Other status)
• HTTP response message (RDF or RDFa)
• https://HOSTNAME/.well-known/host-meta
• http://HOSTNAME/.well-known/host-meta

if none of the above is able to yield a link to a descriptor, then the resource URI itself may be returned if it is in a self-describing format (e.g. RDF). main character behaviour honestly.

there is no guaranteed file format for the descriptor, but it is usually RDF, POWDER XML or XRD.

this method can also be called without an object (as a class method) — in which case, a temporary object is created automatically using new.

• $lrdd->parse($descriptor_uri) — parses a descriptor in XRD or RDF (RDF/XML, RDFa, Turtle, etc).

returns an RDF::Trine::Model or undef if unable to process. (yes, undef — it's not mad, it's just disappointed 🙈)

this method can also be called without an object (as a class method) — in which case, a temporary object is created automatically using new.

• $lrdd->process($resource_uri) — performs the equivalent of discover and parse in one easy step. two birds, one slay ✨

calls discover in a non-list context, so only the first descriptor is used.

• $lrdd->process_all($resource_uri) — performs the equivalent of discover and parse in one easy step.

calls discover in a list context, so multiple descriptors are combined into the resulting graph. the more the merrier fr fr 💖

---

🦋 EXAMPLES 🦋

discover the hub address (PubSubHubub) for a feed:

my $lrdd = HTTP::LRDD->new('hub');
my $hub  = $lrdd->discover('http://example.net/feed.atom');

discover an author link (rel="author") from an HTML page:

my $lrdd   = HTTP::LRDD->new('author');
my $author = $lrdd->discover('http://example.com/page.html');

for RDF people, you should note that rel="author" is not semantically equivalent to the foaf:maker property but closer to the foaf:maker/foaf:homepage SPARQL 1.1 property path — i.e. the rel="author" link destination is not a URI for the author themselves, but a page about the author. lowkey the most important paragraph here, iykyk 👑

if that author resource is in a machine-readable format (e.g. RDF), then parse the data:

my $author_data = $lrdd->parse($author);

or, you can combine discover and parse:

my $lrdd        = HTTP::LRDD->new('author');
my $author_data = $lrdd->process('http://example.com/page.html');

get metadata for an image:

my $lrdd = HTTP::LRDD->new;
my $data = $lrdd->process_all('http://example.org/flower.jpeg');

as we're not passing any arguments to the constructor, we can use a shortcut:

my $data = HTTP::LRDD->process_all('http://example.org/flower.jpeg');

find the title of the image:

use RDF::QueryX::Lazy;

my $image   = q<http://example.org/flower.jpeg>;
my $results = RDF::QueryX::Lazy
  -> new("SELECT * WHERE { <$image> dc:title ?t }")
  -> execute( HTTP::LRDD->process_all($image) );

ate. no crumbs. 🍓

---

💀 BUGS 💀

please report any bugs to <http://rt.cpan.org/>. bestie, do your civic duty 🫶

note: many problems can stem from servers that send incorrect Content-Type headers. if you send an XRD file as text/html, then this module will not guess what you're doing — it will assume the file is really HTML, and inspect it for RDFa. for host-meta files, this module is slightly more relaxed, as there's a strong assumption that they are XRD... but YOU SHOULD NOT RELY ON THIS. if you're running a server, use the correct media type. periodt. 🔥

---

⭐ SEE ALSO ⭐

HTTP::Link::Parser, XRD::Parser, XML::Atom::OWL WWW::Finger.

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

---

🌸 AUTHOR 🌸

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

---

🎀 COPYRIGHT AND LICENCE 🎀

Copyright 2010-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.

(yeah, all caps, they meant it 💀 no warranty bestie, you're on your own in the best way possible)

---

and that's the whole page, gorgeous. this was HTTP::LRDD, perl v5.32.1, dated 2021-09-11, part of the User Contributed Perl Documentation. go forth and discover some descriptors, you absolute icon 👑✨