Rust 手続きマクロ(proc-macro)の勘所


こちらの記事は [Rustマクロ冬期講習アドベントカレンダー](https://qiita.com/advent-calendar/2024/rust-macro) 15日目の記事です！

> アドカレまとめ記事はこちら！: [Rustマクロ作成チートシート！](https://qiita.com/namn1125/items/d601d2cbbf2cc7b5d3dc)

前回までは宣言マクロ ( `macro_rules!` によるマクロ ) に関する話題でした。今回から手続きマクロの話題に入ります！ **が、** 宣言マクロほど詳細な解説はしないつもりです。というのも、基本事項を除けば三種の神器[^sacred]クレート `proc-macro2`, `syn`, `quote` の解説に終始するのですが、全ての解説を試みると12月が何日あっても足りないためです。

[^sacred]: 「三種の神器」(3種の神器) という表現は [Rust の procedural macro を操って黒魔術師になろう〜proc-macro-workshop の紹介](https://zenn.dev/magurotuna/articles/bab4db5999ebfa) という記事様から拝借しました。良い呼び方だと思います！ 

というわけで、手続きマクロの一連のシリーズでは、基本事項及び筆者が悩んだ・気になった話題をピックアップして記事にする予定です！

**投稿予定**

- Rust 手続きマクロ(proc-macro)の勘所 <- 今回
- 関数風マクロ
  - [RTA](https://qiita.com/namn1125/items/fc5aa71690fcb5109cf0)
  - [ちょっとしたマクロをハンズオン](https://qiita.com/namn1125/items/648e915cad62f21656c0)
- 属性風マクロ
  - [RTA](https://qiita.com/namn1125/items/b7d9374e3d6d3f64ab65)
  - [ちょっとしたマクロをハンズオン](https://qiita.com/namn1125/items/28d2e95090ddf7fbc7e0)
- deriveマクロ
  - [RTA](https://qiita.com/namn1125/items/b05ad80d324afcd2ed91)
  - [ちょっとしたマクロをハンズオン](https://qiita.com/namn1125/items/b55fb65f423cca0bef49)
- [Rust 手続きマクロ エラーハンドリング手法](https://qiita.com/namn1125/items/f71f204264aa7cd0a6ab)
  - [`syn::Result`](https://docs.rs/syn/latest/syn/type.Result.html) と [`Span`](https://docs.rs/proc-macro2/1.0.92/proc_macro2/struct.Span.html) に関する解説
- [darlingクレートを使ってみる](https://qiita.com/namn1125/items/d136a51184d044330f00)

なお、一連のシリーズは、主に [dtolnay/proc-macro-workshop: Learn to write Rust procedural macros](https://github.com/dtolnay/proc-macro-workshop) というワークショップに取り組んで得た知識等を利用しています。一次ソースに当たりたい方はぜひ取り組んでみることをオススメします！

https://github.com/dtolnay/proc-macro-workshop

# 手続きマクロの概要

![MacroFlow3.drawio.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/205472/e9b5dd9a-2d9c-a8ce-27c7-f541b995fce4.png)

上図は [Rustマクロの事前知識①「入出力はトークン木」](https://qiita.com/namn1125/items/3288db9acdf2012f78b0) で登場させたものです。[Rust マクロの分類](https://qiita.com/namn1125/items/244803083934bcb7bb51) で解説したように、上図左下部分にあるような「 トークン木([`proc_macro::TokenStream`](https://doc.rust-lang.org/proc_macro/struct.TokenStream.html)) を受け取り、 トークン木([`proc_macro::TokenStream`](https://doc.rust-lang.org/proc_macro/struct.TokenStream.html)) を吐き出す手続きプログラム」を作成し、そのプログラムをマクロを使用しているソースコードのコンパイル時に実行するのが手続きマクロです。

宣言マクロと比べると、「どのようになるか」ではなくて **「どのような流れ(手続き)でRustソースコードを書き換えるか」を記述して作成する** ことになるので、手続きマクロ (Procedual Macro) と呼ばれています。

```rust:src/lib.rs (マクロ定義側)
use proc_macro::TokenStream;
use quote::quote;
use syn::parse_macro_input;

#[proc_macro]
pub fn hello_macro(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as syn::Ident); // <- お決まりの解析処理

    /* この部分にトークン木書き換えのプログラムを書いていく！！ */

    quote! { // <- お決まりの出力処理
        ::std::println!("Hello, {}!", stringify!(#input));
    }
    .into()
}
```

```rust:src/main.rs (マクロ利用側)
use proc_macro_example2::hello_macro;

fn main() {
    hello_macro!(world);
}

// ↓ cargo expand

fn main() {
    {
        ::std::io::_print(format_args!("Hello, {0}!\n", "world"));
    };
}
```

![proc_macro_picture2.drawio.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/205472/95cdd8e9-e9db-c748-d522-62ef09d282e8.png)

# サクッと始めてみる！

「手続きマクロは(宣言マクロと比べて)難しい！」というイメージがあるのは、同一クレート内で定義することができず、単にお手軽さを感じられないからかなと思います。

詳細に実装するまではともかく、ガワを作るまでは簡単なのでちょっとやってみましょう！

まず、いつも通りライブラリクレートを用意します。

```bash
cargo new --lib hello_macro
```

`Cargo.toml` を書き換えます！ `[lib] proc-macro = true` という記述を入れます。

```diff_toml:Cargo.toml
[package]
name = "hello_macro"
version = "0.1.0"
edition = "2021"

+[lib]
+proc-macro = true

[dependencies]
```

`src/lib.rs` の中身を全部消して、マクロを定義します！

```rust:Rust
use proc_macro::TokenStream;

#[proc_macro]
pub fn hello(input: TokenStream) -> TokenStream {
    input
}
```

何もしない関数風マクロ `hello` の完成です！ `nop` とかの名前のほうがいいかも...？

同一クレートからは呼べないのですが、 `hello_macro/src/main.rs` からは `hello_macro/src/lib.rs` をクレート `hello_macro` として呼べるので、ここに書いてマクロを試してみましょう！

```rust:src/main.rs
use hello_macro::hello;

fn main() {
    hello!(println!("Hello, world!"));
}
```

コンパイルが通るはずです。基礎の基礎は以上です！多少手間なだけで手続きマクロの定義自体はWebAssembly等と比べれば格段に楽であることが伝わったんじゃないかなと思います。

# 手続きマクロ 三種の神器クレート

「...いやいや、『伝わったんじゃないかなと思います』じゃないよ！！！ `input: TokenStream` に手を加えるんじゃないのか？！どうするんだよ！！！」

ツッコミありがとうございます！ `proc_macro::TokenStream` はそのままだと扱うのが面倒です。というか **[`proc_macro`](https://doc.rust-lang.org/proc_macro/) が特殊なクレートすぎて扱えません** (テストで利用できなかったりなど)。これらを扱うのに必須な3つのクレートがあるので、それらを `Cargo.toml` に記述するのが次の作業になります。

```bash
cargo add proc-macro2 quote
cargo add syn --features full --features extra-traits
```

`proc-macro2`, `quote`, `syn` というクレートを入れました！

|クレート名|役割|利用度|説明|
|:-|:-|:-|:-|
| [`proc-macro2`](https://docs.rs/proc-macro2/latest/proc_macro2/) | [`TokenStream`](https://docs.rs/proc-macro2/latest/proc_macro2/struct.TokenStream.html) 等の基本的な型の提供 | ★ | 手続きマクロの入出力で最も基本的で重要な型である [`TokenStream`](https://docs.rs/proc-macro2/latest/proc_macro2/struct.TokenStream.html) や [`Span`](https://docs.rs/proc-macro2/latest/proc_macro2/struct.Span.html) を提供するクレート。  `2` なのは 「 [`proc-macro`](https://doc.rust-lang.org/proc_macro/) の後発だから」...というわけではなくて、 `proc-macro` 自体は扱いが特殊すぎるクレートなので、これを普通のクレートと同様に扱えるようにしたものであるため。 |
| [`quote`](https://docs.rs/quote/latest/quote/) | 出力の整形 | ★ | 宣言マクロと似たような記述で出力されるトークン木を宣言的に楽に書ける [`quote!`](https://docs.rs/quote/latest/quote/macro.quote.html) を提供するクレート。 `#変数` という形式を使うことで [`ToTokens`](https://docs.rs/quote/latest/quote/trait.ToTokens.html) トレイトを実装する変数をトークンとして組み込むことが可能になる。 |
| [`syn`](https://docs.rs/syn/latest/syn/) | **Rustの** 文法に沿った解析 | ★★★ | Rustの文法に出現する構文要素を提供したり組み立てたりとにかくいろいろするクレート。おそらく "syntax" の略。他2つのクレートはRustの文法にまつわる機能は提供しておらず、よって文法解析でめちゃくちゃお世話になる。 |

`proc-macro2` と `quote` は入出力時に必須 & 使い方も多くないのでお決まりで入れるという感じです。一方、 `syn` クレートは 「トークン木を受け取りトークン木を返す」だけのプログラムである手続きマクロに **Rustの文法** という文化を取り入れる目的でかなり多用します。(独自構文ではない)普通のRustコードを扱う場合、ドキュメントをかなり参照することになるでしょう。

:::note
**マクロの入力に独自構文を扱いたい**

入力がRustの文法に沿っていないようなマクロを作りたいことがあるかもしれません。 [`yew::html`](https://docs.rs/yew/latest/yew/macro.html.html) などが良い例でしょう。

マクロ入力の制約は [`TokenStream`](https://doc.rust-lang.org/beta/proc_macro/struct.TokenStream.html) 、すなわちトークン木([`TokenTree`](https://doc.rust-lang.org/beta/proc_macro/enum.TokenTree.html)) のストリームであることです。

すなわち、マクロの入力は [`syn`](https://docs.rs/syn/latest/syn/) クレートから提供されているRustの文法に沿っている必要はありません。しかし、トークン木であることより多少の制約は受けます。

トークン木に関する解説は [Rustマクロの事前知識①「入出力はトークン木」](https://qiita.com/namn1125/items/3288db9acdf2012f78b0) に書いたのでそちらを参考にしてほしいのと、普通に [`TokenTree`](https://docs.rs/proc-macro2/latest/proc_macro2/enum.TokenTree.html) のドキュメントが参考になるかと思います。(ついでに [`syn::parse::Parse`](https://docs.rs/syn/latest/syn/parse/trait.Parse.html) トレイトも参考になるかも...？)
:::

# 手続きマクロで作れるもの

Rustに存在するマクロ(ほぼ[^almost])全てをカバーしているのが手続きマクロです。

[^almost]: 一部組み込みで用意されているマクロがあります。これらが手続きマクロでも再現できるかは不明です。

呼び出し方によって若干定義方法も変わります。

|マクロ名|呼び出し方|特徴|
|:-|:-|:-|
|関数風マクロ| `macro!(引数)` | 普通に呼び出せるマクロで、引数部分で受け取ったトークン木を元に何かしらのトークン木を出力する |
|属性風マクロ| `#[macro(メタ)] アイテム` | アイテム部分(関数や構造体や `impl` ブロックなど)を入力として受け取り、何かしらの処理後にトークン木を出力する |
|deriveマクロ| `#[derive(Macro)] 構造体/列挙体` | 構造体/列挙体に実装等を **付与** するマクロです。入力として構造体/列挙体の情報を受け取るものの、置換ではなく追加生成のような処理を行う点で属性風マクロと異なっています。トレイトの簡易実装に用いるのが最も慣例的な利用方法ですが、それ以外の活用も可能です。 |

さらなる詳細は [Rust マクロの分類 #Rust - Qiita](https://qiita.com/namn1125/items/244803083934bcb7bb51) にもまとめているのでそちらも参照してください！次回以降は簡単にこれらのマクロを作ってみたいと思います。

# 手続きマクロについて手っ取り早く学ぶには: proc-macro-workshop

日本語のソースが少ないなと感じていたことをキッカケに始めたのが本アドカレで、手続きマクロパートでその元となっているのがここで紹介する proc-macro-workshop です！

先ほど挙げた三種の神器、そして `anyhow` や `thiserror` をはじめとし様々なクレートを作ったRust界の重鎮 [dtolnay](https://github.com/dtolnay) 氏謹製のワークショップなのでほぼ公式ドキュメントです。英語に抵抗がない方はぜひやりましょう！

[dtolnay/proc-macro-workshop: Learn to write Rust procedural macros](https://github.com/dtolnay/proc-macro-workshop)

https://github.com/dtolnay/proc-macro-workshop

本当はこのワークショップの内容を全部アドベントカレンダー記事に盛り込みたかったのですが筆者も道半ばです...アドベントカレンダーのまとめ記事を書く頃にはワークショップの内容をもっとガッツリ盛り込みたい...(願望)

# まとめ・所感

手続きマクロに関する俯瞰図を与えられたかなと思います。手続きマクロは宣言マクロと比べ広大ではあるのですが、制限が少なくRustプログラムとしてわかりやすく記述できるため、宣言マクロよりも覚えなければならないことは案外少ないんじゃないかなと思います。 "easy" ではありませんが "simple" というやつでしょうか...？

次回以降は駆け足気味にはなるかもしれませんが、3種類のマクロを軽く触っていきたいと思います！