skip to content

In Rust, what does a `#[proc_macro_attribute]` function receive for `#[route(GET, "/users")] fn list_users()`, and what replaces that function?

level: middleimportance: should knowfreq 48%

answer

  1. two parameters, not one
  2. arguments without the outer delimiters
  3. the output replaces the item
  4. re-emit the item yourself

basics

~10 s

It receives two TokenStreams: the attribute's arguments (GET, "/users") and the whole decorated item with its later attributes. Whatever it returns replaces the item, so the macro must re-emit the function to keep it.

solid answer

~40 s

An attribute macro is a `pub fn(TokenStream, TokenStream) -> TokenStream` marked `#[proc_macro_attribute]` at the root of a `proc-macro` crate. The first stream is what sits inside the attribute's delimiters, without them: `GET, "/users"` here, and empty for a bare `#[route]`. The second is the item itself, `fn list_users() -> String { ... }`, including any attributes and doc comments written below `#[route]`. The returned stream **replaces** the item with zero or more items, unlike a derive, whose output is appended after the untouched type. So a `#[route]` that emits only a registration function deletes the handler, and every use of `list_users` fails with `E0425`. Since Rust 1.99 the attribute may also sit on an outlined `mod handlers;`, and the macro then sees only that declaration, never the file's contents.

code

rust · 30 lines
rust
use proc_macro::TokenStream;
use quote::{format_ident, quote};
use syn::parse::{Parse, ParseStream};
use syn::{Ident, ItemFn, LitStr, Token, parse_macro_input};

struct RouteArgs { method: Ident, path: LitStr }

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

#[proc_macro_attribute]
pub fn route(attr: TokenStream, item: TokenStream) -> TokenStream {
    let args = parse_macro_input!(attr as RouteArgs);
    let handler = parse_macro_input!(item as ItemFn);
    let name = &handler.sig.ident;
    let reg = format_ident!("{}_route", name);
    let (method, path) = (args.method.to_string(), &args.path);
    quote! {
        #handler // drop this line and `list_users` disappears
        pub fn #reg() -> (&'static str, &'static str, fn() -> String) {
            (#method, #path, #name)
        }
    }
    .into()
}

go deeper

for a junior

Recall that an attribute macro is a function taking two token streams, the arguments and the item, and that what it returns is what the compiler keeps.

for a middle

Explain which tokens land in each parameter, why the item vanishes if it is not re-emitted, and how that differs from a derive's appended output.

for a senior

Show you can diagnose a missing-item E0425 back to the macro, preserve the item's attributes when rebuilding it, and use absolute paths because the output is unhygienic.

for a principal

Weigh rewriting an item, which hides code from readers, against appending beside it, and set a rule that macros keep the user's item visible wherever possible.

