Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Макросы

На протяжении всей книги мы использовали макросы, такие как println!, но мы ещё полностью не исследовали, что такое макрос и как он работает. Термин макрос относится к семейству возможностей Rust — декларативные макросы с macro_rules! и три вида процедурных макросов:

  • Пользовательские макросы #[derive], которые определяют код, добавляемый атрибутом derive, используемым для структур и перечислений
  • Атрибутоподобные макросы, которые определяют пользовательские атрибуты, применимые к любому элементу
  • Функционально-подобные макросы, которые выглядят как вызовы функций, но работают с токенами, указанными в качестве аргумента

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

Разница между макросами и функциями

По сути, макросы — это способ написания кода, который пишет другой код, известный как метапрограммирование. В Приложении C мы обсуждаем атрибут derive, который генерирует реализацию различных трейтов для вас. Мы также использовали макросы println! и vec! на протяжении всей книги. Все эти макросы разворачиваются, создавая больше кода, чем вы написали бы вручную.

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

Сигнатура функции должна объявлять количество и тип параметров, которые есть у функции. Макросы, с другой стороны, могут принимать переменное количество параметров: мы можем вызвать println!("hello") с одним аргументом или println!("hello {}", name) с двумя аргументами. Кроме того, макросы разворачиваются до того, как компилятор интерпретирует значение кода, поэтому макрос может, например, реализовать трейт для заданного типа. Функция не может этого сделать, потому что она вызывается во время выполнения, а трейт должен быть реализован во время компиляции.

Недостаток реализации макроса вместо функции заключается в том, что определения макросов сложнее определений функций, потому что вы пишете код на Rust, который пишет код на Rust. Из-за этой косвенности определения макросов, как правило, труднее читать, понимать и поддерживать, чем определения функций.

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

Декларативные макросы для общего метапрограммирования

Наиболее широко используемая форма макросов в Rust — декларативный макрос. Их также иногда называют «макросами по примеру», «макросами macro_rules!» или просто «макросами». По своей сути декларативные макросы позволяют писать нечто похожее на выражение match в Rust. Как обсуждалось в главе 6, выражения match — это управляющие структуры, которые принимают выражение, сравнивают результирующее значение выражения с шаблонами и затем выполняют код, связанный с совпавшим шаблоном. Макросы также сравнивают значение с шаблонами, связанными с конкретным кодом: в этой ситуации значение — это буквальный исходный код на Rust, переданный макросу; шаблоны сравниваются со структурой этого исходного кода; и код, связанный с каждым шаблоном, при совпадении заменяет код, переданный макросу. Всё это происходит во время компиляции.

Чтобы определить макрос, вы используете конструкцию macro_rules!. Давайте исследуем, как использовать macro_rules!, посмотрев, как определён макрос vec!. В главе 8 рассказывалось, как мы можем использовать макрос vec! для создания нового вектора с конкретными значениями. Например, следующий макрос создаёт новый вектор, содержащий три целых числа:

#![allow(unused)]
fn main() {
let v: Vec<u32> = vec![1, 2, 3];
}

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

Листинг 20-35 показывает несколько упрощённое определение макроса vec!.

Имя файла: src/lib.rs
#[macro_export]
macro_rules! vec {
    ( $( $x:expr ),* ) => {
        {
            let mut temp_vec = Vec::new();
            $(
                temp_vec.push($x);
            )*
            temp_vec
        }
    };
}
Листинг 20-35: Упрощённая версия определения макроса vec!

Примечание: Фактическое определение макроса vec! в стандартной библиотеке включает код для предварительного выделения правильного объёма памяти. Этот код является оптимизацией, которую мы здесь не включаем, чтобы сделать пример проще.

Аннотация #[macro_export] указывает, что этот макрос должен быть доступен всякий раз, когда крейт, в котором определён макрос, вводится в область видимости. Без этой аннотации макрос не может быть введён в область видимости.

Затем мы начинаем определение макроса с macro_rules! и имени макроса, который мы определяем, без восклицательного знака. Имя, в данном случае vec, сопровождается фигурными скобками, обозначающими тело определения макроса.

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

Допустимый синтаксис шаблонов в определениях макросов отличается от синтаксиса шаблонов, рассмотренного в главе 19, потому что шаблоны макросов сравниваются со структурой кода на Rust, а не со значениями. Давайте разберём, что означают части шаблона в листинге 20-29; полный синтаксис шаблонов макросов см. в Справочнике по Rust.

