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
CdtFnand the pure value-space operation behind each of its members. - limits
- The two resource bounds every
crate::CdtValuesatisfies, 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,CloneandDebug. Destruction threads ancestors through existing slots without allocating; copying and debugging use explicit work lists instead of recursive glue. - value
CdtValue— a parsedcdt:Listorcdt:Map.
Enums§
- Text
Direction - 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/--rtlsuffix 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 theBooleanLiteralshorthand denotes.xsd:boolean.- XSD_
DECIMAL xsd:decimal— the datatype theDECIMALnumeric shorthand denotes.xsd:decimal— exact decimal (this crate:i128mantissa, fixed scale).- XSD_
DOUBLE xsd:double— the datatype theDOUBLEnumeric shorthand denotes.xsd:double— IEEE double-precision.- XSD_
INTEGER xsd:integer— the datatype theINTEGERnumeric shorthand denotes.xsd:integer— arbitrary-magnitude (this crate:i128-bounded) signed integer.- XSD_
STRING xsd:string— the datatype aStringwith noLANGTAGand no^^denotes.xsd:string.