NAME¶
RDF::TrineX::Functions - some shortcut functions for RDF::Trine's
object-oriented interface
SYNOPSIS¶
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);
DESCRIPTION¶
This is a replacement for the venerable RDF::TrineShortcuts. Not a drop-in
replacement. It has fewer features, fewer dependencies, less hackishness, less
magic and fewer places it can go wrong.
It uses Sub::Exporter, which allows exported functions to be renamed easily:
use RDF::TrineX::Functions
parse => { -as => 'parse_rdf' };
Functions¶
- "iri", "literal", "blank",
"variable"
- As per the similarly named functions exported by RDF::Trine
itself.
These are wrapped with a very tiny bit of DWIMmery. A blessed URI object
passed to "iri" will be handled properly; 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 are
passed an existing RDF::Trine::Node, it will be passed through untouched.
Other than that, no magic.
- "curie"
- Like "iri" but 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 are passed through
"iri" and unblessed scalars (i.e. strings) are assumed to be
literals.
- "store"
- As per the similarly named function exported by RDF::Trine
itself.
- "model"
- Returns a new RDF::Trine::Model. May be passed a store as a
parameter.
- "parse($source, %options)"
- Parses the source and returns an RDF::Trine::Model. The
source may be:
- •
- 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 an 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.
- •
- a string
You need to tell the "parse" function what parser to use, and what
base URI to use.
- •
- a model or store
An existing model or store, which will just be returned as-is.
- •
- undef
Returns an empty model.
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.
"into" is an alias for "model"; "type",
"using" and "as" are aliases for "parser".
Examples:
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.
"to" and "file" are aliases for "output";
"type", "using" and "as" are aliases for
"serializer".
Examples:
print serialize($model, as => 'Turtle');
my $file = Path::Class::File->new('/tmp/data.nt');
serialize($iterator, to => $file, as => 'NTriples');
Array References¶
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. That is, the following are
equivalent:
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);
....
}
Your method can now be called like this:
$object->my_method($model, 'foo');
$object->my_method($url, 'foo');
$object->my_method(
[ $filehandle, as => 'Turtle', base => $uri ],
'foo',
);
Export¶
By default, nothing is exported. You need to request things:
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' };
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.
Pseudo-OO interface¶
- "new"
- This acts as a constructor, returning a new
RDF::TrineX::Functions object.
All the normal functions can be called as methods:
my $R = RDF::TrineX::Functions->new;
my $model = $R->model;
There's no real advantage to using this module as an object, but it can help you
avoid namespace pollution.
BUGS¶
Please report any bugs to
http://rt.cpan.org/Dist/Display.html?Queue=RDF-TrineX-Functions
<
http://rt.cpan.org/Dist/Display.html?Queue=RDF-TrineX-Functions>.
SEE ALSO¶
RDF::Trine, RDF::QueryX::Lazy, RDF::NS.
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.