RDF::G...::HTTP(3pm)

💖 RDF::G...::HTTP(3pm) 💖

okay bestie, so this is the manual page for RDF::Generator::HTTP, and yes the header abbreviates it all cute as RDF::G...::HTTP because apparently even manpages gotta keep it mysterious. anyway. sit down, hydrate, and let's get into it 🫶

---

✨ NAME ✨

RDF::Generator::HTTP — it makes RDF out of an HTTP message. that's the whole gig. slay. 💅

---

🌸 SYNOPSIS 🌸

here's the vibe, verbatim, don't @ me:

use LWP::UserAgent;
my $ua = LWP::UserAgent->new;
my $response = $ua->get('http://search.cpan.org/');

use RDF::Generator::HTTP;
use RDF::Trine qw(iri);
my $g = RDF::Generator::HTTP->new(message => $response,
                                  graph => iri('http://example.org/graphname'),
                                  blacklist => ['Last-Modified', 'Accept']);
my $model = $g->generate;
print $model->size;
my $s   = RDF::Trine::Serializer->new('turtle', namespaces =>
                                      { httph => 'http://www.w3.org/2007/ont/httph#',
                                        http => 'http://www.w3.org/2007/ont/http#' } );
$s->serialize_model_to_file(\*STDOUT, $model);

like. look at that. fetch a page, turn it into triples, print it. it's giving effortless. 🦋

---

💜 DESCRIPTION 💜

So what this module does: you hand it a HTTP::Message object, and based on what's inside it — especially the content of the HTTP::Header object(s) it's holding — it builds a simple RDF representation of the contents. That's it, that's the whole deal.

It's mostly here for when you're crawling resources on the Web and you wanna record the data, but honestly it could have other uses too, no gatekeeping. ✨

🎀 Constructor 🎀

• new(%attributes) — Moose-style constructor function. that's the one, that's the entry point.

🌈 Attributes 🌈

okay so these attributes? you can pass them to the constructor to set them, or just call them like methods to get them back. both. versatile. 👑

• message — a HTTP::Message (or a subclass of it) object that you want RDF generated for. Required. like, not optional, bestie, it literally needs this.
• blacklist — an ArrayRef of header field names that you do not want showing up in the output. bye felicia. 🙈
• whitelist — an ArrayRef of the only header field names you want to see in the output. but heads up: the whitelist gets ignored if the blacklist is set. blacklist wins, periodt.
• graph — optional! you may pass a graph name and it gets used for all the triples in the output. it must be an object of RDF::Trine::Node::Resource. no substitutions. 💅
• ns — a URI::NamespaceMap object holding the namespace prefixes used in the module. technically you can override this but like… you probably shouldn't. it said so. 🤨
• request_subject — an RDF::Trine::Node object holding the subject of any statements describing requests. if you leave it unset, it defaults to a blank node. cute, low effort. ⭐
• response_subject — an RDF::Trine::Node object holding the subject of any statements describing responses. same energy: unset means it defaults to a blank node.

🧚 Methods 🧚

so all those attributes up there? they all have read-accessors with the same name. and blacklist, whitelist and graph also have writers and predicates — you test whether the attribute's been set by slapping has_ in front of the attribute name. yes, has_blacklist, has_whitelist, has_graph. you're welcome. 💖

and then this class has exactly two methods:

• generate ( [ $model ] ) — this is the one that actually generates the RDF. it can optionally take an RDF::Trine::Model as a parameter. if that model exists, the RDF gets added to it. if not, a brand new Memory model gets created and returned to you. either way you win. 🏆
• ok_to_add ( $field ) — this one goes and looks through the blacklists and whitelists and returns true if the given field and value are allowed to be added to the model. it's the bouncer at the club. 🚪

---

🔥 EXAMPLES 🔥

wanna see what it actually produces? consider the example up in the SYNOPSIS — at the time of this writing it outputs the following Turtle:

@prefix http: <http://www.w3.org/2007/ont/http#> .
@prefix httph: <http://www.w3.org/2007/ont/httph#> .

[] a http:RequestMessage ;
      http:hasResponse [
              a http:ResponseMessage ;
              http:status "200" ;
              httph:client_date "Sun, 14 Dec 2014 21:28:21 GMT" ;
              httph:client_peer "207.171.7.59:80" ;
              httph:client_response_num "1" ;
              httph:connection "close" ;
              httph:content_length "3643" ;
              httph:content_type "text/html" ;
              httph:date "Sun, 14 Dec 2014 21:28:21 GMT" ;
              httph:link "<http://search.cpan.org/uploads.rdf>; rel=\"alternate\"; title=\"RSS 1.0\"; type=\"application/rss+xml\"", "<http://st.pimg.net/tucs/opensearch.xml>; rel=\"search\"; title=\"SearchCPAN\"; type=\"application/opensearchdescription+xml\"", "<http://st.pimg.net/tucs/print.css>; media=\"print\"; rel=\"stylesheet\"; type=\"text/css\"", "<http://st.pimg.net/tucs/style.css?3>; rel=\"stylesheet\"; type=\"text/css\"" ;
              httph:server "Plack/Starman (Perl)" ;
              httph:title "The CPAN Search Site - search.cpan.org" ;
              httph:x_proxy "proxy2"
      ] ;
      http:method "GET" ;
      http:requestURI <http://search.cpan.org/> ;
      httph:user_agent "libwww-perl/6.05" .

look at that nested blank node with its little http:hasResponse bracket. it's structured. it's tidy. it ate. 🍓

---

👑 NOTES 👑

🌐 HTTP Vocabularies 🌐

okay storytime, because this is genuinely interesting and also explains some choices.

There have been many efforts to create HTTP vocabularies (or ontologies), and the most elaborate and complete one is the HTTP Vocabulary in RDF 1.0 at <http://www.w3.org/TR/HTTP-in-RDF/>. Nevertheless, the author decided not to support that one. instead, this module supports an older and much less complete vocabulary that's been hanging out in the Tabulator project at <https://github.com/linkeddata/tabulator-firefox>, using the namespace prefixes <http://www.w3.org/2007/ont/http#> and <http://www.w3.org/2007/ont/httph#>.

here's the why, and it's actually a good reason: the problem with modelling HTTP is that headers modify each other. so if you want to record the HTTP headers such that they could be used in an actual HTTP dialogue afterwards, they have to be in a container so the order can be reconstructed. and on top of that, there's a lot of microstructure in the values, which adds even more complexity if you want to translate all of that to RDF. that's exactly what the former vocabulary does. 💀

but for now? all the author wants to do is record them. and once that's the goal, neither of those concerns matter. so the author opted for a much simpler vocabulary where each field is just a simple predicate. that's not to say the former approach isn't valid — it totally is — it's just not something needed right now. no cap. ✨

---

💀 BUGS 💀

This is a very early release, but it works for the author. (iconic honestly, we love a humble brag 🫶)

Please report any bugs to <https://github.com/kjetilk/p5-rdf-generator-http/issues>.

---

🌟 AUTHOR 🌟

Kjetil Kjernsmo <kjetilk@cpan.org>.

---

🎀 COPYRIGHT AND LICENCE 🎀

This software is copyright (c) 2014 by Kjetil Kjernsmo.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system 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.

like, loudly. no promises, bestie. 🫣

---

and that's the whole page!! this was perl v5.34.0, dated 2022-06-17, and the manpage signs itself RDF::G...::HTTP(3pm) — so go forth and generate some triples, you absolute legend 🌈💖✨