Сначала мы используем набор круглых скобок, чтобы охватить весь шаблон. Мы используем знак доллара ($), чтобы объявить переменную в системе макросов, которая будет содержать код на Rust, соответствующий шаблону. Знак доллара даёт понять, что это переменная макроса, в отличие от обычной переменной Rust. Затем идёт набор круглых скобок, которые захватывают значения, соответствующие шаблону внутри круглых скобок, для использования в заменяющем коде. Внутри $() находится $x:expr, который соответствует любому выражению Rust и даёт выражению имя $x.

Запятая после $() указывает, что между каждым экземпляром кода, соответствующего коду в $(), должен появляться литеральный символ-разделитель-запятая. Символ * указывает, что шаблон соответствует нулю или более экземпляров того, что предшествует *.

Когда мы вызываем этот макрос с vec![1, 2, 3];, шаблон $x совпадает три раза с тремя выражениями 1, 2 и 3.

Теперь давайте посмотрим на шаблон в теле кода, связанного с этим плечом: temp_vec.push() внутри $()* генерируется для каждой части, соответствующей $() в шаблоне, ноль или более раз в зависимости от того, сколько раз шаблон совпадает. $x заменяется каждым совпавшим выражением. Когда мы вызываем этот макрос с vec![1, 2, 3];, сгенерированный код, заменяющий этот вызов макроса, будет следующим:

{
    let mut temp_vec = Vec::new();
    temp_vec.push(1);
    temp_vec.push(2);
    temp_vec.push(3);
    temp_vec
}

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

Чтобы узнать больше о том, как писать макросы, обратитесь к онлайн-документации или другим ресурсам, например к «The Little Book of Rust Macros», начатой Дэниелом Кипом и продолженной Лукасом Виртом.

Процедурные макросы для генерации кода из атрибутов

Вторая форма макросов — процедурный макрос, который действует больше как функция (и является разновидностью процедуры). Процедурные макросы принимают некоторый код на вход, оперируют этим кодом и производят некоторый код на выходе, вместо того чтобы сопоставлять шаблоны и заменять код другим кодом, как это делают декларативные макросы. Три вида процедурных макросов — пользовательские derive, атрибутоподобные и функционально-подобные, и все они работают схожим образом.

При создании процедурных макросов определения должны находиться в собственном крейте со специальным типом крейта. Это по сложным техническим причинам, которые мы надеемся устранить в будущем. В листинге 20-36 мы показываем, как определить процедурный макрос, где some_attribute — это заполнитель для использования конкретной разновидности макроса.

Имя файла: src/lib.rs
use proc_macro::TokenStream;

#[some_attribute]
pub fn some_name(input: TokenStream) -> TokenStream {
}
Листинг 20-36: Пример определения процедурного макроса

Функция, определяющая процедурный макрос, принимает TokenStream на вход и производит TokenStream на выходе. Тип TokenStream определён крейтом proc_macro, который поставляется с Rust и представляет последовательность токенов. Это ядро макроса: исходный код, с которым работает макрос, составляет входной TokenStream, а код, который производит макрос, — это выходной TokenStream. У функции также есть прикреплённый к ней атрибут, который указывает, какой вид процедурного макроса мы создаём. Мы можем иметь несколько видов процедурных макросов в одном крейте.

Давайте рассмотрим разные виды процедурных макросов. Мы начнём с пользовательского макроса derive, а затем объясним небольшие различия, которые делают другие формы разными.

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

Давайте создадим крейт под названием hello_macro, который определяет трейт под названием HelloMacro с одной ассоциированной функцией под названием hello_macro. Вместо того чтобы заставлять наших пользователей реализовывать трейт HelloMacro для каждого из их типов, мы предоставим процедурный макрос, чтобы пользователи могли аннотировать свой тип с помощью #[derive(HelloMacro)], чтобы получить реализацию по умолчанию функции hello_macro. Реализация по умолчанию будет печатать Hello, Macro! My name is TypeName!, где TypeName — имя типа, для которого был определён этот трейт. Другими словами, мы напишем крейт, который позволяет другому программисту писать код, как в листинге 20-37, используя наш крейт.

Имя файла: src/main.rs
use hello_macro::HelloMacro;
use hello_macro_derive::HelloMacro;

#[derive(HelloMacro)]
struct Pancakes;

fn main() {
    Pancakes::hello_macro();
}
Листинг 20-37: Код, который пользователь нашего крейта сможет написать при использовании нашего процедурного макроса

Этот код напечатает Hello, Macro! My name is Pancakes!, когда мы закончим. Первый шаг — создать новый библиотечный крейт, вот так:

$ cargo new hello_macro --lib

Затем в листинге 20-38 мы определим трейт HelloMacro и его ассоциированную функцию.

