Procedural macros — Derive

#[derive(Debug, Clone)]
struct Point { x: i32, y: i32 }

cargo new describe_macros --lib

# describe_macros/Cargo.toml
[package]
name = "describe_macros"
version = "0.1.0"
edition = "2024"

[lib]
proc-macro = true            # required: makes the crate a macro crate

[dependencies]
syn = { version = "2", features = ["full"] }   # Rust code parsing
quote = "1"                                    # code generation
proc-macro2 = "1"                              # TokenStream usable outside the macro (tests)

# my_app/Cargo.toml
[dependencies]
describe_macros = { path = "../describe_macros" }

use describe_macros::Describe;

#[derive(Describe)]
struct User { name: String, age: u32 }

source code ──► TokenStream ──syn──► tree (DeriveInput) ──you──► quote! ──► TokenStream ──► compiler

use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, DeriveInput};

#[proc_macro_derive(Describe)]
pub fn derive_describe(input: TokenStream) -> TokenStream {
    let ast = parse_macro_input!(input as DeriveInput);   // syntax error -> compile error
    let name = &ast.ident;

    let code = quote! {
        impl #name {
            pub fn describe() -> &'static str {
                stringify!(#name)
            }
        }
    };

    code.into()                                           // proc_macro2::TokenStream -> proc_macro::TokenStream
}

pub struct DeriveInput {
    pub attrs: Vec<Attribute>,     // #[...] placed on the type
    pub vis: Visibility,           // pub, pub(crate)...
    pub ident: Ident,              // the name of the type
    pub generics: Generics,        // <T, 'a, const N: usize> and where
    pub data: Data,                // Struct, Enum or Union, with the fields
}

// describe_macros/src/lib.rs
use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, Data, DeriveInput, Fields};

