The macros discussed above are declarative macros. They are declarative in the way that they are written as part of your code in a fairly high level way. You define them with their own keywords, which is macro-rules! (which is in itself a macro) in Rust. These types of macros always look like functions with an extra exclamation mark at the end.

You will often see declarative macros referred to as "hygienic" in the Rust reference guides and documentation. What does it mean? In essence it means many of the same things as for the Lisp macros above. Macros have their own evaluation context, meaning that there is no way of using variables outside the macro declaration (i,e its inputs and internal structure). Variables don't bleed into the macro from its surroundings to shadow internal ones. This isn't as easy to show, as it is simply internal markers in the Rust compiler handling it. The Rust reference material calls this color-coding.

The inputs are also evaluated as their own unit. Let us do a quick example of that in C:

#define ONE_TENTH_OF(X) X/10.0

// usage:
ONE_TENTH_OF(1 + 1);

// should evaluate to 2/10, but due to C being text replacement:
1 + 1/10
// X=1+1 is inserted verbatim

In Rust, it looks like:

macro_rules! one_tenth_of {
    ($x:expr) => ($x / 10);
}

// usage:
one_tenth_of(1 + 1);

// in essence becomes:
(1 + 1) / 10;
// due to the input being evaluated in its own context

(don't worry the macro looks a bit foreign here, we will discuss them more in detail in the next section!)

Stupid example to show a point. You would probably create a function instead 99 % of the time…

If you want more details, the first edition of the Rust Programming Language book (available online for free) has discussions and comparisons with C.

In addition to declarative macros, we also have procedural macros in Rust. The main difference is that procedural macros must be in their own crates (aka Rust libraries) with a specified key turned on. You write them as functions, but they run during compilation time. You can think of them almost like a compiler plugin, with the difference being that it isn't called until it's used. They can do all sorts of effects, as almost arbitrary new code can be generated. Why are they used then?

• More complex code generation not possible with declarative macros. Rare, but it does happen.
• Sometimes, we want to create new derive attribute inputs. (attributes are almost like markers or annotations in other languages). You have probably been using #[derive(Debug)] on your structs to make it possible to print them to the console (or a log file). Debug an example of a derive macro. Derive macros reads the struct/enum and produces an implementation of a trait. In the case of Debug, it generates an impl-block with an implementation of the fmt function.
• Our own attributes. Maybe you want to create your own Spring (or other web framework) variant in Rust (like this project)? You may just want to mark your functions with the HTTP idiom (e.g, get, post, put etc.) you want, and let them behave as handler functions for a specific path and operation. Then your #[get("/path")] and similar attributes will need to be created as procedural macros. That library seems to link these functions to routes in the Axum web framework, though that is just my educated guess.

I will admit that I rarely write this type of macros. As you might have guessed, they are a bit more complicated then declarative macros. The Rust reference guide has a good section on them. I might make an article on them when I have experimented more with them.

The rest of this article will talk about declarative macros.

We have already gotten a teaser for declarative macros above, but let's look at them in detail now.

In essence, macros take the form:

macro_rules! macro_name {
    // rule: pattern -> rule-body
    // (++ more rules if needed ++)
}

Patterns consist of what we want the syntax to look like. To define types of inputs, we use something called meta-variables. I rarely use all the different types of metavariables, so I understand that a full list can be confusing to beginners. Let us start with a smaller table of them that I find the most useful:

A more complete list can be found in the Macros by example section in the Rust reference guide.

Some of you may be thinking: "Why do we need anything else than expr?" The main reason is that we want to discriminate on the type of input our macro takes. expr is quite all-encompassing to many different types of expressions, and also limits the patterns we can make. How will the compiler know how to match the rest of our pattern if we start with an expr type? The compiler can't read your mind, so you have to tell it what your macro needs. An expression can be many things, so the expressions need to be irrefutable for the compiler to understand them. You can work around the issue above by introducing parentheses around the expression.

Our own if-style statement: when To make a simple example, we will start by defining our own if-style statement. We want to test if an expression is true, and evaluate a block if it is:

macro_rules! when {
    (($cond:expr) $do:block) => {
	if $cond {
	    $do
	}
    };
}

// usage:
when!( (myval == 1) {
    println!("Hello there");
});

Pretty neat! Even if it uses if under the hood, we have now extended the language with our own little extension!

Like we discussed above, we need parentheses around the cond variable for it to work. What happens if we remove them? First of all, the compiler won't know where our expression ends! Let's see what it says:

error: `$cond:expr` is followed by `$r#do:block`, which is not allowed for `expr` fragments
 --> src/main.rs:2:17
  |
2 |     ($cond:expr $do:block) => {
  |                 ^^^^^^^^^ not allowed after `expr` fragments
  |
  = note: allowed there are: `=>`, `,` or `;`

What about arbitrary amount of inputs? In the C macros above, I said that a major flaw was that they didn't allow processing of arbitrary amount of arguments. (well, technically do they, but the processing they can do is VERY limited). Our last Rust example was very basic, so let us now create our own set'ish (or deduplicated vector) implementation! We are referring to creating a vector without duplications here. How would we go about doing just that? Rust gives us a set of patterns for matching repetitions:

To make our deduped_vec macro interesting, we will allow for optional commas between elements. How would such a code look?

macro_rules! deduped_vec {
    // single element to show that we can have several rules!
    ($elem:expr) => {{
	let mut myvec = Vec::new();
	myvec.push($elem);
	myvec
    }};

    // multiple elements
    ($($elem:expr $(,)?)*) => {{
	let mut myvec = Vec::new();

	$(
	    myvec.push($elem);
	)*

	myvec.sort();
	myvec.dedup();
	myvec
    }};
}


// usage with no elements:
// (we still have to give the type, as the Rust compiler can't infer a type if we give it nothing to work with...)
let setish: Vec<u32> = deduped_vec!();

// usage with multiple elements:
let setish = deduped_vec!(1, 2, 2 1, 3 1 + 1);
println!("Our deduped vec: {:?}", setish);
// prints:
// Our deduped vec: [1, 2, 3]

You will notice that we can have several possible match patterns in a macro! Pretty neat! We don't need to dedup or sort if we only have one element.

But wait… What about the extra curly brackets around our code this time? Would that just not be mentioned? No, I will talk about it now. Don't worry! It simply says that the macro returns a code block. Earlier we introduced simple expressions or statements, but not we return a block. Without it we couldn't write the code block we see above. It is just that simple. Might seem unnecessary to some, but makes sense when you think more about it (or get Stockholm syndrome from working too much with the language).

Let' personalize the syntax a bit! To show more of the power of macros, let's make a more personal syntax! Screw everyone else who reads our code, right? We want it OUR way! (Yeah, I'm trying to be funny here. Not always a good idea to make super weird syntax unless if you want others to read your code though). In this example we will make our own syntax for defining variables local to a block of code. Almost like let in Lisps where the variables are only valid within the let-block. We will make the syntax slightly more verbose.

Let us first start with how we want to use our macro:

define_scope!(
    (myval is defined to be 1
     otherval is defined to be "sdfsdf") {
	println!("Myval: {}", myval);
    }
);

Looks awful, but we want to show a point here. Like in the last example, we understand that we need to return a block (so the variables go out of scope after the block is executed if they are not returned from the block). For some of you, this may be straight forward, but you can actually use text directly in your patterns. A possible implementation will look like:

macro_rules! define_scope {
    (($($name:ident is defined to be $result:expr)*) $do:block) => {{
	$(
	    let $name = $result;
	)*
	$do
    }};
}

That actually took very little code! Even if the generated Rust code is less verbose, we proved that you can make the syntax you have always dreamed of (if you are insane)! With great power, comes great responsibility.

You may be asking: Can I use other macros in my own macros? Yes, you can! The standard library even have a lot of them that can help you write better declarative macros! You can even use procedural macros as helpers, so (almost) only your imagination is the limit here! You might already have guessed this to be the case, as we have used println! above. Let us quickly look at some examples of other macro usage.

Creating our own assert Wouldn't it be neat to try to make our own assertion macro, and use it to print the filename and location where it failed? The Rust standard library actually provides some helpers for us to achieve this! The macro file! gives us the filename of the caller, and line! gives us the line number of the caller. In addition, an assertion is simply checking if a condition is met. That gives us a possible implementation:

macro_rules! myassert {
    ($cond:expr) => {
	if !$cond {
	    eprintln!("Assertion failed at {}:{}", file!(), line!());
	}
    };
}

// usage:
myassert!(1 == 2);
// will obviously print:
// Assertion failed at src/main.rs:66
// (it was defined at line 66 in the example file)

(if you are unfamiliar with eprintln!: it prints to standard error instead of standard output).

Stringify When you first start writing macros, you may want to stringify an input. Do you need to take the stringified identifiers in as additional arguments? The standard library to the rescue! To make a stupid simple example, let's just take in an identifier and print it as a string:

macro_rules! print_ident {
    ($name:ident) => {
	println!("My-ident: {}", stringify!($name));
    };
}

// usage:
print_ident!(MyIdentifier);
print_ident!(very_long_not_thing_not_in_quotes);
// prints:
// My-ident: MyIdentifier
// My-ident: very_long_not_thing_not_in_quotes

Now your dream of awkward print helpers without brackets is reality! There are obviously more useful uses of this, as we will see in upcoming examples…

paste! is a procedural macro written to get more advanced template functionality when you want to create new elements with concatenations of identifiers. paste! introduces a way of templating concatenation of names within [< and >]. One example is when you want to create simple new identifiers combined from several others:

paste! {
    let [<My New Shiny Vec>] = vec![1, 2, 3];
}
// equivalent to:
let MyNewShinyVec = vec![1,2,3];

In this example, it might seem a little bit unnecessary, but when introducing identifier input from our own macros, it really shines!

NOTE: It is a separate crate you will have to include in your project.

To make this example a bit more interesting, we will use code from a project I created a while ago. What required me to create a macro?

• I had a function that took an input number and returned a label indicating the number system (e.g, Binary, Octal, Hexadecimal etc.). I wanted tests for several of them, and the tests were almost completely the same except for the function name, label and input number.
• I DID NOT WANT CODE DUPLICATION EVERYWHERE!
• Personalized syntax. "MY work done MY way, nothing else matters to me!" - Howard Roark, The Fountainhead (movie version).

Instead of defining many test functions, I wanted something like this:

base_name_test!(Binary with base 2);
base_name_test!(Octal with base 8);
base_name_test!(Decimal with base 10);
base_name_test!(Duodecimal with base 12);
base_name_test!(Hexadecimal with base 16);
base_name_test!(Base3 with base 3);
base_name_test!(Base32 with base 32);

This code will generate as many test functions as there are macro invocations. We could obviously have taken in an identifier, string and a number, but that would be boring! Why not just lowercase the input to make an test name, stringify the input and use the number directly?

macro_rules! base_name_test {
    ($name:ident with base $base:expr) => {
	paste! {
	    #[test]
	    fn [<base_name_ $name:lower _test>]() {
		assert_eq!(Some(stringify!($name).to_string()), base_name($base));
	    }
	}
    };
}

(paste! also gives us operations to lowercase or uppercase our identifiers like shown in the example).

This leads to us getting a new test function for each invocation of the macro. Example of macro expansion:

// unexpanded
base_name_test!(Binary with base 2);

// expands to:
#[test]
fn base_name_binary_test() {
    assert_eq!(Some("Binary".to_string()), base_name(2));
}

The various links inlined above are good places to learn more. Some summarized resources that I really enjoy are:

• Macros by example in the Rust reference guide
• The Little book of Rust Macros