json_ld/
tracing.rs

1use std::sync::Arc;
2
3use into_owned_trait::IntoOwned;
4use json_syntax::tracing::{JsonBacktrace, JsonBacktraceBuf, JsonBacktraceBuilder, JsonLocated};
5use rdf_syntax::{Iri, IriBuf};
6
7use crate::{JsonLdExpandedDocument, JsonLdFlattenedDocument};
8
9/// Backtrace builder for the JSON-LD processing algorithms.
10///
11/// Accumulates [`JsonLdSourceFileRef`] frames during processing and produces a
12/// [`JsonLdLocated`] value when an error is emitted.
13pub type JsonLdBacktraceBuilder<'a> = JsonBacktraceBuilder<'a, JsonLdSourceFileRef<'a>>;
14
15pub type JsonLdBacktrace = JsonBacktrace<JsonLdSourceFile>;
16
17pub type JsonLdBacktraceBuf = JsonBacktraceBuf<JsonLdSourceFile>;
18
19/// A value annotated with a JSON-LD processing backtrace.
20///
21/// Each frame in the backtrace identifies the source file (which document, at
22/// which processing stage) and the JSON fragment path within it where the
23/// annotated value was produced.
24pub type JsonLdLocated<T> = JsonLocated<T, JsonLdSourceFile>;
25
26/// Borrowed counterpart of [`JsonLdSourceFile`], used while building a backtrace.
27///
28/// Carries references rather than owned values so that frames can be pushed
29/// cheaply onto the [`JsonLdBacktraceBuilder`] stack during processing.
30#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
31pub struct JsonLdSourceFileRef<'a> {
32	/// URL of the document, if any.
33	pub iri: Option<&'a Iri>,
34
35	/// Form of the document at this stage of the processing.
36	pub form: JsonLdDocumentFormRef<'a>,
37}
38
39impl<'a> JsonLdSourceFileRef<'a> {
40	/// Original document, as provided to the algorithm (a JSON-LD document or
41	/// a context document).
42	pub fn original(iri: Option<&'a Iri>) -> Self {
43		Self {
44			iri,
45			form: JsonLdDocumentFormRef::Original,
46		}
47	}
48
49	/// Intermediate expanded version of the document.
50	pub fn expanded(iri: Option<&'a Iri>, document: &'a Arc<JsonLdExpandedDocument>) -> Self {
51		Self {
52			iri,
53			form: JsonLdDocumentFormRef::Expanded(document),
54		}
55	}
56
57	/// Intermediate flattened version of the document.
58	pub fn flattened(iri: Option<&'a Iri>, document: &'a Arc<JsonLdFlattenedDocument>) -> Self {
59		Self {
60			iri,
61			form: JsonLdDocumentFormRef::Flattened(document),
62		}
63	}
64}
65
66impl IntoOwned for JsonLdSourceFileRef<'_> {
67	type Owned = JsonLdSourceFile;
68
69	fn into_owned(self) -> JsonLdSourceFile {
70		JsonLdSourceFile {
71			iri: self.iri.map(Iri::to_owned),
72			form: self.form.into_owned(),
73		}
74	}
75}
76
77/// Borrowed counterpart of [`JsonLdDocumentForm`].
78#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
79pub enum JsonLdDocumentFormRef<'a> {
80	/// Original document.
81	Original,
82
83	/// Expanded version of the document.
84	Expanded(&'a Arc<JsonLdExpandedDocument>),
85
86	/// Flattened version of the document.
87	Flattened(&'a Arc<JsonLdFlattenedDocument>),
88}
89
90impl IntoOwned for JsonLdDocumentFormRef<'_> {
91	type Owned = JsonLdDocumentForm;
92
93	fn into_owned(self) -> JsonLdDocumentForm {
94		match self {
95			Self::Original => JsonLdDocumentForm::Original,
96			Self::Expanded(document) => JsonLdDocumentForm::Expanded(document.clone()),
97			Self::Flattened(document) => JsonLdDocumentForm::Flattened(document.clone()),
98		}
99	}
100}
101
102/// Source file of a JSON-LD processing backtrace frame.
103///
104/// Identifies which document, and at which stage of the processing pipeline, a
105/// particular step took place. The optional [`IriBuf`] is the document's URL;
106/// `None` means the document was provided inline with no associated URL.
107///
108/// The [`JsonLdDocumentForm`] additionally carries a shared reference to the
109/// actual intermediate document, if any, so that diagnostic renderers can
110/// locate and display the relevant JSON fragment.
111#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
112pub struct JsonLdSourceFile {
113	/// URL of the document, if any.
114	pub iri: Option<IriBuf>,
115
116	/// Form of the document at this stage of the processing.
117	pub form: JsonLdDocumentForm,
118}
119
120impl JsonLdSourceFile {
121	/// Original document, as provided to the algorithm (a JSON-LD document or
122	/// a context document).
123	pub fn original(iri: Option<IriBuf>) -> Self {
124		Self {
125			iri,
126			form: JsonLdDocumentForm::Original,
127		}
128	}
129
130	/// Intermediate expanded version of the document.
131	pub fn expanded(iri: Option<IriBuf>, document: Arc<JsonLdExpandedDocument>) -> Self {
132		Self {
133			iri,
134			form: JsonLdDocumentForm::Expanded(document),
135		}
136	}
137
138	/// Intermediate flattened version of the document.
139	pub fn flattened(iri: Option<IriBuf>, document: Arc<JsonLdFlattenedDocument>) -> Self {
140		Self {
141			iri,
142			form: JsonLdDocumentForm::Flattened(document),
143		}
144	}
145}
146
147/// Form of a document at a given stage of the JSON-LD processing pipeline.
148#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
149pub enum JsonLdDocumentForm {
150	/// Original document, as provided to the algorithm (a JSON-LD document or
151	/// a context document).
152	Original,
153
154	/// Intermediate expanded version of the document, together with its
155	/// content.
156	Expanded(Arc<JsonLdExpandedDocument>),
157
158	/// Intermediate flattened version of the document, together with its
159	/// content.
160	Flattened(Arc<JsonLdFlattenedDocument>),
161}
json_ld/tracing.rs

json_ld/
tracing.rs
