mani loviel

1622271947

18885970064 | Minecraft Password Reset | Change Minecraft Username | Change Minecraft Name

How to recover Minecraft account How to recover Minecraft account
Minecraft is a top-rated game where you can benefit significantly if you have a premium account by accessing servers and straightforwardly playing with your friends.

But maybe you haven’t used your account for a long time, or you’ve forgotten your password, and you want to know how to recover your Minecraft account.

Here we have created a complete guide so that you can regain access to it in any way since there are many mechanisms to do so, and here we are going to show you all of them.

Did you identify me with an email address or my username?
In Minecraft, there are two types of accounts, one granted by Minecraft itself and another by Mojang:

All Minecraft accounts created after Fall 2012, or those that were migrated from the old format to the Mojang platform, use an email to identify themselves.

While the old accounts that users have not migrated continue to use the username to enter.

You must know what type of accounts you have to know how to continue with this tutorial.

What if I lost my password?
If you have lost your password because you do not remember where you wrote it down, or it was stolen (that is, your password was changed), there is a way to recover it quickly:

If old accounts have not been migrated (those that use a username to enter), you must visit the site to migrate accounts to Mojang.

Migrate account to Mojang Migrate account to Mojang

The steps are the following:

  1. We enter the email of our account

  2. We enter the username of our account

  3. We enter the password of our account

  4. We enter the new email for our new account

  5. We re-enter the new email for our new account

  6. We put our date of birth

  7. We accept the terms and conditions by checking the box

  8. We click on the migrate account button

If we want to recover the account with the lost password, we have to go to the following page: https://my.minecraft.net/es-es/password/forgot/.

Recover Minecraft Password Recover Minecraft Password

Where we enter our email as indicated, and then we click the request button.

The steps are straightforward from here since we are sent to the address of our account (which must be transparent). All the steps to change it and continue enjoying the game.

What happens if I don’t remember my email address?
If we already have our Mojang account migrated, there is a little trick if we forget which of all our mailboxes is the one we use to register.

We go to the same address to recover the password, and we begin to test all the email addresses that we know to reset our password. Finally, we will get where we have registered.

I don’t remember what my username was like
Just log in to the Mojang-type Minecraft account, and we’ll see the username within the game, either on the account page on the site or in the Minecraft client before launching the game.

I’m still having trouble getting my account back.
You can leave us a comment below, and we will try to help you as soon as possible. Keep in mind that we are not Mojang and our advice goes as far as what any user can do.

We also recommend that you contact the team behind Minecraft to help you with their support system, which you can write to here.

Contact Minecraft to recover lost account Contact Minecraft to recover a lost account.

It is entirely in Spanish, so you will have no problem completing the required information (marked with a red asterisk) and some others that will help make the process easier for them and you.

Command for Minecraft when I forgot the password. Change the password on the Minecraft server through your account and on the client. Password requirements
Minecraft: infinite cubic meters. Walk do not cross. The most cherished dream of any gamer is a true fan of sandbox games. And the progress of development in it captures and the extraction of valuable wealth resources and the manufacture of various items and battles with mobs. And then no kidding, these are just the main points. A large, thick book can be dedicated to all the delights of Minecraft.

On forums, blogs, YouTube video reviews, players compete to show off their Minecraft achievements: “Look what I built!”, “This is how I earned this location!”, “Look what I found!” “Do you know those crafting recipes??!”

For some reason, that’s it. Oh yeah, all these virtual Minecraft honors, medals, and treasures can be lost in an instant! And it’s not because you didn’t get by with the game, climbed somewhere in the wrong place, or someone “squeezed” you hard … It’s all so much sadder and easier! And because you came up with a simple password, and on the server, someone picked it up, knowing your username. Or maybe the password was complicated because some kind of virus stole it. And that’s it, goodbye, your hero passed at the disposal of another player. You understand what the consequences of this situation can be. In short, nothing good.

So, to be safe from these misfortunes, read this article. From it, you will learn how to change your password offline and directly on the server, what to do if you have forgotten it, which login key is more resistant to hacking.

  1. Do not use the “most popular” combinations on the Internet: qwerty, 12345, abcdefg, myparol. Attackers can manually pick them up within 5 minutes and consequently take over the account in a treacherous way.

  2. Avoid minor keys. The optimal password length is 10-16 characters.

  3. Alternate numbers, special characters, and English letters (lowercase and uppercase) in a symbolic sequence.

  4. When registering and changing the password, do not specify the combination you use to access another online service (for example, VKontakte). You risk losing two accounts at once if your key is stolen.

Server
The password change can be done during the game.

  1. Make sure the English keyboard layout is enabled. Press the “/” key to open the console.

  2. To change the password in Minecraft, enter the command:

/ change password (old password) (new)

Attention! Symbolic keys do not need to be in parentheses when entering a command.

If the operation were successful, a message would appear on the console about its successful completion. You can now enter the game using the new authorization data.

If you don’t remember the token key you used to log in, contact the technical support of the server you are playing on with a request to restore access. Or use the particular reset function in the service office. For example, you can change the password on the website on the Rus-Minecraft portal: rus-minecraft.ru/lost-password/.

Official site Minecraft.net

  1. On the login panel, in the error message block, click the link “Forgot your password?” (I forget… ?).

  2. In the “Email” line, enter the email address that you specified in the process of creating your account.

  3. Click the “Request password reset” button.

  4. Go to email, open message from Mojang (game developer) service.

  5. On the page that opens in the browser, enter the new symbolic combination 2 times for authorization.

  6. Click “Reset Password.”

The procedure is complete. Now you can go to your profile on minecraft.net.

And you need to change the password of minecraft.net in the Mojang office. To complete this procedure:

  1. In the “Account details” option block, on the “Password…” line, click the “Edit” command.

  2. Enter a new password in the “New…” and “Repeat” fields.

  3. In the line "Current… " enter the current password.

Change your Minecraft profile password about once every 1-2 months. Exciting game and, most importantly, safe!

Without constant access to high-speed Internet in the modern world, it is essential to be connected to the Internet through your computer or phone at home or work. But if there is a router and wifi in the room where you are, you cannot connect because you do not know the password and cannot ask anyone. There are several ways to find out your wifi password if you forgot it or cannot connect for other reasons. In this article, we will look at the main ways to solve this problem in this situation.

So, we will tell you how to remember your Internet password on the Windows system, starting with seven and above and how to view the password of all networks that have been saved on the device.

