xso_proc/

common.rs

// Copyright (c) 2024 Jonas Schäfer <jonas@zombofant.net>
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.

//! Definitions common to both enums and structs

use proc_macro2::TokenStream;
use quote::{quote, ToTokens};
use syn::*;

use std::collections::{HashMap, HashSet};

use crate::types::{
    iter_referenced_names_in_bound, iter_referenced_names_in_generic_param,
    iter_referenced_names_in_ty, ReferencedIdent,
};

/// Template which renders to a `xso::fromxml::XmlNameMatcher` value.
pub(crate) enum XmlNameMatcher {
    /// Renders as `xso::fromxml::XmlNameMatcher::Any`.
    #[allow(dead_code)] // We keep it for completeness.
    Any,

    /// Renders as `xso::fromxml::XmlNameMatcher::InNamespace(#0)`.
    InNamespace(TokenStream),

    /// Renders as `xso::fromxml::XmlNameMatcher::Specific(#0, #1)`.
    Specific(TokenStream, TokenStream),

    /// Renders as `#0`.
    ///
    /// This is an escape hatch for more complicated constructs, e.g. when
    /// a superset of multiple matchers is required.
    Custom(TokenStream),
}

impl ToTokens for XmlNameMatcher {
    fn to_tokens(&self, tokens: &mut TokenStream) {
        match self {
            Self::Any => tokens.extend(quote! {
                ::xso::fromxml::XmlNameMatcher::<'static>::Any
            }),
            Self::InNamespace(ref namespace) => tokens.extend(quote! {
                ::xso::fromxml::XmlNameMatcher::<'static>::InNamespace(#namespace)
            }),
            Self::Specific(ref namespace, ref name) => tokens.extend(quote! {
                ::xso::fromxml::XmlNameMatcher::<'static>::Specific(#namespace, #name)
            }),
            Self::Custom(ref stream) => tokens.extend(stream.clone()),
        }
    }
}

/// Parts necessary to construct a `::xso::FromXml` implementation.
pub(crate) struct FromXmlParts {
    /// Additional items necessary for the implementation.
    pub(crate) defs: TokenStream,

    /// The body of the `::xso::FromXml::from_xml` function.
    pub(crate) from_events_body: TokenStream,

    /// The type which is the `::xso::FromXml::Builder`.
    pub(crate) builder_ty: Type,

    /// The `XmlNameMatcher` to pre-select elements for this implementation.
    pub(crate) name_matcher: XmlNameMatcher,
}

/// Parts necessary to construct a `::xso::AsXml` implementation.
pub(crate) struct AsXmlParts {
    /// Additional items necessary for the implementation.
    pub(crate) defs: TokenStream,

    /// The body of the `::xso::AsXml::as_xml_iter` function.
    pub(crate) as_xml_iter_body: TokenStream,

    /// The type which is the `::xso::AsXml::ItemIter`.
    pub(crate) item_iter_ty: Type,

    /// The lifetime name used in `item_iter_ty`.
    pub(crate) item_iter_ty_lifetime: Lifetime,
}

/// Generic parameters (incl. bounds) which can be interpolated into
/// `quote!{}`.
#[derive(Clone, Debug)]
pub(crate) struct GenericParams {
    /// The `<` token.
    pub(crate) lt_token: token::Lt,

    /// The list of parameters, with bounds.
    pub(crate) params: punctuated::Punctuated<GenericParam, token::Comma>,

    /// The `>` token.
    pub(crate) gt_token: token::Gt,
}

impl GenericParams {
    fn new(item: GenericParam) -> Self {
        Self {
            lt_token: <Token![<]>::default(),
            params: [item].into_iter().collect(),
            gt_token: <Token![>]>::default(),
        }
    }

    /// Split [`syn::Generics`] into [`GenericParams`] and an optional
    /// [`WhereClause`].
    fn split(generics: Generics) -> (Option<Self>, Option<WhereClause>) {
        let Generics {
            lt_token,
            params,
            gt_token,
            where_clause,
        } = generics;
        let this = if params.len() > 0 {
            if let Some((lt_token, gt_token)) = lt_token.zip(gt_token) {
                Some(Self {
                    lt_token,
                    params,
                    gt_token,
                })
            } else {
                panic!("no lt and gt tokens, but non-empty generic parameter list!");
            }
        } else {
            None
        };
        (this, where_clause)
    }
}

impl ToTokens for GenericParams {
    fn to_tokens(&self, tokens: &mut TokenStream) {
        self.lt_token.to_tokens(tokens);
        self.params.to_tokens(tokens);
        self.gt_token.to_tokens(tokens);
    }
}

/// Collection of generics information.
#[derive(Default, Debug)]
pub(crate) struct GenericsInfo {
    /// List of parameters incl. their bounds, enclosed in `< .. >`, for use
    /// after the `impl` keyword.
    pub(crate) decl: Option<GenericParams>,

