jsonld_core/object/
mod.rs

1//! Nodes, lists and values.
2use crate::{HashMap, Id, IndexSet, Indexed, LenientLangTag, Relabel, ValidId};
3use contextual::{IntoRefWithContext, WithContext};
4use derive_where::derive_where;
5use iri_rs::IriBuf;
6use jsonld_syntax::{IntoJsonWithContext, Keyword};
7use jstrict::Number;
8use rdfx::{
9    BlankIdBuf,
10    LocalGenerator,
11    vocabulary::{Vocabulary, VocabularyMut},
12};
13use smallvec::SmallVec;
14use std::hash::Hash;
15
16/// List objects.
17mod dismantle;
18pub mod list;
19mod mapped_eq;
20/// Node objects.
21pub mod node;
22mod typ;
23/// Value objects.
24pub mod value;
25
26pub use list::List;
27pub use mapped_eq::MappedEq;
28pub use node::{Graph, IndexedNode, Node, NodeParts, Nodes};
29pub use typ::{Type, TypeRef};
30pub use value::{Literal, Value};
31
32/// Abstract object.
33pub trait Any<T, B> {
34    /// Borrows the object as a value, node or list reference.
35    fn as_ref(&self) -> Ref<'_, T, B>;
36
37    #[inline]
38    /// Returns the identifier (`@id`) of the object, if it is a node object
39    /// with one.
40    fn id(&self) -> Option<&Id<T, B>> {
41        match self.as_ref() {
42            Ref::Node(n) => n.id.as_ref(),
43            _ => None,
44        }
45    }
46
47    #[inline]
48    /// Returns the language tag of this value, if it carries one.
49    fn language<'a>(&'a self) -> Option<&'a LenientLangTag>
50    where
51        T: 'a,
52        B: 'a,
53    {
54        match self.as_ref() {
55            Ref::Value(value) => value.language(),
56            _ => None,
57        }
58    }
59
60    #[inline]
61    /// Checks whether the object is a value object.
62    fn is_value(&self) -> bool {
63        matches!(self.as_ref(), Ref::Value(_))
64    }
65
66    #[inline]
67    /// Checks whether the object is a node object.
68    fn is_node(&self) -> bool {
69        matches!(self.as_ref(), Ref::Node(_))
70    }
71
72    #[inline]
73    /// Checks whether the object is a graph object (a node object with a
74    /// `@graph` entry).
75    fn is_graph(&self) -> bool {
76        match self.as_ref() {
77            Ref::Node(n) => n.is_graph(),
78            _ => false,
79        }
80    }
81
82    #[inline]
83    /// Checks whether the object is a list object.
84    fn is_list(&self) -> bool {
85        matches!(self.as_ref(), Ref::List(_))
86    }
87}
88
89/// Object reference.
90pub enum Ref<'a, T, B> {
91    /// Value object.
92    Value(&'a Value<T>),
93
94    /// Node object.
95    Node(&'a Node<T, B>),
96
97    /// List object.
98    List(&'a List<T, B>),
99}
100
101/// Indexed object.
102pub type IndexedObject<T, B = ()> = Indexed<Object<T, B>>;
103
104/// Object.
105///
106/// JSON-LD connects together multiple kinds of data objects.
107/// Objects may be nodes, values or lists of objects.
108///
109/// You can get an `Object` by expanding a JSON-LD document using the
110/// expansion algorithm or by converting an already expanded JSON document
111/// using [`TryFromJson`].
112#[allow(clippy::derived_hash_with_manual_eq)]
113#[derive(Debug, Clone, Hash)]
114#[derive_where(PartialEq; T: Eq + Hash, B: Eq + Hash)]
115pub enum Object<T = IriBuf, B = BlankIdBuf> {
116    /// Value object.
117    Value(Value<T>),
118
119    /// Node object.
120    Node(Box<Node<T, B>>),
121
122    /// List object.
123    List(List<T, B>),
124}
125
126impl<T: Eq + Hash, B: Eq + Hash> Eq for Object<T, B> {}
127
128impl<T, B> Object<T, B> {
129    /// Creates a `null` value object.
130    #[inline(always)]
131    #[must_use]
132    pub fn null() -> Self {
133        Self::Value(Value::null())
134    }
135
136    /// Creates a new node object from a node.
137    #[inline(always)]
138    pub fn node(n: Node<T, B>) -> Self {
139        Self::Node(Box::new(n))
140    }
141
142    /// Identifier of the object, if it is a node object.
143    #[inline(always)]
144    pub fn id(&self) -> Option<&Id<T, B>> {
145        match self {
146            Object::Node(n) => n.id.as_ref(),
147            _ => None,
148        }
149    }
150
151    /// Assigns an identifier to every node included in this object using the given `generator`.
152    ///
153    /// # Errors
154    ///
155    /// Returns an error when the generator runs out of identifiers.
156    pub fn identify_all_with<V: VocabularyMut<Iri = T, BlankId = B>, G: LocalGenerator>(
157        &mut self,
158        vocabulary: &mut V,
159        generator: &mut G,
160    ) -> Result<(), crate::id::GeneratedIdError>
161    where
162        T: Eq + Hash,
163        B: Eq + Hash,
164    {
165        match self {
166            Object::Node(n) => n.identify_all_with(vocabulary, generator)?,
167            Object::List(l) => {
168                for object in l {
169                    object.identify_all_with(vocabulary, generator)?;
170                }
171            }
172            Object::Value(_) => (),
173        }
174        Ok(())
175    }
176
177    /// Use the given `generator` to assign an identifier to all nodes that
178    /// don't have one.
179    ///
180    /// # Errors
181    ///
182    /// Returns an error when the generator runs out of identifiers.
183    pub fn identify_all<G: LocalGenerator>(&mut self, generator: &mut G) -> Result<(), crate::id::GeneratedIdError>
184    where
185        T: Eq + Hash,
186        B: Eq + Hash,
187        (): Vocabulary<Iri = T, BlankId = B>,
188    {
189        self.identify_all_with(&mut (), generator)
190    }
191
192    /// Puts every literal of the object into canonical form, using the given
193    /// `buffer` to render numbers.
194    pub fn canonicalize_with(&mut self, buffer: &mut ryu_js::Buffer) {
195        match self {
196            Self::List(l) => l.canonicalize_with(buffer),
197            Self::Node(n) => n.canonicalize_with(buffer),
198            Self::Value(v) => v.canonicalize_with(buffer),
199        }
200    }
201
202    /// Puts every literal of the object into canonical form.
203    pub fn canonicalize(&mut self) {
204        let mut buffer = ryu_js::Buffer::new();
205        self.canonicalize_with(&mut buffer);
206    }
207
208    /// Returns an iterator over the types of the object.
209    pub fn types(&self) -> Types<'_, T, B> {
210        match self {
211            Self::Value(value) => Types::Value(value.typ()),
212            Self::Node(node) => Types::Node(node.types().iter()),
213            Self::List(_) => Types::List,
214        }
215    }
216
217    /// Identifier of the object as an IRI.
218    ///
219    /// If the object is a node identified by an IRI, returns this IRI.
220    /// Returns `None` otherwise.
221    #[inline(always)]
222    pub fn as_iri(&self) -> Option<&T> {
223        match self {
224            Object::Node(node) => node.as_iri(),
225            _ => None,
226        }
227    }
228
229    /// Tests if the object is a value.
230    #[inline(always)]
231    pub fn is_value(&self) -> bool {
232        matches!(self, Object::Value(_))
233    }
234
235    /// Returns this object as a value, if it is one.
236    #[inline(always)]
237    pub fn as_value(&self) -> Option<&Value<T>> {
238        match self {
239            Self::Value(v) => Some(v),
240            _ => None,
241        }
242    }
243
244    /// Returns this object as a mutable value, if it is one.
245    #[inline(always)]
246    pub fn as_value_mut(&mut self) -> Option<&mut Value<T>> {
247        match self {
248            Self::Value(v) => Some(v),
249            _ => None,
250        }
251    }
252
253    /// Converts this object into a value, if it is one.
254    #[inline(always)]
255    pub fn into_value(self) -> Option<Value<T>> {
256        match self {
257            Self::Value(v) => Some(v),
258            _ => None,
259        }
260    }
261
262    /// Tests if the object is a node.
263    #[inline(always)]
264    pub fn is_node(&self) -> bool {
265        matches!(self, Object::Node(_))
266    }
267
268    /// Returns this object as a node, if it is one.
269    #[inline(always)]
270    pub fn as_node(&self) -> Option<&Node<T, B>> {
271        match self {
272            Self::Node(n) => Some(n),
273            _ => None,
274        }
275    }
276
277    /// Returns this object as a mutable node, if it is one.
278    #[inline(always)]
279    pub fn as_node_mut(&mut self) -> Option<&mut Node<T, B>> {
280        match self {
281            Self::Node(n) => Some(n),
282            _ => None,
283        }
284    }
285
286    /// Converts this object into a node, if it is one.
287    #[inline(always)]
288    pub fn into_node(self) -> Option<Node<T, B>> {
289        match self {
290            Self::Node(n) => Some(*n),
291            _ => None,
292        }
293    }
294
295    /// Tests if the object is a graph object (a node with a `@graph` field).
296    #[inline(always)]
297    pub fn is_graph(&self) -> bool {
298        match self {
299            Object::Node(n) => n.is_graph(),
300            _ => false,
301        }
302    }
303
304    /// Tests if the object is a list.
305    #[inline(always)]
306    pub fn is_list(&self) -> bool {
307        matches!(self, Object::List(_))
308    }
309
310    /// Returns this object as a list, if it is one.
311    #[inline(always)]
312    pub fn as_list(&self) -> Option<&List<T, B>> {
313        match self {
314            Self::List(l) => Some(l),
315            _ => None,
316        }
317    }
318
319    /// Returns this object as a mutable list, if it is one.
320    #[inline(always)]
321    pub fn as_list_mut(&mut self) -> Option<&mut List<T, B>> {
322        match self {
323            Self::List(l) => Some(l),
324            _ => None,
325        }
326    }
327
328    /// Converts this object into a list, if it is one.
329    #[inline(always)]
330    pub fn into_list(self) -> Option<List<T, B>> {
331        match self {
332            Self::List(l) => Some(l),
333            _ => None,
334        }
335    }
336
337    /// Returns the object as a string.
338    ///
339    /// If the object is a value holding a string, returns that string.
340    /// If the object is a node with an identifier, returns the identifier as
341    /// a string. Returns `None` otherwise.
342    #[inline(always)]
343    pub fn as_str(&self) -> Option<&str>
344    where
345        T: AsRef<str>,
346        B: AsRef<str>,
347    {
348        match self {
349            Object::Value(value) => value.as_str(),
350            Object::Node(node) => node.as_str(),
351            Object::List(_) => None,
352        }
353    }
354
355    /// Returns the object as a boolean, if it is a value holding one.
356    #[inline(always)]
357    pub fn as_bool(&self) -> Option<bool> {
358        match self {
359            Object::Value(value) => value.as_bool(),
360            _ => None,
361        }
362    }
363
364    /// Returns the object as a number, if it is a value holding one.
365    #[inline(always)]
366    pub fn as_number(&self) -> Option<&Number> {
367        match self {
368            Object::Value(value) => value.as_number(),
369            _ => None,
370        }
371    }
372
373    /// Returns the associated language, if the object is a language-tagged
374    /// value.
375    #[inline(always)]
376    pub fn language(&self) -> Option<&LenientLangTag> {
377        match self {
378            Object::Value(value) => value.language(),
379            _ => None,
380        }
381    }
382
383    /// Returns an iterator over all fragments of this object, including the
384    /// object itself.
385    ///
386    /// Fragments include:
387    ///   - objects
388    ///   - key-value pairs,
389    ///   - keys
390    ///   - values
391    pub fn traverse(&self) -> Traverse<'_, T, B> {
392        Traverse::new(Some(FragmentRef::Object(self)))
393    }
394
395    fn sub_fragments(&self) -> ObjectSubFragments<'_, T, B> {
396        match self {
397            Self::Value(v) => ObjectSubFragments::Value(v.entries()),
398            Self::List(l) => ObjectSubFragments::List(Some(l.entry())),
399            Self::Node(n) => ObjectSubFragments::Node(n.entries()),
400        }
401    }
402
403    /// Equivalence operator.
404    ///
405    /// Equivalence differs from equality for anonymous objects: list objects
406    /// and anonymous node objects stand for implicit, unlabeled blank nodes,
407    /// so they are never equivalent to anything.
408    pub fn equivalent(&self, other: &Self) -> bool
409    where
410        T: Eq + Hash,
411        B: Eq + Hash,
412    {
413        match (self, other) {
414            (Self::Value(a), Self::Value(b)) => a == b,
415            (Self::Node(a), Self::Node(b)) => a.equivalent(b),
416            _ => false,
417        }
418    }
419
420    /// Returns an iterator over the entries of the JSON representation of
421    /// the object.
422    pub fn entries(&self) -> Entries<'_, T, B> {
423        match self {
424            Self::Value(value) => Entries::Value(value.entries()),
425            Self::List(list) => Entries::List(Some(list.entry())),
426            Self::Node(node) => Entries::Node(node.entries()),
427        }
428    }
429
430    /// Rewrites every IRI and identifier of the object (recursively) with
431    /// the given functions.
432    pub fn map_ids<U, C>(self, mut map_iri: impl FnMut(T) -> U, mut map_id: impl FnMut(Id<T, B>) -> Id<U, C>) -> Object<U, C>
433    where
434        U: Eq + Hash,
435        C: Eq + Hash,
436    {
437        self.map_ids_with(&mut map_iri, &mut map_id)
438    }
439
440    fn map_ids_with<U, C>(self, map_iri: &mut impl FnMut(T) -> U, map_id: &mut impl FnMut(Id<T, B>) -> Id<U, C>) -> Object<U, C>
441    where
442        U: Eq + Hash,
443        C: Eq + Hash,
444    {
445        match self {
446            Self::Value(value) => Object::Value(value.map_ids(map_iri)),
447            Self::List(list) => Object::List(list.map_ids_with(map_iri, map_id)),
448            Self::Node(node) => Object::Node(Box::new((*node).map_ids_with(map_iri, map_id))),
449        }
450    }
451}
452
453impl<T, B> Relabel<T, B> for Object<T, B> {
454    fn relabel_with<N: VocabularyMut<Iri = T, BlankId = B>, G: LocalGenerator>(
455        &mut self,
456        vocabulary: &mut N,
457        generator: &mut G,
458        relabeling: &mut HashMap<B, ValidId<T, B>>,
459    ) -> Result<(), crate::id::GeneratedIdError>
460    where
461        T: Clone + Eq + Hash,
462        B: Clone + Eq + Hash,
463    {
464        match self {
465            Self::Node(n) => n.relabel_with(vocabulary, generator, relabeling),
466            Self::List(l) => l.relabel_with(vocabulary, generator, relabeling),
467            Self::Value(_) => Ok(()),
468        }
469    }
470}
471
472impl<T: Eq + Hash, B: Eq + Hash> Indexed<Object<T, B>> {
473    /// Checks whether the two indexed objects are equivalent: same `@index`
474    /// and [equivalent](Object::equivalent) inner objects.
475    pub fn equivalent(&self, other: &Self) -> bool {
476        self.index() == other.index() && self.inner().equivalent(other.inner())
477    }
478}
479
480impl<T, B> Indexed<Object<T, B>> {
481    /// Converts this indexed object into an indexed node, if it is one.
482    #[inline(always)]
483    pub fn into_indexed_node(self) -> Option<Indexed<Node<T, B>>> {
484        let (object, index) = self.into_parts();
485        object.into_node().map(|node| Indexed::new(node, index))
486    }
487
488    /// Converts this indexed object into an indexed value, if it is one.
489    #[inline(always)]
490    pub fn into_indexed_value(self) -> Option<Indexed<Value<T>>> {
491        let (object, index) = self.into_parts();
492        object.into_value().map(|value| Indexed::new(value, index))
493    }
494
495    /// Converts this indexed object into an indexed list, if it is one.
496    #[inline(always)]
497    pub fn into_indexed_list(self) -> Option<Indexed<List<T, B>>> {
498        let (object, index) = self.into_parts();
499        object.into_list().map(|list| Indexed::new(list, index))
500    }
501
502    /// Try to convert this object into an unnamed graph.
503    ///
504    /// # Errors
505    ///
506    /// Returns `self` unchanged when the object is not a graph object, or is a named graph.
507    pub fn into_unnamed_graph(self) -> Result<Graph<T, B>, Self> {
508        let (obj, index) = self.into_parts();
509        match obj {
510            Object::Node(n) => match n.into_unnamed_graph() {
511                Ok(g) => Ok(g),
512                Err(n) => Err(Indexed::new(Object::Node(n), index)),
513            },
514            obj => Err(Indexed::new(obj, index)),
515        }
516    }
517
518    /// Returns an iterator over the entries of the JSON representation of
519    /// the object, including its `@index` entry if any.
520    pub fn entries(&self) -> IndexedEntries<'_, T, B> {
521        IndexedEntries {
522            index: self.index(),
523            inner: self.inner().entries(),
524        }
525    }
526}
527
528#[derive_where(Clone)]
529/// Iterator over the entries of an object.
530pub enum Entries<'a, T, B> {
531    /// A value object.
532    Value(value::Entries<'a, T>),
533    /// A list object.
534    List(Option<&'a [IndexedObject<T, B>]>),
535    /// A node object.
536    Node(node::Entries<'a, T, B>),
537}
538
539impl<'a, T, B> Iterator for Entries<'a, T, B> {
540    type Item = EntryRef<'a, T, B>;
541
542    fn size_hint(&self) -> (usize, Option<usize>) {
543        let len = match self {
544            Self::Value(v) => v.len(),
545            Self::List(l) => usize::from(l.is_some()),
546            Self::Node(n) => n.len(),
547        };
548
549        (len, Some(len))
550    }
551
552    fn next(&mut self) -> Option<Self::Item> {
553        match self {
554            Self::Value(v) => v.next().map(EntryRef::Value),
555            Self::List(l) => l.take().map(EntryRef::List),
556            Self::Node(n) => n.next().map(EntryRef::Node),
557        }
558    }
559}
560
561impl<T, B> ExactSizeIterator for Entries<'_, T, B> {}
562
563#[derive_where(Clone)]
564/// Iterator over the entries of an indexed object, `@index` included.
565pub struct IndexedEntries<'a, T, B> {
566    index: Option<&'a str>,
567    inner: Entries<'a, T, B>,
568}
569
570impl<'a, T, B> Iterator for IndexedEntries<'a, T, B> {
571    type Item = IndexedEntryRef<'a, T, B>;
572
573    fn size_hint(&self) -> (usize, Option<usize>) {
574        let len = self.inner.len() + usize::from(self.index.is_some());
575        (len, Some(len))
576    }
577
578    fn next(&mut self) -> Option<Self::Item> {
579        self.index
580            .take()
581            .map(IndexedEntryRef::Index)
582            .or_else(|| self.inner.next().map(IndexedEntryRef::Object))
583    }
584}
585
586impl<T, B> ExactSizeIterator for IndexedEntries<'_, T, B> {}
587
588// `bound(false)`: every variant payload is a shared reference, a `Copy` value
589// type, or another unconditionally-`Copy` borrow type, so the impls hold for any
590// `T`/`B`. A plain `derive` would instead add a bound per field
591// type, making the impl conditional and breaking the `&self` methods that consume
592// `self` by copy.
593#[derive(PartialEq, Eq)]
594#[derive_where(Clone, Copy)]
595/// Key of an object entry.
596pub enum EntryKeyRef<'a, T, B> {
597    /// A value object.
598    Value(value::EntryKey),
599    /// A list object.
600    List,
601    /// A node object.
602    Node(node::EntryKeyRef<'a, T, B>),
603}
604
605impl<'a, T, B> EntryKeyRef<'a, T, B> {
606    /// Returns the JSON-LD keyword this key stands for, if any.
607    #[must_use]
608    pub fn into_keyword(self) -> Option<Keyword> {
609        match self {
610            Self::Value(e) => Some(e.into_keyword()),
611            Self::List => Some(Keyword::List),
612            Self::Node(e) => e.into_keyword(),
613        }
614    }
615
616    /// Returns the JSON-LD keyword this key stands for, if any.
617    #[must_use]
618    pub fn as_keyword(&self) -> Option<Keyword> {
619        self.into_keyword()
620    }
621
622    /// Returns the key as a string slice.
623    #[must_use]
624    pub fn into_str(self) -> &'a str
625    where
626        T: AsRef<str>,
627        B: AsRef<str>,
628    {
629        match self {
630            Self::Value(e) => e.into_str(),
631            Self::List => "@list",
632            Self::Node(e) => e.into_str(),
633        }
634    }
635
636    /// Returns this value as a string slice.
637    #[must_use]
638    pub fn as_str(self) -> &'a str
639    where
640        T: AsRef<str>,
641        B: AsRef<str>,
642    {
643        self.into_str()
644    }
645}
646
647impl<'a, T, B, N: Vocabulary<Iri = T, BlankId = B>> IntoRefWithContext<'a, str, N> for EntryKeyRef<'a, T, B> {
648    fn into_ref_with(self, vocabulary: &'a N) -> &'a str {
649        match self {
650            EntryKeyRef::Value(e) => e.into_str(),
651            EntryKeyRef::List => "@list",
652            EntryKeyRef::Node(e) => e.into_with(vocabulary).into_str(),
653        }
654    }
655}
656
657#[derive_where(Clone, Copy)]
658/// Value of an object entry.
659pub enum EntryValueRef<'a, T, B> {
660    /// A value object.
661    Value(value::EntryRef<'a, T>),
662    /// A list object.
663    List(&'a [IndexedObject<T, B>]),
664    /// A node object.
665    Node(node::EntryValueRef<'a, T, B>),
666}
667
668#[derive_where(Clone, Copy)]
669/// Entry of an object, key and value together.
670pub enum EntryRef<'a, T, B> {
671    /// A value object.
672    Value(value::EntryRef<'a, T>),
673    /// A list object.
674    List(&'a [IndexedObject<T, B>]),
675    /// A node object.
676    Node(node::EntryRef<'a, T, B>),
677}
678
679impl<'a, T, B> EntryRef<'a, T, B> {
680    /// Consumes this `EntryRef`, returning its key.
681    #[must_use]
682    pub fn into_key(self) -> EntryKeyRef<'a, T, B> {
683        match self {
684            Self::Value(e) => EntryKeyRef::Value(e.key()),
685            Self::List(_) => EntryKeyRef::List,
686            Self::Node(e) => EntryKeyRef::Node(e.key()),
687        }
688    }
689
690    /// Returns the key of this `EntryRef`.
691    #[must_use]
692    pub fn key(&self) -> EntryKeyRef<'a, T, B> {
693        self.into_key()
694    }
695
696    /// Consumes this `EntryRef`, returning its value.
697    #[must_use]
698    pub fn into_value(self) -> EntryValueRef<'a, T, B> {
699        match self {
700            Self::Value(v) => EntryValueRef::Value(v),
701            Self::List(v) => EntryValueRef::List(v),
702            Self::Node(e) => EntryValueRef::Node(e.value()),
703        }
704    }
705
706    /// Returns the value of this `EntryRef`.
707    #[must_use]
708    pub fn value(&self) -> EntryValueRef<'a, T, B> {
709        self.into_value()
710    }
711
712    /// Consumes this `EntryRef`, returning its key and value.
713    #[must_use]
714    pub fn into_key_value(self) -> (EntryKeyRef<'a, T, B>, EntryValueRef<'a, T, B>) {
715        match self {
716            Self::Value(e) => (EntryKeyRef::Value(e.key()), EntryValueRef::Value(e)),
717            Self::List(e) => (EntryKeyRef::List, EntryValueRef::List(e)),
718            Self::Node(e) => {
719                let (k, v) = e.into_key_value();
720                (EntryKeyRef::Node(k), EntryValueRef::Node(v))
721            }
722        }
723    }
724
725    /// Returns the key and value of this entry.
726    #[must_use]
727    pub fn as_key_value(&self) -> (EntryKeyRef<'a, T, B>, EntryValueRef<'a, T, B>) {
728        self.into_key_value()
729    }
730}
731
732#[derive(PartialEq, Eq)]
733#[derive_where(Clone, Copy)]
734/// Key of an indexed object entry.
735pub enum IndexedEntryKeyRef<'a, T, B> {
736    /// The `@index` entry.
737    Index,
738    /// The key of one of the object's own entries.
739    Object(EntryKeyRef<'a, T, B>),
740}
741
742impl<'a, T, B> IndexedEntryKeyRef<'a, T, B> {
743    /// Returns the JSON-LD keyword this key stands for, if any.
744    #[must_use]
745    pub fn into_keyword(self) -> Option<Keyword> {
746        match self {
747            Self::Index => Some(Keyword::Index),
748            Self::Object(e) => e.into_keyword(),
749        }
750    }
751
752    /// Returns the JSON-LD keyword this key stands for, if any.
753    #[must_use]
754    pub fn as_keyword(&self) -> Option<Keyword> {
755        self.into_keyword()
756    }
757
758    /// Returns the key as a string slice.
759    #[must_use]
760    pub fn into_str(self) -> &'a str
761    where
762        T: AsRef<str>,
763        B: AsRef<str>,
764    {
765        match self {
766            Self::Index => "@index",
767            Self::Object(e) => e.into_str(),
768        }
769    }
770
771    /// Returns this value as a string slice.
772    #[must_use]
773    pub fn as_str(&self) -> &'a str
774    where
775        T: AsRef<str>,
776        B: AsRef<str>,
777    {
778        self.into_str()
779    }
780}
781
782impl<'a, T, B, N: Vocabulary<Iri = T, BlankId = B>> IntoRefWithContext<'a, str, N> for IndexedEntryKeyRef<'a, T, B> {
783    fn into_ref_with(self, vocabulary: &'a N) -> &'a str {
784        match self {
785            IndexedEntryKeyRef::Index => "@index",
786            IndexedEntryKeyRef::Object(e) => e.into_with(vocabulary).into_str(),
787        }
788    }
789}
790
791#[derive_where(Clone, Copy)]
792/// Value of an indexed object entry.
793pub enum IndexedEntryValueRef<'a, T, B> {
794    /// The value of the `@index` entry.
795    Index(&'a str),
796    /// The value of one of the object's own entries.
797    Object(EntryValueRef<'a, T, B>),
798}
799
800#[derive_where(Clone, Copy)]
801/// Entry of an indexed object, key and value together.
802pub enum IndexedEntryRef<'a, T, B> {
803    /// The `@index` entry and its value.
804    Index(&'a str),
805    /// One of the object's own entries.
806    Object(EntryRef<'a, T, B>),
807}
808
809impl<'a, T, B> IndexedEntryRef<'a, T, B> {
810    /// Consumes this `IndexedEntryRef`, returning its key.
811    #[must_use]
812    pub fn into_key(self) -> IndexedEntryKeyRef<'a, T, B> {
813        match self {
814            Self::Index(_) => IndexedEntryKeyRef::Index,
815            Self::Object(e) => IndexedEntryKeyRef::Object(e.key()),
816        }
817    }
818
819    /// Returns the key of this `IndexedEntryRef`.
820    #[must_use]
821    pub fn key(&self) -> IndexedEntryKeyRef<'a, T, B> {
822        self.into_key()
823    }
824
825    /// Consumes this `IndexedEntryRef`, returning its value.
826    #[must_use]
827    pub fn into_value(self) -> IndexedEntryValueRef<'a, T, B> {
828        match self {
829            Self::Index(v) => IndexedEntryValueRef::Index(v),
830            Self::Object(e) => IndexedEntryValueRef::Object(e.value()),
831        }
832    }
833
834    /// Returns the value of this `IndexedEntryRef`.
835    #[must_use]
836    pub fn value(&self) -> IndexedEntryValueRef<'a, T, B> {
837        self.into_value()
838    }
839
840    /// Consumes this `IndexedEntryRef`, returning its key and value.
841    #[must_use]
842    pub fn into_key_value(self) -> (IndexedEntryKeyRef<'a, T, B>, IndexedEntryValueRef<'a, T, B>) {
843        match self {
844            Self::Index(v) => (IndexedEntryKeyRef::Index, IndexedEntryValueRef::Index(v)),
845            Self::Object(e) => {
846                let (k, v) = e.into_key_value();
847                (IndexedEntryKeyRef::Object(k), IndexedEntryValueRef::Object(v))
848            }
849        }
850    }
851
852    /// Returns the key and value of this entry.
853    #[must_use]
854    pub fn as_key_value(&self) -> (IndexedEntryKeyRef<'a, T, B>, IndexedEntryValueRef<'a, T, B>) {
855        self.into_key_value()
856    }
857}
858
859/// Try to convert from a JSON value directly into an expanded JSON-LD document
860/// without going through the expansion algorithm.
861///
862/// The input JSON value must be in expanded JSON-LD form.
863///
864/// Reading recurses once per nesting level of the expanded document; each
865/// level runs on sufficient native stack, so a document of any depth is read
866/// on any thread.
867pub trait TryFromJson<T, B>: Sized {
868    /// Builds this fragment from a JSON value, interning terms in the given
869    /// vocabulary.
870    ///
871    /// # Errors
872    ///
873    /// Returns an error when the JSON does not describe a valid expanded object.
874    fn try_from_json_in(vocabulary: &mut impl VocabularyMut<Iri = T, BlankId = B>, value: jstrict::Value) -> Result<Self, InvalidExpandedJson>;
875}
876
877/// Try to convert from a JSON object directly into an expanded JSON-LD object
878/// without going through the expansion algorithm.
879///
880/// The input JSON object must be in expanded JSON-LD form.
881pub trait TryFromJsonObject<T, B>: Sized {
882    /// Builds this fragment from a JSON object, interning terms in the given
883    /// vocabulary.
884    ///
885    /// # Errors
886    ///
887    /// Returns an error when the JSON object does not describe a valid expanded object.
888    fn try_from_json_object_in(vocabulary: &mut impl VocabularyMut<Iri = T, BlankId = B>, object: jstrict::Object) -> Result<Self, InvalidExpandedJson>;
889}
890
891impl<T, B, V: TryFromJson<T, B>> TryFromJson<T, B> for Vec<V> {
892    fn try_from_json_in(vocabulary: &mut impl VocabularyMut<Iri = T, BlankId = B>, value: jstrict::Value) -> Result<Self, InvalidExpandedJson> {
893        match value {
894            jstrict::Value::Array(items) => {
895                let mut result = Vec::new();
896
897                for item in items {
898                    result.push(V::try_from_json_in(vocabulary, item)?);
899                }
900
901                Ok(result)
902            }
903            _ => Err(InvalidExpandedJson::InvalidList),
904        }
905    }
906}
907
908impl<T, B, V: Eq + Hash + TryFromJson<T, B>> TryFromJson<T, B> for IndexSet<V> {
909    fn try_from_json_in(vocabulary: &mut impl VocabularyMut<Iri = T, BlankId = B>, value: jstrict::Value) -> Result<Self, InvalidExpandedJson> {
910        match value {
911            jstrict::Value::Array(items) => {
912                let mut result = IndexSet::default();
913
914                for item in items {
915                    result.insert(V::try_from_json_in(vocabulary, item)?);
916                }
917
918                Ok(result)
919            }
920            _ => Err(InvalidExpandedJson::InvalidList),
921        }
922    }
923}
924
925impl<T: Eq + Hash, B: Eq + Hash> TryFromJson<T, B> for Object<T, B> {
926    fn try_from_json_in(vocabulary: &mut impl VocabularyMut<Iri = T, BlankId = B>, value: jstrict::Value) -> Result<Self, InvalidExpandedJson> {
927        match value {
928            jstrict::Value::Object(object) => Self::try_from_json_object_in(vocabulary, object),
929            _ => Err(InvalidExpandedJson::InvalidObject),
930        }
931    }
932}
933
934impl<T: Eq + Hash, B: Eq + Hash> TryFromJsonObject<T, B> for Object<T, B> {
935    fn try_from_json_object_in(vocabulary: &mut impl VocabularyMut<Iri = T, BlankId = B>, mut object: jstrict::Object) -> Result<Self, InvalidExpandedJson> {
936        match object.remove_unique("@context").map_err(InvalidExpandedJson::duplicate_key)? {
937            Some(_) => Err(InvalidExpandedJson::NotExpanded),
938            None => {
939                if let Some(value_entry) = object.remove_unique("@value").map_err(InvalidExpandedJson::duplicate_key)? {
940                    Ok(Self::Value(Value::try_from_json_object_in(vocabulary, object, value_entry)?))
941                } else if let Some(list_entry) = object.remove_unique("@list").map_err(InvalidExpandedJson::duplicate_key)? {
942                    Ok(Self::List(List::try_from_json_object_in(vocabulary, object, list_entry)?))
943                } else {
944                    let node = Node::try_from_json_object_in(vocabulary, object)?;
945                    Ok(Self::node(node))
946                }
947            }
948        }
949    }
950}
951
952/// Invalid expanded JSON object error.
953///
954/// This can be raised when trying to directly convert a JSON value into an
955/// expanded JSON-LD object without using the expansion algorithm.
956#[derive(Debug, thiserror::Error)]
957pub enum InvalidExpandedJson {
958    /// The value is not a JSON object.
959    #[error("invalid object")]
960    InvalidObject,
961    /// The `@list` entry does not hold an array.
962    #[error("invalid `@list` value")]
963    InvalidList,
964    /// The `@index` entry does not hold a string.
965    #[error("invalid `@index` value")]
966    InvalidIndex,
967    /// The `@id` entry does not hold a valid identifier.
968    #[error("invalid `@id` value")]
969    InvalidId,
970    /// The `@type` entry of a value object is invalid.
971    #[error("invalid `@type` value")]
972    InvalidValueType,
973    /// The `@value` entry does not hold a literal.
974    #[error("invalid literal")]
975    InvalidLiteral,
976    /// The `@language` entry does not hold a language tag.
977    #[error("invalid `@language` value")]
978    InvalidLanguage,
979    /// The `@direction` entry does not hold `ltr` or `rtl`.
980    #[error("invalid `@direction` value")]
981    InvalidDirection,
982    /// The value is not a well-formed language-tagged string.
983    #[error("invalid language-tagged string")]
984    InvalidLangString,
985    /// The document is not in expanded form.
986    #[error("not an expanded document")]
987    NotExpanded,
988    /// The object carries an entry that is not allowed here.
989    #[error("unexpected entry")]
990    UnexpectedEntry,
991    /// The object carries the same key twice.
992    #[error("duplicate key `{0}`")]
993    DuplicateKey(jstrict::object::Key),
994    /// A value of the wrong JSON kind was found.
995    #[error("unexpected {0}, expected {1}")]
996    Unexpected(jstrict::Kind, jstrict::Kind),
997}
998
999impl InvalidExpandedJson {
1000    /// Builds a duplicate-key error from the duplicate `jstrict` reports.
1001    #[must_use]
1002    pub fn duplicate_key(jstrict::object::Duplicate(a, _): jstrict::object::Duplicate<jstrict::object::Entry>) -> Self {
1003        InvalidExpandedJson::DuplicateKey(a.key)
1004    }
1005}
1006
1007impl<T, B> Any<T, B> for Object<T, B> {
1008    #[inline(always)]
1009    fn as_ref(&self) -> Ref<'_, T, B> {
1010        match self {
1011            Object::Value(value) => Ref::Value(value),
1012            Object::Node(node) => Ref::Node(node),
1013            Object::List(list) => Ref::List(list),
1014        }
1015    }
1016}
1017
1018impl<T, B> From<Value<T>> for Object<T, B> {
1019    #[inline(always)]
1020    fn from(value: Value<T>) -> Self {
1021        Self::Value(value)
1022    }
1023}
1024
1025impl<T, B> From<Node<T, B>> for Object<T, B> {
1026    #[inline(always)]
1027    fn from(node: Node<T, B>) -> Self {
1028        Self::node(node)
1029    }
1030}
1031
1032/// Iterator through the types of an object.
1033pub enum Types<'a, T, B> {
1034    /// A value object.
1035    Value(Option<value::TypeRef<'a, T>>),
1036    /// A node object.
1037    Node(std::slice::Iter<'a, Id<T, B>>),
1038    /// A list object.
1039    List,
1040}
1041
1042impl<'a, T, B> Iterator for Types<'a, T, B> {
1043    type Item = TypeRef<'a, T, B>;
1044
1045    fn next(&mut self) -> Option<Self::Item> {
1046        match self {
1047            Self::Value(ty) => ty.take().map(TypeRef::from_value_type),
1048            Self::Node(tys) => tys.next().map(TypeRef::from_reference),
1049            Self::List => None,
1050        }
1051    }
1052}
1053
1054/// Iterator through indexed objects.
1055pub struct Objects<'a, T, B>(Option<std::slice::Iter<'a, IndexedObject<T, B>>>);
1056
1057impl<'a, T, B> Objects<'a, T, B> {
1058    #[inline(always)]
1059    pub(crate) fn new(inner: Option<std::slice::Iter<'a, IndexedObject<T, B>>>) -> Self {
1060        Self(inner)
1061    }
1062}
1063
1064impl<'a, T, B> Iterator for Objects<'a, T, B> {
1065    type Item = &'a IndexedObject<T, B>;
1066
1067    #[inline(always)]
1068    fn next(&mut self) -> Option<&'a IndexedObject<T, B>> {
1069        match &mut self.0 {
1070            None => None,
1071            Some(it) => it.next(),
1072        }
1073    }
1074}
1075
1076/// Object fragment.
1077pub enum FragmentRef<'a, T, B> {
1078    /// "@index" entry.
1079    IndexEntry(&'a str),
1080
1081    /// "@index" entry key.
1082    IndexKey,
1083
1084    /// "@index" entry value.
1085    IndexValue(&'a str),
1086
1087    /// Object.
1088    Object(&'a Object<T, B>),
1089
1090    /// Indexed object.
1091    IndexedObject(&'a Indexed<Object<T, B>>),
1092
1093    /// Node object.
1094    Node(&'a Node<T, B>),
1095
1096    /// Indexed node object.
1097    IndexedNode(&'a IndexedNode<T, B>),
1098
1099    /// Indexed node list.
1100    IndexedNodeList(&'a [IndexedNode<T, B>]),
1101
1102    /// Value object fragment.
1103    ValueFragment(value::FragmentRef<'a, T>),
1104
1105    /// List object fragment.
1106    ListFragment(list::FragmentRef<'a, T, B>),
1107
1108    /// Node object fragment.
1109    NodeFragment(node::FragmentRef<'a, T, B>),
1110}
1111
1112impl<'a, T, B> FragmentRef<'a, T, B> {
1113    /// Returns the object this fragment stands for, if it is one.
1114    #[must_use]
1115    pub fn into_ref(self) -> Option<Ref<'a, T, B>> {
1116        match self {
1117            Self::Object(o) => Some(o.as_ref()),
1118            Self::IndexedObject(o) => Some(o.inner().as_ref()),
1119            Self::Node(n) => Some(n.as_ref()),
1120            Self::IndexedNode(n) => Some(n.inner().as_ref()),
1121            _ => None,
1122        }
1123    }
1124
1125    /// Returns the identifier this fragment stands for, if it is one.
1126    pub fn into_id(self) -> Option<Id<&'a T, &'a B>> {
1127        match self {
1128            Self::ValueFragment(i) => i.into_iri().map(Id::iri),
1129            Self::NodeFragment(i) => i.into_id().map(Into::into),
1130            _ => None,
1131        }
1132    }
1133
1134    /// Returns the identifier this fragment stands for, if it is one.
1135    pub fn as_id(&self) -> Option<Id<&'a T, &'a B>> {
1136        match self {
1137            Self::ValueFragment(i) => i.as_iri().map(Id::iri),
1138            Self::NodeFragment(i) => i.as_id().map(Into::into),
1139            _ => None,
1140        }
1141    }
1142
1143    /// Checks whether this fragment renders as a JSON array.
1144    #[must_use]
1145    pub fn is_json_array(&self) -> bool {
1146        match self {
1147            Self::IndexedNodeList(_) => true,
1148            Self::ValueFragment(i) => i.is_json_array(),
1149            Self::NodeFragment(n) => n.is_json_array(),
1150            _ => false,
1151        }
1152    }
1153
1154    /// Checks whether this fragment renders as a JSON object.
1155    #[must_use]
1156    pub fn is_json_object(&self) -> bool {
1157        match self {
1158            Self::Object(_) | Self::IndexedObject(_) | Self::Node(_) | Self::IndexedNode(_) => true,
1159            Self::ValueFragment(i) => i.is_json_object(),
1160            Self::NodeFragment(i) => i.is_json_object(),
1161            _ => false,
1162        }
1163    }
1164
1165    /// Returns an iterator over the fragments directly contained in this one.
1166    #[must_use]
1167    pub fn sub_fragments(&self) -> SubFragments<'a, T, B> {
1168        match self {
1169            Self::IndexEntry(v) => SubFragments::IndexEntry(Some(()), Some(v)),
1170            Self::Object(o) => SubFragments::Object(None, o.sub_fragments()),
1171            Self::IndexedObject(o) => SubFragments::Object(o.index(), o.sub_fragments()),
1172            Self::Node(n) => SubFragments::Object(None, ObjectSubFragments::Node(n.entries())),
1173            Self::IndexedNode(n) => SubFragments::Object(n.index(), ObjectSubFragments::Node(n.inner().entries())),
1174            Self::IndexedNodeList(l) => SubFragments::IndexedNodeList(l.iter()),
1175            Self::ValueFragment(i) => SubFragments::Value(i.sub_fragments()),
1176            Self::NodeFragment(i) => SubFragments::Node(i.sub_fragments()),
1177            Self::ListFragment(l) => SubFragments::List(l.sub_fragments()),
1178            Self::IndexKey | Self::IndexValue(_) => SubFragments::None,
1179        }
1180    }
1181}
1182
1183/// Iterator over the fragments directly held by an object.
1184pub enum ObjectSubFragments<'a, T, B> {
1185    /// A list object.
1186    List(Option<&'a [IndexedObject<T, B>]>),
1187    /// A value object.
1188    Value(value::Entries<'a, T>),
1189    /// A node object.
1190    Node(node::Entries<'a, T, B>),
1191}
1192
1193impl<'a, T, B> Iterator for ObjectSubFragments<'a, T, B> {
1194    type Item = FragmentRef<'a, T, B>;
1195
1196    fn next(&mut self) -> Option<Self::Item> {
1197        match self {
1198            Self::List(l) => l.take().map(|e| FragmentRef::ListFragment(list::FragmentRef::Entry(e))),
1199            Self::Value(e) => e.next_back().map(|e| FragmentRef::ValueFragment(value::FragmentRef::Entry(e))),
1200            Self::Node(e) => e.next().map(|e| FragmentRef::NodeFragment(node::FragmentRef::Entry(e))),
1201        }
1202    }
1203}
1204
1205/// Iterator over the fragments directly held by a document fragment.
1206pub enum SubFragments<'a, T, B> {
1207    /// No value.
1208    None,
1209    /// The `@index` entry of an indexed fragment.
1210    IndexEntry(Option<()>, Option<&'a str>),
1211    /// A JSON object.
1212    Object(Option<&'a str>, ObjectSubFragments<'a, T, B>),
1213    /// A value object.
1214    Value(value::SubFragments<'a, T>),
1215    /// A node object.
1216    Node(node::SubFragments<'a, T, B>),
1217    /// A list object.
1218    List(list::SubFragments<'a, T, B>),
1219    /// A list of indexed node objects.
1220    IndexedNodeList(std::slice::Iter<'a, IndexedNode<T, B>>),
1221}
1222
1223impl<'a, T, B> Iterator for SubFragments<'a, T, B> {
1224    type Item = FragmentRef<'a, T, B>;
1225
1226    fn next(&mut self) -> Option<Self::Item> {
1227        match self {
1228            Self::None => None,
1229            Self::IndexEntry(k, v) => k.take().map(|()| FragmentRef::IndexKey).or_else(|| v.take().map(FragmentRef::IndexValue)),
1230            Self::Object(index, i) => match index.take() {
1231                Some(index) => Some(FragmentRef::IndexEntry(index)),
1232                None => i.next(),
1233            },
1234            Self::Value(i) => i.next().map(FragmentRef::ValueFragment),
1235            Self::Node(i) => i.next(),
1236            Self::List(i) => i.next(),
1237            Self::IndexedNodeList(i) => i.next().map(FragmentRef::IndexedNode),
1238        }
1239    }
1240}
1241
1242/// Depth-first iterator over a fragment and everything it contains.
1243pub struct Traverse<'a, T, B> {
1244    stack: SmallVec<[FragmentRef<'a, T, B>; 8]>,
1245}
1246
1247impl<'a, T, B> Traverse<'a, T, B> {
1248    pub(crate) fn new(items: impl IntoIterator<Item = FragmentRef<'a, T, B>>) -> Self {
1249        let stack = items.into_iter().collect();
1250        Self { stack }
1251    }
1252}
1253
1254impl<'a, T, B> Iterator for Traverse<'a, T, B> {
1255    type Item = FragmentRef<'a, T, B>;
1256
1257    fn next(&mut self) -> Option<Self::Item> {
1258        match self.stack.pop() {
1259            Some(item) => {
1260                self.stack.extend(item.sub_fragments());
1261                Some(item)
1262            }
1263            None => None,
1264        }
1265    }
1266}
1267
1268impl<T, B, N: Vocabulary<Iri = T, BlankId = B>> IntoJsonWithContext<N> for Object<T, B> {
1269    fn into_json_with(self, vocabulary: &N) -> jstrict::Value {
1270        match self {
1271            Self::Value(v) => v.into_json_with(vocabulary),
1272            Self::Node(n) => n.into_json_with(vocabulary),
1273            Self::List(l) => l.into_json_with(vocabulary),
1274        }
1275    }
1276}
jsonld_core/object/mod.rs

jsonld_core/object/
mod.rs