#[proc_macro_derive(Describe)]
pub fn derive_describe(input: TokenStream) -> TokenStream {
    let ast = parse_macro_input!(input as DeriveInput);
    let name = &ast.ident;

    let Data::Struct(data) = &ast.data else {
        return syn::Error::new_spanned(&ast.ident, "Describe only applies to structs")
            .to_compile_error()
            .into();
    };

    let Fields::Named(fields) = &data.fields else {
        return syn::Error::new_spanned(&ast.ident, "Describe requires named fields")
            .to_compile_error()
            .into();
    };

    let names: Vec<_> = fields.named.iter().map(|c| c.ident.as_ref().unwrap()).collect();

    quote! {
        impl #name {
            pub fn describe(&self) -> String {
                let mut parts = Vec::new();
                #(
                    parts.push(format!("{} = {:?}", stringify!(#names), self.#names));
                )*
                format!("{} {{ {} }}", stringify!(#name), parts.join(", "))
            }
        }
    }
    .into()
}

// my_app
#[derive(Describe)]
struct User { name: String, age: u32 }

fn main() {
    let u = User { name: "Ada".into(), age: 36 };
    println!("{}", u.describe());     // User { name = "Ada", age = 36 }
}

impl User {
    pub fn describe(&self) -> String {
        let mut parts = Vec::new();
        parts.push(format!("{} = {:?}", "name", self.name));
        parts.push(format!("{} = {:?}", "age", self.age));
        format!("{} {{ {} }}", "User", parts.join(", "))
    }
}

use syn::{Data, Fields};

fn describe_shape(data: &Data) -> &'static str {
    match data {
        Data::Struct(s) => match &s.fields {
            Fields::Named(_) => "struct with named fields",    // struct S { a: i32 }
            Fields::Unnamed(_) => "tuple struct",              // struct S(i32, String);
            Fields::Unit => "unit struct",                     // struct S;
        },
        Data::Enum(_) => "enum",
        Data::Union(_) => "union",
    }
}

pub struct Field {
    pub attrs: Vec<Attribute>,     // #[...] on the field
    pub vis: Visibility,
    pub ident: Option<Ident>,      // None for a tuple field
    pub ty: Type,                  // the type of the field
    // ...
}

use syn::Index;

let indices: Vec<Index> = (0..fields.unnamed.len()).map(Index::from).collect();
// quote! { #( self.#indices ),* }     ->   self.0, self.1, self.2

An interpolated usize would give 0usize; syn::Index gives 0, the correct form after a dot.

use syn::{Type, TypePath};

fn is_option(ty: &Type) -> bool {
    matches!(ty, Type::Path(TypePath { path, .. })
        if path.segments.last().is_some_and(|s| s.ident == "Option"))
}

A macro only sees the syntax: it knows that a field is written Option<String>, not what that type really is. An alias (type MaybeName = Option<String>) or a full path (std::option::Option) are only recognized if you handle them explicitly.

let name = &ast.ident;           // Ident
let ty: syn::Type = syn::parse_quote!(u32);
let n = 42usize;
let text = "hello";

let code = quote! {
    const N: usize = #n;         // 42usize
    fn f() -> #ty { 0 }          // fn f() -> u32
    fn g() -> &'static str { #text }    // "hello" (a string literal)
    impl #name {}
};

Any type that implements ToTokens can be interpolated: Ident, Type, Expr, TokenStream, integers, &str, bool...

let names = vec![quote!(a), quote!(b), quote!(c)];
let types = vec![quote!(i32), quote!(String), quote!(bool)];

quote! {
    struct S { #( #names: #types ),* }        // a: i32, b: String, c: bool
};

quote! {
    #( println!("{}", stringify!(#names)); )*   // one line per element, no separator
};

#( ... ),* repeats with a separator, #( ... )* without. All the variables in the same repetition must have the same length.

use quote::format_ident;

let field = format_ident!("email");
let getter = format_ident!("get_{}", field);        // get_email
let setter = format_ident!("set_{}", field);        // set_email

quote! {
    pub fn #getter(&self) -> &str { &self.#field }
    pub fn #setter(&mut self, v: String) { self.#field = v; }
};

This is what macro_rules! cannot do.

let mut methods = proc_macro2::TokenStream::new();
for c in fields.named.iter() {
    let name = c.ident.as_ref().unwrap();
    let ty = &c.ty;
    methods.extend(quote! {
        pub fn #name(&self) -> &#ty { &self.#name }
    });
}

quote! {
    impl #type_name { #methods }
};

#[derive(Describe)]
struct Wrapper<T> { value: T }

// An impl written as `impl #name { ... }` gives `impl Wrapper { ... }`: ERROR, Wrapper expects a T

let (impl_generics, ty_generics, where_clause) = ast.generics.split_for_impl();

quote! {
    impl #impl_generics #name #ty_generics #where_clause {
        // ...
    }
}
// impl<T> Wrapper<T> { ... }
// impl<'a, T: Clone, const N: usize> S<'a, T, N> where T: Debug { ... }

split_for_impl correctly separates lifetimes, type parameters, const generics and the where clause.

use syn::{Data, Fields};

#[proc_macro_derive(VariantName)]
pub fn derive_variant_name(input: TokenStream) -> TokenStream {
    let ast = parse_macro_input!(input as DeriveInput);
    let name = &ast.ident;

    let Data::Enum(e) = &ast.data else {
        return syn::Error::new_spanned(name, "VariantName only applies to enums")
            .to_compile_error()
            .into();
    };

    let arms = e.variants.iter().map(|v| {
        let variant = &v.ident;
        let text = variant.to_string();
        let pattern = match &v.fields {
            Fields::Unit => quote!(Self::#variant),
            Fields::Unnamed(_) => quote!(Self::#variant(..)),
            Fields::Named(_) => quote!(Self::#variant { .. }),
        };
        quote!(#pattern => #text)
    });

    let (ig, tg, wc) = ast.generics.split_for_impl();
    quote! {
        impl #ig #name #tg #wc {
            pub fn variant_name(&self) -> &'static str {
                match self { #(#arms),* }
            }
        }
    }
    .into()
}

#[derive(VariantName)]
enum Message { Quit, Write(String), Move { x: i32, y: i32 } }

Message::Write("a".into()).variant_name();    // "Write"

#[proc_macro_derive(Describe, attributes(describe))]
pub fn derive_describe(input: TokenStream) -> TokenStream { /* ... */ }

attributes(describe) lets the user write #[describe(...)] on the type and on its fields. Without this declaration, the compiler would reject the unknown attribute.

#[derive(Describe)]
#[describe(name = "Account")]
struct User {
    name: String,
    #[describe(hidden)]
    password: String,
    #[describe(rename = "years")]
    age: u32,
}

struct FieldOptions {
    hidden: bool,
    rename: Option<String>,
}

fn read_options(field: &syn::Field) -> syn::Result<FieldOptions> {
    let mut opts = FieldOptions { hidden: false, rename: None };
    for attr in &field.attrs {
        if !attr.path().is_ident("describe") {
            continue;                                  // another attribute (serde, doc...): ignored
        }
        attr.parse_nested_meta(|meta| {
            if meta.path.is_ident("hidden") {
                opts.hidden = true;                    // #[describe(hidden)]
                Ok(())
            } else if meta.path.is_ident("rename") {
                let value: syn::LitStr = meta.value()?.parse()?;   // #[describe(rename = "...")]
                opts.rename = Some(value.value());
                Ok(())
            } else {
                Err(meta.error("unknown option: expected `hidden` or `rename = \"...\"`"))
            }
        })?;
    }
    Ok(opts)
}

let mut lines = Vec::new();
for c in fields.named.iter() {
    let opts = match read_options(c) {
        Ok(o) => o,
        Err(e) => return e.to_compile_error().into(),
    };
    if opts.hidden {
        continue;                                      // the password never appears
    }
    let ident = c.ident.as_ref().unwrap();
    let label = opts.rename.unwrap_or_else(|| ident.to_string());
    lines.push(quote! {
        parts.push(format!("{} = {:?}", #label, self.#ident));
    });
}

A hidden attribute that removes a secret field from the output is a good example of use: it is the kind of mistake an ordinary #[derive(Debug)] cannot avoid.

// Bad: the user sees "proc-macro derive panicked" with no position
let fields = match &ast.data { Data::Struct(s) => &s.fields, _ => panic!("struct expected") };

// Good: a compile error, underlined in the right place
let Data::Struct(s) = &ast.data else {
    return syn::Error::new_spanned(&ast.ident, "struct expected").to_compile_error().into();
};

let mut errors: Option<syn::Error> = None;
for c in fields.named.iter() {
    if let Err(e) = read_options(c) {
        match &mut errors {
            Some(all) => all.combine(e),              // accumulate
            None => errors = Some(e),
        }
    }
}
if let Some(e) = errors {
    return e.to_compile_error().into();               // all the errors in one compilation
}

#[proc_macro_derive(Describe, attributes(describe))]
pub fn derive_describe(input: TokenStream) -> TokenStream {
    let ast = parse_macro_input!(input as DeriveInput);
    generate(&ast).unwrap_or_else(|e| e.to_compile_error()).into()
}

fn generate(ast: &DeriveInput) -> syn::Result<proc_macro2::TokenStream> {
    // ... ? everywhere ...
    Ok(quote! {})
}

The entry point only converts; all the work is in a function that uses ?.

// Bad: depends on the user's imports
quote! { impl Display for #name { fn fmt(&self, f: &mut Formatter) -> Result { .. } } };

// Good: absolute paths
quote! {
    impl ::std::fmt::Display for #name {
        fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> ::std::fmt::Result { /* .. */ Ok(()) }
    }
};

// my_app/tests/describe.rs (or in the crate that re-exports the macro)
use describe_macros::Describe;

#[derive(Describe)]
struct Point { x: i32, y: i32 }

#[test]
fn describes_the_fields() {
    assert_eq!(Point { x: 1, y: 2 }.describe(), "Point { x = 1, y = 2 }");
}

A proc-macro crate cannot use its own macros in its unit tests: you test them from another crate (integration tests of the library that re-exports it, or an examples folder).

// tests/errors.rs
#[test]
fn compile_errors() {
    let t = trybuild::TestCases::new();
    t.compile_fail("tests/ui/*.rs");      // each file must fail with the message in the neighboring .stderr
    t.pass("tests/ok/*.rs");
}

trybuild compiles small files and compares the error message obtained to an expected .stderr file: this checks that the user gets the right message, in the right place.

my_lib/            ← the library: types, traits, functions; re-exports the macros
my_lib_macros/     ← proc-macro = true: only the macros
my_lib_dsl/        ← (optional) the parser, in a normal crate, reusable elsewhere

// my_lib/src/lib.rs
pub trait Describe { fn describe(&self) -> String; }   // the trait lives here
pub use my_lib_macros::Describe;                       // the derive macro of the same name too

runique/runique_dsl/   ← parser of the model!{} / extend!{} DSL -> tree (normal crate)
runique/derive_form/   ← proc-macro = true: model!{}, extend!{}, #[form]
runique/               ← the framework; re-exports the macros (use runique::prelude::*)

# runique/derive_form/Cargo.toml (excerpt)
[lib]
proc-macro = true

[dependencies]
runique_dsl.workspace = true
syn = { workspace = true, features = ["extra-traits"] }
quote = "1"
proc-macro2 = "1"

// 1. By hand: nothing to learn, but repetitive
struct A { name: String, age: u32 }
impl A {
    fn name(&self) -> &String { &self.name }
    fn age(&self) -> &u32 { &self.age }
}

// 2. macro_rules!: you must repeat the list of fields at the call
macro_rules! getters {
    ($t:ident { $($c:ident : $ty:ty),* }) => {
        impl $t { $( fn $c(&self) -> &$ty { &self.$c } )* }
    };
}
struct B { name: String, age: u32 }
getters!(B { name: String, age: u32 });

// 3. Derive: the macro reads the fields itself
// #[derive(Getters)]
// struct C { name: String, age: u32 }

[lib]
proc-macro = true
[dependencies]
syn = { version = "2", features = ["full"] }
quote = "1"
proc-macro2 = "1"

#[proc_macro_derive(Name, attributes(name))]
pub fn f(input: TokenStream) -> TokenStream {
    let ast = parse_macro_input!(input as DeriveInput);
    let name = &ast.ident;
    let (ig, tg, wc) = ast.generics.split_for_impl();
    quote! { impl #ig ::my_lib::Trait for #name #tg #wc { .. } }.into()
}

Data::Struct(s) / Data::Enum(e)       Fields::Named / Unnamed / Unit
#var   #( #a: #b ),*   #( .. )*        format_ident!("get_{}", x)   syn::Index::from(i)
attr.path().is_ident("name")          attr.parse_nested_meta(|meta| ..)
syn::Error::new_spanned(&node, "..").to_compile_error()      e.combine(other)