We will also tell you what to do in a situation if a device (phone, tablet, computer) has Internet, but you need to connect to another device, and the password is lost or forgotten. And we will tell you how to find out your password if you have a router handy.

Router password
This method of viewing the password from wifi can be helpful if you remember exactly that you did not change the standard password as soon as you bought and connected the router. Also, the standard password of the router is often left for the Internet, which is connected in a rented apartment. This is done so that the next tenant can easily connect to the Internet, and the landlord does not have to explain the password.

Therefore, if you drove to a new apartment and the landlord did not tell you the Internet pin, first try to find the password on the router. It is worth noting that not all routers have a written password; this works mainly with the newer models.

Usually, the PIN code by which you can connect to the router consists of 8 digits. They are printed on the back of the router on a label that also contains information about the service and the serial number. Take a good look. There must be the word PIN on the label, followed by numbers.

Code saved on PC
If you have a laptop on hand with a saved password and the laptop connects to the Internet without any problem and does it automatically, you may have forgotten the password on this network a long time ago. But the time comes when you need to connect another device to the Internet: a purchased phone or a device from a friend or guest who has come to you and wants to use a wireless network. So not knowing the network password can become a real problem. But you can look at the code from the laptop. Different versions of Windows do this differently, so we give detailed instructions for each option.

Windows 10 y Windows 8
To understand how to find out the wi-fi password, you must be connected to it. Then do the following:

You now know your password and can connect other devices to the Internet using it.

In Windows 7
To view the password stored on the computer connected to Windows 7, you must do the following:

If the wireless network is not connected
In the methods of how to view the wi-fi password described by us above, it is assumed that you have a network connection from which you need a password, but if there is no connection, you can view the password through the command line.

If the password is not on the computer
Even if the password is not saved on your PC, but you can connect the computer directly to the router, there is a way to see the password.

This can happen if the computer crashes or you reinstall the Windows system, and now you don’t remember the password for your network that your computer was previously connected to. But you have physical access to the router.

To find out the password in this case, you need to connect the router to the computer via a cable. This is done through the router’s LAN connector, connected to the computer’s network card. When you are connected, you need to go to the settings of the router. You can log in using a standard password and login; it should be written on the back of your router.

If you were able to go to the router settings, you need to find the wireless settings. They are usually found in the wifi settings item and are called Wireless. It is in this configuration that you can see the password of the network that this router distributes.

However, this method has a drawback. During the initial configuration of the router, the password or login used to enter the configuration through the computer can be changed. Sometimes vendor tech support does this. Ordinary users rarely change something in factory settings when setting up a router.

Then, if you don’t know the new username or password, you won’t be able to enter the settings and see the network code. In this case, a factory reset is required. You can read about how to do this below.

Code saved in Android.
To view the network password that you have saved on your phone or tablet running on the Android system, you need to have root access to the device.

If you have such access, you should go to the data / misc / wifi folder. This can be done through ES Explorer, Root Explorer or another file manager installed on your phone. In the folder, you need to find the text file wpa_supplicant.conf. This file will record all the data about the networks you have connected to. Your password will be the psk parameter.

You can also download a program from the app store that will display the passwords for the stored networks on your phone. A similar program is wifi Password (ROOT), but many analogs are in the app store. You can choose what suits you best in this case.

Minecraft Password reset
If you have tried all the methods we described in the previous article, and you cannot figure out how to find out the wifi network password because none of the listed methods work, you will have to reset the password and set a new one. This will help, for example, if you cannot enter the router settings because someone changed your password. However, this only works if you have physical access to the router. That is, to reset the Internet password and set a new one, you must be the owner of the router and the network itself.

It is immediately worth noting that this method has a significant disadvantage. Find out in advance if your ISP uses unique settings to connect to the network. If you do, you will have to call the wizard again and configure the Internet yourself. Or you can do it yourself by following the instructions of the provider’s call center specialist.

To reset the password, you need to look at the back of the router, in which there are buttons with which you can control the router and ports for entering cables from the Internet. You should find the reset button; there will be a reset signature next to it in most cases.

This button can be pressed with a thin paper clip or needle and held down for about 10 seconds. If this method did not work, you need to hold down the button, turn off the router for about half a minute. All this time, you need to hold down the button. After that, while holding the reset button, you need to turn on the router and hold the reset button for about half a minute.

After that, all the settings that were on the router need to be reset. And the password of the router will now be the one written on the back of the router.

After resetting the settings, you need to reconnect the router to the network for everything to work. You can call the provider’s assistant or see how to connect the router in the instructions for it. But the last method works only if your provider doesn’t use unique settings.

conclusions
As you can see, there are many ways to find out your wifi password, but they all work in different cases. Remember that you can always reset the settings as a last resort, but then you will have to reinstall it so that the router can distribute your Internet.

If you know more ways to view the password, you can write them in the comments so that other users can quickly solve your problem.

If this happens, you must immediately change the password. And then, we will tell you how to change the password in Minecraft on the server. By the way, this action is effortless in all multiplayer games. In our case, everything is the same, but with the peculiarities of changing the password, which can sometimes cause difficulties.

Frequently, users want to change their password because this combination of characters seems simple, and therefore they start to worry about the threat of a hack. This is what should be done, rather than waiting for the situation to get worse. It happens that players create very complex passwords that they cannot remember. And then they can’t log into their accounts. There is only one way out: change the password to a more memorable one. Therefore, you need to know how to change the access code, as well as based on what criteria to choose it.

How to enter a password correctly?
In no case should you use the combinations that have become so popular on the Internet (23456, myparols, ertyui)? Any expert cracker can quickly crack them and take over the account.

Use long keys, preferably long ones. The correct option is 10 to 16 characters.

A sequence of numbers, special characters, and English letters (uppercase and lowercase).

It is recommended not to take existing passwords that are used in other services. There is a risk of losing all accounts if your keys are stolen.

How do I change my server password in Minecraft?
There is the possibility of changing the password during the game. For this:

If the password used for authorization was lost, the player must contact the game server technical support to restore access. It is also possible to reset the data by going to the main Minecraft website.

