RDF::a...ncoder(3pm)

💖 RDF::a...ncoder — the manual page, but make it cute 💖

okay bestie, gather round, because we're talking about RDF::a...ncoder (yes that's the short name, it's RDF::aREF::Encoder, the fancy version) and it lives in the User Contributed Perl Documentation section, aka the 3pm girlies. it's literally a Perl module. periodt. 🎀

---

✨ NAME ✨

RDF::aREF::Encoder — encode RDF to another RDF Encoding Form. that's it, that's the whole job description, she's an encoder and she eats. 💅

---

🌸 SYNOPSIS 🌸

here's the whole vibe, no notes, copy it exactly:

use RDF::aREF::Encoder;
my $encoder = RDF::aREF::Encoder->new;

# encode parts of aREF

my $qname  = $encoder->qname('http://schema.org/Review'); # 'schema_Review'

my $predicate = $encoder->predicate({
    type  => 'uri',
    value => 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type'
}); # 'a'

my $object = $encoder->object({
    type  => 'literal',
    value => 'hello, world!',
    lang  => 'en'
}); # 'hello, world!@en'

# method also accepts RDF::Trine::Node instances
my $object = $encoder->object( RDF::Trine::Resource->new($iri) );

# encode RDF graphs (see also function 'encode_aref' in RDF::aREF)
use RDF::Trine::Parser;
my $aref = { };
RDF::Trine::Parser->parse_file ( $base_uri, $fh, sub {
    my $s = shift;
    $encoder->triple( $s->subject, $s->predicate, $s->object, $aref );
} );

look at her go 🦋

---

💜 DESCRIPTION 💜

so this module hands you the methods to encode RDF data in another RDF Encoding Form, aka aREF. and here's the tea 🫖: aREF was designed to make creating RDF data easier, which means it may genuinely be easier to just create aREF "by hand" instead of using this module. no cap. she said it herself. 😭

---

👑 OPTIONS 👑

🌈 ns

a default namespace map, bestie. you can hand it over either as a version string of module RDF::NS (for those stable qNames ✨) or as an instance of RDF::NS.

by default she uses the most recent installed version of RDF::NS. and if you pass the value 0, you only get the required namespace mappings, which are rdf, rdfs, owl and xsd. minimalism, she's serving it. 🎀

🦋 subject_map

by default, RDF graphs that share a common subject get encoded as an aREF predicate map, like this:

{
   _id => $subject, $predicate => $object
}

enable this option and she'll always encode as an aREF subject map instead:

{
    $subject => { $predicate => $object }
}

two different fits, both slay. 💅

---

⭐ METHODS ⭐

⚠️ okay important bestie: no syntax checking is applied. like, none. not "is this a valid URI", not "is this a valid language tag". she trusts you. be trustworthy. 😭

💖 qname( $uri )

abbreviate a URI as a qName, or return "undef" if she can't. for instance http://purl.org/dc/terms/title gets abbreviated to "dct_title". obsessed. ✨

💖 uri( $uri )

abbreviate a URI as a qName, or wrap it up in angular brackets. her choice, honestly. 🫶

💖 literal( $value, $language_tag, $datatype_uri )

encode a literal RDF node. she either appends "@" plus an optional language tag, or "^" plus a datatype URI. iconic behaviour. 🌸

💖 bnode( $identifier )

encode a blank node by prepending "_:" to its identifier. simple, clean, done. 💅

💖 subject( $subject ) , predicate( $predicate ) , object( $object )

encode an RDF subject, predicate, or object respectively. the argument has to come in one of two flavours:

• a hash reference, as defined in the RDF/JSON format (<http://www.w3.org/TR/rdf-json/>) — see also the method "as_hashref" of RDF::Trine::Model
• or an array reference, as internally used by RDF::Trine

🧚 a hash reference is expected to have these fields:

• type — one of "uri", "literal" or "bnode". this one is required, no skipping. 👑
• value — the URI of the object, its lexical value, or a blank node label, depending on whether the object is a uri, literal or bnode
• lang — the language of a literal value. optional, but if you supply it, it must not be empty. she will notice. 🙈
• datatype — the datatype URI of the literal value. optional.

🧚 and an array reference is expected to consist of:

• three elements — (value, language tag, and datatype uri) — for literal nodes
• two elements — "URI" and the URI — for URI nodes
• two elements — "BLANK" and the blank node identifier — for blank nodes

🔥 triple( $subject, $predicate, $object, [, $aref ] )

encode an RDF triple, with its elements given exactly as explained for the methods "subject", "predicate", and "object".

and here's the fun part: if you pass an aREF data structure as the fourth argument, the triple gets added to that structure, and it might even change an aREF predicate map into an aRef subject map. glow-up moment. ✨

returns "undef" on failure. 😭

🌟 add_hashref( $aref, $rdf )

add RDF that's given in RDF/JSON format (<http://www.w3.org/TR/rdf-json/>), as returned by the method "as_hashref" in RDF::Trine::Model. 🫶

🌟 add_iterator( $aref, $iterator )

add a RDF::Trine::Iterator to an aREF subject map.

experimental — she said what she said, proceed with cute caution. 🧚

---

🌈 SEE ALSO 🌈

• RDF::aREF::Decoder
• RDF::Trine::Node

go read your sisters, they're all iconic. 💜

---

and that's the whole page, bestie!! this little masterpiece comes to you from the User Contributed Perl Documentation crew, she's running perl v5.36.0, and this version is dated 2022-12-07. 💖✨🎀 mwah, go encode something gorgeous. 🦋