Имя файла: src/lib.rs
pub trait HelloMacro {
    fn hello_macro();
}
Листинг 20-38: Простой трейт, который мы будем использовать с макросом derive

У нас есть трейт и его функция. На этом этапе пользователь нашего крейта мог бы реализовать трейт для достижения желаемой функциональности, как в листинге 20-39.

Имя файла: src/main.rs
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();
}
Листинг 20-39: Как это выглядело бы, если бы пользователи написали ручную реализацию трейта HelloMacro

Однако им пришлось бы писать блок реализации для каждого типа, который они хотели бы использовать с hello_macro; мы хотим избавить их от этой работы.

Кроме того, мы пока не можем предоставить функции hello_macro реализацию по умолчанию, которая напечатает имя типа, для которого реализован трейт: в Rust нет возможностей рефлексии, поэтому он не может найти имя типа во время выполнения. Нам нужен макрос для генерации кода во время компиляции.

Следующий шаг — определить процедурный макрос. На момент написания этой книги процедурные макросы должны находиться в собственном крейте. В конечном счёте это ограничение может быть снято. Соглашение о структурировании крейтов и крейтов-макросов следующее: для крейта с именем foo крейт пользовательского процедурного макроса derive называется foo_derive. Давайте запустим новый крейт под названием hello_macro_derive внутри нашего проекта hello_macro:

$ cargo new hello_macro_derive --lib

Наши два крейта тесно связаны, поэтому мы создаём крейт процедурного макроса внутри директории нашего крейта hello_macro. Если мы изменим определение трейта в hello_macro, нам придётся изменить реализацию процедурного макроса в hello_macro_derive тоже. Два крейта нужно будет публиковать отдельно, и программистам, использующим эти крейты, нужно будет добавить оба в качестве зависимостей и ввести оба в область видимости. Мы могли бы вместо этого сделать так, чтобы крейт hello_macro использовал hello_macro_derive как зависимость и реэкспортировал код процедурного макроса. Однако то, как мы структурировали проект, позволяет программистам использовать hello_macro, даже если они не хотят функциональность derive.

Нам нужно объявить крейт hello_macro_derive как крейт процедурного макроса. Нам также понадобится функциональность из крейтов syn и quote, как вы скоро увидите, поэтому нам нужно добавить их в качестве зависимостей. Добавьте следующее в файл Cargo.toml для hello_macro_derive:

Имя файла: hello_macro_derive/Cargo.toml
[lib]
proc-macro = true

[dependencies]
syn = "2.0"
quote = "1.0"

Чтобы начать определять процедурный макрос, поместите код из листинга 20-40 в ваш файл src/lib.rs для крейта hello_macro_derive. Обратите внимание, что этот код не скомпилируется, пока мы не добавим определение для функции impl_hello_macro.

Имя файла: hello_macro_derive/src/lib.rs
use proc_macro::TokenStream;
use quote::quote;

#[proc_macro_derive(HelloMacro)]
pub fn hello_macro_derive(input: TokenStream) -> TokenStream {
    // Строим представление кода Rust в виде синтаксического дерева
    // которое мы можем обрабатывать.
    let ast = syn::parse(input).unwrap();

    // Строим реализацию трейта.
    impl_hello_macro(&ast)
}
Листинг 20-40: Код, который потребуется в большинстве крейтов процедурных макросов для обработки кода на Rust

Обратите внимание, что мы разделили код на функцию hello_macro_derive, которая отвечает за разбор TokenStream, и функцию impl_hello_macro, которая отвечает за преобразование синтаксического дерева: это делает написание процедурного макроса более удобным. Код во внешней функции (в данном случае hello_macro_derive) будет одинаковым почти для каждого крейта процедурного макроса, который вы увидите или создадите. Код, который вы указываете в теле внутренней функции (в данном случае impl_hello_macro), будет отличаться в зависимости от назначения вашего процедурного макроса.

Мы представили три новых крейта: proc_macro, syn и quote. Крейт proc_macro поставляется с Rust, поэтому нам не нужно было добавлять его в зависимости в Cargo.toml. Крейт proc_macro — это API компилятора, который позволяет нам читать и манипулировать кодом на Rust из нашего кода.

Крейт syn разбирает код на Rust из строки в структуру данных, с которой мы можем выполнять операции. Крейт quote превращает структуры данных syn обратно в код на Rust. Эти крейты значительно упрощают разбор любого вида кода на Rust, с которым мы могли бы захотеть работать: написание полного парсера для кода на Rust — непростая задача.

