# Crate synstructure [−] [src]

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
     */
    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)) {}
    }

    /*
     * Derive Implementation
     */
    fn walkfields_derive(s: synstructure::Structure) -> quote::Tokens {
        let body = s.each(|bi| quote!{
            walk(#bi)
        });

        s.bound_impl("::WalkFields", quote!{
            fn walk_fields(&self, walk: &mut FnMut(&::WalkFields)) {
                match *self { #body }
            }
        })
    }
    decl_derive!([WalkFields] => walkfields_derive);

    /*
     * Test Case
     */
    fn main() {
        test_derive! {
            walkfields_derive {
                enum A<T> {
                    B(i32, T),
                    C(i32),
                }
            }
            expands to {
                impl<T> ::WalkFields for A<T> where T: ::WalkFields {
                    fn walk_fields(&self, walk: &mut FnMut(&::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
     */
    pub trait Interest {
        fn interesting(&self) -> bool;
    }
    impl Interest for i32 {
        fn interesting(&self) -> bool { *self > 0 }
    }

    /*
     * Derive Implementation
     */
    fn interest_derive(mut s: synstructure::Structure) -> quote::Tokens {
        let body = s.fold(false, |acc, bi| quote!{
            #acc || ::Interest::interesting(#bi)
        });

        s.bound_impl("::Interest", quote!{
            fn interesting(&self) -> bool {
                match *self {
                    #body
                }
            }
        })
    }
    decl_derive!([Interest] => interest_derive);

    /*
     * Test Case
     */
    fn main() {
        test_derive!{
            interest_derive {
                enum A<T> {
                    B(i32, T),
                    C(i32),
                }
            }
            expands to {
                impl<T> ::Interest for A<T> where T: ::Interest {
                    fn interesting(&self) -> bool {
                        match *self {
                            A::B(ref __binding_0, ref __binding_1,) => {
                                false || ::Interest::interesting(__binding_0) ||
                                    ::Interest::interesting(__binding_1)
                            }
                            A::C(ref __binding_0,) => {
                                false || ::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_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 astruct.
VariantInfo | A wrapper around a `syn` `DeriveInput`'s variant which provides utilities for destructuring `Variant`s with `match` expressions.

## Enums

BindStyle | The type of binding to use when generating a pattern.

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)