Crate synstructure

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

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 }
            }
        }
    })
}
synstructure::decl_derive!([WalkFields] => walkfields_derive);

/*
 * Test Case
 */
fn main() {
    synstructure::test_derive! {
        walkfields_derive {
            enum A<T> {
                B(i32, T),
                C(i32),
            }
        }
        expands to {
            const _: () = {
                extern crate synstructure_test_traits;
                impl<T> synstructure_test_traits::WalkFields for A<T>
                    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

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
                }
            }
        }
    })
}
synstructure::decl_derive!([Interest] => interest_derive);

/*
 * Test Case
 */
fn main() {
    synstructure::test_derive!{
        interest_derive {
            enum A<T> {
                B(i32, T),
                C(i32),
            }
        }
        expands to {
            const _: () = {
                extern crate synstructure_test_traits;
                impl<T> synstructure_test_traits::Interest for A<T>
                    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.

Macros

• decl_attribute
  The decl_attribute! macro declares a custom attribute wrapper. It will parse the incoming TokenStream into a synstructure::Structure object, and pass it into the inner function.
• decl_derive
  The decl_derive! macro declares a custom derive wrapper. It will parse the incoming TokenStream into a synstructure::Structure object, and pass it into the inner function.
• test_derive
  Run a test on a custom derive. This macro expands both the original struct and the expansion to ensure that they compile correctly, and confirms that feeding the original struct into the named derive will produce the written output.

Structs

• BindingInfo
  Information about a specific binding. This contains both an Ident reference to the given field, and the syn &'a Field descriptor for that field.
• Structure
  A wrapper around a syn::DeriveInput which provides utilities for creating custom derive trait implementations.
• VariantAst
  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.
• VariantInfo
  A wrapper around a syn::DeriveInput’s variant which provides utilities for destructuring Variants with match expressions.

Enums

• AddBounds
  Changes how bounds are added
• BindStyle
  The type of binding to use when generating a pattern.

Traits

• MacroResult
  Helper trait describing values which may be returned by macro implementation methods used by this crate’s macros.

Functions

• fetch_generics 🔒
• generics_fuse 🔒
• get_or_insert_with 🔒
  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.
• get_ty_params 🔒
  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.
• merge_generics 🔒
• trim_start_matches 🔒
  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.
• unpretty_print
  Dumps an unpretty version of a tokenstream. Takes any type which implements Display.