Функция hello_macro_derive будет вызываться, когда пользователь нашей библиотеки указывает #[derive(HelloMacro)] для типа. Это возможно, потому что мы аннотировали функцию hello_macro_derive здесь с помощью proc_macro_derive и указали имя HelloMacro, которое соответствует имени нашего трейта; это соглашение, которого придерживается большинство процедурных макросов.

Функция hello_macro_derive сначала преобразует input из TokenStream в структуру данных, которую мы затем можем интерпретировать и выполнять операции над ней. Здесь в игру вступает syn. Функция parse в syn принимает TokenStream и возвращает структуру DeriveInput, представляющую разобранный код на Rust. Листинг 20-41 показывает соответствующие части структуры DeriveInput, которые мы получаем при разборе строки struct Pancakes;.

DeriveInput {
    // --snip--

    ident: Ident {
        ident: "Pancakes",
        span: #0 bytes(95..103)
    },
    data: Struct(
        DataStruct {
            struct_token: Struct,
            fields: Unit,
            semi_token: Some(
                Semi
            )
        }
    )
}
Листинг 20-41: Экземпляр DeriveInput, который мы получаем при разборе кода с атрибутом макроса из листинга 20-37

Поля этой структуры показывают, что код на Rust, который мы разобрали, — это unit-структура с ident (identifier, то есть именем) Pancakes. В этой структуре есть больше полей для описания всевозможного кода на Rust; см. документацию syn для DeriveInput для получения дополнительной информации.

Скоро мы определим функцию impl_hello_macro, где мы будем строить новый код на Rust, который хотим включить. Но прежде чем мы это сделаем, обратите внимание, что вывод для нашего макроса derive также является TokenStream. Возвращаемый TokenStream добавляется к коду, который пишут пользователи нашего крейта, поэтому, когда они компилируют свой крейт, они получат дополнительную функциональность, которую мы предоставляем в изменённом TokenStream.

Возможно, вы заметили, что мы вызываем unwrap, чтобы заставить функцию hello_macro_derive вызвать панику, если вызов функции syn::parse завершится неудачей. Это необходимо, чтобы наш процедурный макрос паниковал при ошибках, потому что функции proc_macro_derive должны возвращать TokenStream, а не Result, чтобы соответствовать API процедурных макросов. Мы упростили этот пример, используя unwrap; в production-коде вы должны предоставлять более конкретные сообщения об ошибках о том, что пошло не так, используя panic! или expect.

Теперь, когда у нас есть код для преобразования аннотированного кода на Rust из TokenStream в экземпляр DeriveInput, давайте сгенерируем код, реализующий трейт HelloMacro для аннотированного типа, как показано в листинге 20-42.

Имя файла: hello_macro_derive/src/lib.rs
use proc_macro::TokenStream;
use quote::quote;

#[proc_macro_derive(HelloMacro)]
pub fn hello_macro_derive(input: TokenStream) -> TokenStream {
    // Строим представление кода Rust в виде синтаксического дерева
    // которое мы можем обрабатывать
    let ast = syn::parse(input).unwrap();

    // Строим реализацию трейта
    impl_hello_macro(&ast)
}

