Description
Immutable RDF 1.2 terms with constructor-enforced invariants.
A Term is stored as a flat vector of nodes in child-before-parent order. Nested triple terms name their children by index rather than by access value, so no cycle is representable, traversal is iterative, and the whole term is one contiguous allocation rather than a pointer graph.
"="
function "=" (Left, Right : Term) return Boolean
Compare two terms structurally.
Parameters
- Left
First term
- Right
Second term
Return value
True when both denote the same RDF term
Base_Direction
type Base_Direction is (Left_To_Right, Right_To_Left);
Base direction of a directional language-tagged literal.
Enumeration literals
- Left_To_Right
Corresponds to the --ltr direction
- Right_To_Left
Corresponds to the --rtl direction
Blank_Node
function Blank_Node (Label : String) return Term
Build a blank node with the given label.
The label is an identifier local to whatever scope the caller is working in; this package attaches no meaning to it beyond equality, and in particular does not treat two equal labels from different documents as denoting the same node. Managing that is the caller's job, because only the caller knows what a document boundary is.
Parameters
- Label
Non-empty blank node label
Return value
The corresponding term
Raised exceptions
- Invalid_Term
Label is empty
Datatype
function Datatype (Value : Term) return IRIs.IRI
Return the datatype of a literal.
Parameters
- Value
Term to inspect
Return value
The datatype IRI
Raised exceptions
- Invalid_Term
Value is not a literal
Depth
function Depth (Value : Term) return Natural
Return the quoted-triple nesting depth, zero for a leaf term.
Parameters
- Value
Term to inspect
Return value
Nesting depth
Direction
function Direction (Value : Term) return Base_Direction
Return the base direction of a directional literal.
Parameters
- Value
Term to inspect
Return value
The base direction
Raised exceptions
- Invalid_Term
Value is not a directional literal
Directional_Literal
function Directional_Literal
(Lexical_Form : String;
Language : String;
Direction : Base_Direction) return Term
Build a language-tagged literal that also carries a base direction.
Parameters
- Lexical_Form
The literal's lexical form
- Language
Non-empty language tag
- Direction
The base direction
Return value
The corresponding term
Raised exceptions
- Invalid_Language_Tag
Language is empty or malformed
- Term_Limit_Error
The payload exceeds Maximum_Payload_Bytes
Has_Direction
function Has_Direction (Value : Term) return Boolean
Report whether a literal carries a base direction.
Parameters
- Value
Term to inspect
Return value
True when Direction would succeed
Raised exceptions
- Invalid_Term
Value is not a literal
Has_Language
function Has_Language (Value : Term) return Boolean
Report whether a literal carries a language tag.
Parameters
- Value
Term to inspect
Return value
True when Language would succeed
Raised exceptions
- Invalid_Term
Value is not a literal
Invalid_Language_Tag
Invalid_Language_Tag : exception;
Raised when a language tag is empty or not well formed.
Invalid_Literal
Invalid_Literal : exception;
Raised when a literal's components are individually well formed but inconsistent, such as a language-tagged literal whose datatype is not rdf:langString.
Invalid_Term
Invalid_Term : exception;
Raised when a selector is applied to a term of the wrong kind, or to an optional literal component that is absent.
IRI_Term
function IRI_Term (Value : IRIs.IRI) return Term
Build a term denoting an IRI.
Parameters
- Value
The IRI
Return value
The corresponding term
IRI_Value
function IRI_Value (Value : Term) return IRIs.IRI
Return the IRI of an IRI term.
Parameters
- Value
Term to inspect
Return value
The IRI
Raised exceptions
- Invalid_Term
Value is not an IRI term
Kind
function Kind (Value : Term) return Term_Kind
Report which of the four kinds this term is.
Parameters
- Value
Term to inspect
Return value
The term's kind
Label
function Label (Value : Term) return String
Return the label of a blank node.
Parameters
- Value
Term to inspect
Return value
The label
Raised exceptions
- Invalid_Term
Value is not a blank node
Language
function Language (Value : Term) return String
Return the lowercased language tag of a literal.
Parameters
- Value
Term to inspect
Return value
The language tag
Raised exceptions
- Invalid_Term
Value is not a language-tagged literal
Language_Literal
function Language_Literal
(Lexical_Form : String;
Language : String) return Term
Build a language-tagged literal. Its datatype is rdf:langString.
The tag is stored lowercased. RDF defines the value space of language tags as lowercase, so this is a normalisation the abstract syntax calls for rather than one this package invents -- but it does mean a literal written @en-US is returned as en-us, which anything comparing serialisations byte for byte has to account for.
Parameters
- Lexical_Form
The literal's lexical form
- Language
Non-empty language tag
Return value
The corresponding term
Raised exceptions
- Invalid_Language_Tag
Language is empty or malformed
- Term_Limit_Error
The payload exceeds Maximum_Payload_Bytes
Language_String_Datatype
function Language_String_Datatype return IRIs.IRI
The datatype every language-tagged literal carries.
Return value
rdf:langString
Lexical_Form
function Lexical_Form (Value : Term) return String
Return the lexical form of a literal.
Parameters
- Value
Term to inspect
Return value
The lexical form
Raised exceptions
- Invalid_Term
Value is not a literal
Literal
function Literal
(Lexical_Form : String;
Datatype : IRIs.IRI) return Term
Build a typed literal.
Parameters
- Lexical_Form
The literal's lexical form
- Datatype
The datatype IRI
Return value
The corresponding term
Raised exceptions
- Invalid_Literal
Datatype is rdf:langString, which requires a language tag and must be built with Language_Literal
- Term_Limit_Error
The payload exceeds Maximum_Payload_Bytes
Maximum_Payload_Bytes
Maximum_Payload_Bytes : constant Positive := 16 * 1_024 * 1_024;
Largest total payload a single term may carry, in UTF-8 bytes.
Maximum_Term_Nodes
Maximum_Term_Nodes : constant Positive :=
2 * Maximum_Triple_Term_Depth + 1;
Most nodes a single term may contain. A maximally deep chain of quoted triples contributes one triple node and one leaf per level, plus the innermost leaf.
Maximum_Triple_Term_Depth
Maximum_Triple_Term_Depth : constant Positive := 256;
Deepest nesting of quoted triples a term may reach.
Node_Count
function Node_Count (Value : Term) return Positive
Return the number of nodes in the term's flat tree.
Parameters
- Value
Term to inspect
Return value
Node count, at least one
Node_ID
type Node_ID is range 1 .. Maximum_Term_Nodes;
Visit-local identity of one node in a term's immutable tree. Values are meaningful only for the duration of the Visit_Nodes call that supplied them.
String_Datatype
function String_Datatype return IRIs.IRI
The datatype of a plain string literal.
Return value
xsd:string
Term
type Term (<>) is private;
An immutable RDF term.
Term_Kind
type Term_Kind is
(IRI_Kind, Blank_Node_Kind, Literal_Kind, Triple_Term_Kind);
The four term kinds of the RDF 1.2 abstract syntax.
Enumeration literals
- IRI_Kind
An IRI
- Blank_Node_Kind
A blank node, identified by a label
- Literal_Kind
A literal, always carrying a datatype
- Triple_Term_Kind
A quoted triple used as a term
Term_Limit_Error
Term_Limit_Error : exception;
Raised when a construction would exceed a published bound below.
Triple_Object
function Triple_Object (Value : Term) return Term
Return the object of a quoted triple.
Parameters
- Value
Term to inspect
Return value
The object term
Raised exceptions
- Invalid_Term
Value is not a triple term
Triple_Predicate
function Triple_Predicate (Value : Term) return IRIs.IRI
Return the predicate of a quoted triple.
Parameters
- Value
Term to inspect
Return value
The predicate IRI
Raised exceptions
- Invalid_Term
Value is not a triple term
Triple_Subject
function Triple_Subject (Value : Term) return Term
Return the subject of a quoted triple.
Parameters
- Value
Term to inspect
Return value
The subject term
Raised exceptions
- Invalid_Term
Value is not a triple term
Triple_Term
function Triple_Term
(Subject : Term;
Predicate : IRIs.IRI;
Object : Term) return Term
Build a quoted triple used as a term.
The predicate is typed as an IRI rather than a Term, so a literal or blank node in predicate position is rejected at compile time rather than checked here.
Parameters
- Subject
Subject term
- Predicate
Predicate IRI
- Object
Object term
Return value
The corresponding term
Raised exceptions
- Term_Limit_Error
The result would exceed Maximum_Triple_Term_Depth, Maximum_Term_Nodes, or Maximum_Payload_Bytes
Visit_Nodes
function Visit_Nodes
(Value : Term;
On_IRI : not null access procedure
(Node : Node_ID; Value : IRIs.IRI);
On_Blank : not null access procedure
(Node : Node_ID; Label : String);
On_Literal : not null access procedure
(Node : Node_ID;
Lexical_Form : String;
Datatype : IRIs.IRI;
Has_Language : Boolean;
Language : String;
Has_Direction : Boolean;
Direction : Base_Direction);
On_Triple : not null access procedure
(Node, Subject_Node : Node_ID;
Predicate : IRIs.IRI;
Object_Node : Node_ID)) return Node_ID
Visit every node exactly once in child-before-parent order and return the root's identity. A triple node's child identities always name nodes already visited, so a consumer can build its own representation bottom-up in a single pass. No subtree escapes and nothing is copied.
Parameters
- Value
Term to traverse
- On_IRI
Called for each IRI node
- On_Blank
Called for each blank node
- On_Literal
Called for each literal node
- On_Triple
Called for each quoted-triple node
Return value
Identity of the root node