Procedural macros — Function-like

use proc_macro::TokenStream;

#[proc_macro]
pub fn my_macro(input: TokenStream) -> TokenStream {
    // input: everything between the delimiters of my_macro!( ... ) / [ ... ] / { ... }
    input
}

my_macro!(a + b);
my_macro! { config { port: 8080 } }

// Target syntax example
config! {
    server {
        port: 8080,
        host: "0.0.0.0",
    }
    database {
        url: "postgres://localhost/app",
        connections: 10,
    }
}

use syn::parse::{Parse, ParseStream};
use syn::{Ident, LitInt, Token};

// port: 8080
struct Setting {
    name: Ident,
    value: LitInt,
}

impl Parse for Setting {
    fn parse(input: ParseStream) -> syn::Result<Self> {
        let name: Ident = input.parse()?;       // consumes an identifier
        input.parse::<Token![:]>()?;            // consumes ':'
        let value: LitInt = input.parse()?;     // consumes an integer
        Ok(Setting { name, value })
    }
}

Each input.parse() consumes tokens and returns a positioned error if it is not what was expected.

mod kw {
    syn::custom_keyword!(table);
    syn::custom_keyword!(fields);
}

// table: "users"
struct Table { name: syn::LitStr }

impl Parse for Table {
    fn parse(input: ParseStream) -> syn::Result<Self> {
        input.parse::<kw::table>()?;           // the word `table`, and nothing else
        input.parse::<Token![:]>()?;
        Ok(Table { name: input.parse()? })
    }
}

use syn::{LitBool, LitInt, LitStr};

enum Value {
    Text(LitStr),
    Integer(LitInt),
    Boolean(LitBool),
}

impl Parse for Value {
    fn parse(input: ParseStream) -> syn::Result<Self> {
        let l = input.lookahead1();
        if l.peek(LitStr) {
            Ok(Value::Text(input.parse()?))
        } else if l.peek(LitInt) {
            Ok(Value::Integer(input.parse()?))
        } else if l.peek(LitBool) {
            Ok(Value::Boolean(input.parse()?))
        } else {
            Err(l.error())                     // "expected string literal, integer literal or boolean literal"
        }
    }
}

lookahead1 remembers everything that was tested and builds the error message automatically.

use syn::{braced, punctuated::Punctuated};

// server { port: 8080, host: "0.0.0.0", }
struct Section {
    name: Ident,
    settings: Vec<(Ident, Value)>,
}

impl Parse for Section {
    fn parse(input: ParseStream) -> syn::Result<Self> {
        let name: Ident = input.parse()?;
        let content;
        braced!(content in input);             // everything between { } becomes a new stream
        let list = Punctuated::<Pair, Token![,]>::parse_terminated(&content)?;
        Ok(Section { name, settings: list.into_iter().map(|p| (p.name, p.value)).collect() })
    }
}

struct Pair { name: Ident, value: Value }

impl Parse for Pair {
    fn parse(input: ParseStream) -> syn::Result<Self> {
        let name = input.parse()?;
        input.parse::<Token![:]>()?;
        Ok(Pair { name, value: input.parse()? })
    }
}

struct Config { sections: Vec<Section> }

impl Parse for Config {
    fn parse(input: ParseStream) -> syn::Result<Self> {
        let mut sections = Vec::new();
        while !input.is_empty() {
            sections.push(input.parse()?);
        }
        Ok(Config { sections })
    }
}

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

