bevy_reflect/serde/de/deserializer.rs
1#[cfg(feature = "debug_stack")]
2use crate::serde::de::error_utils::TYPE_INFO_STACK;
3use crate::serde::{ReflectDeserializeWithRegistry, SerializationData};
4use crate::ReflectFromReflect;
5use crate::{
6 serde::{
7 de::{
8 arrays::ArrayVisitor, enums::EnumVisitor, error_utils::make_custom_error,
9 lists::ListVisitor, maps::MapVisitor, options::OptionVisitor, sets::SetVisitor,
10 structs::StructVisitor, tuple_structs::TupleStructVisitor, tuples::TupleVisitor,
11 },
12 TypeRegistrationDeserializer,
13 },
14 PartialReflect, ReflectDeserialize, TypeInfo, TypePath, TypeRegistration, TypeRegistry,
15};
16use alloc::boxed::Box;
17use core::{fmt, fmt::Formatter};
18use serde::de::{DeserializeSeed, Error, IgnoredAny, MapAccess, Visitor};
19
20use super::ReflectDeserializerProcessor;
21
22/// A general purpose deserializer for reflected types.
23///
24/// This is the deserializer counterpart to [`ReflectSerializer`].
25///
26/// See [`TypedReflectDeserializer`] for a deserializer that expects a known type.
27///
28/// # Input
29///
30/// This deserializer expects a map with a single entry,
31/// where the key is the _full_ [type path] of the reflected type
32/// and the value is the serialized data.
33///
34/// # Output
35///
36/// This deserializer will return a [`Box<dyn Reflect>`] containing the deserialized data.
37///
38/// For opaque types (i.e. [`ReflectKind::Opaque`]) or types that register [`ReflectDeserialize`] type data,
39/// this `Box` will contain the expected type.
40/// For example, deserializing an `i32` will return a `Box<i32>` (as a `Box<dyn Reflect>`).
41///
42/// Otherwise, this `Box` will contain the dynamic equivalent.
43/// For example, a deserialized struct might return a [`Box<DynamicStruct>`]
44/// and a deserialized `Vec` might return a [`Box<DynamicList>`].
45///
46/// This means that if the actual type is needed, these dynamic representations will need to
47/// be converted to the concrete type using [`FromReflect`] or [`ReflectFromReflect`].
48///
49/// If you want to override deserialization for a specific [`TypeRegistration`],
50/// you can pass in a reference to a [`ReflectDeserializerProcessor`] which will
51/// take priority over all other deserialization methods - see [`with_processor`].
52///
53/// # Example
54///
55/// ```
56/// # use serde::de::DeserializeSeed;
57/// # use bevy_reflect::prelude::*;
58/// # use bevy_reflect::{DynamicStruct, TypeRegistry, serde::ReflectDeserializer};
59/// #[derive(Reflect, PartialEq, Debug)]
60/// #[type_path = "my_crate"]
61/// struct MyStruct {
62/// value: i32
63/// }
64///
65/// let mut registry = TypeRegistry::default();
66/// registry.register::<MyStruct>();
67///
68/// let input = r#"{
69/// "my_crate::MyStruct": (
70/// value: 123
71/// )
72/// }"#;
73///
74/// let mut deserializer = ron::Deserializer::from_str(input).unwrap();
75/// let reflect_deserializer = ReflectDeserializer::new(®istry);
76///
77/// let output: Box<dyn PartialReflect> = reflect_deserializer.deserialize(&mut deserializer).unwrap();
78///
79/// // Since `MyStruct` is not an opaque type and does not register `ReflectDeserialize`,
80/// // we know that its deserialized value will be a `DynamicStruct`,
81/// // although it will represent `MyStruct`.
82/// assert!(output.as_partial_reflect().represents::<MyStruct>());
83///
84/// // We can convert back to `MyStruct` using `FromReflect`.
85/// let value: MyStruct = <MyStruct as FromReflect>::from_reflect(output.as_partial_reflect()).unwrap();
86/// assert_eq!(value, MyStruct { value: 123 });
87///
88/// // We can also do this dynamically with `ReflectFromReflect`.
89/// let type_id = output.get_represented_type_info().unwrap().type_id();
90/// let reflect_from_reflect = registry.get_type_data::<ReflectFromReflect>(type_id).unwrap();
91/// let value: Box<dyn Reflect> = reflect_from_reflect.from_reflect(output.as_partial_reflect()).unwrap();
92/// assert!(value.is::<MyStruct>());
93/// assert_eq!(value.take::<MyStruct>().unwrap(), MyStruct { value: 123 });
94/// ```
95///
96/// [`ReflectSerializer`]: crate::serde::ReflectSerializer
97/// [type path]: crate::TypePath::type_path
98/// [`Box<dyn Reflect>`]: crate::Reflect
99/// [`ReflectKind::Opaque`]: crate::ReflectKind::Opaque
100/// [`ReflectDeserialize`]: crate::ReflectDeserialize
101/// [`Box<DynamicStruct>`]: crate::DynamicStruct
102/// [`Box<DynamicList>`]: crate::DynamicList
103/// [`FromReflect`]: crate::FromReflect
104/// [`ReflectFromReflect`]: crate::ReflectFromReflect
105/// [`with_processor`]: Self::with_processor
106pub struct ReflectDeserializer<'a, P: ReflectDeserializerProcessor = ()> {
107 registry: &'a TypeRegistry,
108 processor: Option<&'a mut P>,
109}
110
111impl<'a> ReflectDeserializer<'a, ()> {
112 /// Creates a deserializer with no processor.
113 ///
114 /// If you want to add custom logic for deserializing certain types, use
115 /// [`with_processor`].
116 ///
117 /// [`with_processor`]: Self::with_processor
118 pub fn new(registry: &'a TypeRegistry) -> Self {
119 Self {
120 registry,
121 processor: None,
122 }
123 }
124}
125
126impl<'a, P: ReflectDeserializerProcessor> ReflectDeserializer<'a, P> {
127 /// Creates a deserializer with a processor.
128 ///
129 /// If you do not need any custom logic for handling certain types, use
130 /// [`new`].
131 ///
132 /// [`new`]: Self::new
133 pub fn with_processor(registry: &'a TypeRegistry, processor: &'a mut P) -> Self {
134 Self {
135 registry,
136 processor: Some(processor),
137 }
138 }
139}
140
141impl<'de, P: ReflectDeserializerProcessor> DeserializeSeed<'de> for ReflectDeserializer<'_, P> {
142 type Value = Box<dyn PartialReflect>;
143
144 fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
145 where
146 D: serde::Deserializer<'de>,
147 {
148 struct UntypedReflectDeserializerVisitor<'a, P> {
149 registry: &'a TypeRegistry,
150 processor: Option<&'a mut P>,
151 }
152
153 impl<'de, P: ReflectDeserializerProcessor> Visitor<'de>
154 for UntypedReflectDeserializerVisitor<'_, P>
155 {
156 type Value = Box<dyn PartialReflect>;
157
158 fn expecting(&self, formatter: &mut Formatter) -> fmt::Result {
159 formatter
160 .write_str("map containing `type` and `value` entries for the reflected value")
161 }
162
163 fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
164 where
165 A: MapAccess<'de>,
166 {
167 let registration = map
168 .next_key_seed(TypeRegistrationDeserializer::new(self.registry))?
169 .ok_or_else(|| Error::invalid_length(0, &"a single entry"))?;
170
171 let value = map.next_value_seed(TypedReflectDeserializer::new_internal(
172 registration,
173 self.registry,
174 self.processor,
175 ))?;
176
177 if map.next_key::<IgnoredAny>()?.is_some() {
178 return Err(Error::invalid_length(2, &"a single entry"));
179 }
180
181 Ok(value)
182 }
183 }
184
185 deserializer.deserialize_map(UntypedReflectDeserializerVisitor {
186 registry: self.registry,
187 processor: self.processor,
188 })
189 }
190}
191
192/// A deserializer for reflected types whose [`TypeRegistration`] is known.
193///
194/// This is the deserializer counterpart to [`TypedReflectSerializer`].
195///
196/// See [`ReflectDeserializer`] for a deserializer that expects an unknown type.
197///
198/// # Input
199///
200/// Since the type is already known, the input is just the serialized data.
201///
202/// # Output
203///
204/// This deserializer will return a [`Box<dyn Reflect>`] containing the deserialized data.
205///
206/// For opaque types (i.e. [`ReflectKind::Opaque`]) or types that register [`ReflectDeserialize`] type data,
207/// this `Box` will contain the expected type.
208/// For example, deserializing an `i32` will return a `Box<i32>` (as a `Box<dyn Reflect>`).
209///
210/// Otherwise, this `Box` will contain the dynamic equivalent.
211/// For example, a deserialized struct might return a [`Box<DynamicStruct>`]
212/// and a deserialized `Vec` might return a [`Box<DynamicList>`].
213///
214/// This means that if the actual type is needed, these dynamic representations will need to
215/// be converted to the concrete type using [`FromReflect`] or [`ReflectFromReflect`].
216///
217/// If you want to override deserialization for a specific [`TypeRegistration`],
218/// you can pass in a reference to a [`ReflectDeserializerProcessor`] which will
219/// take priority over all other deserialization methods - see [`with_processor`].
220///
221/// # Example
222///
223/// ```
224/// # use core::any::TypeId;
225/// # use serde::de::DeserializeSeed;
226/// # use bevy_reflect::prelude::*;
227/// # use bevy_reflect::{DynamicStruct, TypeRegistry, serde::TypedReflectDeserializer};
228/// #[derive(Reflect, PartialEq, Debug)]
229/// struct MyStruct {
230/// value: i32
231/// }
232///
233/// let mut registry = TypeRegistry::default();
234/// registry.register::<MyStruct>();
235///
236/// let input = r#"(
237/// value: 123
238/// )"#;
239///
240/// let registration = registry.get(TypeId::of::<MyStruct>()).unwrap();
241///
242/// let mut deserializer = ron::Deserializer::from_str(input).unwrap();
243/// let reflect_deserializer = TypedReflectDeserializer::new(registration, ®istry);
244///
245/// let output: Box<dyn PartialReflect> = reflect_deserializer.deserialize(&mut deserializer).unwrap();
246///
247/// // Since `MyStruct` is not an opaque type and does not register `ReflectDeserialize`,
248/// // we know that its deserialized value will be a `DynamicStruct`,
249/// // although it will represent `MyStruct`.
250/// assert!(output.as_partial_reflect().represents::<MyStruct>());
251///
252/// // We can convert back to `MyStruct` using `FromReflect`.
253/// let value: MyStruct = <MyStruct as FromReflect>::from_reflect(output.as_partial_reflect()).unwrap();
254/// assert_eq!(value, MyStruct { value: 123 });
255///
256/// // We can also do this dynamically with `ReflectFromReflect`.
257/// let type_id = output.get_represented_type_info().unwrap().type_id();
258/// let reflect_from_reflect = registry.get_type_data::<ReflectFromReflect>(type_id).unwrap();
259/// let value: Box<dyn Reflect> = reflect_from_reflect.from_reflect(output.as_partial_reflect()).unwrap();
260/// assert!(value.is::<MyStruct>());
261/// assert_eq!(value.take::<MyStruct>().unwrap(), MyStruct { value: 123 });
262/// ```
263///
264/// [`TypedReflectSerializer`]: crate::serde::TypedReflectSerializer
265/// [`Box<dyn Reflect>`]: crate::Reflect
266/// [`ReflectKind::Opaque`]: crate::ReflectKind::Opaque
267/// [`ReflectDeserialize`]: crate::ReflectDeserialize
268/// [`Box<DynamicStruct>`]: crate::DynamicStruct
269/// [`Box<DynamicList>`]: crate::DynamicList
270/// [`FromReflect`]: crate::FromReflect
271/// [`ReflectFromReflect`]: crate::ReflectFromReflect
272/// [`with_processor`]: Self::with_processor
273pub struct TypedReflectDeserializer<'a, P: ReflectDeserializerProcessor = ()> {
274 registration: &'a TypeRegistration,
275 registry: &'a TypeRegistry,
276 processor: Option<&'a mut P>,
277}
278
279impl<'a> TypedReflectDeserializer<'a, ()> {
280 /// Creates a typed deserializer with no processor.
281 ///
282 /// If you want to add custom logic for deserializing certain types, use
283 /// [`with_processor`].
284 ///
285 /// [`with_processor`]: Self::with_processor
286 pub fn new(registration: &'a TypeRegistration, registry: &'a TypeRegistry) -> Self {
287 #[cfg(feature = "debug_stack")]
288 TYPE_INFO_STACK.set(crate::type_info_stack::TypeInfoStack::new());
289
290 Self {
291 registration,
292 registry,
293 processor: None,
294 }
295 }
296
297 /// Creates a new [`TypedReflectDeserializer`] for the given type `T`
298 /// without a processor.
299 ///
300 /// # Panics
301 ///
302 /// Panics if `T` is not registered in the given [`TypeRegistry`].
303 pub fn of<T: TypePath>(registry: &'a TypeRegistry) -> Self {
304 let registration = registry
305 .get(core::any::TypeId::of::<T>())
306 .unwrap_or_else(|| panic!("no registration found for type `{}`", T::type_path()));
307
308 Self {
309 registration,
310 registry,
311 processor: None,
312 }
313 }
314}
315
316impl<'a, P: ReflectDeserializerProcessor> TypedReflectDeserializer<'a, P> {
317 /// Creates a typed deserializer with a processor.
318 ///
319 /// If you do not need any custom logic for handling certain types, use
320 /// [`new`].
321 ///
322 /// [`new`]: Self::new
323 pub fn with_processor(
324 registration: &'a TypeRegistration,
325 registry: &'a TypeRegistry,
326 processor: &'a mut P,
327 ) -> Self {
328 #[cfg(feature = "debug_stack")]
329 TYPE_INFO_STACK.set(crate::type_info_stack::TypeInfoStack::new());
330
331 Self {
332 registration,
333 registry,
334 processor: Some(processor),
335 }
336 }
337
338 /// An internal constructor for creating a deserializer without resetting the type info stack.
339 pub(super) fn new_internal(
340 registration: &'a TypeRegistration,
341 registry: &'a TypeRegistry,
342 processor: Option<&'a mut P>,
343 ) -> Self {
344 Self {
345 registration,
346 registry,
347 processor,
348 }
349 }
350}
351
352impl<'de, P: ReflectDeserializerProcessor> DeserializeSeed<'de>
353 for TypedReflectDeserializer<'_, P>
354{
355 type Value = Box<dyn PartialReflect>;
356
357 fn deserialize<D>(mut self, deserializer: D) -> Result<Self::Value, D::Error>
358 where
359 D: serde::Deserializer<'de>,
360 {
361 let deserialize_internal = || -> Result<Self::Value, D::Error> {
362 // First, check if our processor wants to deserialize this type
363 // This takes priority over any other deserialization operations
364 let deserializer = if let Some(processor) = self.processor.as_deref_mut() {
365 match processor.try_deserialize(self.registration, self.registry, deserializer) {
366 Ok(Ok(value)) => {
367 return Ok(value);
368 }
369 Err(err) => {
370 return Err(make_custom_error(err));
371 }
372 Ok(Err(deserializer)) => deserializer,
373 }
374 } else {
375 deserializer
376 };
377
378 let type_path = self.registration.type_info().type_path();
379
380 // Handle both Value case and types that have a custom `ReflectDeserialize`
381 if let Some(deserialize_reflect) = self.registration.data::<ReflectDeserialize>() {
382 let value = deserialize_reflect.deserialize(deserializer)?;
383 return Ok(value.into_partial_reflect());
384 }
385
386 if let Some(deserialize_reflect) =
387 self.registration.data::<ReflectDeserializeWithRegistry>()
388 {
389 let value = deserialize_reflect.deserialize(deserializer, self.registry)?;
390 return Ok(value);
391 }
392
393 let dynamic_value: Box<dyn PartialReflect> = match self.registration.type_info() {
394 TypeInfo::Struct(struct_info) => {
395 let mut dynamic_struct = deserializer.deserialize_struct(
396 struct_info.type_path_table().ident().unwrap(),
397 struct_info.field_names(),
398 StructVisitor {
399 struct_info,
400 registration: self.registration,
401 registry: self.registry,
402 processor: self.processor,
403 },
404 )?;
405 dynamic_struct.set_represented_type(Some(self.registration.type_info()));
406 Box::new(dynamic_struct)
407 }
408 TypeInfo::TupleStruct(tuple_struct_info) => {
409 let mut dynamic_tuple_struct = if tuple_struct_info.field_len() == 1
410 && self.registration.data::<SerializationData>().is_none()
411 {
412 deserializer.deserialize_newtype_struct(
413 tuple_struct_info.type_path_table().ident().unwrap(),
414 TupleStructVisitor {
415 tuple_struct_info,
416 registration: self.registration,
417 registry: self.registry,
418 processor: self.processor,
419 },
420 )?
421 } else {
422 deserializer.deserialize_tuple_struct(
423 tuple_struct_info.type_path_table().ident().unwrap(),
424 tuple_struct_info.field_len(),
425 TupleStructVisitor {
426 tuple_struct_info,
427 registration: self.registration,
428 registry: self.registry,
429 processor: self.processor,
430 },
431 )?
432 };
433 dynamic_tuple_struct.set_represented_type(Some(self.registration.type_info()));
434 Box::new(dynamic_tuple_struct)
435 }
436 TypeInfo::List(list_info) => {
437 let mut dynamic_list = deserializer.deserialize_seq(ListVisitor {
438 list_info,
439 registry: self.registry,
440 processor: self.processor,
441 })?;
442 dynamic_list.set_represented_type(Some(self.registration.type_info()));
443 Box::new(dynamic_list)
444 }
445 TypeInfo::Array(array_info) => {
446 let mut dynamic_array = deserializer.deserialize_tuple(
447 array_info.capacity(),
448 ArrayVisitor {
449 array_info,
450 registry: self.registry,
451 processor: self.processor,
452 },
453 )?;
454 dynamic_array.set_represented_type(Some(self.registration.type_info()));
455 Box::new(dynamic_array)
456 }
457 TypeInfo::Map(map_info) => {
458 let mut dynamic_map = deserializer.deserialize_map(MapVisitor {
459 map_info,
460 registry: self.registry,
461 processor: self.processor,
462 })?;
463 dynamic_map.set_represented_type(Some(self.registration.type_info()));
464 Box::new(dynamic_map)
465 }
466 TypeInfo::Set(set_info) => {
467 let mut dynamic_set = deserializer.deserialize_seq(SetVisitor {
468 set_info,
469 registry: self.registry,
470 processor: self.processor,
471 })?;
472 dynamic_set.set_represented_type(Some(self.registration.type_info()));
473 Box::new(dynamic_set)
474 }
475 TypeInfo::Tuple(tuple_info) => {
476 let mut dynamic_tuple = deserializer.deserialize_tuple(
477 tuple_info.field_len(),
478 TupleVisitor {
479 tuple_info,
480 registration: self.registration,
481 registry: self.registry,
482 processor: self.processor,
483 },
484 )?;
485 dynamic_tuple.set_represented_type(Some(self.registration.type_info()));
486 Box::new(dynamic_tuple)
487 }
488 TypeInfo::Enum(enum_info) => {
489 let mut dynamic_enum = if enum_info.type_path_table().module_path()
490 == Some("core::option")
491 && enum_info.type_path_table().ident() == Some("Option")
492 {
493 deserializer.deserialize_option(OptionVisitor {
494 enum_info,
495 registry: self.registry,
496 processor: self.processor,
497 })?
498 } else {
499 deserializer.deserialize_enum(
500 enum_info.type_path_table().ident().unwrap(),
501 enum_info.variant_names(),
502 EnumVisitor {
503 enum_info,
504 registration: self.registration,
505 registry: self.registry,
506 processor: self.processor,
507 },
508 )?
509 };
510 dynamic_enum.set_represented_type(Some(self.registration.type_info()));
511 Box::new(dynamic_enum)
512 }
513 TypeInfo::Opaque(_) => {
514 // This case should already be handled
515 return Err(make_custom_error(format_args!(
516 "type `{type_path}` did not register the `ReflectDeserialize` type data. For certain types, this may need to be registered manually using `register_type_data`",
517 )));
518 }
519 };
520
521 // Try to produce a concrete instance of the type to deserialize by using the reflected `FromReflect`.
522 if let Some(from_reflect) = self.registration.data::<ReflectFromReflect>()
523 && let Some(value) = from_reflect.from_reflect(&*dynamic_value)
524 {
525 return Ok(value);
526 }
527
528 Ok(dynamic_value)
529 };
530
531 #[cfg(feature = "debug_stack")]
532 TYPE_INFO_STACK.with_borrow_mut(|stack| stack.push(self.registration.type_info()));
533
534 let output = deserialize_internal();
535
536 #[cfg(feature = "debug_stack")]
537 TYPE_INFO_STACK.with_borrow_mut(crate::type_info_stack::TypeInfoStack::pop);
538
539 output
540 }
541}