Skip to main content

Crate purrdf_cdt

Crate purrdf_cdt 

Source
Expand description

purrdf-cdt — the native SPARQL composite datatypes (SEP-0009) for the RDF 1.2 query stack.

SEP-0009 adds two datatypes to SPARQL — cdt:List and cdt:Map — whose values are ordered sequences and keyed collections of ordinary RDF terms, carried in the lexical form of a single literal. This crate is the value layer for both: it scans that lexical form, gives the result a canonical spelling, and implements the spec’s equality and ordering over it.

§A closed leaf, on purpose

purrdf-cdt depends on exactly two crates — purrdf_iri and purrdf_xsd — and on no part of purrdf-core, in either direction. That is the whole point of the shape: composite values must be reachable from the kernel, so the kernel will depend on this crate, and a dependency in the other direction would close the cycle. It therefore owns its own closed element type, CdtTerm, which is exactly what the grammar admits; converting to and from a host’s term representation happens in the consumer, above this crate.

The crate is #![no_std] plus alloc, so it builds for wasm32-unknown-unknown like every other release crate in the workspace.

§PurRDF is not an ontology, and this is not minting

Every IRI constant here is a fixed, third-party, spec-defined string: CDT_LIST and CDT_MAP come from SEP-0009, and the xsd: / rdf: ones from the W3C Recommendations the grammar’s shorthands resolve into. They are the spelling the grammar is written in, not caller-supplied vocabulary, and there is no default being fabricated for anything.

§Two PurRDF supersets of the SEP-0009 lexical space

Both extend the lexical space only. No IRI is minted and the datatype stays cdt:List / cdt:Map. Each form is emitted only when such a term is actually present — that is, only for values SEP-0009 cannot express at all — so any value SEP-0009 can express is written in SEP-0009’s own lexical space and conformance is preserved.