Sometimes when logging into your account, an error appears identifying the data entered incorrectly. Now you have to reset the password:

  1. You must click on the inscription “Forgot your password?” Did you forget your password? It’s next to the login panel in the login error box.

  2. In the “Email” field, enter your current email address assigned to your account in the system.

  3. Click “Request password reset.”

  4. Open your inbox and find the email sent by Mojang (the game developer).

  5. In the letter, you need to click on the website address.

  6. A browser window will open in front of you, in which you will need to enter a new password twice.

  7. It remains to click “Reset password.”

After graduation, you should take the opportunity to log into your account. By the way, to change the password for minecraft.net, you need to go to the Mojang resource. The steps should be followed as follows:

  1. Log in to account.mojang.com/login.

  2. Find “Account Details” and select “Edit” on the “Password” line.

  3. Enter a new password in the “New” and “Repeat” fields.

  4. In the “Current” line, enter the existing password.

  5. Click the “Save” button for the changes to take effect.

Conclusion
Based on general data, it is recommended to change passwords once every 1-2 months to maintain confidentiality. Minecraft account. Write in the comments your impressions, problems encountered and share the information received with your friends. Rate the news! Thanks!

Video
We are waiting for your comments, do not hesitate to write us!

Account protection in multiplayer games cannot be achieved by any particular means. Most of the time, a password is used for these purposes, which the user thinks for himself so that he can then enter it and enter the game. Naturally, you need to remember this password, but at the same time, not tell anyone so that your account remains yours and no one can access it. If this still happened, that is, you found some evidence that someone else was using your account, you should contact the administration. Accounts are protected precisely according to this principle in all games, including the popular Minecraft sandbox. However, this game has its peculiarities when it comes to password change.

Reasons to change your password.
To get started, consider the most common reasons for changing your password. After all, if you understand that your password, in principle, suits you, you will not have to look for an answer to the question of how to change the password in Minecraft. Most of the time, a password change happens because the user has specified too simple a combination of characters, and therefore they are concerned that they could be easily hacked. It is better to act immediately if you understand that your account may be in jeopardy than to wait until this probability becomes a reality. However, there are also opposite situations: for security reasons, the user sets too complex a password and cannot remember it in any way. Even if you store this password on a piece of paper in front of the computer, it is not very convenient to enter a complex set of characters in the required field each time. Therefore, users prefer to change the password for a simpler one so as not to suffer. And then, the question of how to change the password in Minecraft becomes relevant.

Using the console
The password in this game can only be changed one way: using the game console. In many games, it is called a tilde, but here things are a bit different. If you want to find out how to change the password in “Minecraft,” you will have to go to the game and press not the checkmark but the bar. The difference is slight, but this can be a problem for those used to the standard hotkey. After the console line appears, you must enter the command “password,” which triggers the password change. Then you need to write the old character set with which you previously entered the game and then the new one; with your help, you will later activate your account. Now you know how to change password in Minecraft, but even with such a simple action,

Password verification error
When you change your password, you may receive an error that prevents you from entering the game. This can be a real problem, as you have most likely entered the wrong password. Maybe you made a mistake in a symbol, and it will be a real salvation for you if you made a mistake while trying to enter the game. Since if this happened at the password change stage, you will not be able to find out the entered character set. Also, you will not be able to change the password again as you will have to enter the old value that you do not know. As a result, you will need to contact the administration, so there are even unspoken rules on how to enter a password in Minecraft and other games. You need to check your password several times, make sure you remember it correctly, write it down, or even take a photo. What’s more, During registration, there are often two fields to enter a password for you to type the values ​​twice, and if you make a mistake in one field and type the password correctly in the other, the system will inform you about it. But let’s get back to how to change the password in Minecraft on the server if you can’t do it yourself.

Appeal to the administration
It is always a good idea to solve password problems yourself, as it is not the most challenging task. Asking administrators to change their password is inconvenient - they have many other more complex and essential tasks to think about. But if an emergency occurs, you can contact the administration, explain your situation and request a password change. Naturally, this will take much longer since the moderators will not receive your request immediately. They will have to process it, fulfill your wishes, and only then will you be able to log into the server again.

Additional funds
For those who are incredibly forgetful, there are particular additional fields in which you can select a secret question and type in an answer. You choose one for which only you can know the answer.

Too complex or straightforward combination to enter Minecraft often causes discomfort and inconvenience for the player, which is essential for those who have no idea how to change password in Minecraft.

Because it is necessary
There are many reasons to change the secret combination, the most popular of which are:
The user didn’t bother and initially created an easy password that would make it easy for an advanced hacker to hack into an account. If you suddenly realize that your account is in danger, you should immediately change the combination and protect yourself from trouble.

The player came up with a long password and couldn’t remember it. And even if you keep it written on a piece of paper, it is highly inconvenient to enter a massive list of letters and signs every day. In this case, it is better to change the password to a complex but memorable one.

How to make a change
The change procedure is quite simple:
Log in to the game with your old password.

Press the “/” symbol on the keyboard, while the English layout must be enabled.

A line will appear on the monitor where you must enter: “/ password.” The old and new passwords are your old and new passwords. Password characters must be entered with a space between them. Exclude unnecessary characters as well as " signs.

After entering all the required values, press the “Enter” key on the keyboard.

The user will be notified of the successful password change in Minecraft with the corresponding message.

If the procedure fails on the first try, try again. If you have any difficulties, use the help of the service administrator. Be prepared for the fact that the answer will have to wait.

The process of changing the password is simple. Still, to not forget it or give a reason for scammers to hack into your account due to too simple a combination, you need to approach the task with full responsibility.
https://sites.google.com/view/minecraft-help-centre/

#minecraft password reset #change minecraft username #change minecraft name

What is GEEK

Buddha Community

Shweta Kurra

1631011395

Thanks a lot for sharing this post 

Norton Customer Service

mani loviel

1622271947

18885970064 | Minecraft Password Reset | Change Minecraft Username | Change Minecraft Name

How to recover Minecraft account How to recover Minecraft account
Minecraft is a top-rated game where you can benefit significantly if you have a premium account by accessing servers and straightforwardly playing with your friends.

But maybe you haven’t used your account for a long time, or you’ve forgotten your password, and you want to know how to recover your Minecraft account.

Here we have created a complete guide so that you can regain access to it in any way since there are many mechanisms to do so, and here we are going to show you all of them.

Did you identify me with an email address or my username?
In Minecraft, there are two types of accounts, one granted by Minecraft itself and another by Mojang:

All Minecraft accounts created after Fall 2012, or those that were migrated from the old format to the Mojang platform, use an email to identify themselves.

