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