Both are also separately graded. SEP-0009’s conformance corpus contains no <<( and no --ltr / --rtl, so running it can never reveal that PurRDF accepts more than the spec does; lexical_space therefore lets the crate report its own position, and tests/superset.rs pins every widened form as an executable assertion. See conformance for why that is reporting rather than optionality.

§Superset 1 — RDF 1.2 triple terms

Productions [3] and [8] gain one alternative:

TripleTerm ::= '<<(' Element Element Element ')>>'

Without it, folding a triple-term binding into a cdt:List would have no lexical form at all and could only raise — refusing an RDF 1.2 term type outright. RDF 1.2 is the whole point of this toolkit and triple terms are first-class in it, so refusal is not an admissible outcome; the toolkit carries the term and spells it.

§Superset 2 — directional language-tagged literals

RDFLiteral’s LANGTAG gains RDF 1.2’s base-direction suffix, in both directions, spelled exactly as the rest of this workspace already writes it:

LANGTAG ::= '@' [a-zA-Z]+ ('-' [a-zA-Z0-9]+)* ('--' ('ltr' | 'rtl'))?

So "مرحبا"@ar--rtl and "hello"@en--ltr are both admitted, and both round-trip through the canonical form. As with triple terms, refusing an rdf:dirLangString is not an admissible outcome for either direction.

§Termination, and the two bounds

A CDT lexical form is attacker-controlled data inside a literal, and exhausting the stack in Rust is an abort that no caller can catch. Every walk in this crate — the scanner, the renderer, equality, ordering, the canonical mapping, and the value tree’s own Drop, Clone and Debug (tree) — is therefore iterative over an explicit heap worklist; nothing recurses, so nesting depth costs heap and has no bound of its own. On top of that the crate owns two bounds: MAX_ELEMENTS and MAX_LEXICAL_BYTES, each with its governor justification in the limits module; a level of nesting is one element, so the first bounds depth as a consequence. Exceeding one is a typed CdtError carrying a byte offset, never a panic and never an abort.

§The function library

SEP-0009 also defines fifteen functions over these values — cdt:List, cdt:concat, cdt:get, cdt:merge, cdt:put and the rest. functions is the closed registry (CdtFn, with each member’s spec IRI and arity) and the pure value-space operation behind each one, written against SEP-0009’s own conformance corpus with the pinning test named in every rustdoc. Functions that mint a composite check both bounds against the prospective result before allocating any of it.

§The canonical lexical form

SEP-0009 defines none, so this crate chooses one — for values PurRDF computes, with exactly the standing purrdf_xsd::XsdValue::canonical_lexical has for minted XSD literals. It is a pure, deterministic function of the value: a fixed separator spelling, IRIs as <…>, literals under the SPARQL escape set with numeric and boolean elements always in explicit "…"^^<…> form, null for the null element, and map entries written in the crate’s total key order. See render for the full form.

§Examples

use purrdf_cdt::{list_less_than, parse_list, CdtValue};

// Parse, canonicalize, and re-parse: the canonical form is a fixpoint.
let value = parse_list("[ 1 , 'two'@en--ltr , [ true ] ]")?;
let canonical = value.canonical_lexical();
assert_eq!(parse_list(&canonical)?.canonical_lexical(), canonical);

// The spec's ordering is partial and raises where SPARQL `<` has no answer.
let items = |value: CdtValue| value.into_list().expect("parse_list yields a list");
assert_eq!(
    list_less_than(&items(parse_list("[1,2]")?), &items(parse_list("[1,3]")?)),
    Ok(true)
);

Re-exports§

pub use conformance::LexicalSpace;
pub use conformance::key_lexical_space;
pub use conformance::lexical_space;
pub use conformance::literal_lexical_space;
pub use conformance::term_lexical_space;
pub use datatype::CDT_LIST;
pub use datatype::CDT_MAP;
pub use datatype::CDT_NS;
pub use datatype::CdtDatatype;
pub use error::CdtError;
pub use error::CdtTypeError;
pub use error::CdtTypeErrorKind;
pub use functions::CDT_FUNCTIONS;
pub use functions::CdtArity;
pub use functions::CdtFn;
pub use functions::CdtOutcome;
pub use functions::MapRemoval;
pub use functions::concat;
pub use functions::contains;
pub use functions::contains_key;
pub use functions::get;
pub use functions::head;
pub use functions::integer_argument;
pub use functions::keys;
pub use functions::list_concat;
pub use functions::list_constructor;
pub use functions::list_contains;
pub use functions::list_get;
pub use functions::list_head;
pub use functions::list_reverse;
pub use functions::list_size;
pub use functions::list_subseq;
pub use functions::list_tail;
pub use functions::map_constructor;
pub use functions::map_contains_key;
pub use functions::map_get;
pub use functions::map_keys;
pub use functions::map_merge;
pub use functions::map_put;
pub use functions::map_remove;
pub use functions::map_size;
pub use functions::merge;
pub use functions::put;
pub use functions::remove;
pub use functions::reverse;
pub use functions::size;
pub use functions::subseq;
pub use functions::tail;
pub use limits::MAX_ELEMENTS;
pub use limits::MAX_LEXICAL_BYTES;
pub use literal::LiteralValue;
pub use literal::parse_literal;
pub use ops::list_equal;
pub use ops::list_less_than;
pub use ops::map_equal;
pub use ops::map_less_than;
pub use ops::term_equal;
pub use ops::term_less_than;
pub use ops::total_key_cmp;
pub use ops::total_term_cmp;
pub use ops::total_value_cmp;
pub use ops::value_equal;
pub use ops::value_less_than;
pub use parse::parse_cdt;
pub use parse::parse_cdt_by_iri;
pub use parse::parse_list;
pub use parse::parse_map;
pub use render::canonical_key_lexical;
pub use render::canonical_lexical;
pub use render::canonical_lexical_len;
pub use term::CdtEntry;
pub use term::CdtKey;
pub use term::CdtLiteral;
pub use term::CdtTerm;
pub use term::CdtTripleTerm;
pub use value::CdtContents;
pub use value::CdtParts;
pub use value::CdtValue;

Modules§

conformance
Which lexical space a value’s canonical form lies in: strict SEP-0009, or one of PurRDF’s two documented supersets.
datatype
The two composite datatypes, and the vocabulary IRIs the grammar pins.
error
The two typed failure modes: a scanner failure (CdtError, which always carries a byte offset into the lexical form) and a comparison failure (CdtTypeError, which is a SPARQL type error and has no position).
functions
The SEP-0009 function library: the closed registry CdtFn and the pure value-space operation behind each of its members.
limits
The two resource bounds every crate::CdtValue satisfies, and the machinery that establishes them.
literal
One closed enum over both value spaces this crate can reach, and the crate’s single lexical-to-value choke point.
memory
The CDT lexical diagnostic and caller-supplied fallible box factories.
ops
The two orders this crate defines over composite values, and why there are two.
parse
The SEP-0009 lexical scanner.
render
The canonical lexical mapping: canonical_lexical.
term
The crate’s own closed element type.
tree
The owning value tree’s iterative Drop, Clone and Debug. Destruction threads ancestors through existing slots without allocating; copying and debugging use explicit work lists instead of recursive glue.
value
CdtValue — a parsed cdt:List or cdt:Map.

Enums§

TextDirection
The RDF 1.2 base direction of a directional language-tagged string: the stack’s one direction type, carried exactly as the workspace’s concrete syntaxes write it (the --ltr / --rtl suffix after a language tag). RDF 1.2 base direction for directional language-tagged literals.

Constants§

RDF_DIR_LANG_STRING
rdf:dirLangString — the RDF 1.2 datatype of a directional language-tagged string ("lex"@lang--ltr / "lex"@lang--rtl). rdf:dirLangString — the datatype of a directional language-tagged string, new in RDF 1.2; RDF 1.2 Semantics §8 requires every interpretation to recognize it.
RDF_LANG_STRING
rdf:langString — the datatype of a language-tagged string with no direction. rdf:langString — a datatype RDF 1.2 Semantics §8 requires every RDF interpretation to recognize.
XSD_BOOLEAN
xsd:boolean — the datatype the BooleanLiteral shorthand denotes. xsd:boolean.
XSD_DECIMAL
xsd:decimal — the datatype the DECIMAL numeric shorthand denotes. xsd:decimal — exact decimal (this crate: i128 mantissa, fixed scale).
XSD_DOUBLE
xsd:double — the datatype the DOUBLE numeric shorthand denotes. xsd:double — IEEE double-precision.
XSD_INTEGER
xsd:integer — the datatype the INTEGER numeric shorthand denotes. xsd:integer — arbitrary-magnitude (this crate: i128-bounded) signed integer.
XSD_STRING
xsd:string — the datatype a String with no LANGTAG and no ^^ denotes. xsd:string.