While the old accounts that users have not migrated continue to use the username to enter.

You must know what type of accounts you have to know how to continue with this tutorial.

What if I lost my password?
If you have lost your password because you do not remember where you wrote it down, or it was stolen (that is, your password was changed), there is a way to recover it quickly:

If old accounts have not been migrated (those that use a username to enter), you must visit the site to migrate accounts to Mojang.

Migrate account to Mojang Migrate account to Mojang

The steps are the following:

  1. We enter the email of our account

  2. We enter the username of our account

  3. We enter the password of our account

  4. We enter the new email for our new account

  5. We re-enter the new email for our new account

  6. We put our date of birth

  7. We accept the terms and conditions by checking the box

  8. We click on the migrate account button

If we want to recover the account with the lost password, we have to go to the following page: https://my.minecraft.net/es-es/password/forgot/.

Recover Minecraft Password Recover Minecraft Password

Where we enter our email as indicated, and then we click the request button.

The steps are straightforward from here since we are sent to the address of our account (which must be transparent). All the steps to change it and continue enjoying the game.

What happens if I don’t remember my email address?
If we already have our Mojang account migrated, there is a little trick if we forget which of all our mailboxes is the one we use to register.

We go to the same address to recover the password, and we begin to test all the email addresses that we know to reset our password. Finally, we will get where we have registered.

I don’t remember what my username was like
Just log in to the Mojang-type Minecraft account, and we’ll see the username within the game, either on the account page on the site or in the Minecraft client before launching the game.

I’m still having trouble getting my account back.
You can leave us a comment below, and we will try to help you as soon as possible. Keep in mind that we are not Mojang and our advice goes as far as what any user can do.

We also recommend that you contact the team behind Minecraft to help you with their support system, which you can write to here.

Contact Minecraft to recover lost account Contact Minecraft to recover a lost account.

It is entirely in Spanish, so you will have no problem completing the required information (marked with a red asterisk) and some others that will help make the process easier for them and you.

Command for Minecraft when I forgot the password. Change the password on the Minecraft server through your account and on the client. Password requirements
Minecraft: infinite cubic meters. Walk do not cross. The most cherished dream of any gamer is a true fan of sandbox games. And the progress of development in it captures and the extraction of valuable wealth resources and the manufacture of various items and battles with mobs. And then no kidding, these are just the main points. A large, thick book can be dedicated to all the delights of Minecraft.

On forums, blogs, YouTube video reviews, players compete to show off their Minecraft achievements: “Look what I built!”, “This is how I earned this location!”, “Look what I found!” “Do you know those crafting recipes??!”

For some reason, that’s it. Oh yeah, all these virtual Minecraft honors, medals, and treasures can be lost in an instant! And it’s not because you didn’t get by with the game, climbed somewhere in the wrong place, or someone “squeezed” you hard … It’s all so much sadder and easier! And because you came up with a simple password, and on the server, someone picked it up, knowing your username. Or maybe the password was complicated because some kind of virus stole it. And that’s it, goodbye, your hero passed at the disposal of another player. You understand what the consequences of this situation can be. In short, nothing good.

So, to be safe from these misfortunes, read this article. From it, you will learn how to change your password offline and directly on the server, what to do if you have forgotten it, which login key is more resistant to hacking.

  1. Do not use the “most popular” combinations on the Internet: qwerty, 12345, abcdefg, myparol. Attackers can manually pick them up within 5 minutes and consequently take over the account in a treacherous way.

  2. Avoid minor keys. The optimal password length is 10-16 characters.

  3. Alternate numbers, special characters, and English letters (lowercase and uppercase) in a symbolic sequence.

  4. When registering and changing the password, do not specify the combination you use to access another online service (for example, VKontakte). You risk losing two accounts at once if your key is stolen.

Server
The password change can be done during the game.

  1. Make sure the English keyboard layout is enabled. Press the “/” key to open the console.

  2. To change the password in Minecraft, enter the command:

/ change password (old password) (new)

Attention! Symbolic keys do not need to be in parentheses when entering a command.

If the operation were successful, a message would appear on the console about its successful completion. You can now enter the game using the new authorization data.

If you don’t remember the token key you used to log in, contact the technical support of the server you are playing on with a request to restore access. Or use the particular reset function in the service office. For example, you can change the password on the website on the Rus-Minecraft portal: rus-minecraft.ru/lost-password/.

Official site Minecraft.net

  1. On the login panel, in the error message block, click the link “Forgot your password?” (I forget… ?).

  2. In the “Email” line, enter the email address that you specified in the process of creating your account.

  3. Click the “Request password reset” button.

  4. Go to email, open message from Mojang (game developer) service.

  5. On the page that opens in the browser, enter the new symbolic combination 2 times for authorization.

  6. Click “Reset Password.”

The procedure is complete. Now you can go to your profile on minecraft.net.

And you need to change the password of minecraft.net in the Mojang office. To complete this procedure:

  1. In the “Account details” option block, on the “Password…” line, click the “Edit” command.

  2. Enter a new password in the “New…” and “Repeat” fields.

  3. In the line "Current… " enter the current password.

Change your Minecraft profile password about once every 1-2 months. Exciting game and, most importantly, safe!

Without constant access to high-speed Internet in the modern world, it is essential to be connected to the Internet through your computer or phone at home or work. But if there is a router and wifi in the room where you are, you cannot connect because you do not know the password and cannot ask anyone. There are several ways to find out your wifi password if you forgot it or cannot connect for other reasons. In this article, we will look at the main ways to solve this problem in this situation.

So, we will tell you how to remember your Internet password on the Windows system, starting with seven and above and how to view the password of all networks that have been saved on the device.

We will also tell you what to do in a situation if a device (phone, tablet, computer) has Internet, but you need to connect to another device, and the password is lost or forgotten. And we will tell you how to find out your password if you have a router handy.

Router password
This method of viewing the password from wifi can be helpful if you remember exactly that you did not change the standard password as soon as you bought and connected the router. Also, the standard password of the router is often left for the Internet, which is connected in a rented apartment. This is done so that the next tenant can easily connect to the Internet, and the landlord does not have to explain the password.

Therefore, if you drove to a new apartment and the landlord did not tell you the Internet pin, first try to find the password on the router. It is worth noting that not all routers have a written password; this works mainly with the newer models.

