Procedural macros — Attribute

use proc_macro::TokenStream;

#[proc_macro_attribute]
pub fn my_attribute(attr: TokenStream, item: TokenStream) -> TokenStream {
    // attr: what is between the parentheses of #[my_attribute(...)]
    // item: the annotated item, complete
    item                // returning item unchanged = the attribute changes nothing
}

#[my_attribute(level = "debug", repeats = 3)]
fn compute() {}
// attr = level = "debug", repeats = 3
// item = fn compute() {}

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

#[proc_macro_attribute]
pub fn timer(_attr: TokenStream, item: TokenStream) -> TokenStream {
    let function = parse_macro_input!(item as ItemFn);

    let attrs = &function.attrs;          // #[inline], ///doc... : to keep
    let vis = &function.vis;
    let sig = &function.sig;              // name, parameters, return type, async, generics
    let body = &function.block;
    let name = sig.ident.to_string();

    quote! {
        #(#attrs)*
        #vis #sig {
            let __start = ::std::time::Instant::now();
            let __result = (|| #body)();
            ::std::eprintln!("{}: {:?}", #name, __start.elapsed());
            __result
        }
    }
    .into()
}

#[timer]
fn compute(n: u64) -> u64 {
    (0..n).sum()
}

fn main() {
    compute(1_000_000);        // compute: 1.2ms
}

#[proc_macro_attribute]
pub fn no_argument(attr: TokenStream, item: TokenStream) -> TokenStream {
    if !attr.is_empty() {
        return syn::Error::new(proc_macro2::Span::call_site(), "#[no_argument] takes no argument")
            .to_compile_error()
            .into();
    }
    item
}

use syn::{parse::Parser, punctuated::Punctuated, Expr, Lit, Meta, Token};

struct Options { level: String, repeats: u32, quiet: bool }

fn read_options(attr: TokenStream) -> syn::Result<Options> {
    let mut o = Options { level: "info".into(), repeats: 1, quiet: false };
    let list = Punctuated::<Meta, Token![,]>::parse_terminated.parse(attr)?;
    for meta in list {
        match meta {
            Meta::NameValue(nv) if nv.path.is_ident("level") => {
                let Expr::Lit(e) = &nv.value else {
                    return Err(syn::Error::new_spanned(&nv.value, "string expected"));
                };
                let Lit::Str(s) = &e.lit else {
                    return Err(syn::Error::new_spanned(&e.lit, "string expected"));
                };
                o.level = s.value();
            }
            Meta::NameValue(nv) if nv.path.is_ident("repeats") => {
                let Expr::Lit(syn::ExprLit { lit: Lit::Int(n), .. }) = &nv.value else {
                    return Err(syn::Error::new_spanned(&nv.value, "integer expected"));
                };
                o.repeats = n.base10_parse()?;
            }
            Meta::Path(p) if p.is_ident("quiet") => o.quiet = true,
            other => return Err(syn::Error::new_spanned(other, "unknown option")),
        }
    }
    Ok(o)
}

Meta covers the three forms: path (flag), path = value, path(...) (nested list).

use syn::meta;

fn read_options_v2(attr: TokenStream) -> syn::Result<Options> {
    let mut o = Options { level: "info".into(), repeats: 1, quiet: false };
    let reader = meta::parser(|m| {
        if m.path.is_ident("level") {
            o.level = m.value()?.parse::<syn::LitStr>()?.value();
        } else if m.path.is_ident("repeats") {
            o.repeats = m.value()?.parse::<syn::LitInt>()?.base10_parse()?;
        } else if m.path.is_ident("quiet") {
            o.quiet = true;
        } else {
            return Err(m.error("unknown option"));
        }
        Ok(())
    });
    syn::parse::Parser::parse(reader, attr)?;
    Ok(o)
}

Shorter, and with well-placed error messages. This is the form recommended by syn 2.

pub struct ItemFn {
    pub attrs: Vec<Attribute>,     // remaining attributes (including docs)
    pub vis: Visibility,
    pub sig: Signature,            // const, async, unsafe, fn, name, generics, parameters, return type
    pub block: Box<Block>,         // the body
}

let sig = &function.sig;
sig.ident;                 // name
sig.asyncness.is_some();   // async?
sig.inputs;                // parameters: FnArg::Receiver (self) or FnArg::Typed (name: Type)
sig.output;                // ReturnType::Default (()) or ReturnType::Type(_, ty)
sig.generics;

#[proc_macro_attribute]
pub fn trace(_attr: TokenStream, item: TokenStream) -> TokenStream {
    let mut f = parse_macro_input!(item as ItemFn);
    let name = f.sig.ident.to_string();
    let body = &f.block;

    // Replace the body with a new block that contains the old one
    let new_block: syn::Block = syn::parse_quote!({
        ::std::eprintln!("entering {}", #name);
        #body
    });
    f.block = Box::new(new_block);

    quote!(#f).into()          // ItemFn is interpolated as is
}

Modifying the tree (f.block = ...) and then interpolating all of it automatically keeps the attributes, visibility and signature.

#[proc_macro_attribute]
pub fn timer_async(_attr: TokenStream, item: TokenStream) -> TokenStream {
    let mut f = parse_macro_input!(item as ItemFn);
    let name = f.sig.ident.to_string();
    let body = &f.block;

    let new_block: syn::Block = if f.sig.asyncness.is_some() {
        syn::parse_quote!({
            let __start = ::std::time::Instant::now();
            let __r = async move #body.await;          // an async block keeps .await and ?
            ::std::eprintln!("{}: {:?}", #name, __start.elapsed());
            __r
        })
    } else {
        syn::parse_quote!({
            let __start = ::std::time::Instant::now();
            let __r = (|| #body)();
            ::std::eprintln!("{}: {:?}", #name, __start.elapsed());
            __r
        })
    };
    f.block = Box::new(new_block);
    quote!(#f).into()
}

use syn::{FnArg, Pat};

let names: Vec<_> = f.sig.inputs.iter().filter_map(|a| match a {
    FnArg::Typed(pt) => match &*pt.pat {
        Pat::Ident(i) => Some(i.ident.clone()),
        _ => None,                                 // destructured pattern: no simple name
    },
    FnArg::Receiver(_) => None,                    // self
}).collect();

// quote! { ::std::eprintln!(concat!(#(stringify!(#names), " = {:?} "),*), #(#names),*); }

let f = match syn::parse::<ItemFn>(item.clone()) {
    Ok(f) => f,
    Err(_) => {
        return syn::Error::new(proc_macro2::Span::call_site(), "#[timer] applies to a function")
            .to_compile_error()
            .into();
    }
};

use syn::{parse_macro_input, parse_quote, Fields, ItemStruct};

#[proc_macro_attribute]
pub fn timestamped(_attr: TokenStream, item: TokenStream) -> TokenStream {
    let mut s = parse_macro_input!(item as ItemStruct);

    if let Fields::Named(fields) = &mut s.fields {
        fields.named.push(parse_quote! { pub created_at: ::std::time::SystemTime });
        fields.named.push(parse_quote! { pub updated_at: ::std::time::SystemTime });
    } else {
        return syn::Error::new_spanned(&s.ident, "#[timestamped] requires named fields")
            .to_compile_error()
            .into();
    }

    let name = &s.ident;
    quote! {
        #s
        impl #name {
            pub fn touch(&mut self) { self.updated_at = ::std::time::SystemTime::now(); }
        }
    }
    .into()
}

#[timestamped]
struct Article { title: String }

// becomes:
// struct Article { title: String, pub created_at: SystemTime, pub updated_at: SystemTime }
// impl Article { pub fn touch(&mut self) { .. } }

A derive could not add a field: this is the case where the attribute is needed. The price: the user sees struct Article { title } but must build Article { title, created_at, updated_at }. A macro that adds fields must therefore provide a constructor and document it.

#[proc_macro_attribute]
pub fn make_form(_attr: TokenStream, item: TokenStream) -> TokenStream {
    let s = parse_macro_input!(item as ItemStruct);
    let vis = &s.vis;
    let name = &s.ident;
    let attrs = &s.attrs;

    if !matches!(s.fields, Fields::Unit) {
        return syn::Error::new_spanned(&s.fields, "write `struct Name;`: the fields are generated")
            .to_compile_error()
            .into();
    }

    quote! {
        #(#attrs)*
        #vis struct #name {
            pub data: ::std::collections::HashMap<String, String>,
            pub errors: Vec<String>,
        }
    }
    .into()
}

The user writes #[make_form] pub struct Contact; and gets a complete struct. This is the model of #[form] in Runique (section 10).

let messages = columns.iter().map(|c| {
    let text = c.to_string();
    let msg = format!("`{text}` is the primary key: it cannot be a form field");
    quote_spanned! { c.span()=>
        assert!(!::my_lib::same_name(#schema::PRIMARY_KEY, #text), #msg);
    }
});

In a const block, a failing assert! is a compile error with this message. The function called must be a const fn.

#[a]          // runs first, and receives the item WITH #[b] and #[derive] in its attributes
#[b]          // runs next, on what #[a] produced
#[derive(Debug)]
struct S;

// What #[tokio::main] does, simplified
#[tokio::main]
async fn main() { /* ... */ }

// becomes
fn main() {
    tokio::runtime::Builder::new_multi_thread()
        .enable_all()
        .build()
        .unwrap()
        .block_on(async { /* ... */ })
}

#[form(schema = crate::entities::contact, fields = [email, message])]
pub struct ContactForm;

// runique/derive_form/src/schema_form.rs (excerpt)
enum Columns {
    Only(Vec<Ident>),     // fields = [a, b]
    All,                  // fields = All
    Except(Vec<Ident>),   // exclude = [a, b]
}

struct FormAttrs {
    schema: Path,
    columns: Columns,
}

impl Parse for FormAttrs {
    fn parse(input: ParseStream) -> syn::Result<Self> {
        // key = value loop: schema, fields, exclude
        // fields and exclude together -> error; schema missing -> error;
        // neither fields nor exclude -> "incomplete declaration" error
        // ...
    }
}

This is the technique of section 4.4. The design choice: fields or exclude is required. A form that took all columns without saying so would also take any column added to the model later (an is_admin field, for example), a classic mass assignment flaw. fields = All is still possible, but you have to write it.

// runique/derive_form/src/schema_form.rs (excerpt)
// Each name a column of the entity, checked by the compiler: the error
// lands on the name, not on a panic the first time the form is used.
let checks = fields.iter().chain(exclude.iter()).flatten().map(|field| {
    let mut variant = crate::model::utils::ident_pascal(field);
    variant.set_span(field.span());
    quote_spanned! { field.span()=> let _ = #schema_path::Column::#variant; }
});

// The key is the database's to set: listed in `fields`, refused here.
let key_checks = fields.iter().flatten().map(|field| {
    let name = field.to_string();
    let message = format!(
        "#[form]: `{name}` is the primary key; the database sets it, it is never a form field"
    );
    quote_spanned! { field.span()=>
        assert!(!::runique::forms::__same_name(#schema_path::PRIMARY_KEY, #name), #message);
    }
});

let column_check = quote! { const _: () = { #(#checks)* #(#key_checks)* }; };

This is exactly section 7:

• each field name becomes Column::PascalName: a typo (emial) is a compile error underlined on emial;
• listing the primary key in fields is rejected at compile time by a const assertion, with a message that explains why;
• everything is in a const _: () = { ... };: nothing is executed at startup.

// 1. By hand: explicit, but to repeat in every function
fn a() { eprintln!("entering a"); /* ... */ }

// 2. macro_rules!: you must wrap the whole function
macro_rules! traced {
    (fn $name:ident() $body:block) => {
        fn $name() { eprintln!("entering {}", stringify!($name)); $body }
    };
}
traced!(fn b() { /* ... */ });

// 3. Attribute: one line above an ordinary function
// #[trace]
// fn c() { /* ... */ }

#[proc_macro_attribute]
pub fn name(attr: TokenStream, item: TokenStream) -> TokenStream {
    let args = parse_macro_input!(attr as MyArgs);        // impl Parse for MyArgs
    let mut f = parse_macro_input!(item as ItemFn);       // or ItemStruct, Item...
    f.block = Box::new(parse_quote!({ /* before */ #body }));
    quote!(#f).into()
}

Punctuated::<Meta, Token![,]>::parse_terminated.parse(attr)
syn::meta::parser(|m| { m.path.is_ident("x"); m.value()?.parse::<LitStr>()?; Ok(()) })
bracketed!(content in input)   content.parse_terminated(Ident::parse, Token![,])
quote_spanned! { ident.span()=> let _ = #path::#ident; }
const _: () = { /* checks */ };