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