Usually, the PIN code by which you can connect to the router consists of 8 digits. They are printed on the back of the router on a label that also contains information about the service and the serial number. Take a good look. There must be the word PIN on the label, followed by numbers.

Code saved on PC
If you have a laptop on hand with a saved password and the laptop connects to the Internet without any problem and does it automatically, you may have forgotten the password on this network a long time ago. But the time comes when you need to connect another device to the Internet: a purchased phone or a device from a friend or guest who has come to you and wants to use a wireless network. So not knowing the network password can become a real problem. But you can look at the code from the laptop. Different versions of Windows do this differently, so we give detailed instructions for each option.

Windows 10 y Windows 8
To understand how to find out the wi-fi password, you must be connected to it. Then do the following:

You now know your password and can connect other devices to the Internet using it.

In Windows 7
To view the password stored on the computer connected to Windows 7, you must do the following:

If the wireless network is not connected
In the methods of how to view the wi-fi password described by us above, it is assumed that you have a network connection from which you need a password, but if there is no connection, you can view the password through the command line.

If the password is not on the computer
Even if the password is not saved on your PC, but you can connect the computer directly to the router, there is a way to see the password.

This can happen if the computer crashes or you reinstall the Windows system, and now you don’t remember the password for your network that your computer was previously connected to. But you have physical access to the router.

To find out the password in this case, you need to connect the router to the computer via a cable. This is done through the router’s LAN connector, connected to the computer’s network card. When you are connected, you need to go to the settings of the router. You can log in using a standard password and login; it should be written on the back of your router.

If you were able to go to the router settings, you need to find the wireless settings. They are usually found in the wifi settings item and are called Wireless. It is in this configuration that you can see the password of the network that this router distributes.

However, this method has a drawback. During the initial configuration of the router, the password or login used to enter the configuration through the computer can be changed. Sometimes vendor tech support does this. Ordinary users rarely change something in factory settings when setting up a router.

Then, if you don’t know the new username or password, you won’t be able to enter the settings and see the network code. In this case, a factory reset is required. You can read about how to do this below.

Code saved in Android.
To view the network password that you have saved on your phone or tablet running on the Android system, you need to have root access to the device.

If you have such access, you should go to the data / misc / wifi folder. This can be done through ES Explorer, Root Explorer or another file manager installed on your phone. In the folder, you need to find the text file wpa_supplicant.conf. This file will record all the data about the networks you have connected to. Your password will be the psk parameter.

You can also download a program from the app store that will display the passwords for the stored networks on your phone. A similar program is wifi Password (ROOT), but many analogs are in the app store. You can choose what suits you best in this case.

Minecraft Password reset
If you have tried all the methods we described in the previous article, and you cannot figure out how to find out the wifi network password because none of the listed methods work, you will have to reset the password and set a new one. This will help, for example, if you cannot enter the router settings because someone changed your password. However, this only works if you have physical access to the router. That is, to reset the Internet password and set a new one, you must be the owner of the router and the network itself.

It is immediately worth noting that this method has a significant disadvantage. Find out in advance if your ISP uses unique settings to connect to the network. If you do, you will have to call the wizard again and configure the Internet yourself. Or you can do it yourself by following the instructions of the provider’s call center specialist.

To reset the password, you need to look at the back of the router, in which there are buttons with which you can control the router and ports for entering cables from the Internet. You should find the reset button; there will be a reset signature next to it in most cases.

This button can be pressed with a thin paper clip or needle and held down for about 10 seconds. If this method did not work, you need to hold down the button, turn off the router for about half a minute. All this time, you need to hold down the button. After that, while holding the reset button, you need to turn on the router and hold the reset button for about half a minute.

After that, all the settings that were on the router need to be reset. And the password of the router will now be the one written on the back of the router.

After resetting the settings, you need to reconnect the router to the network for everything to work. You can call the provider’s assistant or see how to connect the router in the instructions for it. But the last method works only if your provider doesn’t use unique settings.

conclusions
As you can see, there are many ways to find out your wifi password, but they all work in different cases. Remember that you can always reset the settings as a last resort, but then you will have to reinstall it so that the router can distribute your Internet.

If you know more ways to view the password, you can write them in the comments so that other users can quickly solve your problem.

If this happens, you must immediately change the password. And then, we will tell you how to change the password in Minecraft on the server. By the way, this action is effortless in all multiplayer games. In our case, everything is the same, but with the peculiarities of changing the password, which can sometimes cause difficulties.

Frequently, users want to change their password because this combination of characters seems simple, and therefore they start to worry about the threat of a hack. This is what should be done, rather than waiting for the situation to get worse. It happens that players create very complex passwords that they cannot remember. And then they can’t log into their accounts. There is only one way out: change the password to a more memorable one. Therefore, you need to know how to change the access code, as well as based on what criteria to choose it.

How to enter a password correctly?
In no case should you use the combinations that have become so popular on the Internet (23456, myparols, ertyui)? Any expert cracker can quickly crack them and take over the account.

Use long keys, preferably long ones. The correct option is 10 to 16 characters.

A sequence of numbers, special characters, and English letters (uppercase and lowercase).

It is recommended not to take existing passwords that are used in other services. There is a risk of losing all accounts if your keys are stolen.

How do I change my server password in Minecraft?
There is the possibility of changing the password during the game. For this:

If the password used for authorization was lost, the player must contact the game server technical support to restore access. It is also possible to reset the data by going to the main Minecraft website.

Sometimes when logging into your account, an error appears identifying the data entered incorrectly. Now you have to reset the password:

  1. You must click on the inscription “Forgot your password?” Did you forget your password? It’s next to the login panel in the login error box.

  2. In the “Email” field, enter your current email address assigned to your account in the system.

  3. Click “Request password reset.”

  4. Open your inbox and find the email sent by Mojang (the game developer).

  5. In the letter, you need to click on the website address.

  6. A browser window will open in front of you, in which you will need to enter a new password twice.

  7. It remains to click “Reset password.”

After graduation, you should take the opportunity to log into your account. By the way, to change the password for minecraft.net, you need to go to the Mojang resource. The steps should be followed as follows:

  1. Log in to account.mojang.com/login.

  2. Find “Account Details” and select “Edit” on the “Password” line.

  3. Enter a new password in the “New” and “Repeat” fields.

  4. In the “Current” line, enter the existing password.

  5. Click the “Save” button for the changes to take effect.

