1622545110
Cloud and data technologies have been the focal point of digital transformation as organizations democratize and modernize their data platforms to turn data into a strategic asset. Our customers have shown tremendous resilience as entire industries have shifted under a landscape of economic uncertainty and they rely on Azure for a full range of use cases. Gartner evaluated these use cases across a wide range of industries and deployment sizes for this Magic Quadrant.
#database #microsoft #magic quadrant #cloud dbms platforms
1622545110
Cloud and data technologies have been the focal point of digital transformation as organizations democratize and modernize their data platforms to turn data into a strategic asset. Our customers have shown tremendous resilience as entire industries have shifted under a landscape of economic uncertainty and they rely on Azure for a full range of use cases. Gartner evaluated these use cases across a wide range of industries and deployment sizes for this Magic Quadrant.
#database #microsoft #magic quadrant #cloud dbms platforms
1623170220
The collection of similar data in one place refers to a database. Let’s not confuse it with data. Data is a collection of information in the form of facts and figures. The database allows users to manipulate data according to their comfort.
This includes retrieval, insertions, and removal of data. It organizes data in tabular, graphical, and many more forms. The database management system is software to help users in managing data.
It provides an interface for the users to handle data in various forms. This may be during database creating or during the time of update. It also ensures that the data is safe all time while maintaining consistency.
Data Definition Language is the scheme that the system follows to see what data will look like in the database. Some famous database management softwares are – MySQL, Oracle, etc. The task of the database management system includes –
1. Data Updation – It is where all the changes in data are made. This may be the addition, removal, or modification of data.
2. Data Retrieval – It allows retrieval of the data from the database for application usage.
**3. User Administration **– It registers, monitors, maintains and enforces data all the time. This includes securing it, controlling it, managing its performance, and recovering information in case of failure.
#computer basics tutorials #advantages of dbms #applications of a dbms #architecture of dbms #basic dbms commands #components of a dbms #database management system #database schema #dbms #dbms vs. flat file #disadvantages of dbms #features of dbms #important dbms terms #popular dbms software #types of dbms #users of dbms
1594162500
A multi-cloud approach is nothing but leveraging two or more cloud platforms for meeting the various business requirements of an enterprise. The multi-cloud IT environment incorporates different clouds from multiple vendors and negates the dependence on a single public cloud service provider. Thus enterprises can choose specific services from multiple public clouds and reap the benefits of each.
Given its affordability and agility, most enterprises opt for a multi-cloud approach in cloud computing now. A 2018 survey on the public cloud services market points out that 81% of the respondents use services from two or more providers. Subsequently, the cloud computing services market has reported incredible growth in recent times. The worldwide public cloud services market is all set to reach $500 billion in the next four years, according to IDC.
By choosing multi-cloud solutions strategically, enterprises can optimize the benefits of cloud computing and aim for some key competitive advantages. They can avoid the lengthy and cumbersome processes involved in buying, installing and testing high-priced systems. The IaaS and PaaS solutions have become a windfall for the enterprise’s budget as it does not incur huge up-front capital expenditure.
However, cost optimization is still a challenge while facilitating a multi-cloud environment and a large number of enterprises end up overpaying with or without realizing it. The below-mentioned tips would help you ensure the money is spent wisely on cloud computing services.
Most organizations tend to get wrong with simple things which turn out to be the root cause for needless spending and resource wastage. The first step to cost optimization in your cloud strategy is to identify underutilized resources that you have been paying for.
Enterprises often continue to pay for resources that have been purchased earlier but are no longer useful. Identifying such unused and unattached resources and deactivating it on a regular basis brings you one step closer to cost optimization. If needed, you can deploy automated cloud management tools that are largely helpful in providing the analytics needed to optimize the cloud spending and cut costs on an ongoing basis.
Another key cost optimization strategy is to identify the idle computing instances and consolidate them into fewer instances. An idle computing instance may require a CPU utilization level of 1-5%, but you may be billed by the service provider for 100% for the same instance.
Every enterprise will have such non-production instances that constitute unnecessary storage space and lead to overpaying. Re-evaluating your resource allocations regularly and removing unnecessary storage may help you save money significantly. Resource allocation is not only a matter of CPU and memory but also it is linked to the storage, network, and various other factors.
The key to efficient cost reduction in cloud computing technology lies in proactive monitoring. A comprehensive view of the cloud usage helps enterprises to monitor and minimize unnecessary spending. You can make use of various mechanisms for monitoring computing demand.
For instance, you can use a heatmap to understand the highs and lows in computing visually. This heat map indicates the start and stop times which in turn lead to reduced costs. You can also deploy automated tools that help organizations to schedule instances to start and stop. By following a heatmap, you can understand whether it is safe to shut down servers on holidays or weekends.
#cloud computing services #all #hybrid cloud #cloud #multi-cloud strategy #cloud spend #multi-cloud spending #multi cloud adoption #why multi cloud #multi cloud trends #multi cloud companies #multi cloud research #multi cloud market
1656924529
Ever wondered what the bang ("!") after "println" means? Not anymore! I will show you exactly how macros work, how to use them, and how to write your own macros.
This is the perfect talk for you if you are using macros, but you always wanted to know how they work and how to implement them yourself.
Rust provides a powerful macro system that allows metaprogramming. As you've seen in previous chapters, macros look like functions, except that their name ends with a bang !
, but instead of generating a function call, macros are expanded into source code that gets compiled with the rest of the program. However, unlike macros in C and other languages, Rust macros are expanded into abstract syntax trees, rather than string preprocessing, so you don't get unexpected precedence bugs.
Macros are created using the macro_rules!
macro.
// This is a simple macro named `say_hello`.
macro_rules! say_hello {
// `()` indicates that the macro takes no argument.
() => {
// The macro will expand into the contents of this block.
println!("Hello!");
};
}
fn main() {
// This call will expand into `println!("Hello");`
say_hello!()
}
So why are macros useful?
Don't repeat yourself. There are many cases where you may need similar functionality in multiple places but with different types. Often, writing a macro is a useful way to avoid repeating code. (More on this later)
Domain-specific languages. Macros allow you to define special syntax for a specific purpose. (More on this later)
Variadic interfaces. Sometimes you want to define an interface that takes a variable number of arguments. An example is println!
which could take any number of arguments, depending on the format string!. (More on this later)
We’ve used macros like println!
throughout this book, but we haven’t fully explored what a macro is and how it works. The term macro refers to a family of features in Rust: declarative macros with macro_rules!
and three kinds of procedural macros:
#[derive]
macros that specify code added with the derive
attribute used on structs and enumsWe’ll talk about each of these in turn, but first, let’s look at why we even need macros when we already have functions.
Fundamentally, macros are a way of writing code that writes other code, which is known as metaprogramming. In Appendix C, we discuss the derive
attribute, which generates an implementation of various traits for you. We’ve also used the println!
and vec!
macros throughout the book. All of these macros expand to produce more code than the code you’ve written manually.
Metaprogramming is useful for reducing the amount of code you have to write and maintain, which is also one of the roles of functions. However, macros have some additional powers that functions don’t.
A function signature must declare the number and type of parameters the function has. Macros, on the other hand, can take a variable number of parameters: we can call println!("hello")
with one argument or println!("hello {}", name)
with two arguments. Also, macros are expanded before the compiler interprets the meaning of the code, so a macro can, for example, implement a trait on a given type. A function can’t, because it gets called at runtime and a trait needs to be implemented at compile time.
The downside to implementing a macro instead of a function is that macro definitions are more complex than function definitions because you’re writing Rust code that writes Rust code. Due to this indirection, macro definitions are generally more difficult to read, understand, and maintain than function definitions.
Another important difference between macros and functions is that you must define macros or bring them into scope before you call them in a file, as opposed to functions you can define anywhere and call anywhere.
macro_rules!
for General MetaprogrammingThe most widely used form of macros in Rust is declarative macros. These are also sometimes referred to as “macros by example,” “macro_rules!
macros,” or just plain “macros.” At their core, declarative macros allow you to write something similar to a Rust match
expression. As discussed in Chapter 6, match
expressions are control structures that take an expression, compare the resulting value of the expression to patterns, and then run the code associated with the matching pattern. Macros also compare a value to patterns that are associated with particular code: in this situation, the value is the literal Rust source code passed to the macro; the patterns are compared with the structure of that source code; and the code associated with each pattern, when matched, replaces the code passed to the macro. This all happens during compilation.
To define a macro, you use the macro_rules!
construct. Let’s explore how to use macro_rules!
by looking at how the vec!
macro is defined. Chapter 8 covered how we can use the vec!
macro to create a new vector with particular values. For example, the following macro creates a new vector containing three integers:
let v: Vec<u32> = vec![1, 2, 3];
We could also use the vec!
macro to make a vector of two integers or a vector of five string slices. We wouldn’t be able to use a function to do the same because we wouldn’t know the number or type of values up front.
Listing 19-28 shows a slightly simplified definition of the vec!
macro.
Filename: src/lib.rs
#[macro_export]
macro_rules! vec {
( $( $x:expr ),* ) => {
{
let mut temp_vec = Vec::new();
$(
temp_vec.push($x);
)*
temp_vec
}
};
}
Listing 19-28: A simplified version of the vec!
macro definition
Note: The actual definition of the
vec!
macro in the standard library includes code to preallocate the correct amount of memory up front. That code is an optimization that we don’t include here to make the example simpler.
The #[macro_export]
annotation indicates that this macro should be made available whenever the crate in which the macro is defined is brought into scope. Without this annotation, the macro can’t be brought into scope.
We then start the macro definition with macro_rules!
and the name of the macro we’re defining without the exclamation mark. The name, in this case vec
, is followed by curly brackets denoting the body of the macro definition.
The structure in the vec!
body is similar to the structure of a match
expression. Here we have one arm with the pattern ( $( $x:expr ),* )
, followed by =>
and the block of code associated with this pattern. If the pattern matches, the associated block of code will be emitted. Given that this is the only pattern in this macro, there is only one valid way to match; any other pattern will result in an error. More complex macros will have more than one arm.
Valid pattern syntax in macro definitions is different than the pattern syntax covered in Chapter 18 because macro patterns are matched against Rust code structure rather than values. Let’s walk through what the pattern pieces in Listing 19-28 mean; for the full macro pattern syntax, see the reference.
First, a set of parentheses encompasses the whole pattern. A dollar sign ($
) is next, followed by a set of parentheses that captures values that match the pattern within the parentheses for use in the replacement code. Within $()
is $x:expr
, which matches any Rust expression and gives the expression the name $x
.
The comma following $()
indicates that a literal comma separator character could optionally appear after the code that matches the code in $()
. The *
specifies that the pattern matches zero or more of whatever precedes the *
.
When we call this macro with vec![1, 2, 3];
, the $x
pattern matches three times with the three expressions 1
, 2
, and 3
.
Now let’s look at the pattern in the body of the code associated with this arm: temp_vec.push()
within $()*
is generated for each part that matches $()
in the pattern zero or more times depending on how many times the pattern matches. The $x
is replaced with each expression matched. When we call this macro with vec![1, 2, 3];
, the code generated that replaces this macro call will be the following:
{
let mut temp_vec = Vec::new();
temp_vec.push(1);
temp_vec.push(2);
temp_vec.push(3);
temp_vec
}
We’ve defined a macro that can take any number of arguments of any type and can generate code to create a vector containing the specified elements.
There are some strange edge cases with macro_rules!
. In the future, Rust will have a second kind of declarative macro that will work in a similar fashion but fix some of these edge cases. After that update, macro_rules!
will be effectively deprecated. With this in mind, as well as the fact that most Rust programmers will use macros more than write macros, we won’t discuss macro_rules!
any further. To learn more about how to write macros, consult the online documentation or other resources, such as “The Little Book of Rust Macros” started by Daniel Keep and continued by Lukas Wirth.
The second form of macros is procedural macros, which act more like functions (and are a type of procedure). Procedural macros accept some code as an input, operate on that code, and produce some code as an output rather than matching against patterns and replacing the code with other code as declarative macros do.
The three kinds of procedural macros (custom derive, attribute-like, and function-like) all work in a similar fashion.
When creating procedural macros, the definitions must reside in their own crate with a special crate type. This is for complex technical reasons that we hope to eliminate in the future. Defining procedural macros looks like the code in Listing 19-29, where some_attribute
is a placeholder for using a specific macro variety.
Filename: src/lib.rs
use proc_macro;
#[some_attribute]
pub fn some_name(input: TokenStream) -> TokenStream {
}
Listing 19-29: An example of defining a procedural macro
The function that defines a procedural macro takes a TokenStream
as an input and produces a TokenStream
as an output. The TokenStream
type is defined by the proc_macro
crate that is included with Rust and represents a sequence of tokens. This is the core of the macro: the source code that the macro is operating on makes up the input TokenStream
, and the code the macro produces is the output TokenStream
. The function also has an attribute attached to it that specifies which kind of procedural macro we’re creating. We can have multiple kinds of procedural macros in the same crate.
Let’s look at the different kinds of procedural macros. We’ll start with a custom derive macro and then explain the small dissimilarities that make the other forms different.
derive
MacroLet’s create a crate named hello_macro
that defines a trait named HelloMacro
with one associated function named hello_macro
. Rather than making our crate users implement the HelloMacro
trait for each of their types, we’ll provide a procedural macro so users can annotate their type with #[derive(HelloMacro)]
to get a default implementation of the hello_macro
function. The default implementation will print Hello, Macro! My name is TypeName!
where TypeName
is the name of the type on which this trait has been defined. In other words, we’ll write a crate that enables another programmer to write code like Listing 19-30 using our crate.
Filename: src/main.rs
use hello_macro::HelloMacro;
use hello_macro_derive::HelloMacro;
#[derive(HelloMacro)]
struct Pancakes;
fn main() {
Pancakes::hello_macro();
}
Listing 19-30: The code a user of our crate will be able to write when using our procedural macro
This code will print Hello, Macro! My name is Pancakes!
when we’re done. The first step is to make a new library crate, like this:
$ cargo new hello_macro --lib
Next, we’ll define the HelloMacro
trait and its associated function:
Filename: src/lib.rs
pub trait HelloMacro {
fn hello_macro();
}
We have a trait and its function. At this point, our crate user could implement the trait to achieve the desired functionality, like so:
use hello_macro::HelloMacro;
struct Pancakes;
impl HelloMacro for Pancakes {
fn hello_macro() {
println!("Hello, Macro! My name is Pancakes!");
}
}
fn main() {
Pancakes::hello_macro();
}
However, they would need to write the implementation block for each type they wanted to use with hello_macro
; we want to spare them from having to do this work.
Additionally, we can’t yet provide the hello_macro
function with default implementation that will print the name of the type the trait is implemented on: Rust doesn’t have reflection capabilities, so it can’t look up the type’s name at runtime. We need a macro to generate code at compile time.
The next step is to define the procedural macro. At the time of this writing, procedural macros need to be in their own crate. Eventually, this restriction might be lifted. The convention for structuring crates and macro crates is as follows: for a crate named foo
, a custom derive procedural macro crate is called foo_derive
. Let’s start a new crate called hello_macro_derive
inside our hello_macro
project:
$ cargo new hello_macro_derive --lib
Our two crates are tightly related, so we create the procedural macro crate within the directory of our hello_macro
crate. If we change the trait definition in hello_macro
, we’ll have to change the implementation of the procedural macro in hello_macro_derive
as well. The two crates will need to be published separately, and programmers using these crates will need to add both as dependencies and bring them both into scope. We could instead have the hello_macro
crate use hello_macro_derive
as a dependency and re-export the procedural macro code. However, the way we’ve structured the project makes it possible for programmers to use hello_macro
even if they don’t want the derive
functionality.
We need to declare the hello_macro_derive
crate as a procedural macro crate. We’ll also need functionality from the syn
and quote
crates, as you’ll see in a moment, so we need to add them as dependencies. Add the following to the Cargo.toml file for hello_macro_derive
:
Filename: hello_macro_derive/Cargo.toml
[lib]
proc-macro = true
[dependencies]
syn = "1.0"
quote = "1.0"
To start defining the procedural macro, place the code in Listing 19-31 into your src/lib.rs file for the hello_macro_derive
crate. Note that this code won’t compile until we add a definition for the impl_hello_macro
function.
Filename: hello_macro_derive/src/lib.rs
use proc_macro::TokenStream;
use quote::quote;
use syn;
#[proc_macro_derive(HelloMacro)]
pub fn hello_macro_derive(input: TokenStream) -> TokenStream {
// Construct a representation of Rust code as a syntax tree
// that we can manipulate
let ast = syn::parse(input).unwrap();
// Build the trait implementation
impl_hello_macro(&ast)
}
Listing 19-31: Code that most procedural macro crates will require in order to process Rust code
Notice that we’ve split the code into the hello_macro_derive
function, which is responsible for parsing the TokenStream
, and the impl_hello_macro
function, which is responsible for transforming the syntax tree: this makes writing a procedural macro more convenient. The code in the outer function (hello_macro_derive
in this case) will be the same for almost every procedural macro crate you see or create. The code you specify in the body of the inner function (impl_hello_macro
in this case) will be different depending on your procedural macro’s purpose.
We’ve introduced three new crates: proc_macro
, syn
, and quote
. The proc_macro
crate comes with Rust, so we didn’t need to add that to the dependencies in Cargo.toml. The proc_macro
crate is the compiler’s API that allows us to read and manipulate Rust code from our code.
The syn
crate parses Rust code from a string into a data structure that we can perform operations on. The quote
crate turns syn
data structures back into Rust code. These crates make it much simpler to parse any sort of Rust code we might want to handle: writing a full parser for Rust code is no simple task.
The hello_macro_derive
function will be called when a user of our library specifies #[derive(HelloMacro)]
on a type. This is possible because we’ve annotated the hello_macro_derive
function here with proc_macro_derive
and specified the name, HelloMacro
, which matches our trait name; this is the convention most procedural macros follow.
The hello_macro_derive
function first converts the input
from a TokenStream
to a data structure that we can then interpret and perform operations on. This is where syn
comes into play. The parse
function in syn
takes a TokenStream
and returns a DeriveInput
struct representing the parsed Rust code. Listing 19-32 shows the relevant parts of the DeriveInput
struct we get from parsing the struct Pancakes;
string:
DeriveInput {
// --snip--
ident: Ident {
ident: "Pancakes",
span: #0 bytes(95..103)
},
data: Struct(
DataStruct {
struct_token: Struct,
fields: Unit,
semi_token: Some(
Semi
)
}
)
}
Listing 19-32: The DeriveInput
instance we get when parsing the code that has the macro’s attribute in Listing 19-30
The fields of this struct show that the Rust code we’ve parsed is a unit struct with the ident
(identifier, meaning the name) of Pancakes
. There are more fields on this struct for describing all sorts of Rust code; check the syn
documentation for DeriveInput
for more information.
Soon we’ll define the impl_hello_macro
function, which is where we’ll build the new Rust code we want to include. But before we do, note that the output for our derive macro is also a TokenStream
. The returned TokenStream
is added to the code that our crate users write, so when they compile their crate, they’ll get the extra functionality that we provide in the modified TokenStream
.
You might have noticed that we’re calling unwrap
to cause the hello_macro_derive
function to panic if the call to the syn::parse
function fails here. It’s necessary for our procedural macro to panic on errors because proc_macro_derive
functions must return TokenStream
rather than Result
to conform to the procedural macro API. We’ve simplified this example by using unwrap
; in production code, you should provide more specific error messages about what went wrong by using panic!
or expect
.
Now that we have the code to turn the annotated Rust code from a TokenStream
into a DeriveInput
instance, let’s generate the code that implements the HelloMacro
trait on the annotated type, as shown in Listing 19-33.
Filename: hello_macro_derive/src/lib.rs
fn impl_hello_macro(ast: &syn::DeriveInput) -> TokenStream {
let name = &ast.ident;
let gen = quote! {
impl HelloMacro for #name {
fn hello_macro() {
println!("Hello, Macro! My name is {}!", stringify!(#name));
}
}
};
gen.into()
}
Listing 19-33: Implementing the HelloMacro
trait using the parsed Rust code
We get an Ident
struct instance containing the name (identifier) of the annotated type using ast.ident
. The struct in Listing 19-32 shows that when we run the impl_hello_macro
function on the code in Listing 19-30, the ident
we get will have the ident
field with a value of "Pancakes"
. Thus, the name
variable in Listing 19-33 will contain an Ident
struct instance that, when printed, will be the string "Pancakes"
, the name of the struct in Listing 19-30.
The quote!
macro lets us define the Rust code that we want to return. The compiler expects something different to the direct result of the quote!
macro’s execution, so we need to convert it to a TokenStream
. We do this by calling the into
method, which consumes this intermediate representation and returns a value of the required TokenStream
type.
The quote!
macro also provides some very cool templating mechanics: we can enter #name
, and quote!
will replace it with the value in the variable name
. You can even do some repetition similar to the way regular macros work. Check out the quote
crate’s docs for a thorough introduction.
We want our procedural macro to generate an implementation of our HelloMacro
trait for the type the user annotated, which we can get by using #name
. The trait implementation has one function, hello_macro
, whose body contains the functionality we want to provide: printing Hello, Macro! My name is
and then the name of the annotated type.
The stringify!
macro used here is built into Rust. It takes a Rust expression, such as 1 + 2
, and at compile time turns the expression into a string literal, such as "1 + 2"
. This is different than format!
or println!
, macros which evaluate the expression and then turn the result into a String
. There is a possibility that the #name
input might be an expression to print literally, so we use stringify!
. Using stringify!
also saves an allocation by converting #name
to a string literal at compile time.
At this point, cargo build
should complete successfully in both hello_macro
and hello_macro_derive
. Let’s hook up these crates to the code in Listing 19-30 to see the procedural macro in action! Create a new binary project in your projects directory using cargo new pancakes
. We need to add hello_macro
and hello_macro_derive
as dependencies in the pancakes
crate’s Cargo.toml. If you’re publishing your versions of hello_macro
and hello_macro_derive
to crates.io, they would be regular dependencies; if not, you can specify them as path
dependencies as follows:
hello_macro = { path = "../hello_macro" }
hello_macro_derive = { path = "../hello_macro/hello_macro_derive" }
Put the code in Listing 19-30 into src/main.rs, and run cargo run
: it should print Hello, Macro! My name is Pancakes!
The implementation of the HelloMacro
trait from the procedural macro was included without the pancakes
crate needing to implement it; the #[derive(HelloMacro)]
added the trait implementation.
Next, let’s explore how the other kinds of procedural macros differ from custom derive macros.
Attribute-like macros are similar to custom derive macros, but instead of generating code for the derive
attribute, they allow you to create new attributes. They’re also more flexible: derive
only works for structs and enums; attributes can be applied to other items as well, such as functions. Here’s an example of using an attribute-like macro: say you have an attribute named route
that annotates functions when using a web application framework:
#[route(GET, "/")]
fn index() {
This #[route]
attribute would be defined by the framework as a procedural macro. The signature of the macro definition function would look like this:
#[proc_macro_attribute]
pub fn route(attr: TokenStream, item: TokenStream) -> TokenStream {
Here, we have two parameters of type TokenStream
. The first is for the contents of the attribute: the GET, "/"
part. The second is the body of the item the attribute is attached to: in this case, fn index() {}
and the rest of the function’s body.
Other than that, attribute-like macros work the same way as custom derive macros: you create a crate with the proc-macro
crate type and implement a function that generates the code you want!
Function-like macros define macros that look like function calls. Similarly to macro_rules!
macros, they’re more flexible than functions; for example, they can take an unknown number of arguments. However, macro_rules!
macros can be defined only using the match-like syntax we discussed in the section “Declarative Macros with macro_rules!
for General Metaprogramming” earlier. Function-like macros take a TokenStream
parameter and their definition manipulates that TokenStream
using Rust code as the other two types of procedural macros do. An example of a function-like macro is an sql!
macro that might be called like so:
let sql = sql!(SELECT * FROM posts WHERE id=1);
This macro would parse the SQL statement inside it and check that it’s syntactically correct, which is much more complex processing than a macro_rules!
macro can do. The sql!
macro would be defined like this:
#[proc_macro]
pub fn sql(input: TokenStream) -> TokenStream {
This definition is similar to the custom derive macro’s signature: we receive the tokens that are inside the parentheses and return the code we wanted to generate.
Whew! Now you have some Rust features in your toolbox that you won’t use often, but you’ll know they’re available in very particular circumstances. We’ve introduced several complex topics so that when you encounter them in error message suggestions or in other peoples’ code, you’ll be able to recognize these concepts and syntax. Use this chapter as a reference to guide you to solutions.
In this tutorial, we’ll cover everything you need to know about Rust macros, including an introduction to macros in Rust and a demonstration of how to use Rust macros with examples.
Rust has excellent support for macros. Macros enable you to write code that writes other code, which is known as metaprogramming.
Macros provide functionality similar to functions but without the runtime cost. There is some compile-time cost, however, since macros are expanded during compile time.
Rust macros are very different from macros in C. Rust macros are applied to the token tree whereas C macros are text substitution.
Rust has two types of macros:
TokenStream
(or two) to another TokenStream
, where the output replaces the macro invocationLet’s zoom in on both declarative and procedural macros and explore some examples of how to use macros in Rust.
These macros are declared using macro_rules!
. Declarative macros are a bit less powerful but provide an easy to use interface for creating macros to remove duplicate code. One of the common declarative macro is println!
. Declarative macros provide a match
like an interface where on match the macro is replaced with code inside the matched arm.
// use macro_rules! <name of macro>{<Body>}
macro_rules! add{
// macth like arm for macro
($a:expr,$b:expr)=>{
// macro expand to this code
{
// $a and $b will be templated using the value/variable provided to macro
$a+$b
}
}
}
fn main(){
// call to macro, $a=1 and $b=2
add!(1,2);
}
This code creates a macro to add two numbers. [macro_rules!]
are used with the name of the macro, add
, and the body of the macro.
The macro doesn’t add two numbers, it just replaces itself with the code to add two numbers. Each arm of the macro takes an argument for functions and multiple types can be assigned to arguments. If the add
function can also take a single argument, we add another arm.
macro_rules! add{
// first arm match add!(1,2), add!(2,3) etc
($a:expr,$b:expr)=>{
{
$a+$b
}
};
// Second arm macth add!(1), add!(2) etc
($a:expr)=>{
{
$a
}
}
}
fn main(){
// call the macro
let x=0;
add!(1,2);
add!(x);
}
There can be multiple branches in a single macro expanding to different code based on different arguments. Each branch can take multiple arguments, starting with the $
sign and followed by a token type:
item
— an item, like a function, struct, module, etc.block
— a block (i.e. a block of statements and/or an expression, surrounded by braces)stmt
— a statementpat
— a patternexpr
— an expressionty
— a typeident
— an identifierpath
— a path (e.g., foo
, ::std::mem::replace
, transmute::<_, int>
, …)meta
— a meta item; the things that go inside #[...]
and #![...]
attributestt
— a single token treevis
— a possibly empty Visibility
qualifierIn the example, we use the $typ
argument with token type ty
as a datatype like u8
, u16
, etc. This macro converts to a particular type before adding the numbers.
macro_rules! add_as{
// using a ty token type for macthing datatypes passed to maccro
($a:expr,$b:expr,$typ:ty)=>{
$a as $typ + $b as $typ
}
}
fn main(){
println!("{}",add_as!(0,2,u8));
}
Rust macros also support taking a nonfixed number of arguments. The operators are very similar to the regular expression. *
is used for zero or more token types and +
for zero or one argument.
macro_rules! add_as{
(
// repeated block
$($a:expr)
// seperator
,
// zero or more
*
)=>{
{
// to handle the case without any arguments
0
// block to be repeated
$(+$a)*
}
}
}
fn main(){
println!("{}",add_as!(1,2,3,4)); // => println!("{}",{0+1+2+3+4})
}
The token type that repeats is enclosed in $()
, followed by a separator and a *
or a +
, indicating the number of times the token will repeat. The separator is used to distinguish the tokens from each other. The $()
block followed by *
or +
is used to indicate the repeating block of code. In the above example, +$a
is a repeating code.
If you look closely, you’ll notice an additional zero is added to the code to make the syntax valid. To remove this zero and make the add
expression the same as the argument, we need to create a new macro known as TT muncher.
macro_rules! add{
// first arm in case of single argument and last remaining variable/number
($a:expr)=>{
$a
};
// second arm in case of two arument are passed and stop recursion in case of odd number ofarguments
($a:expr,$b:expr)=>{
{
$a+$b
}
};
// add the number and the result of remaining arguments
($a:expr,$($b:tt)*)=>{
{
$a+add!($($b)*)
}
}
}
fn main(){
println!("{}",add!(1,2,3,4));
}
The TT muncher processes each token separately in a recursive fashion. It’s easier to process a single token at a time. The macro has three arms:
add
macro again with the rest of the argumentsThe macro arguments don’t need to be comma-separated. Multiple tokens can be used with different token types. For example, brackets can be used with the ident
token type. The Rust compiler takes the matched arm and extracts the variable from the argument string.
macro_rules! ok_or_return{
// match something(q,r,t,6,7,8) etc
// compiler extracts function name and arguments. It injects the values in respective varibles.
($a:ident($($b:tt)*))=>{
{
match $a($($b)*) {
Ok(value)=>value,
Err(err)=>{
return Err(err);
}
}
}
};
}
fn some_work(i:i64,j:i64)->Result<(i64,i64),String>{
if i+j>2 {
Ok((i,j))
} else {
Err("error".to_owned())
}
}
fn main()->Result<(),String>{
ok_or_return!(some_work(1,4));
ok_or_return!(some_work(1,0));
Ok(())
}
The ok_or_return
macro returns the function if an operation returns Err
or the value of an operation returns Ok
. It takes a function as an argument and executes it inside a match statement. For arguments passed to function, it uses repetition.
Often, few macros need to be grouped into a single macro. In these cases, internal macro rules are used. It helps to manipulate the macro inputs and write clean TT munchers.
To create an internal rule, add the rule name starting with @
as the argument. Now the macro will never match for an internal rule until explicitly specified as an argument.
macro_rules! ok_or_return{
// internal rule.
(@error $a:ident,$($b:tt)* )=>{
{
match $a($($b)*) {
Ok(value)=>value,
Err(err)=>{
return Err(err);
}
}
}
};
// public rule can be called by the user.
($a:ident($($b:tt)*))=>{
ok_or_return!(@error $a,$($b)*)
};
}
fn some_work(i:i64,j:i64)->Result<(i64,i64),String>{
if i+j>2 {
Ok((i,j))
} else {
Err("error".to_owned())
}
}
fn main()->Result<(),String>{
// instead of round bracket curly brackets can also be used
ok_or_return!{some_work(1,4)};
ok_or_return!(some_work(1,0));
Ok(())
}
Macros sometimes perform tasks that require parsing of the Rust language itself.
Do put together all the concepts we’ve covered to this point, let’s create a macro that makes a struct public by suffixing the pub
keyword.
First, we need to parse the Rust struct to get the name of the struct, fields of the struct, and field type.
A struct
declaration has a visibility keyword at the start (such as pub
), followed by the struct
keyword and then the name of the struct
and the body of the struct
.
macro_rules! make_public{
(
// use vis type for visibility keyword and ident for struct name
$vis:vis struct $struct_name:ident { }
) => {
{
pub struct $struct_name{ }
}
}
}
The $vis
will have visibility and $struct_name
will have a struct name. To make a struct public, we just need to add the pub
keyword and ignore the $vis
variable.
A struct
may contain multiple fields with the same or different data types and visibility. The ty
token type is used for the data type, vis
for visibility, and ident
for the field name. We’ll use *
repetition for zero or more fields.
macro_rules! make_public{
(
$vis:vis struct $struct_name:ident {
$(
// vis for field visibility, ident for field name and ty for field data type
$field_vis:vis $field_name:ident : $field_type:ty
),*
}
) => {
{
pub struct $struct_name{
$(
pub $field_name : $field_type,
)*
}
}
}
}
struct
Often the struct
has some metadata attached or procedural macros, such as #[derive(Debug)]
. This metadata needs to stay intact. Parsing this metadata is done using the meta
type.
macro_rules! make_public{
(
// meta data about struct
$(#[$meta:meta])*
$vis:vis struct $struct_name:ident {
$(
// meta data about field
$(#[$field_meta:meta])*
$field_vis:vis $field_name:ident : $field_type:ty
),*$(,)+
}
) => {
{
$(#[$meta])*
pub struct $struct_name{
$(
$(#[$field_meta:meta])*
pub $field_name : $field_type,
)*
}
}
}
}
Our make_public
macro is ready now. To see how make_public
works, let’s use Rust Playground to expand the macro to the actual code that is compiled.
macro_rules! make_public{
(
$(#[$meta:meta])*
$vis:vis struct $struct_name:ident {
$(
$(#[$field_meta:meta])*
$field_vis:vis $field_name:ident : $field_type:ty
),*$(,)+
}
) => {
$(#[$meta])*
pub struct $struct_name{
$(
$(#[$field_meta:meta])*
pub $field_name : $field_type,
)*
}
}
}
fn main(){
make_public!{
#[derive(Debug)]
struct Name{
n:i64,
t:i64,
g:i64,
}
}
}
The expanded code looks like this:
// some imports
macro_rules! make_public {
($ (#[$ meta : meta]) * $ vis : vis struct $ struct_name : ident
{
$
($ (#[$ field_meta : meta]) * $ field_vis : vis $ field_name : ident
: $ field_type : ty), * $ (,) +
}) =>
{
$ (#[$ meta]) * pub struct $ struct_name
{
$
($ (#[$ field_meta : meta]) * pub $ field_name : $
field_type,) *
}
}
}
fn main() {
pub struct name {
pub n: i64,
pub t: i64,
pub g: i64,
}
}
Declarative macros have a few limitations. Some are related to Rust macros themselves while others are more specific to declarative macros.
Procedural macros are a more advanced version of macros. Procedural macros allow you to expand the existing syntax of Rust. It takes arbitrary input and returns valid Rust code.
Procedural macros are functions that take a TokenStream
as input and return another Token Stream
. Procedural macros manipulate the input TokenStream
to produce an output stream.
There are three types of procedural macros:
We’ll go into each procedural macro type in detail below.
Attribute-like macros enable you to create a custom attribute that attaches itself to an item and allows manipulation of that item. It can also take arguments.
#[some_attribute_macro(some_argument)]
fn perform_task(){
// some code
}
In the above code, some_attribute_macros
is an attribute macro. It manipulates the function perform_task
.
To write an attribute-like macro, start by creating a project using cargo new macro-demo --lib
. Once the project is ready, update the Cargo.toml
to notify cargo the project will create procedural macros.
# Cargo.toml
[lib]
proc-macro = true
Now we are all set to venture into procedural macros.
Procedural macros are public functions that take TokenStream
as input and return another TokenStream
. To write a procedural macro, we need to write our parser to parse TokenStream
. The Rust community has a very good crate, syn
, for parsing TokenStream
.
syn
provides a ready-made parser for Rust syntax that can be used to parse TokenStream
. You can also parse your syntax by combining low-level parsers providing syn
.
Add syn
and quote
to Cargo.toml
:
# Cargo.toml
[dependencies]
syn = {version="1.0.57",features=["full","fold"]}
quote = "1.0.8"
Now we can write an attribute-like a macro in lib.rs
using the proc_macro
crate provided by the compiler for writing procedural macros. A procedural macro crate cannot export anything else other than procedural macros and procedural macros defined in the crate can’t be used in the crate itself.
// lib.rs
extern crate proc_macro;
use proc_macro::{TokenStream};
use quote::{quote};
// using proc_macro_attribute to declare an attribute like procedural macro
#[proc_macro_attribute]
// _metadata is argument provided to macro call and _input is code to which attribute like macro attaches
pub fn my_custom_attribute(_metadata: TokenStream, _input: TokenStream) -> TokenStream {
// returing a simple TokenStream for Struct
TokenStream::from(quote!{struct H{}})
}
To test the macro we added, create an ingratiation test by creating a folder named tests
and adding the file attribute_macro.rs
in the folder. In this file, we can use our attribute-like macro for testing.
// tests/attribute_macro.rs
use macro_demo::*;
// macro converts struct S to struct H
#[my_custom_attribute]
struct S{}
#[test]
fn test_macro(){
// due to macro we have struct H in scope
let demo=H{};
}
Run the above test using the cargo test
command.
Now that we understand the basics of procedural macros, lets use syn
for some advanced TokenStream
manipulation and parsing.
To learn how syn
is used for parsing and manipulation, let’s take an example from the syn
GitHub repo. This example creates a Rust macro that trace variables when value changes.
First, we need to identify how our macro will manipulate the code it attaches.
#[trace_vars(a)]
fn do_something(){
let a=9;
a=6;
a=0;
}
The trace_vars
macro takes the name of the variable it needs to trace and injects a print statement each time the value of the input variable i.e a
changes. It tracks the value of input variables.
First, parse the code to which the attribute-like macro attaches. syn
provides an inbuilt parser for Rust function syntax. ItemFn
will parse the function and throw an error if the syntax is invalid.
#[proc_macro_attribute]
pub fn trace_vars(_metadata: TokenStream, input: TokenStream) -> TokenStream {
// parsing rust function to easy to use struct
let input_fn = parse_macro_input!(input as ItemFn);
TokenStream::from(quote!{fn dummy(){}})
}
Now that we have the parsed input
, let’s move to metadata
. For metadata
, no inbuilt parser will work, so we’ll have to write one ourselves using syn
‘s parse
module.
#[trace_vars(a,c,b)] // we need to parse a "," seperated list of tokens
// code
For syn
to work, we need to implement the Parse
trait provided by syn
. Punctuated
is used to create a vector
of Indent
separated by ,
.
struct Args{
vars:HashSet<Ident>
}
impl Parse for Args{
fn parse(input: ParseStream) -> Result<Self> {
// parses a,b,c, or a,b,c where a,b and c are Indent
let vars = Punctuated::<Ident, Token![,]>::parse_terminated(input)?;
Ok(Args {
vars: vars.into_iter().collect(),
})
}
}
Once we implement the Parse
trait, we can use parse_macro_input
macro for parsing metadata
.
#[proc_macro_attribute]
pub fn trace_vars(metadata: TokenStream, input: TokenStream) -> TokenStream {
let input_fn = parse_macro_input!(input as ItemFn);
// using newly created struct Args
let args= parse_macro_input!(metadata as Args);
TokenStream::from(quote!{fn dummy(){}})
}
We will now modify the input_fn
to add println!
when the variable changes the value. To add this, we need to filter outlines that have an assignment and insert a print statement after that line.
impl Args {
fn should_print_expr(&self, e: &Expr) -> bool {
match *e {
Expr::Path(ref e) => {
// variable shouldn't start wiht ::
if e.path.leading_colon.is_some() {
false
// should be a single variable like `x=8` not n::x=0
} else if e.path.segments.len() != 1 {
false
} else {
// get the first part
let first = e.path.segments.first().unwrap();
// check if the variable name is in the Args.vars hashset
self.vars.contains(&first.ident) && first.arguments.is_empty()
}
}
_ => false,
}
}
// used for checking if to print let i=0 etc or not
fn should_print_pat(&self, p: &Pat) -> bool {
match p {
// check if variable name is present in set
Pat::Ident(ref p) => self.vars.contains(&p.ident),
_ => false,
}
}
// manipulate tree to insert print statement
fn assign_and_print(&mut self, left: Expr, op: &dyn ToTokens, right: Expr) -> Expr {
// recurive call on right of the assigment statement
let right = fold::fold_expr(self, right);
// returning manipulated sub-tree
parse_quote!({
#left #op #right;
println!(concat!(stringify!(#left), " = {:?}"), #left);
})
}
// manipulating let statement
fn let_and_print(&mut self, local: Local) -> Stmt {
let Local { pat, init, .. } = local;
let init = self.fold_expr(*init.unwrap().1);
// get the variable name of assigned variable
let ident = match pat {
Pat::Ident(ref p) => &p.ident,
_ => unreachable!(),
};
// new sub tree
parse_quote! {
let #pat = {
#[allow(unused_mut)]
let #pat = #init;
println!(concat!(stringify!(#ident), " = {:?}"), #ident);
#ident
};
}
}
}
In the above example, the quote
macro is used for templating and writing Rust. #
is used for injecting the value of the variable.
Now we’ll do a DFS over input_fn
and insert the print statement. syn
provides a Fold
trait that can be implemented for DFS over any Item
. We just need to modify the trait methods that correspond with the token type we want to manipulate.
impl Fold for Args {
fn fold_expr(&mut self, e: Expr) -> Expr {
match e {
// for changing assignment like a=5
Expr::Assign(e) => {
// check should print
if self.should_print_expr(&e.left) {
self.assign_and_print(*e.left, &e.eq_token, *e.right)
} else {
// continue with default travesal using default methods
Expr::Assign(fold::fold_expr_assign(self, e))
}
}
// for changing assigment and operation like a+=1
Expr::AssignOp(e) => {
// check should print
if self.should_print_expr(&e.left) {
self.assign_and_print(*e.left, &e.op, *e.right)
} else {
// continue with default behaviour
Expr::AssignOp(fold::fold_expr_assign_op(self, e))
}
}
// continue with default behaviour for rest of expressions
_ => fold::fold_expr(self, e),
}
}
// for let statements like let d=9
fn fold_stmt(&mut self, s: Stmt) -> Stmt {
match s {
Stmt::Local(s) => {
if s.init.is_some() && self.should_print_pat(&s.pat) {
self.let_and_print(s)
} else {
Stmt::Local(fold::fold_local(self, s))
}
}
_ => fold::fold_stmt(self, s),
}
}
}
The Fold
trait is used to do a DFS of Item
. It enables you to use different behavior for various token types.
Now we can use fold_item_fn
to inject print statements in our parsed code.
#[proc_macro_attribute]
pub fn trace_var(args: TokenStream, input: TokenStream) -> TokenStream {
// parse the input
let input = parse_macro_input!(input as ItemFn);
// parse the arguments
let mut args = parse_macro_input!(args as Args);
// create the ouput
let output = args.fold_item_fn(input);
// return the TokenStream
TokenStream::from(quote!(#output))
}
This code example is from the syn
examples repo, which is an excellent resource to learn about procedural macros.
Custom derive macros in Rust allow auto implement traits. These macros enable you to implement traits using #[derive(Trait)]
.
syn
has excellent support for derive
macros.
#[derive(Trait)]
struct MyStruct{}
To write a custom derive macro in Rust, we can use DeriveInput
for parsing input to derive macro. We’ll also use the proc_macro_derive
macro to define a custom derive macro.
#[proc_macro_derive(Trait)]
pub fn derive_trait(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
let input = parse_macro_input!(input as DeriveInput);
let name = input.ident;
let expanded = quote! {
impl Trait for #name {
fn print(&self) -> usize {
println!("{}","hello from #name")
}
}
};
proc_macro::TokenStream::from(expanded)
}
More advanced procedural macros can be written using syn
. Check out this example from syn
‘s repo.
Function-like macros are similar to declarative macros in that they’re invoked with the macro invocation operator !
and look like function calls. They operate on the code that is inside the parentheses.
Here’s how to write a function-like macro in Rust:
#[proc_macro]
pub fn a_proc_macro(_input: TokenStream) -> TokenStream {
TokenStream::from(quote!(
fn anwser()->i32{
5
}
))
}
Function-like macros are executed not at runtime but at compile time. They can be used anywhere in Rust code. Function-like macros also take a TokenStream
and return a TokenStream
.
Advantages of using procedural macros include:
span
syn
and quote
In this Rust macros tutorial, we covered the basics of macros in Rust, defined declarative and procedural macros, and walked through how to write both types of macros using various syntax and community-built crates. We also outlined the advantages of using each type of Rust macro.
#rust #programming
1652510548
We’ve used macros like println!
throughout this book, but we haven’t fully explored what a macro is and how it works. The term macro refers to a family of features in Rust: declarative macros with macro_rules!
and three kinds of procedural macros:
#[derive]
macros that specify code added with the derive
attribute used on structs and enumsWe’ll talk about each of these in turn, but first, let’s look at why we even need macros when we already have functions.
Fundamentally, macros are a way of writing code that writes other code, which is known as metaprogramming. In Appendix C, we discuss the derive
attribute, which generates an implementation of various traits for you. We’ve also used the println!
and vec!
macros throughout the book. All of these macros expand to produce more code than the code you’ve written manually.
Metaprogramming is useful for reducing the amount of code you have to write and maintain, which is also one of the roles of functions. However, macros have some additional powers that functions don’t.
A function signature must declare the number and type of parameters the function has. Macros, on the other hand, can take a variable number of parameters: we can call println!("hello")
with one argument or println!("hello {}", name)
with two arguments. Also, macros are expanded before the compiler interprets the meaning of the code, so a macro can, for example, implement a trait on a given type. A function can’t, because it gets called at runtime and a trait needs to be implemented at compile time.
The downside to implementing a macro instead of a function is that macro definitions are more complex than function definitions because you’re writing Rust code that writes Rust code. Due to this indirection, macro definitions are generally more difficult to read, understand, and maintain than function definitions.
Another important difference between macros and functions is that you must define macros or bring them into scope before you call them in a file, as opposed to functions you can define anywhere and call anywhere.
macro_rules!
for General MetaprogrammingThe most widely used form of macros in Rust is declarative macros. These are also sometimes referred to as “macros by example,” “macro_rules!
macros,” or just plain “macros.” At their core, declarative macros allow you to write something similar to a Rust match
expression. As discussed in Chapter 6, match
expressions are control structures that take an expression, compare the resulting value of the expression to patterns, and then run the code associated with the matching pattern. Macros also compare a value to patterns that are associated with particular code: in this situation, the value is the literal Rust source code passed to the macro; the patterns are compared with the structure of that source code; and the code associated with each pattern, when matched, replaces the code passed to the macro. This all happens during compilation.
To define a macro, you use the macro_rules!
construct. Let’s explore how to use macro_rules!
by looking at how the vec!
macro is defined. Chapter 8 covered how we can use the vec!
macro to create a new vector with particular values. For example, the following macro creates a new vector containing three integers:
#![allow(unused)]
fn main() {
let v: Vec<u32> = vec![1, 2, 3];
}
We could also use the vec!
macro to make a vector of two integers or a vector of five string slices. We wouldn’t be able to use a function to do the same because we wouldn’t know the number or type of values up front.
Listing 19-28 shows a slightly simplified definition of the vec!
macro.
Filename: src/lib.rs
#[macro_export]
macro_rules! vec {
( $( $x:expr ),* ) => {
{
let mut temp_vec = Vec::new();
$(
temp_vec.push($x);
)*
temp_vec
}
};
}
Listing 19-28: A simplified version of the vec!
macro definition
Note: The actual definition of the
vec!
macro in the standard library includes code to preallocate the correct amount of memory up front. That code is an optimization that we don’t include here to make the example simpler.
The #[macro_export]
annotation indicates that this macro should be made available whenever the crate in which the macro is defined is brought into scope. Without this annotation, the macro can’t be brought into scope.
We then start the macro definition with macro_rules!
and the name of the macro we’re defining without the exclamation mark. The name, in this case vec
, is followed by curly brackets denoting the body of the macro definition.
The structure in the vec!
body is similar to the structure of a match
expression. Here we have one arm with the pattern ( $( $x:expr ),* )
, followed by =>
and the block of code associated with this pattern. If the pattern matches, the associated block of code will be emitted. Given that this is the only pattern in this macro, there is only one valid way to match; any other pattern will result in an error. More complex macros will have more than one arm.
Valid pattern syntax in macro definitions is different than the pattern syntax covered in Chapter 18 because macro patterns are matched against Rust code structure rather than values. Let’s walk through what the pattern pieces in Listing 19-28 mean; for the full macro pattern syntax, see the reference.
First, a set of parentheses encompasses the whole pattern. A dollar sign ($
) is next, followed by a set of parentheses that captures values that match the pattern within the parentheses for use in the replacement code. Within $()
is $x:expr
, which matches any Rust expression and gives the expression the name $x
.
The comma following $()
indicates that a literal comma separator character could optionally appear after the code that matches the code in $()
. The *
specifies that the pattern matches zero or more of whatever precedes the *
.
When we call this macro with vec![1, 2, 3];
, the $x
pattern matches three times with the three expressions 1
, 2
, and 3
.
Now let’s look at the pattern in the body of the code associated with this arm: temp_vec.push()
within $()*
is generated for each part that matches $()
in the pattern zero or more times depending on how many times the pattern matches. The $x
is replaced with each expression matched. When we call this macro with vec![1, 2, 3];
, the code generated that replaces this macro call will be the following:
{
let mut temp_vec = Vec::new();
temp_vec.push(1);
temp_vec.push(2);
temp_vec.push(3);
temp_vec
}
We’ve defined a macro that can take any number of arguments of any type and can generate code to create a vector containing the specified elements.
There are some strange edge cases with macro_rules!
. In the future, Rust will have a second kind of declarative macro that will work in a similar fashion but fix some of these edge cases. After that update, macro_rules!
will be effectively deprecated. With this in mind, as well as the fact that most Rust programmers will use macros more than write macros, we won’t discuss macro_rules!
any further. To learn more about how to write macros, consult the online documentation or other resources, such as “The Little Book of Rust Macros” started by Daniel Keep and continued by Lukas Wirth.
The second form of macros is procedural macros, which act more like functions (and are a type of procedure). Procedural macros accept some code as an input, operate on that code, and produce some code as an output rather than matching against patterns and replacing the code with other code as declarative macros do.
The three kinds of procedural macros (custom derive, attribute-like, and function-like) all work in a similar fashion.
When creating procedural macros, the definitions must reside in their own crate with a special crate type. This is for complex technical reasons that we hope to eliminate in the future. Using procedural macros looks like the code in Listing 19-29, where some_attribute
is a placeholder for using a specific macro.
Filename: src/lib.rs
use proc_macro;
#[some_attribute]
pub fn some_name(input: TokenStream) -> TokenStream {
}
Listing 19-29: An example of using a procedural macro
The function that defines a procedural macro takes a TokenStream
as an input and produces a TokenStream
as an output. The TokenStream
type is defined by the proc_macro
crate that is included with Rust and represents a sequence of tokens. This is the core of the macro: the source code that the macro is operating on makes up the input TokenStream
, and the code the macro produces is the output TokenStream
. The function also has an attribute attached to it that specifies which kind of procedural macro we’re creating. We can have multiple kinds of procedural macros in the same crate.
Let’s look at the different kinds of procedural macros. We’ll start with a custom derive macro and then explain the small dissimilarities that make the other forms different.
derive
MacroLet’s create a crate named hello_macro
that defines a trait named HelloMacro
with one associated function named hello_macro
. Rather than making our crate users implement the HelloMacro
trait for each of their types, we’ll provide a procedural macro so users can annotate their type with #[derive(HelloMacro)]
to get a default implementation of the hello_macro
function. The default implementation will print Hello, Macro! My name is TypeName!
where TypeName
is the name of the type on which this trait has been defined. In other words, we’ll write a crate that enables another programmer to write code like Listing 19-30 using our crate.
Filename: src/main.rs
use hello_macro::HelloMacro;
use hello_macro_derive::HelloMacro;
#[derive(HelloMacro)]
struct Pancakes;
fn main() {
Pancakes::hello_macro();
}
Listing 19-30: The code a user of our crate will be able to write when using our procedural macro
This code will print Hello, Macro! My name is Pancakes!
when we’re done. The first step is to make a new library crate, like this:
$ cargo new hello_macro --lib
Next, we’ll define the HelloMacro
trait and its associated function:
Filename: src/lib.rs
pub trait HelloMacro {
fn hello_macro();
}
We have a trait and its function. At this point, our crate user could implement the trait to achieve the desired functionality, like so:
use hello_macro::HelloMacro;
struct Pancakes;
impl HelloMacro for Pancakes {
fn hello_macro() {
println!("Hello, Macro! My name is Pancakes!");
}
}
fn main() {
Pancakes::hello_macro();
}
However, they would need to write the implementation block for each type they wanted to use with hello_macro
; we want to spare them from having to do this work.
Additionally, we can’t yet provide the hello_macro
function with default implementation that will print the name of the type the trait is implemented on: Rust doesn’t have reflection capabilities, so it can’t look up the type’s name at runtime. We need a macro to generate code at compile time.
The next step is to define the procedural macro. At the time of this writing, procedural macros need to be in their own crate. Eventually, this restriction might be lifted. The convention for structuring crates and macro crates is as follows: for a crate named foo
, a custom derive procedural macro crate is called foo_derive
. Let’s start a new crate called hello_macro_derive
inside our hello_macro
project:
$ cargo new hello_macro_derive --lib
Our two crates are tightly related, so we create the procedural macro crate within the directory of our hello_macro
crate. If we change the trait definition in hello_macro
, we’ll have to change the implementation of the procedural macro in hello_macro_derive
as well. The two crates will need to be published separately, and programmers using these crates will need to add both as dependencies and bring them both into scope. We could instead have the hello_macro
crate use hello_macro_derive
as a dependency and re-export the procedural macro code. However, the way we’ve structured the project makes it possible for programmers to use hello_macro
even if they don’t want the derive
functionality.
We need to declare the hello_macro_derive
crate as a procedural macro crate. We’ll also need functionality from the syn
and quote
crates, as you’ll see in a moment, so we need to add them as dependencies. Add the following to the Cargo.toml file for hello_macro_derive
:
Filename: hello_macro_derive/Cargo.toml
[lib]
proc-macro = true
[dependencies]
syn = "1.0"
quote = "1.0"
To start defining the procedural macro, place the code in Listing 19-31 into your src/lib.rs file for the hello_macro_derive
crate. Note that this code won’t compile until we add a definition for the impl_hello_macro
function.
Filename: hello_macro_derive/src/lib.rs
extern crate proc_macro;
use proc_macro::TokenStream;
use quote::quote;
use syn;
#[proc_macro_derive(HelloMacro)]
pub fn hello_macro_derive(input: TokenStream) -> TokenStream {
// Construct a representation of Rust code as a syntax tree
// that we can manipulate
let ast = syn::parse(input).unwrap();
// Build the trait implementation
impl_hello_macro(&ast)
}
Listing 19-31: Code that most procedural macro crates will require in order to process Rust code
Notice that we’ve split the code into the hello_macro_derive
function, which is responsible for parsing the TokenStream
, and the impl_hello_macro
function, which is responsible for transforming the syntax tree: this makes writing a procedural macro more convenient. The code in the outer function (hello_macro_derive
in this case) will be the same for almost every procedural macro crate you see or create. The code you specify in the body of the inner function (impl_hello_macro
in this case) will be different depending on your procedural macro’s purpose.
We’ve introduced three new crates: proc_macro
, syn
, and quote
. The proc_macro
crate comes with Rust, so we didn’t need to add that to the dependencies in Cargo.toml. The proc_macro
crate is the compiler’s API that allows us to read and manipulate Rust code from our code.
The syn
crate parses Rust code from a string into a data structure that we can perform operations on. The quote
crate turns syn
data structures back into Rust code. These crates make it much simpler to parse any sort of Rust code we might want to handle: writing a full parser for Rust code is no simple task.
The hello_macro_derive
function will be called when a user of our library specifies #[derive(HelloMacro)]
on a type. This is possible because we’ve annotated the hello_macro_derive
function here with proc_macro_derive
and specified the name, HelloMacro
, which matches our trait name; this is the convention most procedural macros follow.
The hello_macro_derive
function first converts the input
from a TokenStream
to a data structure that we can then interpret and perform operations on. This is where syn
comes into play. The parse
function in syn
takes a TokenStream
and returns a DeriveInput
struct representing the parsed Rust code. Listing 19-32 shows the relevant parts of the DeriveInput
struct we get from parsing the struct Pancakes;
string:
DeriveInput {
// --snip--
ident: Ident {
ident: "Pancakes",
span: #0 bytes(95..103)
},
data: Struct(
DataStruct {
struct_token: Struct,
fields: Unit,
semi_token: Some(
Semi
)
}
)
}
Listing 19-32: The DeriveInput
instance we get when parsing the code that has the macro’s attribute in Listing 19-30
The fields of this struct show that the Rust code we’ve parsed is a unit struct with the ident
(identifier, meaning the name) of Pancakes
. There are more fields on this struct for describing all sorts of Rust code; check the syn
documentation for DeriveInput
for more information.
Soon we’ll define the impl_hello_macro
function, which is where we’ll build the new Rust code we want to include. But before we do, note that the output for our derive macro is also a TokenStream
. The returned TokenStream
is added to the code that our crate users write, so when they compile their crate, they’ll get the extra functionality that we provide in the modified TokenStream
.
You might have noticed that we’re calling unwrap
to cause the hello_macro_derive
function to panic if the call to the syn::parse
function fails here. It’s necessary for our procedural macro to panic on errors because proc_macro_derive
functions must return TokenStream
rather than Result
to conform to the procedural macro API. We’ve simplified this example by using unwrap
; in production code, you should provide more specific error messages about what went wrong by using panic!
or expect
.
Now that we have the code to turn the annotated Rust code from a TokenStream
into a DeriveInput
instance, let’s generate the code that implements the HelloMacro
trait on the annotated type, as shown in Listing 19-33.
Filename: hello_macro_derive/src/lib.rs
extern crate proc_macro;
use proc_macro::TokenStream;
use quote::quote;
use syn;
#[proc_macro_derive(HelloMacro)]
pub fn hello_macro_derive(input: TokenStream) -> TokenStream {
// Construct a representation of Rust code as a syntax tree
// that we can manipulate
let ast = syn::parse(input).unwrap();
// Build the trait implementation
impl_hello_macro(&ast)
}
fn impl_hello_macro(ast: &syn::DeriveInput) -> TokenStream {
let name = &ast.ident;
let gen = quote! {
impl HelloMacro for #name {
fn hello_macro() {
println!("Hello, Macro! My name is {}!", stringify!(#name));
}
}
};
gen.into()
}
Listing 19-33: Implementing the HelloMacro
trait using the parsed Rust code
We get an Ident
struct instance containing the name (identifier) of the annotated type using ast.ident
. The struct in Listing 19-32 shows that when we run the impl_hello_macro
function on the code in Listing 19-30, the ident
we get will have the ident
field with a value of "Pancakes"
. Thus, the name
variable in Listing 19-33 will contain an Ident
struct instance that, when printed, will be the string "Pancakes"
, the name of the struct in Listing 19-30.
The quote!
macro lets us define the Rust code that we want to return. The compiler expects something different to the direct result of the quote!
macro’s execution, so we need to convert it to a TokenStream
. We do this by calling the into
method, which consumes this intermediate representation and returns a value of the required TokenStream
type.
The quote!
macro also provides some very cool templating mechanics: we can enter #name
, and quote!
will replace it with the value in the variable name
. You can even do some repetition similar to the way regular macros work. Check out the quote
crate’s docs for a thorough introduction.
We want our procedural macro to generate an implementation of our HelloMacro
trait for the type the user annotated, which we can get by using #name
. The trait implementation has one function, hello_macro
, whose body contains the functionality we want to provide: printing Hello, Macro! My name is
and then the name of the annotated type.
The stringify!
macro used here is built into Rust. It takes a Rust expression, such as 1 + 2
, and at compile time turns the expression into a string literal, such as "1 + 2"
. This is different than format!
or println!
, macros which evaluate the expression and then turn the result into a String
. There is a possibility that the #name
input might be an expression to print literally, so we use stringify!
. Using stringify!
also saves an allocation by converting #name
to a string literal at compile time.
At this point, cargo build
should complete successfully in both hello_macro
and hello_macro_derive
. Let’s hook up these crates to the code in Listing 19-30 to see the procedural macro in action! Create a new binary project in your projects directory using cargo new pancakes
. We need to add hello_macro
and hello_macro_derive
as dependencies in the pancakes
crate’s Cargo.toml. If you’re publishing your versions of hello_macro
and hello_macro_derive
to crates.io, they would be regular dependencies; if not, you can specify them as path
dependencies as follows:
hello_macro = { path = "../hello_macro" }
hello_macro_derive = { path = "../hello_macro/hello_macro_derive" }
Put the code in Listing 19-30 into src/main.rs, and run cargo run
: it should print Hello, Macro! My name is Pancakes!
The implementation of the HelloMacro
trait from the procedural macro was included without the pancakes
crate needing to implement it; the #[derive(HelloMacro)]
added the trait implementation.
Next, let’s explore how the other kinds of procedural macros differ from custom derive macros.
Attribute-like macros are similar to custom derive macros, but instead of generating code for the derive
attribute, they allow you to create new attributes. They’re also more flexible: derive
only works for structs and enums; attributes can be applied to other items as well, such as functions. Here’s an example of using an attribute-like macro: say you have an attribute named route
that annotates functions when using a web application framework:
#[route(GET, "/")]
fn index() {
This #[route]
attribute would be defined by the framework as a procedural macro. The signature of the macro definition function would look like this:
#[proc_macro_attribute]
pub fn route(attr: TokenStream, item: TokenStream) -> TokenStream {
Here, we have two parameters of type TokenStream
. The first is for the contents of the attribute: the GET, "/"
part. The second is the body of the item the attribute is attached to: in this case, fn index() {}
and the rest of the function’s body.
Other than that, attribute-like macros work the same way as custom derive macros: you create a crate with the proc-macro
crate type and implement a function that generates the code you want!
Function-like macros define macros that look like function calls. Similarly to macro_rules!
macros, they’re more flexible than functions; for example, they can take an unknown number of arguments. However, macro_rules!
macros can be defined only using the match-like syntax we discussed in the section “Declarative Macros with macro_rules!
for General Metaprogramming” earlier. Function-like macros take a TokenStream
parameter and their definition manipulates that TokenStream
using Rust code as the other two types of procedural macros do. An example of a function-like macro is an sql!
macro that might be called like so:
let sql = sql!(SELECT * FROM posts WHERE id=1);
This macro would parse the SQL statement inside it and check that it’s syntactically correct, which is much more complex processing than a macro_rules!
macro can do. The sql!
macro would be defined like this:
#[proc_macro]
pub fn sql(input: TokenStream) -> TokenStream {
Whew! Now you have some Rust features in your toolbox that you won’t use often, but you’ll know they’re available in very particular circumstances. We’ve introduced several complex topics so that when you encounter them in error message suggestions or in other peoples’ code, you’ll be able to recognize these concepts and syntax. Use this chapter as a reference to guide you to solutions.
Syntax
MacroRulesDefinition :
macro_rules ! IDENTIFIER MacroRulesDef
MacroRulesDef :
( MacroRules ) ;
| [ MacroRules ] ;
| { MacroRules }
MacroRules :
MacroRule ( ; MacroRule )* ;?
MacroRule :
MacroMatcher => MacroTranscriber
MacroMatcher :
( MacroMatch* )
| [ MacroMatch* ]
| { MacroMatch* }
MacroMatch :
Tokenexcept $ and delimiters
| MacroMatcher
| $ ( IDENTIFIER_OR_KEYWORD except crate | RAW_IDENTIFIER | _ ) : MacroFragSpec
| $ ( MacroMatch+ ) MacroRepSep? MacroRepOp
MacroFragSpec :
block | expr | ident | item | lifetime | literal
| meta | pat | pat_param | path | stmt | tt | ty | vis
MacroRepSep :
Tokenexcept delimiters and MacroRepOp
MacroRepOp :
* | + | ?
MacroTranscriber :
DelimTokenTree
macro_rules
allows users to define syntax extension in a declarative way. We call such extensions "macros by example" or simply "macros".
Each macro by example has a name, and one or more rules. Each rule has two parts: a matcher, describing the syntax that it matches, and a transcriber, describing the syntax that will replace a successfully matched invocation. Both the matcher and the transcriber must be surrounded by delimiters. Macros can expand to expressions, statements, items (including traits, impls, and foreign items), types, or patterns.
When a macro is invoked, the macro expander looks up macro invocations by name, and tries each macro rule in turn. It transcribes the first successful match; if this results in an error, then future matches are not tried. When matching, no lookahead is performed; if the compiler cannot unambiguously determine how to parse the macro invocation one token at a time, then it is an error. In the following example, the compiler does not look ahead past the identifier to see if the following token is a )
, even though that would allow it to parse the invocation unambiguously:
#![allow(unused)]
fn main() {
macro_rules! ambiguity {
($($i:ident)* $j:ident) => { };
}
ambiguity!(error); // Error: local ambiguity
}
In both the matcher and the transcriber, the $
token is used to invoke special behaviours from the macro engine (described below in Metavariables and Repetitions). Tokens that aren't part of such an invocation are matched and transcribed literally, with one exception. The exception is that the outer delimiters for the matcher will match any pair of delimiters. Thus, for instance, the matcher (())
will match {()}
but not {{}}
. The character $
cannot be matched or transcribed literally.
When forwarding a matched fragment to another macro-by-example, matchers in the second macro will see an opaque AST of the fragment type. The second macro can't use literal tokens to match the fragments in the matcher, only a fragment specifier of the same type. The ident
, lifetime
, and tt
fragment types are an exception, and can be matched by literal tokens. The following illustrates this restriction:
#![allow(unused)]
fn main() {
macro_rules! foo {
($l:expr) => { bar!($l); }
// ERROR: ^^ no rules expected this token in macro call
}
macro_rules! bar {
(3) => {}
}
foo!(3);
}
The following illustrates how tokens can be directly matched after matching a tt
fragment:
#![allow(unused)]
fn main() {
// compiles OK
macro_rules! foo {
($l:tt) => { bar!($l); }
}
macro_rules! bar {
(3) => {}
}
foo!(3);
}
In the matcher, $
name :
fragment-specifier matches a Rust syntax fragment of the kind specified and binds it to the metavariable $
name. Valid fragment specifiers are:
item
: an Itemblock
: a BlockExpressionstmt
: a Statement without the trailing semicolon (except for item statements that require semicolons)pat_param
: a PatternNoTopAltpat
: at least any PatternNoTopAlt, and possibly more depending on editionexpr
: an Expressionty
: a Typeident
: an IDENTIFIER_OR_KEYWORD or RAW_IDENTIFIERpath
: a TypePath style pathtt
: a TokenTree (a single token or tokens in matching delimiters ()
, []
, or {}
)meta
: an Attr, the contents of an attributelifetime
: a LIFETIME_TOKENvis
: a possibly empty Visibility qualifierliteral
: matches -
?LiteralExpressionIn the transcriber, metavariables are referred to simply by $
name, since the fragment kind is specified in the matcher. Metavariables are replaced with the syntax element that matched them. The keyword metavariable $crate
can be used to refer to the current crate; see Hygiene below. Metavariables can be transcribed more than once or not at all.
For reasons of backwards compatibility, though _
is also an expression, a standalone underscore is not matched by the expr
fragment specifier. However, _
is matched by the expr
fragment specifier when it appears as a subexpression.
In both the matcher and transcriber, repetitions are indicated by placing the tokens to be repeated inside $(
…)
, followed by a repetition operator, optionally with a separator token between. The separator token can be any token other than a delimiter or one of the repetition operators, but ;
and ,
are the most common. For instance, $( $i:ident ),*
represents any number of identifiers separated by commas. Nested repetitions are permitted.
The repetition operators are:
*
— indicates any number of repetitions.+
— indicates any number but at least one.?
— indicates an optional fragment with zero or one occurrences.Since ?
represents at most one occurrence, it cannot be used with a separator.
The repeated fragment both matches and transcribes to the specified number of the fragment, separated by the separator token. Metavariables are matched to every repetition of their corresponding fragment. For instance, the $( $i:ident ),*
example above matches $i
to all of the identifiers in the list.
During transcription, additional restrictions apply to repetitions so that the compiler knows how to expand them properly:
$( $i:ident ),*
, the transcribers => { $i }
, => { $( $( $i)* )* }
, and => { $( $i )+ }
are all illegal, but => { $( $i );* }
is correct and replaces a comma-separated list of identifiers with a semicolon-separated list.( $( $i:ident ),* ; $( $j:ident ),* ) => (( $( ($i,$j) ),* ))
must bind the same number of $i
fragments as $j
fragments. This means that invoking the macro with (a, b, c; d, e, f)
is legal and expands to ((a,d), (b,e), (c,f))
, but (a, b, c; d, e)
is illegal because it does not have the same number. This requirement applies to every layer of nested repetitions.For historical reasons, the scoping of macros by example does not work entirely like items. Macros have two forms of scope: textual scope, and path-based scope. Textual scope is based on the order that things appear in source files, or even across multiple files, and is the default scoping. It is explained further below. Path-based scope works exactly the same way that item scoping does. The scoping, exporting, and importing of macros is controlled largely by attributes.
When a macro is invoked by an unqualified identifier (not part of a multi-part path), it is first looked up in textual scoping. If this does not yield any results, then it is looked up in path-based scoping. If the macro's name is qualified with a path, then it is only looked up in path-based scoping.
use lazy_static::lazy_static; // Path-based import.
macro_rules! lazy_static { // Textual definition.
(lazy) => {};
}
lazy_static!{lazy} // Textual lookup finds our macro first.
self::lazy_static!{} // Path-based lookup ignores our macro, finds imported one.
Textual scope is based largely on the order that things appear in source files, and works similarly to the scope of local variables declared with let
except it also applies at the module level. When macro_rules!
is used to define a macro, the macro enters the scope after the definition (note that it can still be used recursively, since names are looked up from the invocation site), up until its surrounding scope, typically a module, is closed. This can enter child modules and even span across multiple files:
//// src/lib.rs
mod has_macro {
// m!{} // Error: m is not in scope.
macro_rules! m {
() => {};
}
m!{} // OK: appears after declaration of m.
mod uses_macro;
}
// m!{} // Error: m is not in scope.
//// src/has_macro/uses_macro.rs
m!{} // OK: appears after declaration of m in src/lib.rs
It is not an error to define a macro multiple times; the most recent declaration will shadow the previous one unless it has gone out of scope.
#![allow(unused)]
fn main() {
macro_rules! m {
(1) => {};
}
m!(1);
mod inner {
m!(1);
macro_rules! m {
(2) => {};
}
// m!(1); // Error: no rule matches '1'
m!(2);
macro_rules! m {
(3) => {};
}
m!(3);
}
m!(1);
}
Macros can be declared and used locally inside functions as well, and work similarly:
#![allow(unused)]
fn main() {
fn foo() {
// m!(); // Error: m is not in scope.
macro_rules! m {
() => {};
}
m!();
}
// m!(); // Error: m is not in scope.
}
macro_use
attributeThe macro_use
attribute has two purposes. First, it can be used to make a module's macro scope not end when the module is closed, by applying it to a module:
#![allow(unused)]
fn main() {
#[macro_use]
mod inner {
macro_rules! m {
() => {};
}
}
m!();
}
Second, it can be used to import macros from another crate, by attaching it to an extern crate
declaration appearing in the crate's root module. Macros imported this way are imported into the macro_use
prelude, not textually, which means that they can be shadowed by any other name. While macros imported by #[macro_use]
can be used before the import statement, in case of a conflict, the last macro imported wins. Optionally, a list of macros to import can be specified using the MetaListIdents syntax; this is not supported when #[macro_use]
is applied to a module.
#[macro_use(lazy_static)] // Or #[macro_use] to import all macros.
extern crate lazy_static;
lazy_static!{}
// self::lazy_static!{} // Error: lazy_static is not defined in `self`
Macros to be imported with #[macro_use]
must be exported with #[macro_export]
, which is described below.
By default, a macro has no path-based scope. However, if it has the #[macro_export]
attribute, then it is declared in the crate root scope and can be referred to normally as such:
#![allow(unused)]
fn main() {
self::m!();
m!(); // OK: Path-based lookup finds m in the current module.
mod inner {
super::m!();
crate::m!();
}
mod mac {
#[macro_export]
macro_rules! m {
() => {};
}
}
}
Macros labeled with #[macro_export]
are always pub
and can be referred to by other crates, either by path or by #[macro_use]
as described above.
By default, all identifiers referred to in a macro are expanded as-is, and are looked up at the macro's invocation site. This can lead to issues if a macro refers to an item or macro which isn't in scope at the invocation site. To alleviate this, the $crate
metavariable can be used at the start of a path to force lookup to occur inside the crate defining the macro.
//// Definitions in the `helper_macro` crate.
#[macro_export]
macro_rules! helped {
// () => { helper!() } // This might lead to an error due to 'helper' not being in scope.
() => { $crate::helper!() }
}
#[macro_export]
macro_rules! helper {
() => { () }
}
//// Usage in another crate.
// Note that `helper_macro::helper` is not imported!
use helper_macro::helped;
fn unit() {
helped!();
}
Note that, because $crate
refers to the current crate, it must be used with a fully qualified module path when referring to non-macro items:
#![allow(unused)]
fn main() {
pub mod inner {
#[macro_export]
macro_rules! call_foo {
() => { $crate::inner::foo() };
}
pub fn foo() {}
}
}
Additionally, even though $crate
allows a macro to refer to items within its own crate when expanding, its use has no effect on visibility. An item or macro referred to must still be visible from the invocation site. In the following example, any attempt to invoke call_foo!()
from outside its crate will fail because foo()
is not public.
#![allow(unused)]
fn main() {
#[macro_export]
macro_rules! call_foo {
() => { $crate::foo() };
}
fn foo() {}
}
Version & Edition Differences: Prior to Rust 1.30,
$crate
andlocal_inner_macros
(below) were unsupported. They were added alongside path-based imports of macros (described above), to ensure that helper macros did not need to be manually imported by users of a macro-exporting crate. Crates written for earlier versions of Rust that use helper macros need to be modified to use$crate
orlocal_inner_macros
to work well with path-based imports.
When a macro is exported, the #[macro_export]
attribute can have the local_inner_macros
keyword added to automatically prefix all contained macro invocations with $crate::
. This is intended primarily as a tool to migrate code written before $crate
was added to the language to work with Rust 2018's path-based imports of macros. Its use is discouraged in new code.
#![allow(unused)]
fn main() {
#[macro_export(local_inner_macros)]
macro_rules! helped {
() => { helper!() } // Automatically converted to $crate::helper!().
}
#[macro_export]
macro_rules! helper {
() => { () }
}
}
The parser used by the macro system is reasonably powerful, but it is limited in order to prevent ambiguity in current or future versions of the language. In particular, in addition to the rule about ambiguous expansions, a nonterminal matched by a metavariable must be followed by a token which has been decided can be safely used after that kind of match.
As an example, a macro matcher like $i:expr [ , ]
could in theory be accepted in Rust today, since [,]
cannot be part of a legal expression and therefore the parse would always be unambiguous. However, because [
can start trailing expressions, [
is not a character which can safely be ruled out as coming after an expression. If [,]
were accepted in a later version of Rust, this matcher would become ambiguous or would misparse, breaking working code. Matchers like $i:expr,
or $i:expr;
would be legal, however, because ,
and ;
are legal expression separators. The specific rules are:
expr
and stmt
may only be followed by one of: =>
, ,
, or ;
.pat_param
may only be followed by one of: =>
, ,
, =
, |
, if
, or in
.pat
may only be followed by one of: =>
, ,
, =
, if
, or in
.path
and ty
may only be followed by one of: =>
, ,
, =
, |
, ;
, :
, >
, >>
, [
, {
, as
, where
, or a macro variable of block
fragment specifier.vis
may only be followed by one of: ,
, an identifier other than a non-raw priv
, any token that can begin a type, or a metavariable with a ident
, ty
, or path
fragment specifier.Edition Differences: Before the 2021 edition,
pat
may also be followed by|
.
When repetitions are involved, then the rules apply to every possible number of expansions, taking separators into account. This means:
*
or +
), then the contents must be able to follow themselves.*
or ?
), then whatever comes after must be able to follow whatever comes before.In this tutorial, we’ll cover everything you need to know about Rust macros, including an introduction to macros in Rust and a demonstration of how to use Rust macros with examples.
Rust has excellent support for macros. Macros enable you to write code that writes other code, which is known as metaprogramming.
Macros provide functionality similar to functions but without the runtime cost. There is some compile-time cost, however, since macros are expanded during compile time.
Rust macros are very different from macros in C. Rust macros are applied to the token tree whereas C macros are text substitution.
Rust has two types of macros:
TokenStream
(or two) to another TokenStream
, where the output replaces the macro invocationLet’s zoom in on both declarative and procedural macros and explore some examples of how to use macros in Rust.
These macros are declared using macro_rules!
. Declarative macros are a bit less powerful but provide an easy to use interface for creating macros to remove duplicate code. One of the common declarative macro is println!
. Declarative macros provide a match
like an interface where on match the macro is replaced with code inside the matched arm.
// use macro_rules! <name of macro>{<Body>}
macro_rules! add{
// macth like arm for macro
($a:expr,$b:expr)=>{
// macro expand to this code
{
// $a and $b will be templated using the value/variable provided to macro
$a+$b
}
}
}
fn main(){
// call to macro, $a=1 and $b=2
add!(1,2);
}
This code creates a macro to add two numbers. [macro_rules!]
are used with the name of the macro, add
, and the body of the macro.
The macro doesn’t add two numbers, it just replaces itself with the code to add two numbers. Each arm of the macro takes an argument for functions and multiple types can be assigned to arguments. If the add
function can also take a single argument, we add another arm.
macro_rules! add{
// first arm match add!(1,2), add!(2,3) etc
($a:expr,$b:expr)=>{
{
$a+$b
}
};
// Second arm macth add!(1), add!(2) etc
($a:expr)=>{
{
$a
}
}
}
fn main(){
// call the macro
let x=0;
add!(1,2);
add!(x);
}
There can be multiple branches in a single macro expanding to different code based on different arguments. Each branch can take multiple arguments, starting with the $
sign and followed by a token type:
item
— an item, like a function, struct, module, etc.block
— a block (i.e. a block of statements and/or an expression, surrounded by braces)stmt
— a statementpat
— a patternexpr
— an expressionty
— a typeident
— an identifierpath
— a path (e.g., foo
, ::std::mem::replace
, transmute::<_, int>
, …)meta
— a meta item; the things that go inside #[...]
and #![...]
attributestt
— a single token treevis
— a possibly empty Visibility
qualifierIn the example, we use the $typ
argument with token type ty
as a datatype like u8
, u16
, etc. This macro converts to a particular type before adding the numbers.
macro_rules! add_as{
// using a ty token type for macthing datatypes passed to maccro
($a:expr,$b:expr,$typ:ty)=>{
$a as $typ + $b as $typ
}
}
fn main(){
println!("{}",add_as!(0,2,u8));
}
Rust macros also support taking a nonfixed number of arguments. The operators are very similar to the regular expression. *
is used for zero or more token types and +
for zero or one argument.
macro_rules! add_as{
(
// repeated block
$($a:expr)
// seperator
,
// zero or more
*
)=>{
{
// to handle the case without any arguments
0
// block to be repeated
$(+$a)*
}
}
}
fn main(){
println!("{}",add_as!(1,2,3,4)); // => println!("{}",{0+1+2+3+4})
}
The token type that repeats is enclosed in $()
, followed by a separator and a *
or a +
, indicating the number of times the token will repeat. The separator is used to distinguish the tokens from each other. The $()
block followed by *
or +
is used to indicate the repeating block of code. In the above example, +$a
is a repeating code.
If you look closely, you’ll notice an additional zero is added to the code to make the syntax valid. To remove this zero and make the add
expression the same as the argument, we need to create a new macro known as TT muncher.
macro_rules! add{
// first arm in case of single argument and last remaining variable/number
($a:expr)=>{
$a
};
// second arm in case of two arument are passed and stop recursion in case of odd number ofarguments
($a:expr,$b:expr)=>{
{
$a+$b
}
};
// add the number and the result of remaining arguments
($a:expr,$($b:tt)*)=>{
{
$a+add!($($b)*)
}
}
}
fn main(){
println!("{}",add!(1,2,3,4));
}
The TT muncher processes each token separately in a recursive fashion. It’s easier to process a single token at a time. The macro has three arms:
add
macro again with the rest of the argumentsThe macro arguments don’t need to be comma-separated. Multiple tokens can be used with different token types. For example, brackets can be used with the ident
token type. The Rust compiler takes the matched arm and extracts the variable from the argument string.
macro_rules! ok_or_return{
// match something(q,r,t,6,7,8) etc
// compiler extracts function name and arguments. It injects the values in respective varibles.
($a:ident($($b:tt)*))=>{
{
match $a($($b)*) {
Ok(value)=>value,
Err(err)=>{
return Err(err);
}
}
}
};
}
fn some_work(i:i64,j:i64)->Result<(i64,i64),String>{
if i+j>2 {
Ok((i,j))
} else {
Err("error".to_owned())
}
}
fn main()->Result<(),String>{
ok_or_return!(some_work(1,4));
ok_or_return!(some_work(1,0));
Ok(())
}
The ok_or_return
macro returns the function if an operation returns Err
or the value of an operation returns Ok
. It takes a function as an argument and executes it inside a match statement. For arguments passed to function, it uses repetition.
Often, few macros need to be grouped into a single macro. In these cases, internal macro rules are used. It helps to manipulate the macro inputs and write clean TT munchers.
To create an internal rule, add the rule name starting with @
as the argument. Now the macro will never match for an internal rule until explicitly specified as an argument.
macro_rules! ok_or_return{
// internal rule.
(@error $a:ident,$($b:tt)* )=>{
{
match $a($($b)*) {
Ok(value)=>value,
Err(err)=>{
return Err(err);
}
}
}
};
// public rule can be called by the user.
($a:ident($($b:tt)*))=>{
ok_or_return!(@error $a,$($b)*)
};
}
fn some_work(i:i64,j:i64)->Result<(i64,i64),String>{
if i+j>2 {
Ok((i,j))
} else {
Err("error".to_owned())
}
}
fn main()->Result<(),String>{
// instead of round bracket curly brackets can also be used
ok_or_return!{some_work(1,4)};
ok_or_return!(some_work(1,0));
Ok(())
}
Macros sometimes perform tasks that require parsing of the Rust language itself.
Do put together all the concepts we’ve covered to this point, let’s create a macro that makes a struct public by suffixing the pub
keyword.
First, we need to parse the Rust struct to get the name of the struct, fields of the struct, and field type.
A struct
declaration has a visibility keyword at the start (such as pub
), followed by the struct
keyword and then the name of the struct
and the body of the struct
.
macro_rules! make_public{
(
// use vis type for visibility keyword and ident for struct name
$vis:vis struct $struct_name:ident { }
) => {
{
pub struct $struct_name{ }
}
}
}
The $vis
will have visibility and $struct_name
will have a struct name. To make a struct public, we just need to add the pub
keyword and ignore the $vis
variable.
A struct
may contain multiple fields with the same or different data types and visibility. The ty
token type is used for the data type, vis
for visibility, and ident
for the field name. We’ll use *
repetition for zero or more fields.
macro_rules! make_public{
(
$vis:vis struct $struct_name:ident {
$(
// vis for field visibility, ident for field name and ty for field data type
$field_vis:vis $field_name:ident : $field_type:ty
),*
}
) => {
{
pub struct $struct_name{
$(
pub $field_name : $field_type,
)*
}
}
}
}
struct
Often the struct
has some metadata attached or procedural macros, such as #[derive(Debug)]
. This metadata needs to stay intact. Parsing this metadata is done using the meta
type.
macro_rules! make_public{
(
// meta data about struct
$(#[$meta:meta])*
$vis:vis struct $struct_name:ident {
$(
// meta data about field
$(#[$field_meta:meta])*
$field_vis:vis $field_name:ident : $field_type:ty
),*$(,)+
}
) => {
{
$(#[$meta])*
pub struct $struct_name{
$(
$(#[$field_meta:meta])*
pub $field_name : $field_type,
)*
}
}
}
}
Our make_public
macro is ready now. To see how make_public
works, let’s use Rust Playground to expand the macro to the actual code that is compiled.
macro_rules! make_public{
(
$(#[$meta:meta])*
$vis:vis struct $struct_name:ident {
$(
$(#[$field_meta:meta])*
$field_vis:vis $field_name:ident : $field_type:ty
),*$(,)+
}
) => {
$(#[$meta])*
pub struct $struct_name{
$(
$(#[$field_meta:meta])*
pub $field_name : $field_type,
)*
}
}
}
fn main(){
make_public!{
#[derive(Debug)]
struct Name{
n:i64,
t:i64,
g:i64,
}
}
}
The expanded code looks like this:
// some imports
macro_rules! make_public {
($ (#[$ meta : meta]) * $ vis : vis struct $ struct_name : ident
{
$
($ (#[$ field_meta : meta]) * $ field_vis : vis $ field_name : ident
: $ field_type : ty), * $ (,) +
}) =>
{
$ (#[$ meta]) * pub struct $ struct_name
{
$
($ (#[$ field_meta : meta]) * pub $ field_name : $
field_type,) *
}
}
}
fn main() {
pub struct name {
pub n: i64,
pub t: i64,
pub g: i64,
}
}
Declarative macros have a few limitations. Some are related to Rust macros themselves while others are more specific to declarative macros.
Procedural macros are a more advanced version of macros. Procedural macros allow you to expand the existing syntax of Rust. It takes arbitrary input and returns valid Rust code.
Procedural macros are functions that take a TokenStream
as input and return another Token Stream
. Procedural macros manipulate the input TokenStream
to produce an output stream.
There are three types of procedural macros:
We’ll go into each procedural macro type in detail below.
Attribute-like macros enable you to create a custom attribute that attaches itself to an item and allows manipulation of that item. It can also take arguments.
#[some_attribute_macro(some_argument)]
fn perform_task(){
// some code
}
In the above code, some_attribute_macros
is an attribute macro. It manipulates the function perform_task
.
To write an attribute-like macro, start by creating a project using cargo new macro-demo --lib
. Once the project is ready, update the Cargo.toml
to notify cargo the project will create procedural macros.
# Cargo.toml
[lib]
proc-macro = true
Now we are all set to venture into procedural macros.
Procedural macros are public functions that take TokenStream
as input and return another TokenStream
. To write a procedural macro, we need to write our parser to parse TokenStream
. The Rust community has a very good crate, syn
, for parsing TokenStream
.
syn
provides a ready-made parser for Rust syntax that can be used to parse TokenStream
. You can also parse your syntax by combining low-level parsers providing syn
.
Add syn
and quote
to Cargo.toml
:
# Cargo.toml
[dependencies]
syn = {version="1.0.57",features=["full","fold"]}
quote = "1.0.8"
Now we can write an attribute-like a macro in lib.rs
using the proc_macro
crate provided by the compiler for writing procedural macros. A procedural macro crate cannot export anything else other than procedural macros and procedural macros defined in the crate can’t be used in the crate itself.
// lib.rs
extern crate proc_macro;
use proc_macro::{TokenStream};
use quote::{quote};
// using proc_macro_attribute to declare an attribute like procedural macro
#[proc_macro_attribute]
// _metadata is argument provided to macro call and _input is code to which attribute like macro attaches
pub fn my_custom_attribute(_metadata: TokenStream, _input: TokenStream) -> TokenStream {
// returing a simple TokenStream for Struct
TokenStream::from(quote!{struct H{}})
}
To test the macro we added, create an ingratiation test by creating a folder named tests
and adding the file attribute_macro.rs
in the folder. In this file, we can use our attribute-like macro for testing.
// tests/attribute_macro.rs
use macro_demo::*;
// macro converts struct S to struct H
#[my_custom_attribute]
struct S{}
#[test]
fn test_macro(){
// due to macro we have struct H in scope
let demo=H{};
}
Run the above test using the cargo test
command.
Now that we understand the basics of procedural macros, lets use syn
for some advanced TokenStream
manipulation and parsing.
To learn how syn
is used for parsing and manipulation, let’s take an example from the syn
GitHub repo. This example creates a Rust macro that trace variables when value changes.
First, we need to identify how our macro will manipulate the code it attaches.
#[trace_vars(a)]
fn do_something(){
let a=9;
a=6;
a=0;
}
The trace_vars
macro takes the name of the variable it needs to trace and injects a print statement each time the value of the input variable i.e a
changes. It tracks the value of input variables.
First, parse the code to which the attribute-like macro attaches. syn
provides an inbuilt parser for Rust function syntax. ItemFn
will parse the function and throw an error if the syntax is invalid.
#[proc_macro_attribute]
pub fn trace_vars(_metadata: TokenStream, input: TokenStream) -> TokenStream {
// parsing rust function to easy to use struct
let input_fn = parse_macro_input!(input as ItemFn);
TokenStream::from(quote!{fn dummy(){}})
}
Now that we have the parsed input
, let’s move to metadata
. For metadata
, no inbuilt parser will work, so we’ll have to write one ourselves using syn
‘s parse
module.
#[trace_vars(a,c,b)] // we need to parse a "," seperated list of tokens
// code
For syn
to work, we need to implement the Parse
trait provided by syn
. Punctuated
is used to create a vector
of Indent
separated by ,
.
struct Args{
vars:HashSet<Ident>
}
impl Parse for Args{
fn parse(input: ParseStream) -> Result<Self> {
// parses a,b,c, or a,b,c where a,b and c are Indent
let vars = Punctuated::<Ident, Token![,]>::parse_terminated(input)?;
Ok(Args {
vars: vars.into_iter().collect(),
})
}
}
Once we implement the Parse
trait, we can use parse_macro_input
macro for parsing metadata
.
#[proc_macro_attribute]
pub fn trace_vars(metadata: TokenStream, input: TokenStream) -> TokenStream {
let input_fn = parse_macro_input!(input as ItemFn);
// using newly created struct Args
let args= parse_macro_input!(metadata as Args);
TokenStream::from(quote!{fn dummy(){}})
}
We will now modify the input_fn
to add println!
when the variable changes the value. To add this, we need to filter outlines that have an assignment and insert a print statement after that line.
impl Args {
fn should_print_expr(&self, e: &Expr) -> bool {
match *e {
Expr::Path(ref e) => {
// variable shouldn't start wiht ::
if e.path.leading_colon.is_some() {
false
// should be a single variable like `x=8` not n::x=0
} else if e.path.segments.len() != 1 {
false
} else {
// get the first part
let first = e.path.segments.first().unwrap();
// check if the variable name is in the Args.vars hashset
self.vars.contains(&first.ident) && first.arguments.is_empty()
}
}
_ => false,
}
}
// used for checking if to print let i=0 etc or not
fn should_print_pat(&self, p: &Pat) -> bool {
match p {
// check if variable name is present in set
Pat::Ident(ref p) => self.vars.contains(&p.ident),
_ => false,
}
}
// manipulate tree to insert print statement
fn assign_and_print(&mut self, left: Expr, op: &dyn ToTokens, right: Expr) -> Expr {
// recurive call on right of the assigment statement
let right = fold::fold_expr(self, right);
// returning manipulated sub-tree
parse_quote!({
#left #op #right;
println!(concat!(stringify!(#left), " = {:?}"), #left);
})
}
// manipulating let statement
fn let_and_print(&mut self, local: Local) -> Stmt {
let Local { pat, init, .. } = local;
let init = self.fold_expr(*init.unwrap().1);
// get the variable name of assigned variable
let ident = match pat {
Pat::Ident(ref p) => &p.ident,
_ => unreachable!(),
};
// new sub tree
parse_quote! {
let #pat = {
#[allow(unused_mut)]
let #pat = #init;
println!(concat!(stringify!(#ident), " = {:?}"), #ident);
#ident
};
}
}
}
In the above example, the quote
macro is used for templating and writing Rust. #
is used for injecting the value of the variable.
Now we’ll do a DFS over input_fn
and insert the print statement. syn
provides a Fold
trait that can be implemented for DFS over any Item
. We just need to modify the trait methods that correspond with the token type we want to manipulate.
impl Fold for Args {
fn fold_expr(&mut self, e: Expr) -> Expr {
match e {
// for changing assignment like a=5
Expr::Assign(e) => {
// check should print
if self.should_print_expr(&e.left) {
self.assign_and_print(*e.left, &e.eq_token, *e.right)
} else {
// continue with default travesal using default methods
Expr::Assign(fold::fold_expr_assign(self, e))
}
}
// for changing assigment and operation like a+=1
Expr::AssignOp(e) => {
// check should print
if self.should_print_expr(&e.left) {
self.assign_and_print(*e.left, &e.op, *e.right)
} else {
// continue with default behaviour
Expr::AssignOp(fold::fold_expr_assign_op(self, e))
}
}
// continue with default behaviour for rest of expressions
_ => fold::fold_expr(self, e),
}
}
// for let statements like let d=9
fn fold_stmt(&mut self, s: Stmt) -> Stmt {
match s {
Stmt::Local(s) => {
if s.init.is_some() && self.should_print_pat(&s.pat) {
self.let_and_print(s)
} else {
Stmt::Local(fold::fold_local(self, s))
}
}
_ => fold::fold_stmt(self, s),
}
}
}
The Fold
trait is used to do a DFS of Item
. It enables you to use different behavior for various token types.
Now we can use fold_item_fn
to inject print statements in our parsed code.
#[proc_macro_attribute]
pub fn trace_var(args: TokenStream, input: TokenStream) -> TokenStream {
// parse the input
let input = parse_macro_input!(input as ItemFn);
// parse the arguments
let mut args = parse_macro_input!(args as Args);
// create the ouput
let output = args.fold_item_fn(input);
// return the TokenStream
TokenStream::from(quote!(#output))
}
This code example is from the syn
examples repo, which is an excellent resource to learn about procedural macros.
Custom derive macros in Rust allow auto implement traits. These macros enable you to implement traits using #[derive(Trait)]
.
syn
has excellent support for derive
macros.
#[derive(Trait)]
struct MyStruct{}
To write a custom derive macro in Rust, we can use DeriveInput
for parsing input to derive macro. We’ll also use the proc_macro_derive
macro to define a custom derive macro.
#[proc_macro_derive(Trait)]
pub fn derive_trait(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
let input = parse_macro_input!(input as DeriveInput);
let name = input.ident;
let expanded = quote! {
impl Trait for #name {
fn print(&self) -> usize {
println!("{}","hello from #name")
}
}
};
proc_macro::TokenStream::from(expanded)
}
More advanced procedural macros can be written using syn
. Check out this example from syn
‘s repo.
Function-like macros are similar to declarative macros in that they’re invoked with the macro invocation operator !
and look like function calls. They operate on the code that is inside the parentheses.
Here’s how to write a function-like macro in Rust:
#[proc_macro]
pub fn a_proc_macro(_input: TokenStream) -> TokenStream {
TokenStream::from(quote!(
fn anwser()->i32{
5
}
))
}
Function-like macros are executed not at runtime but at compile time. They can be used anywhere in Rust code. Function-like macros also take a TokenStream
and return a TokenStream
.
Advantages of using procedural macros include:
span
syn
and quote
In this Rust macros tutorial, we covered the basics of macros in Rust, defined declarative and procedural macros, and walked through how to write both types of macros using various syntax and community-built crates. We also outlined the advantages of using each type of Rust macro.
References:
- Please support those who need it the most right now: https://help.gov.ua/en
- Source Code: https://github.com/tsoding/noq
- Macros by Example: https://doc.rust-lang.org/reference/macros-by-example.html
- TT munchers: https://danielkeep.github.io/tlborm/book/pat-incremental-tt-munchers.html
#rust #programming