    /// List of parameters without their bounds, for use as ref_ when
    /// referencing the type.
    pub(crate) ref_: Option<AngleBracketedGenericArguments>,

    /// Where clause of the type, if any.
    pub(crate) where_clause: Option<WhereClause>,

    /// Index of the first bound which was added via add_bound_if_generic.
    new_bounds_at: usize,
}

impl GenericsInfo {
    /// Extract the relevant parts from an [`Item`]'s [`Generics`] so
    /// that they can be used inside [`quote::quote`] to form `impl` items.
    pub(crate) fn bake(generics: Generics) -> Self {
        let (decl, where_clause) = GenericParams::split(generics);
        let ref_ = if let Some(decl) = decl
            .as_ref()
            .and_then(|x| if x.params.len() > 0 { Some(x) } else { None })
            .as_ref()
        {
            let mut args = punctuated::Punctuated::new();
            for pair in decl.params.pairs() {
                args.push_value(match pair.value() {
                    GenericParam::Lifetime(lt) => GenericArgument::Lifetime(lt.lifetime.clone()),
                    GenericParam::Type(ty) => GenericArgument::Type(Type::Path(TypePath {
                        qself: None,
                        path: ty.ident.clone().into(),
                    })),
                    GenericParam::Const(cst) => GenericArgument::Const(Expr::Path(ExprPath {
                        attrs: Vec::new(),
                        qself: None,
                        path: cst.ident.clone().into(),
                    })),
                });
                if let Some(punct) = pair.punct() {
                    args.push_punct(**punct);
                }
            }

            Some(AngleBracketedGenericArguments {
                colon2_token: None,
                lt_token: decl.lt_token.clone(),
                args,
                gt_token: decl.gt_token.clone(),
            })
        } else {
            None
        };
        Self {
            decl,
            ref_,
            new_bounds_at: where_clause
                .as_ref()
                .map(|x| x.predicates.len())
                .unwrap_or(0),
            where_clause,
        }
    }

    fn where_clause_mut(&mut self) -> &mut WhereClause {
        self.where_clause.get_or_insert_with(|| WhereClause {
            where_token: <Token![where]>::default(),
            predicates: punctuated::Punctuated::default(),
        })
    }

    pub fn add_bound_if_generic(&mut self, ty: &Type, trait_: Path) {
        let Some(decl) = self.decl.as_ref() else {
            // no declarations -> no generics.
            return;
        };

        let mut known_names = HashSet::new();
        known_names.extend(decl.params.iter().filter_map(|x| match x {
            GenericParam::Type(ty) => Some(&ty.ident),
            _ => None,
        }));

        let mut is_generic = false;
        iter_referenced_names_in_ty(&ty, &mut |reference| match reference {
            ReferencedIdent::Name(name) => {
                if known_names.contains(name) {
                    is_generic = true;
                }
                Ok(())
            }
            _ => Ok(()),
        })
        .unwrap();
        if !is_generic {
            return;
        }

        self.where_clause_mut()
            .predicates
            .push(WherePredicate::Type(PredicateType {
                lifetimes: None,
                bounded_ty: ty.clone(),
                colon_token: <Token![:]>::default(),
                bounds: [TypeParamBound::Trait(TraitBound {
                    paren_token: None,
                    modifier: TraitBoundModifier::None,
                    lifetimes: None,
                    path: trait_,
                })]
                .into_iter()
                .collect(),
            }))
    }

    pub fn insert_lifetime(&mut self, lifetime: &Lifetime) {
        let param = GenericParam::Lifetime(LifetimeParam {
            attrs: vec![],
            lifetime: lifetime.clone(),
            colon_token: None,
            bounds: punctuated::Punctuated::default(),
        });
        match self.decl.as_mut() {
            Some(decl) => {
                for param in decl.params.iter_mut() {
                    match param {
                        GenericParam::Lifetime(other_lifetime) => {
                            other_lifetime.colon_token.get_or_insert_default();
                            other_lifetime.bounds.push(lifetime.clone());
                        }
                        GenericParam::Type(ty) => {
                            ty.colon_token.get_or_insert_default();
                            ty.bounds.push(TypeParamBound::Lifetime(lifetime.clone()));
                        }
                        _ => (),
                    }
                }
                decl.params.insert(0, param)
            }
            None => self.decl = Some(GenericParams::new(param)),
        }

        let arg = GenericArgument::Lifetime(lifetime.clone());
        match self.ref_.as_mut() {
            Some(v) => v.args.insert(0, arg),
            None => {
                self.ref_ = Some(AngleBracketedGenericArguments {
                    colon2_token: None,
                    lt_token: <Token![<]>::default(),
                    args: [arg].into_iter().collect(),
                    gt_token: <Token![>]>::default(),
                })
            }
        }
    }