Conclusion
Based on general data, it is recommended to change passwords once every 1-2 months to maintain confidentiality. Minecraft account. Write in the comments your impressions, problems encountered and share the information received with your friends. Rate the news! Thanks!

Video
We are waiting for your comments, do not hesitate to write us!

Account protection in multiplayer games cannot be achieved by any particular means. Most of the time, a password is used for these purposes, which the user thinks for himself so that he can then enter it and enter the game. Naturally, you need to remember this password, but at the same time, not tell anyone so that your account remains yours and no one can access it. If this still happened, that is, you found some evidence that someone else was using your account, you should contact the administration. Accounts are protected precisely according to this principle in all games, including the popular Minecraft sandbox. However, this game has its peculiarities when it comes to password change.

Reasons to change your password.
To get started, consider the most common reasons for changing your password. After all, if you understand that your password, in principle, suits you, you will not have to look for an answer to the question of how to change the password in Minecraft. Most of the time, a password change happens because the user has specified too simple a combination of characters, and therefore they are concerned that they could be easily hacked. It is better to act immediately if you understand that your account may be in jeopardy than to wait until this probability becomes a reality. However, there are also opposite situations: for security reasons, the user sets too complex a password and cannot remember it in any way. Even if you store this password on a piece of paper in front of the computer, it is not very convenient to enter a complex set of characters in the required field each time. Therefore, users prefer to change the password for a simpler one so as not to suffer. And then, the question of how to change the password in Minecraft becomes relevant.

Using the console
The password in this game can only be changed one way: using the game console. In many games, it is called a tilde, but here things are a bit different. If you want to find out how to change the password in “Minecraft,” you will have to go to the game and press not the checkmark but the bar. The difference is slight, but this can be a problem for those used to the standard hotkey. After the console line appears, you must enter the command “password,” which triggers the password change. Then you need to write the old character set with which you previously entered the game and then the new one; with your help, you will later activate your account. Now you know how to change password in Minecraft, but even with such a simple action,

Password verification error
When you change your password, you may receive an error that prevents you from entering the game. This can be a real problem, as you have most likely entered the wrong password. Maybe you made a mistake in a symbol, and it will be a real salvation for you if you made a mistake while trying to enter the game. Since if this happened at the password change stage, you will not be able to find out the entered character set. Also, you will not be able to change the password again as you will have to enter the old value that you do not know. As a result, you will need to contact the administration, so there are even unspoken rules on how to enter a password in Minecraft and other games. You need to check your password several times, make sure you remember it correctly, write it down, or even take a photo. What’s more, During registration, there are often two fields to enter a password for you to type the values ​​twice, and if you make a mistake in one field and type the password correctly in the other, the system will inform you about it. But let’s get back to how to change the password in Minecraft on the server if you can’t do it yourself.

Appeal to the administration
It is always a good idea to solve password problems yourself, as it is not the most challenging task. Asking administrators to change their password is inconvenient - they have many other more complex and essential tasks to think about. But if an emergency occurs, you can contact the administration, explain your situation and request a password change. Naturally, this will take much longer since the moderators will not receive your request immediately. They will have to process it, fulfill your wishes, and only then will you be able to log into the server again.

Additional funds
For those who are incredibly forgetful, there are particular additional fields in which you can select a secret question and type in an answer. You choose one for which only you can know the answer.

Too complex or straightforward combination to enter Minecraft often causes discomfort and inconvenience for the player, which is essential for those who have no idea how to change password in Minecraft.

Because it is necessary
There are many reasons to change the secret combination, the most popular of which are:
The user didn’t bother and initially created an easy password that would make it easy for an advanced hacker to hack into an account. If you suddenly realize that your account is in danger, you should immediately change the combination and protect yourself from trouble.

The player came up with a long password and couldn’t remember it. And even if you keep it written on a piece of paper, it is highly inconvenient to enter a massive list of letters and signs every day. In this case, it is better to change the password to a complex but memorable one.

How to make a change
The change procedure is quite simple:
Log in to the game with your old password.

Press the “/” symbol on the keyboard, while the English layout must be enabled.

A line will appear on the monitor where you must enter: “/ password.” The old and new passwords are your old and new passwords. Password characters must be entered with a space between them. Exclude unnecessary characters as well as " signs.

After entering all the required values, press the “Enter” key on the keyboard.

The user will be notified of the successful password change in Minecraft with the corresponding message.

If the procedure fails on the first try, try again. If you have any difficulties, use the help of the service administrator. Be prepared for the fact that the answer will have to wait.

The process of changing the password is simple. Still, to not forget it or give a reason for scammers to hack into your account due to too simple a combination, you need to approach the task with full responsibility.
https://sites.google.com/view/minecraft-help-centre/

#minecraft password reset #change minecraft username #change minecraft name

Ethen Ellen

1616393382

Thumbs Up To New Trick of Reset Verizon Email Password

This is image title
Verizon Email is one of the most trusted email services in the entire world. It is installed with more security features and optional email services such as AOL, Outlook, Gmail or Yahoo Email. If you want to use your Verizon email account, first of all, you have to create an account. After that, you will login to your account with your username and password. Through these identities, you can access your Verizon account and enjoy all other activities provided by Verizon email.

But sometimes, If your Verizon account is hacked or blocked by someone else, you can easily login to your email account by resetting your Verizon email password. If you do not understand how to Reset Verizon Email Password. Then, you can contact Verizon Email Support Expert via a toll-free number (888-857-5157). Our experienced professionals can fix any type of issue in a few minutes.

Solutions to Reset Verizon Mail Password (Known Password)

If you remember your current password then you have to continue to process it. As well as known your login details you can follow the steps below to reset verizon mail password.

Step 1: First of all, you need to open your browser and log in to your Verizon email account.

Step 2: In the next step, you have to navigate to Account Settings from the main menu.

Step 3: After that, you have to open security settings and choose “Change Password”.

Step 4: Input your current password in the field provided.

Step 5: Finally, you will click on the next field and type in a new password for your Verizon mail account.

Once you are confirmed that your password has changed, you can close the browser and log in to your mail account using your new Verizon email password.

Solution to reset the Verizon Mail password (Forgot password)

If you need to reset your password because you do not remember your current mail password, the steps will vary as you will have to verify your identity before changing the password, you will have to reset your Verizon mail password. You can use the ‘Forgot Password’ option:

Step 1: First of all, you will go to the Verizon Mail website and click on ‘Forgot Password’.

