1// Copyright (c) 2024 Jonas Schäfer <jonas@zombofant.net>
2//
3// This Source Code Form is subject to the terms of the Mozilla Public
4// License, v. 2.0. If a copy of the MPL was not distributed with this
5// file, You can obtain one at http://mozilla.org/MPL/2.0/.
6
7//! This module concerns the processing of typed child elements.
8//!
9//! In particular, it provides both `#[xml(extract)]` and `#[xml(child)]`
10//! implementations in a single type.
11
12use proc_macro2::{Span, TokenStream};
13use quote::{quote, quote_spanned};
14use syn::{spanned::Spanned, *};
15
16use crate::compound::Compound;
17use crate::error_message::{self, ParentRef};
18use crate::meta::{AmountConstraint, Flag, NameRef, NamespaceRef};
19use crate::scope::{AsItemsScope, FromEventsScope};
20use crate::types::{
21 as_xml_iter_fn, default_fn, extend_fn, from_events_fn, from_xml_builder_ty,
22 into_iterator_into_iter_fn, into_iterator_item_ty, into_iterator_iter_ty, item_iter_ty,
23 option_as_xml_ty, option_ty, ref_ty, ty_from_ident,
24};
25
26use super::{Field, FieldBuilderPart, FieldIteratorPart, FieldTempInit, NestedMatcher};
27
28/// The field maps to a child
29pub(super) struct ChildField {
30 /// Flag indicating whether the value should be defaulted if the
31 /// child is absent.
32 pub(super) default_: Flag,
33
34 /// Number of child elements allowed.
35 pub(super) amount: AmountConstraint,
36
37 /// If set, the child element is not parsed as a field implementing
38 /// `FromXml` / `AsXml`, but instead its contents are extracted.
39 pub(super) extract: Option<ExtractDef>,
40}
41
42impl Field for ChildField {
43 fn make_builder_part(
44 &self,
45 scope: &FromEventsScope,
46 container_name: &ParentRef,
47 member: &Member,
48 ty: &Type,
49 ) -> Result<FieldBuilderPart> {
50 let (element_ty, is_container) = match self.amount {
51 AmountConstraint::FixedSingle(_) => (ty.clone(), false),
52 AmountConstraint::Any(_) => (into_iterator_item_ty(ty.clone()), true),
53 };
54
55 let (extra_defs, matcher, fetch, builder) = match self.extract {
56 Some(ref extract) => extract.make_from_xml_builder_parts(
57 scope,
58 container_name,
59 member,
60 is_container,
61 ty,
62 )?,
63 None => {
64 let FromEventsScope {
65 ref substate_result,
66 ..
67 } = scope;
68
69 let from_events = from_events_fn(element_ty.clone());
70
71 let span = element_ty.span();
72 let matcher = quote_spanned! { span=> #from_events(name, attrs, ctx) };
73 let builder = from_xml_builder_ty(element_ty.clone());
74
75 (
76 TokenStream::default(),
77 matcher,
78 quote! { #substate_result },
79 builder,
80 )
81 }
82 };
83
84 let field_access = scope.access_field(member);
85 match self.amount {
86 AmountConstraint::FixedSingle(_) => {
87 let missing_msg = error_message::on_missing_child(container_name, member);
88 let duplicate_msg = error_message::on_duplicate_child(container_name, member);
89
90 let on_absent = match self.default_ {
91 Flag::Absent => quote! {
92 return ::core::result::Result::Err(::xso::error::Error::Other(#missing_msg).into())
93 },
94 Flag::Present(_) => {
95 let default_ = default_fn(element_ty.clone());
96 quote! {
97 #default_()
98 }
99 }
100 };
101
102 Ok(FieldBuilderPart::Nested {
103 extra_defs,
104 value: FieldTempInit {
105 init: quote! { ::core::option::Option::None },
106 ty: option_ty(ty.clone()),
107 },
108 matcher: NestedMatcher::Selective(quote! {
109 match #matcher {
110 ::core::result::Result::Ok(v) => if #field_access.is_some() {
111 ::core::result::Result::Err(::xso::error::FromEventsError::Invalid(::xso::error::Error::Other(#duplicate_msg)))
112 } else {
113 ::core::result::Result::Ok(v)
114 },
115 ::core::result::Result::Err(e) => ::core::result::Result::Err(e),
116 }
117 }),
118 builder,
119 collect: quote! {
120 #field_access = ::core::option::Option::Some(#fetch);
121 },
122 finalize: quote! {
123 match #field_access {
124 ::core::option::Option::Some(value) => value,
125 ::core::option::Option::None => #on_absent,
126 }
127 },
128 })
129 }
130 AmountConstraint::Any(_) => {
131 let ty_extend = extend_fn(ty.clone(), element_ty.clone());
132 let ty_default = default_fn(ty.clone());
133 Ok(FieldBuilderPart::Nested {
134 extra_defs,
135 value: FieldTempInit {
136 init: quote! { #ty_default() },
137 ty: ty.clone(),
138 },
139 matcher: NestedMatcher::Selective(matcher),
140 builder,
141 collect: quote! {
142 #ty_extend(&mut #field_access, [#fetch]);
143 },
144 finalize: quote! { #field_access },
145 })
146 }
147 }
148 }
149
150 fn make_iterator_part(
151 &self,
152 scope: &AsItemsScope,
153 container_name: &ParentRef,
154 bound_name: &Ident,
155 member: &Member,
156 ty: &Type,
157 ) -> Result<FieldIteratorPart> {
158 let AsItemsScope { ref lifetime, .. } = scope;
159
160 let (item_ty, is_container) = match self.amount {
161 AmountConstraint::FixedSingle(_) => (ty.clone(), false),
162 AmountConstraint::Any(_) => {
163 // This should give us the type of element stored in the
164 // collection.
165 (into_iterator_item_ty(ty.clone()), true)
166 }
167 };
168
169 let (extra_defs, init, iter_ty) = match self.extract {
170 Some(ref extract) => extract.make_as_item_iter_parts(
171 scope,
172 ty,
173 container_name,
174 bound_name,
175 member,
176 is_container,
177 )?,
178 None => {
179 let as_xml_iter = as_xml_iter_fn(item_ty.clone());
180 let item_iter = item_iter_ty(item_ty.clone(), lifetime.clone());
181
182 let span = item_ty.span();
183 (
184 TokenStream::default(),
185 quote_spanned! { span=> #as_xml_iter(#bound_name)? },
186 item_iter,
187 )
188 }
189 };
190
191 match self.amount {
192 AmountConstraint::FixedSingle(_) => Ok(FieldIteratorPart::Content {
193 extra_defs,
194 value: FieldTempInit { init, ty: iter_ty },
195 generator: quote! {
196 #bound_name.next().transpose()
197 },
198 }),
199 AmountConstraint::Any(_) => {
200 // This is the collection type we actually work
201 // with -- as_xml_iter uses references after all.
202 let ty = ref_ty(ty.clone(), lifetime.clone());
203
204 // But the iterator for iterating over the elements
205 // inside the collection must use the ref type.
206 let element_iter = into_iterator_iter_ty(ty.clone());
207
208 // And likewise the into_iter impl.
209 let into_iter = into_iterator_into_iter_fn(ty.clone());
210
211 let state_ty = Type::Tuple(TypeTuple {
212 paren_token: token::Paren::default(),
213 elems: [element_iter, option_ty(iter_ty)].into_iter().collect(),
214 });
215
216 Ok(FieldIteratorPart::Content {
217 extra_defs,
218 value: FieldTempInit {
219 init: quote! {
220 (#into_iter(#bound_name), ::core::option::Option::None)
221 },
222 ty: state_ty,
223 },
224 generator: quote! {
225 loop {
226 if let ::core::option::Option::Some(current) = #bound_name.1.as_mut() {
227 if let ::core::option::Option::Some(item) = current.next() {
228 break ::core::option::Option::Some(item).transpose();
229 }
230 }
231 if let ::core::option::Option::Some(item) = #bound_name.0.next() {
232 #bound_name.1 = ::core::option::Option::Some({
233 let #bound_name = item;
234 #init
235 });
236 } else {
237 break ::core::result::Result::Ok(::core::option::Option::None)
238 }
239 }
240 },
241 })
242 }
243 }
244 }
245}
246
247/// Definition of what to extract from a child element.
248pub(super) struct ExtractDef {
249 /// The XML namespace of the child to extract data from.
250 pub(super) xml_namespace: NamespaceRef,
251
252 /// The XML name of the child to extract data from.
253 pub(super) xml_name: NameRef,
254
255 /// Compound which contains the arguments of the `extract(..)` meta
256 /// (except the `from`), transformed into a struct with unnamed
257 /// fields.
258 ///
259 /// This is used to generate the parsing/serialisation code, by
260 /// essentially "declaring" a shim struct, as if it were a real Rust
261 /// struct, and using the result of the parsing process directly for
262 /// the field on which the `extract(..)` option was used, instead of
263 /// putting it into a Rust struct.
264 pub(super) parts: Compound,
265}
266
267impl ExtractDef {
268 /// Construct
269 /// [`FieldBuilderPart::Nested::extra_defs`],
270 /// [`FieldBuilderPart::Nested::matcher`],
271 /// an expression which pulls the extraction result from
272 /// `substate_result`,
273 /// and the [`FieldBuilderPart::Nested::builder`] type.
274 fn make_from_xml_builder_parts(
275 &self,
276 scope: &FromEventsScope,
277 container_name: &ParentRef,
278 member: &Member,
279 collecting_into_container: bool,
280 output_ty: &Type,
281 ) -> Result<(TokenStream, TokenStream, TokenStream, Type)> {
282 let FromEventsScope {
283 ref substate_result,
284 ..
285 } = scope;
286
287 let xml_namespace = &self.xml_namespace;
288 let xml_name = &self.xml_name;
289
290 let from_xml_builder_ty_ident = scope.make_member_type_name(member, "FromXmlBuilder");
291 let state_ty_ident = quote::format_ident!("{}State", from_xml_builder_ty_ident,);
292
293 let extra_defs = self.parts.make_from_events_statemachine(
294 &state_ty_ident,
295 &container_name.child(member.clone()),
296 "",
297 )?.with_augmented_init(|init| quote! {
298 if name.0 == #xml_namespace && name.1 == #xml_name {
299 #init
300 } else {
301 ::core::result::Result::Err(::xso::error::FromEventsError::Mismatch { name, attrs })
302 }
303 }).compile().render(
304 &Visibility::Inherited,
305 &from_xml_builder_ty_ident,
306 &state_ty_ident,
307 &self.parts.to_tuple_ty().into(),
308 None,
309 )?;
310 let from_xml_builder_ty = ty_from_ident(from_xml_builder_ty_ident.clone()).into();
311
312 let matcher = quote! { #state_ty_ident::new(name, attrs, ctx).map(|x| #from_xml_builder_ty_ident(::core::option::Option::Some(x))) };
313
314 let inner_ty = self.parts.to_single_or_tuple_ty();
315
316 let fetch = if self.parts.field_count() == 1 {
317 // If we extract only a single field, we automatically unwrap the
318 // tuple, because that behaviour is more obvious to users.
319 quote! { #substate_result.0 }
320 } else {
321 // If we extract more than one field, we pass the value down as
322 // the tuple that it is.
323 quote! { #substate_result }
324 };
325
326 let fetch = if collecting_into_container {
327 // This is for symmetry with the AsXml implementation part. Please
328 // see there for why we cannot do option magic in the collection
329 // case.
330 fetch
331 } else {
332 // This little ".into()" here goes a long way. It relies on one of
333 // the most underrated trait implementations in the standard
334 // library: `impl From<T> for Option<T>`, which creates a
335 // `Some(_)` from a `T`. Why is it so great? Because there is also
336 // `impl From<Option<T>> for Option<T>` (obviously), which is just
337 // a move. So even without knowing the exact type of the substate
338 // result and the field, we can make an "downcast" to `Option<T>`
339 // if the field is of type `Option<T>`, and it does the right
340 // thing no matter whether the extracted field is of type
341 // `Option<T>` or `T`.
342 //
343 // And then, type inference does the rest: There is ambiguity
344 // there, of course, if we call `.into()` on a value of type
345 // `Option<T>`: Should Rust wrap it into another layer of
346 // `Option`, or should it just move the value? The answer lies in
347 // the type constraint imposed by the place the value is *used*,
348 // which is strictly bound by the field's type (so there is, in
349 // fact, no ambiguity). So this works all kinds of magic.
350 quote_spanned! {
351 output_ty.span()=>
352 <#output_ty as ::core::convert::From::<#inner_ty>>::from(#fetch)
353 }
354 };
355
356 Ok((extra_defs, matcher, fetch, from_xml_builder_ty))
357 }
358
359 /// Construct
360 /// [`FieldIteratorPart::Content::extra_defs`],
361 /// the [`FieldIteratorPart::Content::value`] init,
362 /// and the iterator type.
363 fn make_as_item_iter_parts(
364 &self,
365 scope: &AsItemsScope,
366 input_ty: &Type,
367 container_name: &ParentRef,
368 bound_name: &Ident,
369 member: &Member,
370 iterating_container: bool,
371 ) -> Result<(TokenStream, TokenStream, Type)> {
372 let AsItemsScope { ref lifetime, .. } = scope;
373
374 let xml_namespace = &self.xml_namespace;
375 let xml_name = &self.xml_name;
376
377 let item_iter_ty_ident = scope.make_member_type_name(member, "AsXmlIterator");
378 let state_ty_ident = quote::format_ident!("{}State", item_iter_ty_ident,);
379 let mut item_iter_ty = ty_from_ident(item_iter_ty_ident.clone());
380 item_iter_ty.path.segments[0].arguments =
381 PathArguments::AngleBracketed(AngleBracketedGenericArguments {
382 colon2_token: None,
383 lt_token: token::Lt::default(),
384 args: [GenericArgument::Lifetime(lifetime.clone())]
385 .into_iter()
386 .collect(),
387 gt_token: token::Gt::default(),
388 });
389 let item_iter_ty = item_iter_ty.into();
390 let tuple_ty = self.parts.to_ref_tuple_ty(lifetime);
391
392 let (repack, inner_ty) = match self.parts.single_ty() {
393 Some(single_ty) => (
394 quote! { #bound_name, },
395 ref_ty(single_ty.clone(), lifetime.clone()),
396 ),
397 None => {
398 let mut repack_tuple = TokenStream::default();
399 // The cast here is sound, because the constructor of Compound
400 // already asserts that there are less than 2^32 fields (with
401 // what I think is a great error message, go check it out).
402 for i in 0..(tuple_ty.elems.len() as u32) {
403 let index = Index {
404 index: i,
405 span: Span::call_site(),
406 };
407 repack_tuple.extend(quote! {
408 &#bound_name.#index,
409 })
410 }
411 let ref_tuple_ty = ref_ty(self.parts.to_tuple_ty().into(), lifetime.clone());
412 (repack_tuple, ref_tuple_ty)
413 }
414 };
415
416 let extra_defs = self
417 .parts
418 .make_as_item_iter_statemachine(
419 &container_name.child(member.clone()),
420 &state_ty_ident,
421 "",
422 lifetime,
423 )?
424 .with_augmented_init(|init| {
425 quote! {
426 let name = (
427 ::xso::exports::rxml::Namespace::from(#xml_namespace),
428 ::xso::exports::alloc::borrow::Cow::Borrowed(#xml_name),
429 );
430 #init
431 }
432 })
433 .compile()
434 .render(
435 &Visibility::Inherited,
436 &tuple_ty.into(),
437 &state_ty_ident,
438 lifetime,
439 &item_iter_ty,
440 )?;
441
442 let (make_iter, item_iter_ty) = if iterating_container {
443 // When we are iterating a container, the container's iterator's
444 // item type may either be `&(A, B, ...)` or `(&A, &B, ...)`.
445 // Unfortunately, to be able to handle both, we need to omit the
446 // magic Option cast, because we cannot specify the type of the
447 // argument of the `.map(...)` closure and rust is not able to
448 // infer that type because the repacking is too opaque.
449 //
450 // However, this is not much of a loss, because it doesn't really
451 // make sense to have the option cast there, anyway: optional
452 // elements in a container would be weird.
453 (
454 quote! {
455 #item_iter_ty_ident::new((#repack))?
456 },
457 item_iter_ty,
458 )
459 } else {
460 // Again we exploit the extreme usefulness of the
461 // `impl From<T> for Option<T>`. We already wrote extensively
462 // about that in [`make_from_xml_builder_parts`] implementation
463 // corresponding to this code above, and we will not repeat it
464 // here.
465
466 // These sections with quote_spanned are used to improve error
467 // messages on type mismatches. Without these, the rustc errors
468 // will point at `#[derive(AsXml)]` only, instead of directly
469 // pointing at the sources of those types.
470 let cast = quote_spanned! { input_ty.span()=>
471 ::core::option::Option::from(#bound_name)
472 };
473 let type_assert = quote_spanned! { inner_ty.span()=>
474 ::core::option::Option<#inner_ty>
475 };
476 (
477 quote! {
478 ::xso::asxml::OptionAsXml::new({ let x: #type_assert = #cast; x.map(|#bound_name: #inner_ty| {
479 #item_iter_ty_ident::new((#repack))
480 })}.transpose()?)
481 },
482 option_as_xml_ty(item_iter_ty),
483 )
484 };
485
486 Ok((extra_defs, make_iter, item_iter_ty))
487 }
488}