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

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 рассказывают в рамках практических онлайн-курсов. По ссылке вы можете ознакомиться с полным каталогом курсов, а также зарегистрироваться на бесплатные вебинары.