Step 2: After that, input your username and choose the recovery method (Mail / Phone).

Step 3: Input on the mobile number associated with your Verizon mail account.

Step 4: Press ‘Yes’ to allow Verizon to send you a verification code.

Step 5: You will type a security verification code in the field provided.

Step 6: Then, press ‘Submit’ and wait for Verizon to confirm the code.

Step 7: In the last, create a new password for your Verizon account by completing the instructions on the screen.

If you encounter any problems while resetting a Verizon email password, you can call a Verizon Email Support Number (888-857-5157) and seek advice from a certified expert to resolve the issue. Experts from Verizon are available 24 * 7 hours, which will help you to fix any problems encountered using Verizon’s email account.

Source: https://sites.google.com/view/verizon-key-settings

#change verizon email password #reset verizon email password #change verizon mail password #reset verizon mail password #change verizon password #reset verizon password

Ayan Code

1656193861

Simple Login Page in HTML and CSS | Source Code

Hello guys, Today in this post we’ll learn How to Create a Simple Login Page with a fantastic design. To create it we are going to use pure CSS and HTML. Hope you enjoy this post.

A login page is one of the most important component of a website or app that allows authorized users to access an entire site or a part of a website. You would have already seen them when visiting a website. Let's head to create it.

Whether it’s a signup or login page, it should be catchy, user-friendly and easy to use. These types of Forms lead to increased sales, lead generation, and customer growth.


Demo

Click to watch demo!

Simple Login Page HTML CSS (source code)

<!DOCTYPE html>
  <html lang="en" >
  <head>
    <meta charset="UTF-8">
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/normalize/5.0.0/normalize.min.css">
  <link rel="stylesheet" href="styledfer.css">
  </head>

  <body>
   <div id="login-form-wrap">
    <h2>Login</h2>
    <form id="login-form">
      <p>
      <input type="email" id="email" name="email" placeholder="Email " required><i class="validation"><span></span><span></span></i>
      </p>
      <p>
      <input type="password" id="password" name="password" placeholder="Password" required><i class="validation"><span></span><span></span></i>
      </p>
      <p>
      <input type="submit" id="login" value="Login">
      </p>

      </form>
    <div id="create-account-wrap">
      <p>Don't have an accout? <a href="#">Create One</a><p>
    </div>
   </div>
    
  <script src='https://code.jquery.com/jquery-2.2.4.min.js'></script>
  <script src='https://cdnjs.cloudflare.com/ajax/libs/jquery-validate/1.15.0/jquery.validate.min.js'></script>
  </body>
</html>

CSS CODE

body {
  background-color: #020202;
  font-size: 1.6rem;
  font-family: "Open Sans", sans-serif;
  color: #2b3e51;
}
h2 {
  font-weight: 300;
  text-align: center;
}
p {
  position: relative;
}
a,
a:link,
a:visited,
a:active {
  color: #ff9100;
  -webkit-transition: all 0.2s ease;
  transition: all 0.2s ease;
}
a:focus, a:hover,
a:link:focus,
a:link:hover,
a:visited:focus,
a:visited:hover,
a:active:focus,
a:active:hover {
  color: #ff9f22;
  -webkit-transition: all 0.2s ease;
  transition: all 0.2s ease;
}
#login-form-wrap {
  background-color: #fff;
  width: 16em;
  margin: 30px auto;
  text-align: center;
  padding: 20px 0 0 0;
  border-radius: 4px;
  box-shadow: 0px 30px 50px 0px rgba(0, 0, 0, 0.2);
}
#login-form {
  padding: 0 60px;
}
input {
  display: block;
  box-sizing: border-box;
  width: 100%;
  outline: none;
  height: 60px;
  line-height: 60px;
  border-radius: 4px;
}
#email,
#password {
  width: 100%;
  padding: 0 0 0 10px;
  margin: 0;
  color: #8a8b8e;
  border: 1px solid #c2c0ca;
  font-style: normal;
  font-size: 16px;
  -webkit-appearance: none;
     -moz-appearance: none;
          appearance: none;
  position: relative;
  display: inline-block;
  background: none;
}
#email:focus,
#password:focus {
  border-color: #3ca9e2;
}
#email:focus:invalid,
#password:focus:invalid {
  color: #cc1e2b;
  border-color: #cc1e2b;
}
#email:valid ~ .validation,
#password:valid ~ .validation 
{
  display: block;
  border-color: #0C0;
}
#email:valid ~ .validation span,
#password:valid ~ .validation span{
  background: #0C0;
  position: absolute;
  border-radius: 6px;
}
#email:valid ~ .validation span:first-child,
#password:valid ~ .validation span:first-child{
  top: 30px;
  left: 14px;
  width: 20px;
  height: 3px;
  -webkit-transform: rotate(-45deg);
          transform: rotate(-45deg);
}
#email:valid ~ .validation span:last-child
#password:valid ~ .validation span:last-child
{
  top: 35px;
  left: 8px;
  width: 11px;
  height: 3px;
  -webkit-transform: rotate(45deg);
          transform: rotate(45deg);
}
.validation {
  display: none;
  position: absolute;
  content: " ";
  height: 60px;
  width: 30px;
  right: 15px;
  top: 0px;
}
input[type="submit"] {
  border: none;
  display: block;
  background-color: #ff9100;
  color: #fff;
  font-weight: bold;
  text-transform: uppercase;
  cursor: pointer;
  -webkit-transition: all 0.2s ease;
  transition: all 0.2s ease;
  font-size: 18px;
  position: relative;
  display: inline-block;
  cursor: pointer;
  text-align: center;
}
input[type="submit"]:hover {
  background-color: #ff9b17;
  -webkit-transition: all 0.2s ease;
  transition: all 0.2s ease;
}

#create-account-wrap {
  background-color: #eeedf1;
  color: #8a8b8e;
  font-size: 14px;
  width: 100%;
  padding: 10px 0;
  border-radius: 0 0 4px 4px;
}

Congratulations! You have now successfully created our Simple Login Page in HTML and CSS.

My Website: codewithayan, see this to checkout all of my amazing Tutorials.

Rust  Language

Rust Language

1652510548

The Rust Programming Language - Macros

Rust Macros

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:

  • Custom #[derive] macros that specify code added with the derive attribute used on structs and enums
  • Attribute-like macros that define custom attributes usable on any item
  • Function-like macros that look like function calls but operate on the tokens specified as their argument

