modules/rdf/term.zzm

=encoding utf8

=head1 NAME

rdf/term - RDF terms and quads.

=head1 SYNOPSIS

  from rdf/term import rdf_iri, rdf_literal, rdf_quad;
  
  let quad := rdf_quad(
      rdf_iri("http://example.com/s"),
      rdf_iri("http://example.com/p"),
      rdf_literal("value"),
  );


=head1 DESCRIPTION

This module defines value objects for RDF IRIs, blank nodes, literals,
the default graph, and RDF quads. It also provides constructors and stable
term keys suitable for comparison, hashing, storage, and test output.

=head1 EXPORTS

=head2 Constants

=over

=item C<RDF_NS>

The RDF namespace IRI.

=item C<XSD_NS>

The XML Schema namespace IRI.

=item C<DEFAULT_GRAPH_KEY>

The canonical key used for the default graph.

=back

=head2 Classes

=over

=item C<RDFIRI>

An RDF IRI term. Construct with C<new RDFIRI(value: iri)> or use
C<rdf_iri>. C<get_value> returns the IRI string. C<to_String> returns
the N-Triples-style angle-bracket form.

=item C<RDFBlank>

An RDF blank node term. C<get_value> returns the blank node label.

=item C<RDFLiteral>

An RDF literal term. C<get_value>, C<get_lang>, and C<get_datatype>
return the lexical form, lowercased language tag, and datatype IRI. If no
datatype is supplied, plain literals use C<xsd:string> and language
literals use C<rdf:langString>.

=item C<RDFDefaultGraph>

The default graph marker used by quads when no graph is supplied.

=item C<RDFQuad>

A subject, predicate, object, and graph tuple. C<get_subject>,
C<get_predicate>, C<get_object>, and C<get_graph> return the components.
C<to_Array> returns them in quad order.

=item C<RDFError>, C<RDFSyntaxError>, C<RDFStoreError>, C<SPARQLError>

Exception classes used by the RDF parsers, store, and SPARQL modules.

=back

=head2 Functions

=over

=item C<< rdf_iri(String value) >>

Returns an C<RDFIRI>.

=item C<< rdf_blank(String value) >>

Returns an C<RDFBlank>.

=item C<< rdf_literal(value, String lang := "", datatype := null) >>

Returns an C<RDFLiteral>. C<value> is stringified. C<lang> and
C<datatype> are optional.

=item C<< rdf_default_graph() >>

Returns an C<RDFDefaultGraph>.

=item C<< rdf_quad(subject, predicate, object, graph?) >>

Returns an C<RDFQuad>. The graph defaults to C<rdf_default_graph()>.

=item C<< rdf_term_kind(term) >>

Returns C<iri>, C<blank>, C<literal>, or C<default>. Throws if C<term>
is not an RDF term.

=item C<< rdf_term_key(term) >>

Returns a stable string key for exact term identity.

=item C<< rdf_term_hash(term) >>

Returns a SHA-256 hash of C<rdf_term_key(term)>.

=item C<< rdf_term_equals(left, right) >>

Returns true when two RDF terms have the same key.

=back

=head1 COPYRIGHT AND LICENCE

B<< rdf/term >> is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under
the terms of either the Artistic License 1.0 or the GNU General Public
License version 2.

=cut

from std/digest/sha import sha256_hex;
from std/string import replace;

const RDF_NS := "http://www.w3.org/1999/02/22-rdf-syntax-ns#";
const XSD_NS := "http://www.w3.org/2001/XMLSchema#";
const DEFAULT_GRAPH_KEY := "G|";

function rdf_iri;
function rdf_default_graph;
function rdf_term_key;

class RDFError extends Exception;
class RDFSyntaxError extends RDFError;
class RDFStoreError extends RDFError;
class SPARQLError extends RDFError;

class RDFIRI {
	let String value with get := "";

	method to_String () {
		return "<" _ value _ ">";
	}
}

class RDFBlank {
	let String value with get := "";

	method to_String () {
		return "_:" _ value;
	}
}

class RDFLiteral {
	let String value with get := "";
	let String lang with get := "";
	let datatype with get := null;

	method __build__ () {
		lang := lc(lang) if lang ne "";
		datatype := rdf_iri(lang ne "" ? RDF_NS _ "langString" : XSD_NS _ "string")
			if datatype == null;
	}

	method to_String () {
		let out := "\"" _ value _ "\"";
		out _= "@" _ lang if lang ne "";
		if ( lang eq "" and not (datatype == null) and rdf_term_key(datatype) ne
			rdf_term_key(rdf_iri(XSD_NS _ "string")) ) {
			out _= "^^" _ datatype.to_String();
		}
		return out;
	}
}

class RDFDefaultGraph {
	method to_String () {
		return "#default";
	}
}

class RDFQuad {
	let subject with get := null;
	let predicate with get := null;
	let object with get := null;
	let graph with get := null;

	method __build__ () {
		graph := rdf_default_graph() if graph == null;
	}

	method to_Array () {
		return [ subject, predicate, object, graph ];
	}
}

function rdf_iri ( String value ) {
	return new RDFIRI(value: value);
}

function rdf_blank ( String value ) {
	return new RDFBlank(value: value);
}

function rdf_literal ( value, String lang := "", datatype := null ) {
	return new RDFLiteral(value: "" _ value, lang: "" _ lang, datatype: datatype);
}

function rdf_default_graph () {
	return new RDFDefaultGraph();
}

function rdf_quad ( subject, predicate, object, graph? ) {
	return new RDFQuad(
		subject: subject,
		predicate: predicate,
		object: object,
		graph: graph == null ? rdf_default_graph() : graph,
	);
}

function rdf_term_kind ( term ) {
	return "iri" if term instanceof RDFIRI;
	return "blank" if term instanceof RDFBlank;
	return "literal" if term instanceof RDFLiteral;
	return "default" if term instanceof RDFDefaultGraph;
	die "rdf: expected RDF term";
}

function _escape_key ( String text ) {
	let out := replace( text, /\\/, "\\\\", "g" );
	out := replace( out, "\n", "\\n", "g" );
	out := replace( out, /\|/, "\\|", "g" );
	return out;
}

function rdf_term_key ( term ) {
	if ( term instanceof RDFIRI ) {
		return "I|" _ _escape_key(term.get_value());
	}
	if ( term instanceof RDFBlank ) {
		return "B|" _ _escape_key(term.get_value());
	}
	if ( term instanceof RDFLiteral ) {
		return "L|" _ _escape_key(term.get_value()) _ "|" _
			_escape_key(term.get_lang()) _ "|" _
			_escape_key(term.get_datatype().get_value());
	}
	if ( term instanceof RDFDefaultGraph ) {
		return DEFAULT_GRAPH_KEY;
	}
	die "rdf: expected RDF term";
}

function rdf_term_hash ( term ) {
	return sha256_hex(to_binary(rdf_term_key(term)));
}

function rdf_term_equals ( left, right ) {
	return rdf_term_key(left) eq rdf_term_key(right);
}