#[proc_macro]
pub fn query(input: TokenStream) -> TokenStream {
    let text = parse_macro_input!(input as LitStr);
    let sql = text.value();
    let uppercase = sql.trim_start().to_uppercase();

    if !uppercase.starts_with("SELECT") {
        return syn::Error::new(text.span(), "query! only accepts SELECT")
            .to_compile_error()
            .into();
    }
    if sql.contains(';') {
        return syn::Error::new(text.span(), "a single statement, without `;`")
            .to_compile_error()
            .into();
    }

    quote!(#text).into()                      // the text, now checked
}

let q = query!("SELECT id, email FROM users WHERE id = $1");
// let r = query!("DELETE FROM users");   // compile-time ERROR, underlined on the text

#[proc_macro]
pub fn config(input: TokenStream) -> TokenStream {
    let cfg = parse_macro_input!(input as Config);

    let structs = cfg.sections.iter().map(|s| {
        let struct_name = quote::format_ident!("{}", capitalize(&s.name.to_string()));
        let fields = s.settings.iter().map(|(n, v)| {
            let ty = match v {
                Value::Text(_) => quote!(&'static str),
                Value::Integer(_) => quote!(i64),
                Value::Boolean(_) => quote!(bool),
            };
            quote!(pub #n: #ty)
        });
        let values = s.settings.iter().map(|(n, v)| {
            let lit = match v {
                Value::Text(l) => quote!(#l),
                Value::Integer(l) => quote!(#l),
                Value::Boolean(l) => quote!(#l),
            };
            quote!(#n: #lit)
        });
        quote! {
            #[derive(Debug, Clone)]
            pub struct #struct_name { #(#fields),* }
            impl #struct_name {
                pub const fn default_values() -> Self { Self { #(#values),* } }
            }
        }
    });

    quote!(#(#structs)*).into()
}

fn capitalize(s: &str) -> String {
    let mut c = s.chars();
    c.next().map(|f| f.to_uppercase().collect::<String>() + c.as_str()).unwrap_or_default()
}

config! {
    server { port: 8080, host: "0.0.0.0" }
    database { connections: 10, ssl: true }
}

const SERVER: Server = Server::default_values();     // Server { port: 8080, host: "0.0.0.0" }

// name: type [option1, option2]     the brackets are optional
struct Field {
    name: Ident,
    ty: Ident,
    options: Vec<Ident>,
}

impl Parse for Field {
    fn parse(input: ParseStream) -> syn::Result<Self> {
        let name = input.parse()?;
        input.parse::<Token![:]>()?;
        let ty = input.parse()?;
        let options = if input.peek(syn::token::Bracket) {        // brackets present?
            let content;
            syn::bracketed!(content in input);
            Punctuated::<Ident, Token![,]>::parse_terminated(&content)?.into_iter().collect()
        } else {
            Vec::new()
        };
        Ok(Field { name, ty, options })
    }
}

struct Meta { table: Option<syn::LitStr>, order: Option<syn::LitStr> }

impl Parse for Meta {
    fn parse(input: ParseStream) -> syn::Result<Self> {
        let mut m = Meta { table: None, order: None };
        while !input.is_empty() {
            let key: Ident = input.parse()?;
            input.parse::<Token![:]>()?;
            let value: syn::LitStr = input.parse()?;
            let slot = match key.to_string().as_str() {
                "table" => &mut m.table,
                "order" => &mut m.order,
                _ => return Err(syn::Error::new(key.span(), "unknown key: `table` or `order`")),
            };
            if slot.replace(value).is_some() {
                return Err(syn::Error::new(key.span(), format!("`{key}` is already defined")));
            }
            if input.peek(Token![,]) {
                input.parse::<Token![,]>()?;
            }
        }
        Ok(m)
    }
}

Option::replace returns the old value: if there was one, the key is duplicated.

#[test]
fn rejects_a_duplicate_key() {
    let r: syn::Result<Meta> = syn::parse_str(r#"table: "a", table: "b""#);
    assert!(r.is_err());
}

syn::parse_str and syn::parse2 let you test Parse like ordinary code, if the parser lives in a normal crate (section 10).

let x = my_macro!(...);       // must produce an expression
my_macro! { ... }             // in item position: can produce declarations

A macro designed for both uses only works in one of them: decide which, and document it.

// demo-app/src/entities/chapitre.rs
model! {
    Chapitre,
    table: "chapitre",
    pk: id => Pk,
    {
        cour_id:    Pk [required],
        slug:       text [required],
        title:      text [required],
        lead:       text [nullable],
        sort_order: int [required],
    },
    relations: {
        belongs_to: Cour via cour_id [cascade],
    }
}

It uses the techniques of this course: a keyword followed by : (table:, pk:, relations:), a { ... } group of fields, optional lists in brackets ([required], [cascade]), and custom keywords (via, belongs_to).

model! { ... }
   │  tokens
   ▼
runique_dsl      parses the DSL → tree (AST)          normal crate
   │
   ├──► derive_form   generates the SeaORM entity, the columns, the form   (proc-macro)
   │
   └──► runique (CLI) makemigrations: compares the tree to the schema and writes the migrations

The parser is in runique_dsl, an ordinary crate: a proc-macro crate cannot export anything other than macros, and the runique makemigrations command must read exactly the same declarations as the macro. The same impl Parse therefore serves at compile time (code generation) and in the CLI (SQL migration generation).

Another advantage: the parser can be tested like ordinary code (section 7.4). runique_dsl has property tests (proptest) that send it generated inputs: it must answer with a tree or an error, never panic.

// runique/derive_form/src/lib.rs (excerpt)
#[proc_macro]
pub fn extend(input: TokenStream) -> TokenStream {
    const FRAMEWORK_TABLES: &[&str] = &["eihwaz_users", "eihwaz_groupes"];

    let dsl = match syn::parse::<extend_schema::ExtendDsl>(input) {
        Ok(d) => d,
        Err(e) => return e.to_compile_error().into(),
    };

    if !FRAMEWORK_TABLES.contains(&dsl.table.as_str()) {
        let tables_list = FRAMEWORK_TABLES.join(", ");
        let msg = format!(
            "extend!{{}}: \"{}\" is not a known framework table. Allowed: {}",
            dsl.table, tables_list
        );
        return quote::quote! { compile_error!(#msg); }.into();
    }
    // ...
}

extend!{} adds columns to the framework tables. An unknown table is rejected at compile time, with the list of allowed tables: the typo cannot reach a migration.

// runique/derive_form/src/lib.rs (start)
#[cfg(all(not(doc), not(feature = "all-databases"), feature = "postgres", feature = "mysql"))]
compile_error!("features `postgres` and `mysql` are mutually exclusive");

The macro crate receives the same features as runique (forwarded by runique/Cargo.toml: postgres = [..., "derive_form/postgres"]). It therefore knows the database engine at compile time and applies the same exclusion rules (see cargo-dependances, section 9).

The old mechanism read the engine from .env (DB_ENGINE, DATABASE_URL) during compilation, with exactly the flaws of section 9.1: a modified .env did not trigger a recompilation, and a forgotten file could point to a different engine than the one actually compiled. It remains as a fallback, only for projects whose Cargo.toml does not forward the feature yet (runique/derive_form/src/model/utils/db_engine.rs); the feature itself cannot diverge from what is compiled.

#[proc_macro]
pub fn name(input: TokenStream) -> TokenStream {
    let dsl = parse_macro_input!(input as MyDsl);   // impl Parse for MyDsl
    generate(&dsl).unwrap_or_else(|e| e.to_compile_error()).into()
}

input.parse::<Ident>()?        input.parse::<Token![:]>()?      input.parse::<LitStr>()?
syn::custom_keyword!(table);   input.parse::<kw::table>()?
input.peek(Token![,])          input.peek(syn::token::Bracket)  input.is_empty()
let l = input.lookahead1(); if l.peek(LitStr) { .. } else { Err(l.error()) }
let c; braced!(c in input);    bracketed!   parenthesized!
Punctuated::<T, Token![,]>::parse_terminated(&c)?
syn::Error::new(lit.span(), "..")   syn::parse_str::<T>("..")   format_ident!("{}", x)