## The signature rustc requires A **procedural macro** is ordinary Rust code that the compiler runs while it compiles another crate. It must live in a crate whose type is `proc-macro` (in Cargo, `proc-macro = true` under `[lib]`), and that crate may export nothing except its macros. An **attribute macro** is one of three kinds. The Reference requires the function to be: - `pub`, at the root of the proc-macro crate, with the Rust ABI and no other qualifiers; - marked `#[proc_macro_attribute]`, which defines an attribute of the same name in the macro namespace; - of type `fn(TokenStream, TokenStream) -> TokenStream`, with `TokenStream` from the compiler-provided `proc_macro` crate. A **token stream** is a sequence of token trees: identifiers, punctuation, literals and delimited groups. It is not a typed syntax tree, so most macros parse it with **syn** and build their output with **quote**. ## The first stream: the attribute's arguments The first parameter holds the tokens after the attribute's name, **without the outer delimiters**. For `#[route(GET, "/users")]` it is `GET, "/users"`. For `#[route]` or `#[route()]` it is empty. The name `route` itself is never part of it. Parentheses, brackets and braces all work as the outer delimiter, and the content can be any tokens, so a macro can define its own small argument grammar. In the example below, a `syn::parse::Parse` impl reads an identifier, a comma and a string literal. ## The second stream: the item The second parameter is the rest of the item: the function signature and body, plus any attributes written **after** `#[route]`. Doc comments arrive as `#[doc = "..."]` attributes. A macro that rebuilds the function from scratch must carry those attributes over, or they are lost. ## The output replaces the item This is the rule that catches people: **the decorated item is replaced by the zero or more items in the returned stream**. Each kind of procedural macro handles its output differently: | Kind | Input | What happens to the output | |---|---|---| | `#[proc_macro_derive]` | the struct, enum or union | appended after the unchanged item | | `#[proc_macro_attribute]` | arguments and the item | replaces the item | | `#[proc_macro]` | tokens inside `name!( ... )` | replaces the whole invocation | So the `#[route]` macro in the example re-emits `#handler` and then adds `list_users_route`. If you delete the `#handler` line, the function no longer exists. The generated `(#method, #path, #name)` still names it, and rustc reports `error[E0425]: cannot find value `list_users` in this scope`, pointing at the identifier in the user's source, because that token's span came from there. The same rule covers the error path. Returning an empty stream is legal and deletes the item. Returning only a `compile_error!` replaces the item with that error, which is what `parse_macro_input!` does when the arguments do not parse. Replacement is also what makes attribute macros useful. They can wrap a body in timing code, rewrite the signature, rename the function and register it, or delete the item entirely when that is the point. ## Where it may appear 1. On **items** (functions, structs, `impl` blocks, modules and so on), on items inside `extern` blocks, and on associated items inside `impl` blocks and trait definitions. 2. Only as an **outer** attribute: `#![route]` is rejected as an inner attribute. 3. On modules. An inline `mod handlers { ... }` passes its whole body. **Since Rust 1.99**, `#[my_macro] mod handlers;` (an outlined module whose code is in another file) is stable, and an outlined `mod` inside a macro's input is accepted too. In both cases the macro sees **only the declaration tokens**, `mod handlers;`, and the file is not read into its input. 4. **Never in the crate that defines it.** A procedural macro can only be used from another crate, which is why its tests go in the crate's `tests/` directory or in a separate crate. ## Mistakes to avoid - Treating the first stream as if it contained `route(...)`. - Parsing the item as `syn::ItemFn` without syn's `full` feature, which is the only feature that provides that type. - Returning only the new code and losing the original item. - Assuming the output is appended, as a derive's is. - Forgetting that procedural-macro output is **unhygienic**: it behaves as if written at the call site, so generated code should name items by absolute paths such as `::std::string::String`.

  • If `#[route]` sits above `#[inline]` and a `///` doc comment, does the macro see them?
    Yes. Attributes written below `#[route]` are part of the item stream, and doc comments arrive as `#[doc = "..."]` attributes. Re-emitting the parsed `syn::ItemFn` keeps them, because syn stores them in its `attrs` field. A macro that builds a new function from pieces has to copy `attrs` across, or the documentation and `#[inline]` silently disappear.
  • Why can't the crate that defines `route` put `#[route]` on its own functions?
    The Reference says a procedural macro can only be used from a crate other than the one that defines it. The proc-macro crate is compiled into a library that rustc loads while compiling other crates, and it may export only its macros. Integration tests in its `tests/` directory are separate crates, so they can use it, and a framework usually re-exports the macro from its runtime crate.

  • An attribute macro receives only the decorated item, not the attribute's arguments
  • The first TokenStream includes the attribute name and its parentheses
  • An attribute macro's output is appended after the function, as a derive's is
  • Returning only the generated code leaves the original function in place
  • On `mod handlers;` the macro receives the contents of the module's file

Assumes Rust 1.99 on edition 2024; 1.99 stabilised attribute macros on outlined mod foo; declarations, which pass only the declaration tokens.