Делаем макросы в Rust

Привет, Хабр!

Rust имеет два основных типа макросов: декларативные и процедурные. Каждый из этих типов служит различным целям и предоставляет различные возможности манипуляции с кодом.

Декларативные макросы работают, сопоставляя заданные шаблоны с фактическим кодом и заменяя его на другой код во время компиляции. Что-то вроде хорошей системы поиска и замены, но для исходного кода. Декларативные макросы подходят для задач, когда нужно избежать дублирования кода или когда нужно предоставить удобный синтаксис для повторяющихся задач.

А вот процедурные макросы уже имеют больше возможностей, они позволяют манипулировать абстрактным синтаксическим деревом кода, т.е можно анализировать, модифицировать и генерировать код на лету. Процедурные макросы могут быть разделены на три категории: атрибутивные макросы, макросы производных и функциональные макросы.

В этой статье мы как раз и рассмотрим то, как их пишут на Rust.

Начнем с декларативных!

Декларативные макросы

Итак, декларативные макросы в Раст позволяют создавать код, похожий на выражение match в Rust, где значение сравнивается с шаблонами и выполняется код, связанный с соответствующим шаблоном. Это происходит во время компиляции. Для определения макроса используется конструкция macro_rules!. Например, макрос vec! позволяет создавать новый вектор с указанными значениями:

Пример определения макроса vec!:

#[macro_export] macro_rules! vec {     ( $( $x:expr ),* ) => {         {             let mut temp_vec = Vec::new();             $(                 temp_vec.push($x);             )*             temp_vec         }     }; }

Макрос может принимать любое количество аргументов любого типа и генерировать код для создания вектора, содержащего указанные элементы. Структура тела макроса vec! аналогична структуре выражения match. Здесь мы видим один вариант с шаблоном ( $( $x:expr ),* ), за которым следует блок кода, связанный с этим шаблоном. Если шаблон совпадает, будет сгенерирован ассоциированный блок кода.

Рассмотрим макрос power!, который может вычислять квадрат или куб числа:

macro_rules! power {     ($value:expr, squared) => { $value.pow(2_i32) };     ($value:expr, cubed) => { $value.pow(3_i32) }; }

Здесь выполняется множественное соответствие, позволяя макросу захватывать различные уровни специфичности. Важно правильно упорядочить правила соответствия, чтобы избежать неверного сопоставления!

Макросы могут принимать переменное количество входных данных. Например, вызов vec![2] или vec![1, 2, 3] использует операторы повторения подобно Regex. Чтобы добавить n чисел, можно использовать следующую конструкцию:

macro_rules! adder {     ($($right:expr),+) => {{     let mut total: i32 = 0;     $(          total += $right;     )+     total }};

В данном случае мы суммируем все переданные значения. + после фрагмента кода указывает, что данный фрагмент может повторяться один или более раз​​.

Макросы могут требовать разделителей между повторяющимися элементами:

macro_rules! no_trailing {     ($($e:expr),*) => {} };  macro_rules! with_trailing {     ($($e:expr,)*) => {} };  macro_rules! either {     ($($e:expr),* $(,)*) => {} };

Для выполнения нескольких действий внутри макроса, как вы уже наверное заметили, используются двойные фигурные скобки:

macro_rules! etwas {     ($value:expr, squared) => {{          let x: u32 = $value;         x.pow(2)     }} };

Можно обрабатывать несколько наборов повторяющихся данных, используя контекст для определения количества повторений для каждого набора данных:

macro_rules! operations {     (add $($addend:expr),+; mult $($multiplier:expr),+) => {{         let mut sum = 0;         $(             sum += $addend;          )*           let mut product = 1;          $(               product *= $multiplier;           )*            println!("Sum: {} | Product: {}", sum, product);     }}  };

Процедурные макросы

Процедурные макросы в Rust должны быть определены в отдельных крейтах с типом proc-macro в Cargo.toml файле. Процедурные макросы делятся на три основных типа: функциональные, пользовательские derive и атрибутивные​​​​​​.

Для работы с процедурными макросами нужно будет создать отдельный крейт с типом proc-macro в Cargo.toml файле:

[lib] proc-macro = true

И добавить зависимости syn и quote для парсинга входящих TokenStream и генерации выходного кода.

Функциональные макросы

Функциональные макросы в Rust позволяют создавать расширения языка, которые могут принимать код Rust в качестве входных данных и генерировать код Rust в качестве выходных данных. Они похожи на функции в том смысле, что вызываются с использованием оператора ! и выглядят как вызовы функций. Пример простого функционального макроса:

extern crate proc_macro; use proc_macro::TokenStream;  #[proc_macro] pub fn my_fn_like_proc_macro(input: TokenStream) -> TokenStream {     // логика обработки входного TokenStream     // и генерации нового TokenStream.     input }

Макрос my_fn_like_proc_macro принимает TokenStream в качестве входных данных (который представляет собой код, переданный в макрос) и возвращает TokenStream в качестве выходных данных (который является кодом Rust, сгенерированным макросом).

Предположим, мы хотим создать макрос, который читает имя переменной и возвращает строку с этим именем:

use proc_macro::TokenStream; use quote::quote; use syn::{parse_macro_input, Ident};  #[proc_macro] pub fn var_name(input: TokenStream) -> TokenStream {     let input_parsed = parse_macro_input!(input as Ident);          let name = input_parsed.to_string();          let expanded = quote! {         {             let my_var_name = stringify!(#input_parsed);             println!("Переменная: {}, значение: {}", #name, my_var_name);         }     };      TokenStream::from(expanded) }

Юзаем крейты syn для парсинга входных данных макроса в AST и quote для генерации кода Rust на основе этого AST. Макрос var_name принимает имя переменной и генерирует код, который выводит имя этой переменной и её значение.

Чтобы использовать этот макрос, нужно написать в коде:

let my_variable = 42; var_name!(my_variable);

Это вызовет макрос var_name, который сгенерирует код для печати имени и значения переменной my_variable.

Пользовательские derive макросы

Пользовательские derive макросы в Rust позволяют автоматически реализовывать определенные трейты для структур или перечислений.

Создадим простой derive макрос, который будет реализовывать трейт Description для структуры или перечисления, предоставляя им метод describe(), возвращающий строковое представление:

// в crate для процедурных макросов, в lib.rs  use proc_macro::TokenStream; use quote::quote; use syn::{parse_macro_input, DeriveInput};  #[proc_macro_derive(Describe)] pub fn derive_describe(input: TokenStream) -> TokenStream {     let input = parse_macro_input!(input as DeriveInput);          let name = input.ident;     let gen = quote! {         impl Description for #name {             fn describe() -> String {                 format!("This is a {}", stringify!(#name))             }         }     };      gen.into() }

Юзаем крейты syn для парсинга входящего TokenStream в структуру DeriveInput, которая предоставляет информацию о типе, к которому применяется макрос. Используем quote! для генерации кода, который реализует трейт Description.

Используем макрос:

// в основном crate  #[derive(Describe)] struct MyStruct;  trait Description {     fn describe() -> String; }  fn main() {     println!("{}", MyStruct::describe()); }

После добавления макроса #[derive(Describe)] к MyStruct, можно метод describe(), который был автоматически реализован для MyStruct благодаря процедурному макросу.

Атрибутивные макросы

С атрибутивными макросами можно определять пользовательские атрибуты, которые можно применять к различным элементам кода, таким как функции, структуры, модули и т.д. Эти макросы принимают два аргумента: набор токенов атрибута и токен TokenStream элемента, к которому применяется атрибут. Результатом работы атрибутивного макроса является новый TokenStream, который заменяет исходный элемент.

Создадим атрибутивный макрос log_function, который будет добавлять логирование при входе и выходе из функции:

extern crate proc_macro; use proc_macro::TokenStream; use quote::quote; use syn::{parse_macro_input, ItemFn};  #[proc_macro_attribute] pub fn log_function(_attr: TokenStream, item: TokenStream) -> TokenStream {     let input_fn = parse_macro_input!(item as ItemFn);     let fn_name = &input_fn.sig.ident;     let fn_body = &input_fn.block;          let result = quote! {         fn #fn_name() {             println!("Entering {}", stringify!(#fn_name));             #fn_body             println!("Exiting {}", stringify!(#fn_name));         }     };      result.into() }

Код берет функцию, к которой применяется атрибутивный макрос, и модифицирует ее так, чтобы при ее вызове в консоль выводились сообщения о входе в функцию и выходе из нее.

use my_proc_macros::log_function;  #[log_function] fn my_function() {     println!("Function body execution"); }

После добавления атрибута #[log_function] к функции my_function, при ее вызове в консоли будут отображаться соответствующие сообщения о входе и выходе.

---

Про самые популярные ЯП и практические инструменты мои коллеги из OTUS рассказывают в рамках практических онлайн-курсов. По ссылке вы можете ознакомиться с полным каталогом курсов, а также зарегистрироваться на бесплатные вебинары.