fn impl_hello_macro(ast: &syn::DeriveInput) -> TokenStream {
    let name = &ast.ident;
    let generated = quote! {
        impl HelloMacro for #name {
            fn hello_macro() {
                println!("Hello, Macro! My name is {}!", stringify!(#name));
            }
        }
    };
    generated.into()
}
Листинг 20-42: Реализация трейта HelloMacro с использованием разобранного кода на Rust

Мы получаем экземпляр структуры Ident, содержащий имя (идентификатор) аннотированного типа, используя ast.ident. Структура в листинге 20-41 показывает, что когда мы запускаем функцию impl_hello_macro на коде из листинга 20-37, ident, который мы получим, будет иметь поле ident со значением "Pancakes". Таким образом, переменная name в листинге 20-42 будет содержать экземпляр структуры Ident, который при печати будет строкой "Pancakes", именем структуры из листинга 20-37.

Макрос quote! позволяет нам определить код на Rust, который мы хотим вернуть. Компилятор ожидает нечто отличное от прямого результата выполнения макроса quote!, поэтому нам нужно преобразовать его в TokenStream. Мы делаем это, вызывая метод into, который потребляет это промежуточное представление и возвращает значение требуемого типа TokenStream.

Макрос quote! также предоставляет некоторые очень крутые механизмы шаблонизации: мы можем ввести #name, и quote! заменит его значением в переменной name. Вы даже можете сделать некоторое повторение, аналогичное тому, как работают обычные макросы. Ознакомьтесь с документацией крейта quote для подробного введения.

Мы хотим, чтобы наш процедурный макрос генерировал реализацию нашего трейта HelloMacro для типа, который аннотировал пользователь, что мы можем получить, используя #name. Реализация трейта имеет одну функцию hello_macro, тело которой содержит функциональность, которую мы хотим предоставить: печать Hello, Macro! My name is, а затем имя аннотированного типа.

Используемый здесь макрос stringify! встроен в Rust. Он принимает выражение Rust, например 1 + 2, и во время компиляции превращает выражение в строковый литерал, например "1 + 2". Это отличается от format! или println!, которые являются макросами, вычисляющими выражение и затем превращающими результат в String. Есть вероятность, что ввод #name может быть выражением для печати буквально, поэтому мы используем stringify!. Использование stringify! также экономит выделение памяти за счёт преобразования #name в строковый литерал во время компиляции.

На этом этапе cargo build должен успешно завершиться как в hello_macro, так и в hello_macro_derive. Давайте подключим эти крейты к коду из листинга 20-37, чтобы увидеть процедурный макрос в действии! Создайте новый бинарный проект в вашей директории projects, используя cargo new pancakes. Нам нужно добавить hello_macro и hello_macro_derive как зависимости в Cargo.toml крейта pancakes. Если вы публикуете ваши версии hello_macro и hello_macro_derive на crates.io, они были бы обычными зависимостями; если нет, вы можете указать их как path-зависимости следующим образом:

[dependencies]
hello_macro = { path = "../hello_macro" }
hello_macro_derive = { path = "../hello_macro/hello_macro_derive" }

Поместите код из листинга 20-37 в src/main.rs и запустите cargo run: он должен напечатать Hello, Macro! My name is Pancakes!. Реализация трейта HelloMacro из процедурного макроса была включена без необходимости крейту pancakes реализовывать её; #[derive(HelloMacro)] добавил реализацию трейта.

Далее давайте исследуем, чем другие виды процедурных макросов отличаются от пользовательских макросов derive.

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

Атрибутоподобные макросы похожи на пользовательские макросы derive, но вместо генерации кода для атрибута derive они позволяют создавать новые атрибуты. Они также более гибкие: derive работает только для структур и перечислений; атрибуты можно применять и к другим элементам, например к функциям. Вот пример использования атрибутоподобного макроса. Допустим, у вас есть атрибут под названием route, который аннотирует функции при использовании веб-фреймворка:

#[route(GET, "/")]
fn index() {

Этот атрибут #[route] был бы определён фреймворком как процедурный макрос. Сигнатура функции определения макроса выглядела бы так:

#[proc_macro_attribute]
pub fn route(attr: TokenStream, item: TokenStream) -> TokenStream {

Здесь у нас два параметра типа TokenStream. Первый — для содержимого атрибута: части GET, "/". Второй — тело элемента, к которому прикреплён атрибут: в данном случае fn index() {} и остальное тело функции.

Помимо этого, атрибутоподобные макросы работают так же, как пользовательские макросы derive: вы создаёте крейт с типом крейта proc-macro и реализуете функцию, которая генерирует нужный вам код!

Функционально-подобные макросы

Функционально-подобные макросы определяют макросы, которые выглядят как вызовы функций. Подобно макросам macro_rules!, они более гибкие, чем функции; например, они могут принимать неизвестное количество аргументов. Однако макросы macro_rules! можно определять только с использованием match-подобного синтаксиса, который мы обсуждали в разделе «Декларативные макросы для общего метапрограммирования» ранее. Функционально-подобные макросы принимают параметр TokenStream, и их определение манипулирует этим TokenStream с использованием кода на Rust, как это делают два других вида процедурных макросов. Пример функционально-подобного макроса — макрос sql!, который мог бы вызываться так:

let sql = sql!(SELECT * FROM posts WHERE id=1);

Этот макрос разбирал бы SQL-выражение внутри него и проверял, что оно синтаксически корректно, что является гораздо более сложной обработкой, чем может сделать макрос macro_rules!. Макрос sql! был бы определён так:

#[proc_macro]
pub fn sql(input: TokenStream) -> TokenStream {

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

Итоги

Ух! Теперь у вас в наборе инструментов есть некоторые возможности Rust, которые вы, вероятно, не будете использовать часто, но вы будете знать, что они доступны в очень специфических обстоятельствах. Мы представили несколько сложных тем, чтобы, когда вы столкнётесь с ними в подсказках сообщений об ошибках или в чужом коде, вы могли распознать эти концепции и синтаксис. Используйте эту главу как справочник, который направит вас к решениям.

Далее мы применим на практике всё, что обсуждали на протяжении всей книги, и сделаем ещё один проект!