We’ll talk about each of these in turn, but first, let’s look at why we even need macros when we already have functions.

The Difference Between Macros and 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.

Declarative Macros with macro_rules! for General Metaprogramming

The 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.

Procedural Macros for Generating Code from Attributes

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.

How to Write a Custom derive Macro

Let’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

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

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 {

Summary

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.


Macros By Example

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.

Transcribing

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);
}

Metavariables

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:

In 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.

Repetitions

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:

  1. A metavariable must appear in exactly the same number, kind, and nesting order of repetitions in the transcriber as it did in the matcher. So for the matcher $( $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.
  2. Each repetition in the transcriber must contain at least one metavariable to decide how many times to expand it. If multiple metavariables appear in the same repetition, they must be bound to the same number of fragments. For instance, ( $( $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.

Scoping, Exporting, and Importing

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

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.
}

The macro_use attribute

The 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.

Path-Based Scope

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.

Hygiene

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 and local_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 or local_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 {
    () => { () }
}
}

Follow-set Ambiguity Restrictions

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.
  • All other fragment specifiers have no restrictions.

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:

  • If the repetition includes a separator, that separator must be able to follow the contents of the repetition.
  • If the repetition can repeat multiple times (* or +), then the contents must be able to follow themselves.
  • The contents of the repetition must be able to follow whatever comes before, and whatever comes after must be able to follow the contents of the repetition.
  • If the repetition can match zero times (* or ?), then whatever comes after must be able to follow whatever comes before.


Macros in Rust: A tutorial with examples

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.

What are Rust macros?

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.

Types of macros in Rust

Rust has two types of macros:

  1. Declarative macros enable you to write something similar to a match expression that operates on the Rust code you provide as arguments. It uses the code you provide to generate code that replaces the macro invocation
  2. Procedural macros allow you to operate on the abstract syntax tree (AST) of the Rust code it is given. A proc macro is a function from a TokenStream (or two) to another TokenStream, where the output replaces the macro invocation

Let’s zoom in on both declarative and procedural macros and explore some examples of how to use macros in Rust.

Declarative 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.

Creating declarative macros

// 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 statement
  • pat — a pattern
  • expr — an expression
  • ty — a type
  • ident — an identifier
  • path — a path (e.g., foo, ::std::mem::replace, transmute::<_, int>, …)
  • meta — a meta item; the things that go inside #[...] and #![...] attributes
  • tt — a single token tree
  • vis — a possibly empty Visibility qualifier

In 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:

  1. The first arms handle the case if a single argument is passed
  2. The second one handles the case if two arguments are passed
  3. The third arm calls the add macro again with the rest of the arguments

The 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(())
}

Advanced parsing in Rust with declarative macros

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.

Parsing the name and field of a struct

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,
                )*
            }
        }
    }
}

Parsing metadata from the 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,
    }
}

Limitations of declarative macros

Declarative macros have a few limitations. Some are related to Rust macros themselves while others are more specific to declarative macros.

  • Lack of support for macros autocompletion and expansion
  • Debugging declarative macros is difficult
  • Limited modification capabilities
  • Larger binaries
  • Longer compile time (this applies to both declarative and procedural macros)

Procedural macros in Rust

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:

  1. Attribute-like macros
  2. Derive macros
  3. Function-like macros

We’ll go into each procedural macro type in detail below.

Attribute-like macros

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.

synprovides 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

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

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:

  • Better error handling using span
  • Better control over output
  • Community-built crates syn and quote
  • More powerful than declarative macros

Conclusion

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 

Rust  Language

Rust Language

1656924529

Macros in Rust - Everything You Need To Know

Macros in Rust - Everything You Need To Know

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.


macro_rules!

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)


Macros

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:

  • Custom #[derive] macros that specify code added with the derive attribute used on structs and enums
  • Attribute-like macros that define custom attributes usable on any item
  • Function-like macros that look like function calls but operate on the tokens specified as their argument

We’ll talk about each of these in turn, but first, let’s look at why we even need macros when we already have functions.

The Difference Between Macros and 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.

Declarative Macros with macro_rules! for General Metaprogramming

The 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.

Procedural Macros for Generating Code from Attributes

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.

How to Write a Custom derive Macro

Let’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

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

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.

Summary

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.


Macros in Rust: A tutorial with examples

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.

What are Rust macros?

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.

Types of macros in Rust

Rust has two types of macros:

  1. Declarative macros enable you to write something similar to a match expression that operates on the Rust code you provide as arguments. It uses the code you provide to generate code that replaces the macro invocation
  2. Procedural macros allow you to operate on the abstract syntax tree (AST) of the Rust code it is given. A proc macro is a function from a TokenStream (or two) to another TokenStream, where the output replaces the macro invocation

Let’s zoom in on both declarative and procedural macros and explore some examples of how to use macros in Rust.

Declarative 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.

Creating declarative macros

// 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 statement
  • pat — a pattern
  • expr — an expression
  • ty — a type
  • ident — an identifier
  • path — a path (e.g., foo, ::std::mem::replace, transmute::<_, int>, …)
  • meta — a meta item; the things that go inside #[...] and #![...] attributes
  • tt — a single token tree
  • vis — a possibly empty Visibility qualifier

In 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:

  1. The first arms handle the case if a single argument is passed
  2. The second one handles the case if two arguments are passed
  3. The third arm calls the add macro again with the rest of the arguments

The 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(())
}

Advanced parsing in Rust with declarative macros

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.

Parsing the name and field of a struct

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.

Parsing Struct Name Field Diagram

 

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.

Make Struct Public with Keyword

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,
                )*
            }
        }
    }
}

Parsing metadata from the 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,
    }
}

Limitations of declarative macros

Declarative macros have a few limitations. Some are related to Rust macros themselves while others are more specific to declarative macros.

  • Lack of support for macros autocompletion and expansion
  • Debugging declarative macros is difficult
  • Limited modification capabilities
  • Larger binaries
  • Longer compile time (this applies to both declarative and procedural macros)

Procedural macros in Rust

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:

  1. Attribute-like macros
  2. Derive macros
  3. Function-like macros

We’ll go into each procedural macro type in detail below.

Attribute-like macros

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.

synprovides 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

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

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:

  • Better error handling using span
  • Better control over output
  • Community-built crates syn and quote
  • More powerful than declarative macros

Conclusion

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