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(&registry);
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, &registry);
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}