    pub(crate) fn path_arguments(&self) -> PathArguments {
        match self.ref_.as_ref() {
            None => PathArguments::None,
            Some(v) => PathArguments::AngleBracketed(v.clone()),
        }
    }

    pub fn ty_with_arguments(&self, ident: Ident) -> Type {
        Type::Path(TypePath {
            qself: None,
            path: Path {
                leading_colon: None,
                segments: [PathSegment {
                    ident,
                    arguments: self.path_arguments(),
                }]
                .into_iter()
                .collect(),
            },
        })
    }

    pub fn subscope(&self) -> Self {
        Self {
            decl: self.decl.clone(),
            ref_: self.ref_.clone(),
            where_clause: self.where_clause.clone(),
            new_bounds_at: self
                .where_clause
                .as_ref()
                .map(|x| x.predicates.len())
                .unwrap_or(0),
        }
    }

    /// Return a subset of this `GenericsInfo` which only contains parameters
    /// and their constraints relevant for the given `ty`.
    ///
    /// This preserves:
    /// - parameters which are referenced in `ty` (and their argument form)
    /// - parameters which are referenced by trait bounds of parameters
    ///   referenced by `ty`
    /// - where clauses where all referenced parameters occur in the set of
    ///   parameters included.
    ///
    /// The same holds for lifetimes and consts.
    pub(crate) fn scoped_for(&self, ty: &Type) -> Result<Self> {
        let (decl, ref_) = if let Some(decl) = self.decl.as_ref() {
            if let Some(ref_) = self.ref_.as_ref() {
                (decl, ref_)
            } else {
                panic!("internal xso-proc error: ref_ is None, but decl is not.");
            }
        } else {
            assert!(self.ref_.is_none());
            return Ok(self.subscope());
        };

        // First, we gather all declared names (types, consts and lifetimes).
        let mut declarations = HashMap::new();
        for param in decl.params.iter() {
            match param {
                GenericParam::Type(ty) => {
                    declarations.insert(ReferencedIdent::Name(&ty.ident), param)
                }
                GenericParam::Const(cst) => {
                    declarations.insert(ReferencedIdent::Name(&cst.ident), param)
                }
                GenericParam::Lifetime(lt) => {
                    declarations.insert(ReferencedIdent::Lifetime(&lt.lifetime.ident), param)
                }
            };
        }

        // Then, we visit all names in `ty` and add them to the `used_names`
        // hash set.
        let mut used_names = HashSet::new();
        match crate::types::iter_referenced_names_in_ty(ty, &mut |ident| {
            let declared = declarations.contains_key(&ident);
            if declared {
                used_names.insert(ident);
            }
            Ok(())
        }) {
            Ok(()) => (),
            Err(e) => {
                return Err({
                    let mut my_err = Error::new_spanned(
                        ty,
                        "cannot build subset of generic types needed for this type",
                    );
                    my_err.combine(e);
                    my_err
                })
            }
        };

        // Now we iterate over `used_names` and add them to `keep`, while also
        // looking for any further names referenced in their bounds which
        // we'll then also have to keep.
        let mut keep = HashSet::new();
        while let Some(name) = used_names.iter().next() {
            let name = *name;
            used_names.remove(&name);
            let rhs = declarations.get(&name).unwrap();
            match iter_referenced_names_in_generic_param(&rhs, &mut |ident| {
                if keep.contains(&ident) {
                    // ^ this is important, otherwise we end up in an infinite
                    // loop when we have cyclic trait bounds (like
                    // `A: From<B>, B: From<A>`).
                    return Ok(());
                }
                let declared = declarations.contains_key(&ident);
                if declared {
                    used_names.insert(ident);
                }
                Ok(())
            }) {
                Ok(()) => (),
                Err(e) => {
                    return Err({
                        let mut my_err = Error::new_spanned(
                            ty,
                            "cannot build subset of generic types needed for this type",
                        );
                        my_err.combine(e);
                        my_err
                    })
                }
            };
            keep.insert(name);
        }

        // Now that we know all the things, we keep those which are, in fact,
        // relevant.
        let mut result_params = punctuated::Punctuated::new();
        let mut result_arguments = punctuated::Punctuated::new();
        for (param, argument) in decl.params.pairs().zip(ref_.args.pairs()) {
            let key = match param.value() {
                GenericParam::Type(ty) => ReferencedIdent::Name(&ty.ident),
                GenericParam::Const(cst) => ReferencedIdent::Name(&cst.ident),
                GenericParam::Lifetime(lt) => ReferencedIdent::Lifetime(&lt.lifetime.ident),
            };

            if !keep.contains(&key) {
                continue;
            }

            result_params.push_value((*param.value()).clone());
            if let Some(punct) = param.punct() {
                result_params.push_punct(**punct);
            }

            result_arguments.push_value((*argument.value()).clone());
            if let Some(punct) = argument.punct() {
                result_arguments.push_punct(**punct);
            }
        }

        // And finally, we gather all where clauses which only contain names
        // which are already in the set to keep (ignoring names which
        // haven't been declared by us, such as `std`).
        let result_where = if let Some(where_clause) = self.where_clause.as_ref() {
            let mut result_predicates = punctuated::Punctuated::new();
            // Note that I'm not 100% sure this logic is complete; there may be
            // cases where additional clauses need to be kept... For now I
            // went with "keep only those where all names are already kept"
            // because I assume that we'd run into issues with
            // "type parameter not used" errors.
            for predicate in where_clause.predicates.pairs() {
                // we start with true, and once we hit a declared name which
                // isn't kept, we set it to false.
                let mut keep_this_predicate = true;
                match predicate.value() {
                    WherePredicate::Lifetime(predicate) => {
                        keep_this_predicate = keep_this_predicate
                            && keep.contains(&ReferencedIdent::Lifetime(&predicate.lifetime.ident));
                        for bound in predicate.bounds.iter() {
                            let name = ReferencedIdent::Lifetime(&bound.ident);
                            if declarations.contains_key(&name) {
                                keep_this_predicate = keep_this_predicate && keep.contains(&name);
                            }
                        }
                    }
                    WherePredicate::Type(predicate) => {
                        iter_referenced_names_in_ty(&predicate.bounded_ty, &mut |ident| {
                            if declarations.contains_key(&ident) {
                                keep_this_predicate = keep_this_predicate && keep.contains(&ident);
                            }
                            Ok(())
                        })?;
                        for bound in predicate.bounds.iter() {
                            iter_referenced_names_in_bound(&bound, &mut |ident| {
                                if declarations.contains_key(&ident) {
                                    keep_this_predicate =
                                        keep_this_predicate && keep.contains(&ident);
                                }
                                Ok(())
                            })?;
                        }
                    }
                    other => {
                        return Err({
                            let mut my_err = Error::new_spanned(
                                ty,
                                "cannot build subset of generic types needed for this type",
                            );
                            my_err.combine(Error::new_spanned(
                                other,
                                "this kind of where predicate is not supported",
                            ));
                            my_err
                        })
                    }
                }
                if keep_this_predicate {
                    result_predicates.push_value((*predicate.value()).clone());
                    if let Some(punct) = predicate.punct() {
                        result_predicates.push_punct(**punct);
                    }
                }
            }

            if result_predicates.len() > 0 {
                Some(WhereClause {
                    where_token: where_clause.where_token.clone(),
                    predicates: result_predicates,
                })
            } else {
                None
            }
        } else {
            None
        };

        Ok(Self {
            decl: if result_params.len() > 0 {
                Some(GenericParams {
                    lt_token: decl.lt_token.clone(),
                    params: result_params,
                    gt_token: decl.gt_token.clone(),
                })
            } else {
                None
            },
            ref_: if result_arguments.len() > 0 {
                Some(AngleBracketedGenericArguments {
                    colon2_token: ref_.colon2_token.clone(),
                    lt_token: ref_.lt_token.clone(),
                    args: result_arguments,
                    gt_token: ref_.gt_token.clone(),
                })
            } else {
                None
            },
            new_bounds_at: result_where
                .as_ref()
                .map(|x| x.predicates.len())
                .unwrap_or(0),
            where_clause: result_where,
        })
    }

    pub fn into_new_bounds(self) -> impl Iterator<Item = WherePredicate> {
        self.where_clause
            .map(|x| x.predicates)
            .unwrap_or_else(|| punctuated::Punctuated::default())
            .into_iter()
            .skip(self.new_bounds_at)
    }

    pub fn extend_bounds(&mut self, iter: impl IntoIterator<Item = WherePredicate>) {
        self.where_clause_mut().predicates.extend(iter)
    }
}

/// Trait describing the definition of the XML (de-)serialisation for an item
/// (enum or struct).
pub(crate) trait ItemDef {
    /// Construct the parts necessary for the caller to build an
    /// `xso::FromXml` implementation for the item.
    fn make_from_events_builder(
        &self,
        vis: &Visibility,
        generics: &mut GenericsInfo,
        name_ident: &Ident,
        attrs_ident: &Ident,
    ) -> Result<FromXmlParts>;

    /// Construct the parts necessary for the caller to build an `xso::AsXml`
    /// implementation for the item.
    fn make_as_xml_iter(&self, vis: &Visibility, generics: &mut GenericsInfo)
        -> Result<AsXmlParts>;

    /// Return true iff the user requested debug output.
    fn debug(&self) -> bool;
}