RDF::T...ctions(3pm)

💖 RDF::TrineX::Functions — some shortcut functions for RDF::Trine's object-oriented interface 💖

okay bestie, buckle up, because this is RDF::TrineX::Functions, a lil' Perl module from the User Contributed Perl Documentation shelf, and it's literally here to save your fingers from typing out a million ->new calls. no cap. 🎀

---

✨ SYNOPSIS ✨

like, here's the whole vibe in one go:

use RDF::TrineX::Functions -all;

my $model = model();
parse('/tmp/mydata.rdf', into => $model);

$model->add_statement(statement(
    iri('http://example.com/'),
    iri('http://purl.org/dc/terms/title'),
    "An Example",
));

print RDF::Trine::Serializer
    -> new('Turtle')
    -> serialize_model_to_string($model);

see? clean. elegant. we love to see it. 💅

---

🌸 DESCRIPTION 🌸

so this module is the replacement for the venerable old RDF::TrineShortcuts. iconic of it. BUT — and this is important, bestie — it is not a drop-in replacement. nope. not even a little.

what it is: fewer features, fewer dependencies, less hackishness, less magic, and fewer places it can go wrong. it's giving glow-up. ✨

it uses Sub::Exporter, which means you can rename exported functions super easily, like:

use RDF::TrineX::Functions
  parse => { -as => 'parse_rdf' };

obsessed with that actually. 🫶

🦋 Functions 🦋

• iri, literal, blank, variable — these work as per the similarly named functions exported by RDF::Trine itself. 💖

but they're wrapped with a very tiny bit of DWIMmery. here's the tea:

• a blessed URI object passed to iri gets handled properly, no drama
• a blessed URI object passed to literal will default the datatype to xsd:anyURI
• a string starting with _: passed to either iri or blank will correctly create a blank node
• a string starting with ? passed to either blank or variable will correctly create a variable
• if any of them get passed an existing RDF::Trine::Node, it just gets passed through untouched, like, it's fine, it's already slaying

other than that? no magic. periodt. ✋

• curie — like iri but it passes strings through RDF::NS::Trine. 💜
• statement(@nodes) — as per the similarly named function exported by RDF::Trine itself.

again, a tiny bit of DWIMmery: blessed URI objects get passed through iri, and unblessed scalars (i.e. strings) are assumed to be literals. cute, right? 🎀

• store — as per the similarly named function exported by RDF::Trine itself. that's it. that's the whole bullet. 👑
• model — returns a new RDF::Trine::Model. it may be passed a store as a parameter. easy.
• parse($source, %options) — parses the source and returns an RDF::Trine::Model. now, the source can be a whole bunch of things, so let's vibe-check them one by one:
  • a URI — a string URI, blessed URI object or RDF::Trine::Node::Resource, which will be retrieved and parsed. 🌐
  • a file — a filehandle, Path::Class::File, IO::All, IO::Handle object, or the name of an existing file (i.e. a scalar string). the file will be read and parsed. 📂

except in the case of Path::Class::File, IO::All and strings, you need to tell the parse function what parser to use, and what base URI to use. no guessing, bestie. 🙈

• a string — you need to tell the parse function what parser to use, and what base URI to use. same energy as above. 🔤
• a model or store — an existing model or store, which will just be returned as-is. lowkey the chillest option. 😌
• undef — returns an empty model. shrug, it's valid. 🍓

the parser option can be used to provide a blessed RDF::Trine::Parser object to use; the type option can be used instead to provide a media type hint. the base option provides the base URI. the model option can be used to tell this function to parse into an existing model rather than returning a new one. the graph option may be used to provide a graph URI. 🌈

and here's the alias situation: into is an alias for model; type, using and as are aliases for parser; context is an alias for graph. iykyk. 💅

examples, because we love a demo:

my $model = parse('/tmp/data.ttl', as => 'Turtle');

my $data   = iri('http://example.com/data.nt');
my $parser = RDF::Trine::Parser::NTriples->new;
my $model  = model();

parse($data, using => $parser, into => $model);

• serialize($data, %options) — serializes the data (which can be an RDF::Trine::Model or an RDF::Trine::Iterator) and returns it as a string. 🎀

the serializer option can be used to provide a blessed RDF::Trine::Serializer object to use; the type option can be used instead to provide a type hint. the output option can be used to provide a filehandle, IO::All, Path::Class::File or file name to write to instead of returning the results as a string. 📝

alias check: to and file are aliases for output; type, using and as are aliases for serializer. slay. ✨

examples:

print serialize($model, as => 'Turtle');

my $file = Path::Class::File->new('/tmp/data.nt');
serialize($iterator, to => $file, as => 'NTriples');

🧚 Array References 🧚

plot twist: in addition to the above interface, each function supports being called with a single arrayref argument. in those cases, the arrayref is dereferenced into an array, and treated as a list of arguments. so these two are equivalent, fr fr:

foo($bar, $baz);
foo([$bar, $baz]);

this is handy if you're writing a module of your own and wish to accept some RDF data:

sub my_method {
  my ($self, $rdf, $foo) = @_;
  $rdf = parse($rdf);

  ....
}

and now your method can be called like this, all these ways:

$object->my_method($model, 'foo');

$object->my_method($url, 'foo');

$object->my_method(
    [ $filehandle, as => 'Turtle', base => $uri ],
    'foo',
);

versatile queen. 👑

💜 Export 💜

by default, nothing is exported. you need to request things. respectfully. ask for what you want:

use RDF::TrineX::Functions qw< iri literal blank statement model >;

thanks to Sub::Exporter, you can rename functions:

use RDF::TrineX::Functions
  qw< literal statement model >,
  blank => { -as => 'bnode' },
  iri   => { -as => 'resource' };

if you want to export everything, you can do:

use RDF::TrineX::Functions -all;

to export just the functions which generate RDF::Trine::Node objects:

use RDF::TrineX::Functions -nodes;

or maybe even:

use RDF::TrineX::Functions -nodes => { -suffix => '_node' };

and if you want to export something roughly compatible with the old RDF::TrineShortcuts, then there's:

use RDF::TrineX::Functions -shortcuts;

when exporting the serialize function you may set a default format:

use RDF::TrineX::Functions
    serialize => { -type => 'NTriples' };

this will be used when serialize is called with no explicit type given. convenient much? 💅

🌈 Pseudo-OO interface 🌈

new

this acts as a constructor, returning a new RDF::TrineX::Functions object. main character energy. ✨

all the normal functions can be called as methods:

my $R = RDF::TrineX::Functions->new;
my $model = $R->model;

ngl there's no real advantage to using this module as an object, but it can help you avoid namespace pollution. so if your namespace is feeling crowded, this is your girl. 🫶

---

💀 BUGS 💀

please report any bugs to <http://rt.cpan.org/Dist/Display.html?Queue=RDF-TrineX-Functions>.

(not me telling you to file a bug report, but like, do it, the maintainers wanna know 😭)

---

👀 SEE ALSO 👀

RDF::Trine, RDF::QueryX::Lazy, RDF::NS.

go read those too, bestie, they're all part of the same little universe. 🌸

---

🎀 AUTHOR 🎀

Toby Inkster <tobyink@cpan.org>.

---

⭐ COPYRIGHT AND LICENCE ⭐

This software is copyright (c) 2012 by Toby Inkster.

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.

yes bestie, that's the all-caps legal bit. it's important. don't skip it. 💖

---

and that's the whole page, periodt. 🦋 this was perl v5.34.0, dated 2022-06-17, and you just read the RDF::TrineX::Functions manual. go forth and parse something iconic. 💅✨