//! This crate provides helper types for matching against enum variants, and //! extracting bindings to each of the fields in the deriving Struct or Enum in //! a generic way. //! //! If you are writing a `#[derive]` which needs to perform some operation on //! every field, then you have come to the right place! //! //! # Example: `WalkFields` //! ### Trait Implementation //! ``` //! pub trait WalkFields: std::any::Any { //! fn walk_fields(&self, walk: &mut FnMut(&WalkFields)); //! } //! impl WalkFields for i32 { //! fn walk_fields(&self, _walk: &mut FnMut(&WalkFields)) {} //! } //! ``` //! //! ### Custom Derive //! ``` //! # use quote::quote; //! fn walkfields_derive(s: synstructure::Structure) -> proc_macro2::TokenStream { //! let body = s.each(|bi| quote!{ //! walk(#bi) //! }); //! //! s.gen_impl(quote! { //! extern crate synstructure_test_traits; //! //! gen impl synstructure_test_traits::WalkFields for @Self { //! fn walk_fields(&self, walk: &mut FnMut(&synstructure_test_traits::WalkFields)) { //! match *self { #body } //! } //! } //! }) //! } //! # const _IGNORE: &'static str = stringify!( //! synstructure::decl_derive!([WalkFields] => walkfields_derive); //! # ); //! //! /* //! * Test Case //! */ //! fn main() { //! synstructure::test_derive! { //! walkfields_derive { //! enum A { //! B(i32, T), //! C(i32), //! } //! } //! expands to { //! #[allow(non_upper_case_globals)] //! const _DERIVE_synstructure_test_traits_WalkFields_FOR_A: () = { //! extern crate synstructure_test_traits; //! impl synstructure_test_traits::WalkFields for A //! where T: synstructure_test_traits::WalkFields //! { //! fn walk_fields(&self, walk: &mut FnMut(&synstructure_test_traits::WalkFields)) { //! match *self { //! A::B(ref __binding_0, ref __binding_1,) => { //! { walk(__binding_0) } //! { walk(__binding_1) } //! } //! A::C(ref __binding_0,) => { //! { walk(__binding_0) } //! } //! } //! } //! } //! }; //! } //! } //! } //! ``` //! //! # Example: `Interest` //! ### Trait Implementation //! ``` //! pub trait Interest { //! fn interesting(&self) -> bool; //! } //! impl Interest for i32 { //! fn interesting(&self) -> bool { *self > 0 } //! } //! ``` //! //! ### Custom Derive //! ``` //! # use quote::quote; //! fn interest_derive(mut s: synstructure::Structure) -> proc_macro2::TokenStream { //! let body = s.fold(false, |acc, bi| quote!{ //! #acc || synstructure_test_traits::Interest::interesting(#bi) //! }); //! //! s.gen_impl(quote! { //! extern crate synstructure_test_traits; //! gen impl synstructure_test_traits::Interest for @Self { //! fn interesting(&self) -> bool { //! match *self { //! #body //! } //! } //! } //! }) //! } //! # const _IGNORE: &'static str = stringify!( //! synstructure::decl_derive!([Interest] => interest_derive); //! # ); //! //! /* //! * Test Case //! */ //! fn main() { //! synstructure::test_derive!{ //! interest_derive { //! enum A { //! B(i32, T), //! C(i32), //! } //! } //! expands to { //! #[allow(non_upper_case_globals)] //! const _DERIVE_synstructure_test_traits_Interest_FOR_A: () = { //! extern crate synstructure_test_traits; //! impl synstructure_test_traits::Interest for A //! where T: synstructure_test_traits::Interest //! { //! fn interesting(&self) -> bool { //! match *self { //! A::B(ref __binding_0, ref __binding_1,) => { //! false || //! synstructure_test_traits::Interest::interesting(__binding_0) || //! synstructure_test_traits::Interest::interesting(__binding_1) //! } //! A::C(ref __binding_0,) => { //! false || //! synstructure_test_traits::Interest::interesting(__binding_0) //! } //! } //! } //! } //! }; //! } //! } //! } //! ``` //! //! For more example usage, consider investigating the `abomonation_derive` crate, //! which makes use of this crate, and is fairly simple. #[cfg(all( not(all(target_arch = "wasm32", any(target_os = "unknown", target_os = "wasi"))), feature = "proc-macro" ))] extern crate proc_macro; use std::collections::HashSet; use syn::parse::{ParseStream, Parser}; use syn::visit::{self, Visit}; use syn::{ braced, punctuated, token, Attribute, Data, DeriveInput, Error, Expr, Field, Fields, FieldsNamed, FieldsUnnamed, GenericParam, Generics, Ident, PredicateType, Result, Token, TraitBound, Type, TypeMacro, TypeParamBound, TypePath, WhereClause, WherePredicate, }; use quote::{format_ident, quote_spanned, ToTokens}; // re-export the quote! macro so we can depend on it being around in our macro's // implementations. #[doc(hidden)] pub use quote::quote; use unicode_xid::UnicodeXID; use proc_macro2::{Span, TokenStream, TokenTree}; // NOTE: This module has documentation hidden, as it only exports macros (which // always appear in the root of the crate) and helper methods / re-exports used // in the implementation of those macros. #[doc(hidden)] pub mod macros; /// Changes how bounds are added #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)] pub enum AddBounds { /// Add for fields and generics Both, /// Fields only Fields, /// Generics only Generics, /// None None, #[doc(hidden)] __Nonexhaustive, } /// The type of binding to use when generating a pattern. #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)] pub enum BindStyle { /// `x` Move, /// `mut x` MoveMut, /// `ref x` Ref, /// `ref mut x` RefMut, } impl ToTokens for BindStyle { fn to_tokens(&self, tokens: &mut TokenStream) { match self { BindStyle::Move => {} BindStyle::MoveMut => quote_spanned!(Span::call_site() => mut).to_tokens(tokens), BindStyle::Ref => quote_spanned!(Span::call_site() => ref).to_tokens(tokens), BindStyle::RefMut => quote_spanned!(Span::call_site() => ref mut).to_tokens(tokens), } } } // Internal method for merging seen_generics arrays together. fn generics_fuse(res: &mut Vec, new: &[bool]) { for (i, &flag) in new.iter().enumerate() { if i == res.len() { res.push(false); } if flag { res[i] = true; } } } // Internal method for extracting the set of generics which have been matched. fn fetch_generics<'a>(set: &[bool], generics: &'a Generics) -> Vec<&'a Ident> { let mut tys = vec![]; for (&seen, param) in set.iter().zip(generics.params.iter()) { if seen { if let GenericParam::Type(tparam) = param { tys.push(&tparam.ident) } } } tys } // Internal method for sanitizing an identifier for hygiene purposes. fn sanitize_ident(s: &str) -> Ident { let mut res = String::with_capacity(s.len()); for mut c in s.chars() { if !UnicodeXID::is_xid_continue(c) { c = '_' } // Deduplicate consecutive _ characters. if res.ends_with('_') && c == '_' { continue; } res.push(c); } Ident::new(&res, Span::call_site()) } // Internal method to merge two Generics objects together intelligently. fn merge_generics(into: &mut Generics, from: &Generics) -> Result<()> { // Try to add the param into `into`, and merge parmas with identical names. for p in &from.params { for op in &into.params { match (op, p) { (GenericParam::Type(otp), GenericParam::Type(tp)) => { // NOTE: This is only OK because syn ignores the span for equality purposes. if otp.ident == tp.ident { return Err(Error::new_spanned( p, format!( "Attempted to merge conflicting generic parameters: {} and {}", quote!(#op), quote!(#p) ), )); } } (GenericParam::Lifetime(olp), GenericParam::Lifetime(lp)) => { // NOTE: This is only OK because syn ignores the span for equality purposes. if olp.lifetime == lp.lifetime { return Err(Error::new_spanned( p, format!( "Attempted to merge conflicting generic parameters: {} and {}", quote!(#op), quote!(#p) ), )); } } // We don't support merging Const parameters, because that wouldn't make much sense. _ => (), } } into.params.push(p.clone()); } // Add any where clauses from the input generics object. if let Some(from_clause) = &from.where_clause { into.make_where_clause() .predicates .extend(from_clause.predicates.iter().cloned()); } Ok(()) } /// Helper method which does the same thing as rustc 1.20's /// `Option::get_or_insert_with`. This method is used to keep backwards /// compatibility with rustc 1.15. fn get_or_insert_with(opt: &mut Option, f: F) -> &mut T where F: FnOnce() -> T, { if opt.is_none() { *opt = Some(f()); } match opt { Some(v) => v, None => unreachable!(), } } /// Information about a specific binding. This contains both an `Ident` /// reference to the given field, and the syn `&'a Field` descriptor for that /// field. /// /// This type supports `quote::ToTokens`, so can be directly used within the /// `quote!` macro. It expands to a reference to the matched field. #[derive(Debug, Clone, PartialEq, Eq, Hash)] pub struct BindingInfo<'a> { /// The name which this BindingInfo will bind to. pub binding: Ident, /// The type of binding which this BindingInfo will create. pub style: BindStyle, field: &'a Field, // These are used to determine which type parameters are avaliable. generics: &'a Generics, seen_generics: Vec, // The original index of the binding // this will not change when .filter() is called index: usize, } impl<'a> ToTokens for BindingInfo<'a> { fn to_tokens(&self, tokens: &mut TokenStream) { self.binding.to_tokens(tokens); } } impl<'a> BindingInfo<'a> { /// Returns a reference to the underlying `syn` AST node which this /// `BindingInfo` references pub fn ast(&self) -> &'a Field { self.field } /// Generates the pattern fragment for this field binding. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B{ a: i32, b: i32 }, /// C(u32), /// } /// }; /// let s = Structure::new(&di); /// /// assert_eq!( /// s.variants()[0].bindings()[0].pat().to_string(), /// quote! { /// ref __binding_0 /// }.to_string() /// ); /// ``` pub fn pat(&self) -> TokenStream { let BindingInfo { binding, style, .. } = self; quote!(#style #binding) } /// Returns a list of the type parameters which are referenced in this /// field's type. /// /// # Caveat /// /// If the field contains any macros in type position, all parameters will /// be considered bound. This is because we cannot determine which type /// parameters are bound by type macros. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// struct A { /// a: Option, /// b: U, /// } /// }; /// let mut s = Structure::new(&di); /// /// assert_eq!( /// s.variants()[0].bindings()[0].referenced_ty_params(), /// &["e::format_ident!("T")] /// ); /// ``` pub fn referenced_ty_params(&self) -> Vec<&'a Ident> { fetch_generics(&self.seen_generics, self.generics) } } /// This type is similar to `syn`'s `Variant` type, however each of the fields /// are references rather than owned. When this is used as the AST for a real /// variant, this struct simply borrows the fields of the `syn::Variant`, /// however this type may also be used as the sole variant for a struct. #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)] pub struct VariantAst<'a> { pub attrs: &'a [Attribute], pub ident: &'a Ident, pub fields: &'a Fields, pub discriminant: &'a Option<(token::Eq, Expr)>, } /// A wrapper around a `syn::DeriveInput`'s variant which provides utilities /// for destructuring `Variant`s with `match` expressions. #[derive(Debug, Clone, PartialEq, Eq, Hash)] pub struct VariantInfo<'a> { pub prefix: Option<&'a Ident>, bindings: Vec>, ast: VariantAst<'a>, generics: &'a Generics, // The original length of `bindings` before any `.filter()` calls original_length: usize, } /// Helper function used by the VariantInfo constructor. Walks all of the types /// in `field` and returns a list of the type parameters from `ty_params` which /// are referenced in the field. fn get_ty_params(field: &Field, generics: &Generics) -> Vec { // Helper type. Discovers all identifiers inside of the visited type, // and calls a callback with them. struct BoundTypeLocator<'a> { result: Vec, generics: &'a Generics, } impl<'a> Visit<'a> for BoundTypeLocator<'a> { // XXX: This also (intentionally) captures paths like T::SomeType. Is // this desirable? fn visit_ident(&mut self, id: &Ident) { for (idx, i) in self.generics.params.iter().enumerate() { if let GenericParam::Type(tparam) = i { if tparam.ident == *id { self.result[idx] = true; } } } } fn visit_type_macro(&mut self, x: &'a TypeMacro) { // If we see a type_mac declaration, then we can't know what type parameters // it might be binding, so we presume it binds all of them. for r in &mut self.result { *r = true; } visit::visit_type_macro(self, x) } } let mut btl = BoundTypeLocator { result: vec![false; generics.params.len()], generics, }; btl.visit_type(&field.ty); btl.result } impl<'a> VariantInfo<'a> { fn new(ast: VariantAst<'a>, prefix: Option<&'a Ident>, generics: &'a Generics) -> Self { let bindings = match ast.fields { Fields::Unit => vec![], Fields::Unnamed(FieldsUnnamed { unnamed: fields, .. }) | Fields::Named(FieldsNamed { named: fields, .. }) => { fields .into_iter() .enumerate() .map(|(i, field)| { BindingInfo { // XXX: This has to be call_site to avoid privacy // when deriving on private fields. binding: format_ident!("__binding_{}", i), style: BindStyle::Ref, field, generics, seen_generics: get_ty_params(field, generics), index: i, } }) .collect::>() } }; let original_length = bindings.len(); VariantInfo { prefix, bindings, ast, generics, original_length, } } /// Returns a slice of the bindings in this Variant. pub fn bindings(&self) -> &[BindingInfo<'a>] { &self.bindings } /// Returns a mut slice of the bindings in this Variant. pub fn bindings_mut(&mut self) -> &mut [BindingInfo<'a>] { &mut self.bindings } /// Returns a `VariantAst` object which contains references to the /// underlying `syn` AST node which this `Variant` was created from. pub fn ast(&self) -> VariantAst<'a> { self.ast } /// True if any bindings were omitted due to a `filter` call. pub fn omitted_bindings(&self) -> bool { self.original_length != self.bindings.len() } /// Generates the match-arm pattern which could be used to match against this Variant. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B(i32, i32), /// C(u32), /// } /// }; /// let s = Structure::new(&di); /// /// assert_eq!( /// s.variants()[0].pat().to_string(), /// quote!{ /// A::B(ref __binding_0, ref __binding_1,) /// }.to_string() /// ); /// ``` pub fn pat(&self) -> TokenStream { let mut t = TokenStream::new(); if let Some(prefix) = self.prefix { prefix.to_tokens(&mut t); quote!(::).to_tokens(&mut t); } self.ast.ident.to_tokens(&mut t); match self.ast.fields { Fields::Unit => { assert!(self.bindings.is_empty()); } Fields::Unnamed(..) => token::Paren(Span::call_site()).surround(&mut t, |t| { let mut expected_index = 0; for binding in &self.bindings { while expected_index < binding.index { quote!(_,).to_tokens(t); expected_index += 1; } binding.pat().to_tokens(t); quote!(,).to_tokens(t); expected_index += 1; } if expected_index != self.original_length { quote!(..).to_tokens(t); } }), Fields::Named(..) => token::Brace(Span::call_site()).surround(&mut t, |t| { for binding in &self.bindings { binding.field.ident.to_tokens(t); quote!(:).to_tokens(t); binding.pat().to_tokens(t); quote!(,).to_tokens(t); } if self.omitted_bindings() { quote!(..).to_tokens(t); } }), } t } /// Generates the token stream required to construct the current variant. /// /// The init array initializes each of the fields in the order they are /// written in `variant.ast().fields`. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B(usize, usize), /// C{ v: usize }, /// } /// }; /// let s = Structure::new(&di); /// /// assert_eq!( /// s.variants()[0].construct(|_, i| quote!(#i)).to_string(), /// /// quote!{ /// A::B(0usize, 1usize,) /// }.to_string() /// ); /// /// assert_eq!( /// s.variants()[1].construct(|_, i| quote!(#i)).to_string(), /// /// quote!{ /// A::C{ v: 0usize, } /// }.to_string() /// ); /// ``` pub fn construct(&self, mut func: F) -> TokenStream where F: FnMut(&Field, usize) -> T, T: ToTokens, { let mut t = TokenStream::new(); if let Some(prefix) = self.prefix { quote!(#prefix ::).to_tokens(&mut t); } self.ast.ident.to_tokens(&mut t); match &self.ast.fields { Fields::Unit => (), Fields::Unnamed(FieldsUnnamed { unnamed, .. }) => { token::Paren::default().surround(&mut t, |t| { for (i, field) in unnamed.into_iter().enumerate() { func(field, i).to_tokens(t); quote!(,).to_tokens(t); } }) } Fields::Named(FieldsNamed { named, .. }) => { token::Brace::default().surround(&mut t, |t| { for (i, field) in named.into_iter().enumerate() { field.ident.to_tokens(t); quote!(:).to_tokens(t); func(field, i).to_tokens(t); quote!(,).to_tokens(t); } }) } } t } /// Runs the passed-in function once for each bound field, passing in a `BindingInfo`. /// and generating a `match` arm which evaluates the returned tokens. /// /// This method will ignore fields which are ignored through the `filter` /// method. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B(i32, i32), /// C(u32), /// } /// }; /// let s = Structure::new(&di); /// /// assert_eq!( /// s.variants()[0].each(|bi| quote!(println!("{:?}", #bi))).to_string(), /// /// quote!{ /// A::B(ref __binding_0, ref __binding_1,) => { /// { println!("{:?}", __binding_0) } /// { println!("{:?}", __binding_1) } /// } /// }.to_string() /// ); /// ``` pub fn each(&self, mut f: F) -> TokenStream where F: FnMut(&BindingInfo<'_>) -> R, R: ToTokens, { let pat = self.pat(); let mut body = TokenStream::new(); for binding in &self.bindings { token::Brace::default().surround(&mut body, |body| { f(binding).to_tokens(body); }); } quote!(#pat => { #body }) } /// Runs the passed-in function once for each bound field, passing in the /// result of the previous call, and a `BindingInfo`. generating a `match` /// arm which evaluates to the resulting tokens. /// /// This method will ignore fields which are ignored through the `filter` /// method. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B(i32, i32), /// C(u32), /// } /// }; /// let s = Structure::new(&di); /// /// assert_eq!( /// s.variants()[0].fold(quote!(0), |acc, bi| quote!(#acc + #bi)).to_string(), /// /// quote!{ /// A::B(ref __binding_0, ref __binding_1,) => { /// 0 + __binding_0 + __binding_1 /// } /// }.to_string() /// ); /// ``` pub fn fold(&self, init: I, mut f: F) -> TokenStream where F: FnMut(TokenStream, &BindingInfo<'_>) -> R, I: ToTokens, R: ToTokens, { let pat = self.pat(); let body = self.bindings.iter().fold(quote!(#init), |i, bi| { let r = f(i, bi); quote!(#r) }); quote!(#pat => { #body }) } /// Filter the bindings created by this `Variant` object. This has 2 effects: /// /// * The bindings will no longer appear in match arms generated by methods /// on this `Variant` or its subobjects. /// /// * Impl blocks created with the `bound_impl` or `unsafe_bound_impl` /// method only consider type parameters referenced in the types of /// non-filtered fields. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B{ a: i32, b: i32 }, /// C{ a: u32 }, /// } /// }; /// let mut s = Structure::new(&di); /// /// s.variants_mut()[0].filter(|bi| { /// bi.ast().ident == Some(quote::format_ident!("b")) /// }); /// /// assert_eq!( /// s.each(|bi| quote!(println!("{:?}", #bi))).to_string(), /// /// quote!{ /// A::B{ b: ref __binding_1, .. } => { /// { println!("{:?}", __binding_1) } /// } /// A::C{ a: ref __binding_0, } => { /// { println!("{:?}", __binding_0) } /// } /// }.to_string() /// ); /// ``` pub fn filter(&mut self, f: F) -> &mut Self where F: FnMut(&BindingInfo<'_>) -> bool, { self.bindings.retain(f); self } /// Remove the binding at the given index. /// /// # Panics /// /// Panics if the index is out of range. pub fn remove_binding(&mut self, idx: usize) -> &mut Self { self.bindings.remove(idx); self } /// Updates the `BindStyle` for each of the passed-in fields by calling the /// passed-in function for each `BindingInfo`. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B(i32, i32), /// C(u32), /// } /// }; /// let mut s = Structure::new(&di); /// /// s.variants_mut()[0].bind_with(|bi| BindStyle::RefMut); /// /// assert_eq!( /// s.each(|bi| quote!(println!("{:?}", #bi))).to_string(), /// /// quote!{ /// A::B(ref mut __binding_0, ref mut __binding_1,) => { /// { println!("{:?}", __binding_0) } /// { println!("{:?}", __binding_1) } /// } /// A::C(ref __binding_0,) => { /// { println!("{:?}", __binding_0) } /// } /// }.to_string() /// ); /// ``` pub fn bind_with(&mut self, mut f: F) -> &mut Self where F: FnMut(&BindingInfo<'_>) -> BindStyle, { for binding in &mut self.bindings { binding.style = f(&binding); } self } /// Updates the binding name for each fo the passed-in fields by calling the /// passed-in function for each `BindingInfo`. /// /// The function will be called with the `BindingInfo` and its index in the /// enclosing variant. /// /// The default name is `__binding_{}` where `{}` is replaced with an /// increasing number. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B{ a: i32, b: i32 }, /// C{ a: u32 }, /// } /// }; /// let mut s = Structure::new(&di); /// /// s.variants_mut()[0].binding_name(|bi, i| bi.ident.clone().unwrap()); /// /// assert_eq!( /// s.each(|bi| quote!(println!("{:?}", #bi))).to_string(), /// /// quote!{ /// A::B{ a: ref a, b: ref b, } => { /// { println!("{:?}", a) } /// { println!("{:?}", b) } /// } /// A::C{ a: ref __binding_0, } => { /// { println!("{:?}", __binding_0) } /// } /// }.to_string() /// ); /// ``` pub fn binding_name(&mut self, mut f: F) -> &mut Self where F: FnMut(&Field, usize) -> Ident, { for (it, binding) in self.bindings.iter_mut().enumerate() { binding.binding = f(binding.field, it); } self } /// Returns a list of the type parameters which are referenced in this /// field's type. /// /// # Caveat /// /// If the field contains any macros in type position, all parameters will /// be considered bound. This is because we cannot determine which type /// parameters are bound by type macros. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// struct A { /// a: Option, /// b: U, /// } /// }; /// let mut s = Structure::new(&di); /// /// assert_eq!( /// s.variants()[0].bindings()[0].referenced_ty_params(), /// &["e::format_ident!("T")] /// ); /// ``` pub fn referenced_ty_params(&self) -> Vec<&'a Ident> { let mut flags = Vec::new(); for binding in &self.bindings { generics_fuse(&mut flags, &binding.seen_generics); } fetch_generics(&flags, self.generics) } } /// A wrapper around a `syn::DeriveInput` which provides utilities for creating /// custom derive trait implementations. #[derive(Debug, Clone, PartialEq, Eq, Hash)] pub struct Structure<'a> { variants: Vec>, omitted_variants: bool, underscore_const: bool, ast: &'a DeriveInput, extra_impl: Vec, extra_predicates: Vec, add_bounds: AddBounds, } impl<'a> Structure<'a> { /// Create a new `Structure` with the variants and fields from the passed-in /// `DeriveInput`. /// /// # Panics /// /// This method will panic if the provided AST node represents an untagged /// union. pub fn new(ast: &'a DeriveInput) -> Self { Self::try_new(ast).expect("Unable to create synstructure::Structure") } /// Create a new `Structure` with the variants and fields from the passed-in /// `DeriveInput`. /// /// Unlike `Structure::new`, this method does not panic if the provided AST /// node represents an untagged union. pub fn try_new(ast: &'a DeriveInput) -> Result { let variants = match &ast.data { Data::Enum(data) => (&data.variants) .into_iter() .map(|v| { VariantInfo::new( VariantAst { attrs: &v.attrs, ident: &v.ident, fields: &v.fields, discriminant: &v.discriminant, }, Some(&ast.ident), &ast.generics, ) }) .collect::>(), Data::Struct(data) => { // SAFETY NOTE: Normally putting an `Expr` in static storage // wouldn't be safe, because it could contain `Term` objects // which use thread-local interning. However, this static always // contains the value `None`. Thus, it will never contain any // unsafe values. struct UnsafeMakeSync(Option<(token::Eq, Expr)>); unsafe impl Sync for UnsafeMakeSync {} static NONE_DISCRIMINANT: UnsafeMakeSync = UnsafeMakeSync(None); vec![VariantInfo::new( VariantAst { attrs: &ast.attrs, ident: &ast.ident, fields: &data.fields, discriminant: &NONE_DISCRIMINANT.0, }, None, &ast.generics, )] } Data::Union(_) => { return Err(Error::new_spanned( ast, "unexpected unsupported untagged union", )); } }; Ok(Structure { variants, omitted_variants: false, underscore_const: false, ast, extra_impl: vec![], extra_predicates: vec![], add_bounds: AddBounds::Both, }) } /// Returns a slice of the variants in this Structure. pub fn variants(&self) -> &[VariantInfo<'a>] { &self.variants } /// Returns a mut slice of the variants in this Structure. pub fn variants_mut(&mut self) -> &mut [VariantInfo<'a>] { &mut self.variants } /// Returns a reference to the underlying `syn` AST node which this /// `Structure` was created from. pub fn ast(&self) -> &'a DeriveInput { self.ast } /// True if any variants were omitted due to a `filter_variants` call. pub fn omitted_variants(&self) -> bool { self.omitted_variants } /// Runs the passed-in function once for each bound field, passing in a `BindingInfo`. /// and generating `match` arms which evaluate the returned tokens. /// /// This method will ignore variants or fields which are ignored through the /// `filter` and `filter_variant` methods. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B(i32, i32), /// C(u32), /// } /// }; /// let s = Structure::new(&di); /// /// assert_eq!( /// s.each(|bi| quote!(println!("{:?}", #bi))).to_string(), /// /// quote!{ /// A::B(ref __binding_0, ref __binding_1,) => { /// { println!("{:?}", __binding_0) } /// { println!("{:?}", __binding_1) } /// } /// A::C(ref __binding_0,) => { /// { println!("{:?}", __binding_0) } /// } /// }.to_string() /// ); /// ``` pub fn each(&self, mut f: F) -> TokenStream where F: FnMut(&BindingInfo<'_>) -> R, R: ToTokens, { let mut t = TokenStream::new(); for variant in &self.variants { variant.each(&mut f).to_tokens(&mut t); } if self.omitted_variants { quote!(_ => {}).to_tokens(&mut t); } t } /// Runs the passed-in function once for each bound field, passing in the /// result of the previous call, and a `BindingInfo`. generating `match` /// arms which evaluate to the resulting tokens. /// /// This method will ignore variants or fields which are ignored through the /// `filter` and `filter_variant` methods. /// /// If a variant has been ignored, it will return the `init` value. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B(i32, i32), /// C(u32), /// } /// }; /// let s = Structure::new(&di); /// /// assert_eq!( /// s.fold(quote!(0), |acc, bi| quote!(#acc + #bi)).to_string(), /// /// quote!{ /// A::B(ref __binding_0, ref __binding_1,) => { /// 0 + __binding_0 + __binding_1 /// } /// A::C(ref __binding_0,) => { /// 0 + __binding_0 /// } /// }.to_string() /// ); /// ``` pub fn fold(&self, init: I, mut f: F) -> TokenStream where F: FnMut(TokenStream, &BindingInfo<'_>) -> R, I: ToTokens, R: ToTokens, { let mut t = TokenStream::new(); for variant in &self.variants { variant.fold(&init, &mut f).to_tokens(&mut t); } if self.omitted_variants { quote!(_ => { #init }).to_tokens(&mut t); } t } /// Runs the passed-in function once for each variant, passing in a /// `VariantInfo`. and generating `match` arms which evaluate the returned /// tokens. /// /// This method will ignore variants and not bind fields which are ignored /// through the `filter` and `filter_variant` methods. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B(i32, i32), /// C(u32), /// } /// }; /// let s = Structure::new(&di); /// /// assert_eq!( /// s.each_variant(|v| { /// let name = &v.ast().ident; /// quote!(println!(stringify!(#name))) /// }).to_string(), /// /// quote!{ /// A::B(ref __binding_0, ref __binding_1,) => { /// println!(stringify!(B)) /// } /// A::C(ref __binding_0,) => { /// println!(stringify!(C)) /// } /// }.to_string() /// ); /// ``` pub fn each_variant(&self, mut f: F) -> TokenStream where F: FnMut(&VariantInfo<'_>) -> R, R: ToTokens, { let mut t = TokenStream::new(); for variant in &self.variants { let pat = variant.pat(); let body = f(variant); quote!(#pat => { #body }).to_tokens(&mut t); } if self.omitted_variants { quote!(_ => {}).to_tokens(&mut t); } t } /// Filter the bindings created by this `Structure` object. This has 2 effects: /// /// * The bindings will no longer appear in match arms generated by methods /// on this `Structure` or its subobjects. /// /// * Impl blocks created with the `bound_impl` or `unsafe_bound_impl` /// method only consider type parameters referenced in the types of /// non-filtered fields. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B{ a: i32, b: i32 }, /// C{ a: u32 }, /// } /// }; /// let mut s = Structure::new(&di); /// /// s.filter(|bi| { /// bi.ast().ident == Some(quote::format_ident!("a")) /// }); /// /// assert_eq!( /// s.each(|bi| quote!(println!("{:?}", #bi))).to_string(), /// /// quote!{ /// A::B{ a: ref __binding_0, .. } => { /// { println!("{:?}", __binding_0) } /// } /// A::C{ a: ref __binding_0, } => { /// { println!("{:?}", __binding_0) } /// } /// }.to_string() /// ); /// ``` pub fn filter(&mut self, mut f: F) -> &mut Self where F: FnMut(&BindingInfo<'_>) -> bool, { for variant in &mut self.variants { variant.filter(&mut f); } self } /// Specify additional where predicate bounds which should be generated by /// impl-generating functions such as `gen_impl`, `bound_impl`, and /// `unsafe_bound_impl`. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B(T), /// C(Option), /// } /// }; /// let mut s = Structure::new(&di); /// /// // Add an additional where predicate. /// s.add_where_predicate(syn::parse_quote!(T: std::fmt::Display)); /// /// assert_eq!( /// s.bound_impl(quote!(krate::Trait), quote!{ /// fn a() {} /// }).to_string(), /// quote!{ /// #[allow(non_upper_case_globals)] /// #[doc(hidden)] /// const _DERIVE_krate_Trait_FOR_A: () = { /// extern crate krate; /// impl krate::Trait for A /// where T: std::fmt::Display, /// T: krate::Trait, /// Option: krate::Trait, /// U: krate::Trait /// { /// fn a() {} /// } /// }; /// }.to_string() /// ); /// ``` pub fn add_where_predicate(&mut self, pred: WherePredicate) -> &mut Self { self.extra_predicates.push(pred); self } /// Specify which bounds should be generated by impl-generating functions /// such as `gen_impl`, `bound_impl`, and `unsafe_bound_impl`. /// /// The default behaviour is to generate both field and generic bounds from /// type parameters. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B(T), /// C(Option), /// } /// }; /// let mut s = Structure::new(&di); /// /// // Limit bounds to only generics. /// s.add_bounds(AddBounds::Generics); /// /// assert_eq!( /// s.bound_impl(quote!(krate::Trait), quote!{ /// fn a() {} /// }).to_string(), /// quote!{ /// #[allow(non_upper_case_globals)] /// #[doc(hidden)] /// const _DERIVE_krate_Trait_FOR_A: () = { /// extern crate krate; /// impl krate::Trait for A /// where T: krate::Trait, /// U: krate::Trait /// { /// fn a() {} /// } /// }; /// }.to_string() /// ); /// ``` pub fn add_bounds(&mut self, mode: AddBounds) -> &mut Self { self.add_bounds = mode; self } /// Filter the variants matched by this `Structure` object. This has 2 effects: /// /// * Match arms destructuring these variants will no longer be generated by /// methods on this `Structure` /// /// * Impl blocks created with the `bound_impl` or `unsafe_bound_impl` /// method only consider type parameters referenced in the types of /// fields in non-fitered variants. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B(i32, i32), /// C(u32), /// } /// }; /// /// let mut s = Structure::new(&di); /// /// s.filter_variants(|v| v.ast().ident != "B"); /// /// assert_eq!( /// s.each(|bi| quote!(println!("{:?}", #bi))).to_string(), /// /// quote!{ /// A::C(ref __binding_0,) => { /// { println!("{:?}", __binding_0) } /// } /// _ => {} /// }.to_string() /// ); /// ``` pub fn filter_variants(&mut self, f: F) -> &mut Self where F: FnMut(&VariantInfo<'_>) -> bool, { let before_len = self.variants.len(); self.variants.retain(f); if self.variants.len() != before_len { self.omitted_variants = true; } self } /// Remove the variant at the given index. /// /// # Panics /// /// Panics if the index is out of range. pub fn remove_variant(&mut self, idx: usize) -> &mut Self { self.variants.remove(idx); self.omitted_variants = true; self } /// Updates the `BindStyle` for each of the passed-in fields by calling the /// passed-in function for each `BindingInfo`. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B(i32, i32), /// C(u32), /// } /// }; /// let mut s = Structure::new(&di); /// /// s.bind_with(|bi| BindStyle::RefMut); /// /// assert_eq!( /// s.each(|bi| quote!(println!("{:?}", #bi))).to_string(), /// /// quote!{ /// A::B(ref mut __binding_0, ref mut __binding_1,) => { /// { println!("{:?}", __binding_0) } /// { println!("{:?}", __binding_1) } /// } /// A::C(ref mut __binding_0,) => { /// { println!("{:?}", __binding_0) } /// } /// }.to_string() /// ); /// ``` pub fn bind_with(&mut self, mut f: F) -> &mut Self where F: FnMut(&BindingInfo<'_>) -> BindStyle, { for variant in &mut self.variants { variant.bind_with(&mut f); } self } /// Updates the binding name for each fo the passed-in fields by calling the /// passed-in function for each `BindingInfo`. /// /// The function will be called with the `BindingInfo` and its index in the /// enclosing variant. /// /// The default name is `__binding_{}` where `{}` is replaced with an /// increasing number. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B{ a: i32, b: i32 }, /// C{ a: u32 }, /// } /// }; /// let mut s = Structure::new(&di); /// /// s.binding_name(|bi, i| bi.ident.clone().unwrap()); /// /// assert_eq!( /// s.each(|bi| quote!(println!("{:?}", #bi))).to_string(), /// /// quote!{ /// A::B{ a: ref a, b: ref b, } => { /// { println!("{:?}", a) } /// { println!("{:?}", b) } /// } /// A::C{ a: ref a, } => { /// { println!("{:?}", a) } /// } /// }.to_string() /// ); /// ``` pub fn binding_name(&mut self, mut f: F) -> &mut Self where F: FnMut(&Field, usize) -> Ident, { for variant in &mut self.variants { variant.binding_name(&mut f); } self } /// Returns a list of the type parameters which are refrenced in the types /// of non-filtered fields / variants. /// /// # Caveat /// /// If the struct contains any macros in type position, all parameters will /// be considered bound. This is because we cannot determine which type /// parameters are bound by type macros. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B(T, i32), /// C(Option), /// } /// }; /// let mut s = Structure::new(&di); /// /// s.filter_variants(|v| v.ast().ident != "C"); /// /// assert_eq!( /// s.referenced_ty_params(), /// &["e::format_ident!("T")] /// ); /// ``` pub fn referenced_ty_params(&self) -> Vec<&'a Ident> { let mut flags = Vec::new(); for variant in &self.variants { for binding in &variant.bindings { generics_fuse(&mut flags, &binding.seen_generics); } } fetch_generics(&flags, &self.ast.generics) } /// Adds an `impl<>` generic parameter. /// This can be used when the trait to be derived needs some extra generic parameters. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B(T), /// C(Option), /// } /// }; /// let mut s = Structure::new(&di); /// let generic: syn::GenericParam = syn::parse_quote!(X: krate::AnotherTrait); /// /// assert_eq!( /// s.add_impl_generic(generic) /// .bound_impl(quote!(krate::Trait), /// quote!{ /// fn a() {} /// } /// ).to_string(), /// quote!{ /// #[allow(non_upper_case_globals)] /// #[doc(hidden)] /// const _DERIVE_krate_Trait_X_FOR_A: () = { /// extern crate krate; /// impl krate::Trait for A /// where T : krate :: Trait < X >, /// Option: krate::Trait, /// U: krate::Trait /// { /// fn a() {} /// } /// }; /// }.to_string() /// ); /// ``` pub fn add_impl_generic(&mut self, param: GenericParam) -> &mut Self { self.extra_impl.push(param); self } /// Add trait bounds for a trait with the given path for each type parmaeter /// referenced in the types of non-filtered fields. /// /// # Caveat /// /// If the method contains any macros in type position, all parameters will /// be considered bound. This is because we cannot determine which type /// parameters are bound by type macros. pub fn add_trait_bounds( &self, bound: &TraitBound, where_clause: &mut Option, mode: AddBounds, ) { // If we have any explicit where predicates, make sure to add them first. if !self.extra_predicates.is_empty() { let clause = get_or_insert_with(&mut *where_clause, || WhereClause { where_token: Default::default(), predicates: punctuated::Punctuated::new(), }); clause .predicates .extend(self.extra_predicates.iter().cloned()); } let mut seen = HashSet::new(); let mut pred = |ty: Type| { if !seen.contains(&ty) { seen.insert(ty.clone()); // Add a predicate. let clause = get_or_insert_with(&mut *where_clause, || WhereClause { where_token: Default::default(), predicates: punctuated::Punctuated::new(), }); clause.predicates.push(WherePredicate::Type(PredicateType { lifetimes: None, bounded_ty: ty, colon_token: Default::default(), bounds: Some(punctuated::Pair::End(TypeParamBound::Trait(bound.clone()))) .into_iter() .collect(), })); } }; for variant in &self.variants { for binding in &variant.bindings { match mode { AddBounds::Both | AddBounds::Fields => { for &seen in &binding.seen_generics { if seen { pred(binding.ast().ty.clone()); break; } } } _ => {} } match mode { AddBounds::Both | AddBounds::Generics => { for param in binding.referenced_ty_params() { pred(Type::Path(TypePath { qself: None, path: (*param).clone().into(), })); } } _ => {} } } } } /// Configure whether to use `const _` instead of a generated const name in /// code generated by `gen_impl` and `bound_impl`. /// /// This syntax is only supported by rust 1.37, and later versions. /// /// Defaults to `false` for backwards compatibility reasons. /// /// # Example /// /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// struct MyStruct; /// }; /// let mut s = Structure::new(&di); /// /// assert_eq!( /// s.underscore_const(true) /// .gen_impl(quote! { gen impl Trait for @Self { } }) /// .to_string(), /// quote! { /// const _: () = { /// impl Trait for MyStruct { } /// }; /// } /// .to_string() /// ); /// /// assert_eq!( /// s.underscore_const(false) /// .gen_impl(quote! { gen impl Trait for @Self { } }) /// .to_string(), /// quote! { /// #[allow(non_upper_case_globals)] /// const _DERIVE_Trait_FOR_MyStruct: () = { /// impl Trait for MyStruct { } /// }; /// } /// .to_string() /// ); /// ``` pub fn underscore_const(&mut self, enabled: bool) -> &mut Self { self.underscore_const = enabled; self } /// > NOTE: This methods' features are superceded by `Structure::gen_impl`. /// /// Creates an `impl` block with the required generic type fields filled in /// to implement the trait `path`. /// /// This method also adds where clauses to the impl requiring that all /// referenced type parmaeters implement the trait `path`. /// /// # Hygiene and Paths /// /// This method wraps the impl block inside of a `const` (see the example /// below). In this scope, the first segment of the passed-in path is /// `extern crate`-ed in. If you don't want to generate that `extern crate` /// item, use a global path. /// /// This means that if you are implementing `my_crate::Trait`, you simply /// write `s.bound_impl(quote!(my_crate::Trait), quote!(...))`, and for the /// entirety of the definition, you can refer to your crate as `my_crate`. /// /// # Caveat /// /// If the method contains any macros in type position, all parameters will /// be considered bound. This is because we cannot determine which type /// parameters are bound by type macros. /// /// # Panics /// /// Panics if the path string parameter is not a valid `TraitBound`. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B(T), /// C(Option), /// } /// }; /// let mut s = Structure::new(&di); /// /// s.filter_variants(|v| v.ast().ident != "B"); /// /// assert_eq!( /// s.bound_impl(quote!(krate::Trait), quote!{ /// fn a() {} /// }).to_string(), /// quote!{ /// #[allow(non_upper_case_globals)] /// #[doc(hidden)] /// const _DERIVE_krate_Trait_FOR_A: () = { /// extern crate krate; /// impl krate::Trait for A /// where Option: krate::Trait, /// U: krate::Trait /// { /// fn a() {} /// } /// }; /// }.to_string() /// ); /// ``` pub fn bound_impl(&self, path: P, body: B) -> TokenStream { self.impl_internal( path.into_token_stream(), body.into_token_stream(), quote!(), None, ) } /// > NOTE: This methods' features are superceded by `Structure::gen_impl`. /// /// Creates an `impl` block with the required generic type fields filled in /// to implement the unsafe trait `path`. /// /// This method also adds where clauses to the impl requiring that all /// referenced type parmaeters implement the trait `path`. /// /// # Hygiene and Paths /// /// This method wraps the impl block inside of a `const` (see the example /// below). In this scope, the first segment of the passed-in path is /// `extern crate`-ed in. If you don't want to generate that `extern crate` /// item, use a global path. /// /// This means that if you are implementing `my_crate::Trait`, you simply /// write `s.bound_impl(quote!(my_crate::Trait), quote!(...))`, and for the /// entirety of the definition, you can refer to your crate as `my_crate`. /// /// # Caveat /// /// If the method contains any macros in type position, all parameters will /// be considered bound. This is because we cannot determine which type /// parameters are bound by type macros. /// /// # Panics /// /// Panics if the path string parameter is not a valid `TraitBound`. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B(T), /// C(Option), /// } /// }; /// let mut s = Structure::new(&di); /// /// s.filter_variants(|v| v.ast().ident != "B"); /// /// assert_eq!( /// s.unsafe_bound_impl(quote!(krate::Trait), quote!{ /// fn a() {} /// }).to_string(), /// quote!{ /// #[allow(non_upper_case_globals)] /// #[doc(hidden)] /// const _DERIVE_krate_Trait_FOR_A: () = { /// extern crate krate; /// unsafe impl krate::Trait for A /// where Option: krate::Trait, /// U: krate::Trait /// { /// fn a() {} /// } /// }; /// }.to_string() /// ); /// ``` pub fn unsafe_bound_impl(&self, path: P, body: B) -> TokenStream { self.impl_internal( path.into_token_stream(), body.into_token_stream(), quote!(unsafe), None, ) } /// > NOTE: This methods' features are superceded by `Structure::gen_impl`. /// /// Creates an `impl` block with the required generic type fields filled in /// to implement the trait `path`. /// /// This method will not add any where clauses to the impl. /// /// # Hygiene and Paths /// /// This method wraps the impl block inside of a `const` (see the example /// below). In this scope, the first segment of the passed-in path is /// `extern crate`-ed in. If you don't want to generate that `extern crate` /// item, use a global path. /// /// This means that if you are implementing `my_crate::Trait`, you simply /// write `s.bound_impl(quote!(my_crate::Trait), quote!(...))`, and for the /// entirety of the definition, you can refer to your crate as `my_crate`. /// /// # Panics /// /// Panics if the path string parameter is not a valid `TraitBound`. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B(T), /// C(Option), /// } /// }; /// let mut s = Structure::new(&di); /// /// s.filter_variants(|v| v.ast().ident != "B"); /// /// assert_eq!( /// s.unbound_impl(quote!(krate::Trait), quote!{ /// fn a() {} /// }).to_string(), /// quote!{ /// #[allow(non_upper_case_globals)] /// #[doc(hidden)] /// const _DERIVE_krate_Trait_FOR_A: () = { /// extern crate krate; /// impl krate::Trait for A { /// fn a() {} /// } /// }; /// }.to_string() /// ); /// ``` pub fn unbound_impl(&self, path: P, body: B) -> TokenStream { self.impl_internal( path.into_token_stream(), body.into_token_stream(), quote!(), Some(AddBounds::None), ) } /// > NOTE: This methods' features are superceded by `Structure::gen_impl`. /// /// Creates an `impl` block with the required generic type fields filled in /// to implement the unsafe trait `path`. /// /// This method will not add any where clauses to the impl. /// /// # Hygiene and Paths /// /// This method wraps the impl block inside of a `const` (see the example /// below). In this scope, the first segment of the passed-in path is /// `extern crate`-ed in. If you don't want to generate that `extern crate` /// item, use a global path. /// /// This means that if you are implementing `my_crate::Trait`, you simply /// write `s.bound_impl(quote!(my_crate::Trait), quote!(...))`, and for the /// entirety of the definition, you can refer to your crate as `my_crate`. /// /// # Panics /// /// Panics if the path string parameter is not a valid `TraitBound`. /// /// # Example /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B(T), /// C(Option), /// } /// }; /// let mut s = Structure::new(&di); /// /// s.filter_variants(|v| v.ast().ident != "B"); /// /// assert_eq!( /// s.unsafe_unbound_impl(quote!(krate::Trait), quote!{ /// fn a() {} /// }).to_string(), /// quote!{ /// #[allow(non_upper_case_globals)] /// #[doc(hidden)] /// const _DERIVE_krate_Trait_FOR_A: () = { /// extern crate krate; /// unsafe impl krate::Trait for A { /// fn a() {} /// } /// }; /// }.to_string() /// ); /// ``` #[deprecated] pub fn unsafe_unbound_impl(&self, path: P, body: B) -> TokenStream { self.impl_internal( path.into_token_stream(), body.into_token_stream(), quote!(unsafe), Some(AddBounds::None), ) } fn impl_internal( &self, path: TokenStream, body: TokenStream, safety: TokenStream, mode: Option, ) -> TokenStream { let mode = mode.unwrap_or(self.add_bounds); let name = &self.ast.ident; let mut gen_clone = self.ast.generics.clone(); gen_clone.params.extend(self.extra_impl.clone().into_iter()); let (impl_generics, _, _) = gen_clone.split_for_impl(); let (_, ty_generics, where_clause) = self.ast.generics.split_for_impl(); let bound = syn::parse2::(path) .expect("`path` argument must be a valid rust trait bound"); let mut where_clause = where_clause.cloned(); self.add_trait_bounds(&bound, &mut where_clause, mode); // This function is smart. If a global path is passed, no extern crate // statement will be generated, however, a relative path will cause the // crate which it is relative to to be imported within the current // scope. let mut extern_crate = quote!(); if bound.path.leading_colon.is_none() { if let Some(seg) = bound.path.segments.first() { let seg = &seg.ident; extern_crate = quote! { extern crate #seg; }; } } let generated = quote! { #extern_crate #safety impl #impl_generics #bound for #name #ty_generics #where_clause { #body } }; if self.underscore_const { quote! { const _: () = { #generated }; } } else { let dummy_const: Ident = sanitize_ident(&format!( "_DERIVE_{}_FOR_{}", (&bound).into_token_stream(), name.into_token_stream(), )); quote! { #[allow(non_upper_case_globals)] #[doc(hidden)] const #dummy_const: () = { #generated }; } } } /// Generate an impl block for the given struct. This impl block will /// automatically use hygiene tricks to avoid polluting the caller's /// namespace, and will automatically add trait bounds for generic type /// parameters. /// /// # Syntax /// /// This function accepts its arguments as a `TokenStream`. The recommended way /// to call this function is passing the result of invoking the `quote!` /// macro to it. /// /// ```ignore /// s.gen_impl(quote! { /// // You can write any items which you want to import into scope here. /// // For example, you may want to include an `extern crate` for the /// // crate which implements your trait. These items will only be /// // visible to the code you generate, and won't be exposed to the /// // consuming crate /// extern crate krate; /// /// // You can also add `use` statements here to bring types or traits /// // into scope. /// // /// // WARNING: Try not to use common names here, because the stable /// // version of syn does not support hygiene and you could accidentally /// // shadow types from the caller crate. /// use krate::Trait as MyTrait; /// /// // The actual impl block is a `gen impl` or `gen unsafe impl` block. /// // You can use `@Self` to refer to the structure's type. /// gen impl MyTrait for @Self { /// fn f(&self) { ... } /// } /// }) /// ``` /// /// The most common usage of this trait involves loading the crate the /// target trait comes from with `extern crate`, and then invoking a `gen /// impl` block. /// /// # Hygiene /// /// This method tries to handle hygiene intelligenly for both stable and /// unstable proc-macro implementations, however there are visible /// differences. /// /// The output of every `gen_impl` function is wrapped in a dummy `const` /// value, to ensure that it is given its own scope, and any values brought /// into scope are not leaked to the calling crate. /// /// By default, the above invocation may generate an output like the /// following: /// /// ```ignore /// const _DERIVE_krate_Trait_FOR_Struct: () = { /// extern crate krate; /// use krate::Trait as MyTrait; /// impl MyTrait for Struct where T: MyTrait { /// fn f(&self) { ... } /// } /// }; /// ``` /// /// The `Structure` may also be confired with the [`underscore_const`] method /// to generate `const _` instead. /// /// ```ignore /// const _: () = { /// extern crate krate; /// use krate::Trait as MyTrait; /// impl MyTrait for Struct where T: MyTrait { /// fn f(&self) { ... } /// } /// }; /// ``` /// /// ### Using the `std` crate /// /// If you are using `quote!()` to implement your trait, with the /// `proc-macro2/nightly` feature, `std` isn't considered to be in scope for /// your macro. This means that if you use types from `std` in your /// procedural macro, you'll want to explicitly load it with an `extern /// crate std;`. /// /// ### Absolute paths /// /// You should generally avoid using absolute paths in your generated code, /// as they will resolve very differently when using the stable and nightly /// versions of `proc-macro2`. Instead, load the crates you need to use /// explictly with `extern crate` and /// /// # Trait Bounds /// /// This method will automatically add trait bounds for any type parameters /// which are referenced within the types of non-ignored fields. /// /// Additional type parameters may be added with the generics syntax after /// the `impl` keyword. /// /// ### Type Macro Caveat /// /// If the method contains any macros in type position, all parameters will /// be considered bound. This is because we cannot determine which type /// parameters are bound by type macros. /// /// # Errors /// /// This function will generate a `compile_error!` if additional type /// parameters added by `impl<..>` conflict with generic type parameters on /// the original struct. /// /// # Panics /// /// This function will panic if the input `TokenStream` is not well-formed. /// /// # Example Usage /// /// ``` /// # use synstructure::*; /// let di: syn::DeriveInput = syn::parse_quote! { /// enum A { /// B(T), /// C(Option), /// } /// }; /// let mut s = Structure::new(&di); /// /// s.filter_variants(|v| v.ast().ident != "B"); /// /// assert_eq!( /// s.gen_impl(quote! { /// extern crate krate; /// gen impl krate::Trait for @Self { /// fn a() {} /// } /// }).to_string(), /// quote!{ /// #[allow(non_upper_case_globals)] /// const _DERIVE_krate_Trait_FOR_A: () = { /// extern crate krate; /// impl krate::Trait for A /// where /// Option: krate::Trait, /// U: krate::Trait /// { /// fn a() {} /// } /// }; /// }.to_string() /// ); /// /// // NOTE: You can also add extra generics after the impl /// assert_eq!( /// s.gen_impl(quote! { /// extern crate krate; /// gen impl krate::Trait for @Self /// where /// X: Send + Sync, /// { /// fn a() {} /// } /// }).to_string(), /// quote!{ /// #[allow(non_upper_case_globals)] /// const _DERIVE_krate_Trait_X_FOR_A: () = { /// extern crate krate; /// impl krate::Trait for A /// where /// X: Send + Sync, /// Option: krate::Trait, /// U: krate::Trait /// { /// fn a() {} /// } /// }; /// }.to_string() /// ); /// /// // NOTE: you can generate multiple traits with a single call /// assert_eq!( /// s.gen_impl(quote! { /// extern crate krate; /// /// gen impl krate::Trait for @Self { /// fn a() {} /// } /// /// gen impl krate::OtherTrait for @Self { /// fn b() {} /// } /// }).to_string(), /// quote!{ /// #[allow(non_upper_case_globals)] /// const _DERIVE_krate_Trait_FOR_A: () = { /// extern crate krate; /// impl krate::Trait for A /// where /// Option: krate::Trait, /// U: krate::Trait /// { /// fn a() {} /// } /// /// impl krate::OtherTrait for A /// where /// Option: krate::OtherTrait, /// U: krate::OtherTrait /// { /// fn b() {} /// } /// }; /// }.to_string() /// ); /// ``` /// /// Use `add_bounds` to change which bounds are generated. pub fn gen_impl(&self, cfg: TokenStream) -> TokenStream { Parser::parse2( |input: ParseStream<'_>| -> Result { self.gen_impl_parse(input, true) }, cfg, ) .expect("Failed to parse gen_impl") } fn gen_impl_parse(&self, input: ParseStream<'_>, wrap: bool) -> Result { fn parse_prefix(input: ParseStream<'_>) -> Result> { if input.parse::()? != "gen" { return Err(input.error("Expected keyword `gen`")); } let safety = input.parse::>()?; let _ = input.parse::()?; Ok(safety) } let mut before = vec![]; loop { if parse_prefix(&input.fork()).is_ok() { break; } before.push(input.parse::()?); } // Parse the prefix "for real" let safety = parse_prefix(input)?; // optional `<>` let mut generics = input.parse::()?; // @bound let bound = input.parse::()?; // `for @Self` let _ = input.parse::()?; let _ = input.parse::()?; let _ = input.parse::()?; // optional `where ...` generics.where_clause = input.parse()?; // Body of the impl let body; braced!(body in input); let body = body.parse::()?; // Try to parse the next entry in sequence. If this fails, we'll fall // back to just parsing the entire rest of the TokenStream. let maybe_next_impl = self.gen_impl_parse(&input.fork(), false); // Eat tokens to the end. Whether or not our speculative nested parse // succeeded, we're going to want to consume the rest of our input. let mut after = input.parse::()?; if let Ok(stream) = maybe_next_impl { after = stream; } assert!(input.is_empty(), "Should've consumed the rest of our input"); /* Codegen Logic */ let name = &self.ast.ident; // Add the generics from the original struct in, and then add any // additional trait bounds which we need on the type. if let Err(err) = merge_generics(&mut generics, &self.ast.generics) { // Report the merge error as a `compile_error!`, as it may be // triggerable by an end-user. return Ok(err.to_compile_error()); } self.add_trait_bounds(&bound, &mut generics.where_clause, self.add_bounds); let (impl_generics, _, where_clause) = generics.split_for_impl(); let (_, ty_generics, _) = self.ast.generics.split_for_impl(); let generated = quote! { #(#before)* #safety impl #impl_generics #bound for #name #ty_generics #where_clause { #body } #after }; if wrap { if self.underscore_const { Ok(quote! { const _: () = { #generated }; }) } else { let dummy_const: Ident = sanitize_ident(&format!( "_DERIVE_{}_FOR_{}", (&bound).into_token_stream(), name.into_token_stream(), )); Ok(quote! { #[allow(non_upper_case_globals)] const #dummy_const: () = { #generated }; }) } } else { Ok(generated) } } } /// Dumps an unpretty version of a tokenstream. Takes any type which implements /// `Display`. /// /// This is mostly useful for visualizing the output of a procedural macro, as /// it makes it marginally more readable. It is used in the implementation of /// `test_derive!` to unprettily print the output. /// /// # Stability /// /// The stability of the output of this function is not guaranteed. Do not /// assert that the output of this function does not change between minor /// versions. /// /// # Example /// /// ``` /// # use quote::quote; /// assert_eq!( /// synstructure::unpretty_print(quote! { /// #[allow(non_upper_case_globals)] /// const _DERIVE_krate_Trait_FOR_A: () = { /// extern crate krate; /// impl krate::Trait for A /// where /// Option: krate::Trait, /// U: krate::Trait /// { /// fn a() {} /// } /// }; /// }), /// "# [ /// allow ( /// non_upper_case_globals ) /// ] /// const _DERIVE_krate_Trait_FOR_A : ( /// ) /// = { /// extern crate krate ; /// impl < T , U > krate :: Trait for A < T , U > where Option < U > : krate :: Trait , U : krate :: Trait { /// fn a ( /// ) /// { /// } /// } /// } /// ; /// " /// ) /// ``` pub fn unpretty_print(ts: T) -> String { let mut res = String::new(); let raw_s = ts.to_string(); let mut s = &raw_s[..]; let mut indent = 0; while let Some(i) = s.find(&['(', '{', '[', ')', '}', ']', ';'][..]) { match &s[i..=i] { "(" | "{" | "[" => indent += 1, ")" | "}" | "]" => indent -= 1, _ => {} } res.push_str(&s[..=i]); res.push('\n'); for _ in 0..indent { res.push_str(" "); } s = trim_start_matches(&s[i + 1..], ' '); } res.push_str(s); res } /// `trim_left_matches` has been deprecated in favor of `trim_start_matches`. /// This helper silences the warning, as we need to continue using /// `trim_left_matches` for rust 1.15 support. #[allow(deprecated)] fn trim_start_matches(s: &str, c: char) -> &str { s.trim_left_matches(c) } /// Helper trait describing values which may be returned by macro implementation /// methods used by this crate's macros. pub trait MacroResult { /// Convert this result into a `Result` for further processing / validation. fn into_result(self) -> Result; /// Convert this result into a `proc_macro::TokenStream`, ready to return /// from a native `proc_macro` implementation. /// /// If `into_result()` would return an `Err`, this method should instead /// generate a `compile_error!` invocation to nicely report the error. /// /// *This method is available if `synstructure` is built with the /// `"proc-macro"` feature.* #[cfg(all( not(all(target_arch = "wasm32", any(target_os = "unknown", target_os = "wasi"))), feature = "proc-macro" ))] fn into_stream(self) -> proc_macro::TokenStream where Self: Sized, { match self.into_result() { Ok(ts) => ts.into(), Err(err) => err.to_compile_error().into(), } } } #[cfg(all( not(all(target_arch = "wasm32", any(target_os = "unknown", target_os = "wasi"))), feature = "proc-macro" ))] impl MacroResult for proc_macro::TokenStream { fn into_result(self) -> Result { Ok(self.into()) } fn into_stream(self) -> proc_macro::TokenStream { self } } impl MacroResult for TokenStream { fn into_result(self) -> Result { Ok(self) } } impl MacroResult for Result { fn into_result(self) -> Result { match self { Ok(v) => v.into_result(), Err(err) => Err(err), } } } #[cfg(test)] mod tests { use super::*; // Regression test for #48 #[test] fn test_each_enum() { let di: syn::DeriveInput = syn::parse_quote! { enum A { Foo(usize, bool), Bar(bool, usize), Baz(usize, bool, usize), Quux(bool, usize, bool) } }; let mut s = Structure::new(&di); s.filter(|bi| bi.ast().ty.to_token_stream().to_string() == "bool"); assert_eq!( s.each(|bi| quote!(do_something(#bi))).to_string(), quote! { A::Foo(_, ref __binding_1,) => { { do_something(__binding_1) } } A::Bar(ref __binding_0, ..) => { { do_something(__binding_0) } } A::Baz(_, ref __binding_1, ..) => { { do_something(__binding_1) } } A::Quux(ref __binding_0, _, ref __binding_2,) => { { do_something(__binding_0) } { do_something(__binding_2) } } } .to_string() ); } }