Day 059 — マクロ① macro_rules! ④ tt マンチャと内部規則で、状態遷移表の DSL を読むマクロを書く

📚 背景知識（読んでから問題へ）

Day 056 で展開結果を予想し、Day 057 で hashmap! などを書き、Day 058 で他人のマクロをレビューしました。今日は macro_rules! の最後の大物、tt マンチャ（tt muncher）と内部規則を使って、小さな DSL（専用の書式）を解析するマクロを書きます。

題材は状態遷移表です。次のように「どの状態から、どの事象で、どの状態へ」を1行ずつ書くと、列挙型と遷移関数が生成されます。

📋 コピーfsm! {
    state JobState { Idle, Running, Done, Failed }
    event JobEvent { Start, Finish, Crash, Reset }

    Idle => Running on Start;
    Running => Done on Finish;
    Idle | Running => Failed on Crash;
    Done | Failed => Idle on Reset "reset";   // 末尾の文字列はメモ（省略できる）
    Running => Failed after 30;              // 30 ティック経ったら自動で遷移
}

ここで新しく出てくる道具は3つです。

そして、今日使う2つのフラグメント指定子があります。

今日いちばん大事な落とし穴は pat です。Idle と書いたパターンは、その名前の列挙子が見えていれば列挙子、見えていなければ「何にでも一致する変数の束縛」になります。遷移元に Runing（typo）と書いても、デフォルトのままでは警告が出るだけでコンパイルは通り、挙動が静かに変わります（実測は後述）。マクロの利用者が打ち間違えたとき、エラーにできるのかどうかが、今日の実装の勘所です。

📝 問題

cargo new macro_day059（edition 2024、外部クレートなし）の src/main.rs に、fsm! マクロを実装してください。上の呼び出し例が通り、次の7つの要件を満たすこと。

📋 コピー// 先に置いておく（ライブラリ側の部品。マクロの外）
use std::fmt;

#[derive(Debug, PartialEq, Eq)]
pub struct Rejected<S, E> {
    pub state: S,
    pub event: E,
}
// impl fmt::Display for Rejected<S, E> も付ける:
//   "event Finish is not allowed in state Idle"

要件

テストも書きます。表とは別に人が手で書いた正解表（オラクル）を用意し、4状態×4事象の 16組すべてで on の結果と照合してください。

設計の設問（コードの後に答える）

• D1. 遷移表の読み方は3案あります。(A) tt マンチャ、(B) 1つの繰り返し $( ... )* で読む「平らな」版、(C) 表を transitions { ... } と timeouts { ... } の2区画に分けて、それぞれ繰り返しで読む。今回 (A) を使う理由を、(B) で何ができて何ができないかを実際に試して答えてください。また (A) の弱点（再帰の上限）が何行目で出るかを測ってください
• D2. R7 の検査をマクロの内側（生成コードに #[deny(...)] を付ける）に入れる案と、利用者の #![deny(...)] に任せる案があります。どちらを採り、何が代償ですか
• D3. 列挙型の名前を呼び出し側から受け取る代わりに、paste クレートで Job から JobState を組み立てる案があります。採りますか

💡 ヒント

📋 コピーmacro_rules! fsm {
    // 入口: 宣言を受け取り、遷移表は tt の塊のまま内部規則へ渡す
    (state $State:ident { $($S:ident),+ $(,)? }
     event $Event:ident { $($E:ident),+ $(,)? }
     $($table:tt)*) => {
        fsm!(@munch $State $Event [] [] [] $($table)*);   // 3つのアキュムレータ: on の腕 / after の腕 / 表の行
        // enum を2つ出す
    };

    // 終端: 残りが空 → 溜めた腕で impl を出す
    (@munch $State:ident $Event:ident [$($on:tt)*] [$($after:tt)*] [$($row:tt)*]) => { /* impl */ };

    // 1行食べる: `$from:pat => $to:ident after $n:literal ;`
    (@munch $State:ident $Event:ident [$($on:tt)*] [$($after:tt)*] [$($row:tt)*]
     $from:pat => $to:ident after $n:literal ; $($rest:tt)*) => {
        fsm!(@munch $State $Event [$($on)*] [$($after)* /* 腕を足す */] [$($row)* /* 行を足す */] $($rest)*);
    };

    // on 行は、メモ付き・メモ無しの2本
}

✅ 模範解答

📋 コピーuse std::fmt;

/// 遷移できなかったときの値。マクロの外(ライブラリ側)に置く
#[derive(Debug, PartialEq, Eq)]
pub struct Rejected<S, E> {
    pub state: S,
    pub event: E,
}

impl<S: fmt::Debug, E: fmt::Debug> fmt::Display for Rejected<S, E> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "event {:?} is not allowed in state {:?}", self.event, self.state)
    }
}

macro_rules! fsm {
    // ---- 入口: 状態と事象の宣言を受け取り、残りの「遷移表」を内部規則へ渡す ----
    (
        state $State:ident { $($S:ident),+ $(,)? }
        event $Event:ident { $($E:ident),+ $(,)? }
        $($table:tt)*
    ) => {
        fsm!(@munch $State $Event [] [] [] $($table)*);
        #[derive(Debug, Clone, Copy, PartialEq, Eq)]
        pub enum $State { $($S),+ }
        #[derive(Debug, Clone, Copy, PartialEq, Eq)]
        pub enum $Event { $($E),+ }
    };

    // ---- 終端: 遷移表を読み切ったので、溜めた腕から impl を出す ----
    (@munch $State:ident $Event:ident
        [$($on:tt)*] [$($after:tt)*] [$($row:tt)*]
    ) => {
        impl $State {
            #[deny(unused_variables, unreachable_patterns)]
            pub fn on(self, ev: $Event) -> Result<(Self, Option<&'static str>), Rejected<Self, $Event>> {
                #[allow(unused_imports)]
                use {$State::*, $Event::*};
                match (self, ev) {
                    $($on)*
                    (state, event) => Err(Rejected { state, event }),
                }
            }
            #[deny(unused_variables, unreachable_patterns)]
            pub fn timeout(self) -> Option<(Self, u32)> {
                #[allow(unused_imports)]
                use $State::*;
                match self {
                    $($after)*
                    _ => None,
                }
            }
            pub const TRANSITIONS: &'static [(&'static str, &'static str, &'static str)] = &[$($row)*];
        }
    };

    // ---- 1行読む: `A | B => C after N;`(タイムアウト遷移) ----
    (@munch $State:ident $Event:ident
        [$($on:tt)*] [$($after:tt)*] [$($row:tt)*]
        $from:pat => $to:ident after $n:literal ; $($rest:tt)*
    ) => {
        fsm!(@munch $State $Event
            [$($on)*]
            [$($after)* $from => Some(($State::$to, $n)),]
            [$($row)* (stringify!($from), stringify!($to), concat!("after ", stringify!($n))),]
            $($rest)*);
    };

    // ---- 1行読む: `A => B on E "メモ";`(メモ付き。メモなしより先に置く) ----
    (@munch $State:ident $Event:ident
        [$($on:tt)*] [$($after:tt)*] [$($row:tt)*]
        $from:pat => $to:ident on $ev:ident $note:literal ; $($rest:tt)*
    ) => {
        fsm!(@munch $State $Event
            [$($on)* ($from, $Event::$ev) => Ok(($State::$to, Some($note))),]
            [$($after)*]
            [$($row)* (stringify!($from), stringify!($to), stringify!($ev)),]
            $($rest)*);
    };

    // ---- 1行読む: `A => B on E;` ----
    (@munch $State:ident $Event:ident
        [$($on:tt)*] [$($after:tt)*] [$($row:tt)*]
        $from:pat => $to:ident on $ev:ident ; $($rest:tt)*
    ) => {
        fsm!(@munch $State $Event
            [$($on)* ($from, $Event::$ev) => Ok(($State::$to, None)),]
            [$($after)*]
            [$($row)* (stringify!($from), stringify!($to), stringify!($ev)),]
            $($rest)*);
    };
}

fsm! {
    state JobState { Idle, Running, Done, Failed }
    event JobEvent { Start, Finish, Crash, Reset }

    Idle => Running on Start;
    Running => Done on Finish;
    Idle | Running => Failed on Crash;
    Done | Failed => Idle on Reset "reset";
    Running => Failed after 30;
}

fn main() {
    let s = JobState::Idle;
    let (s, _) = s.on(JobEvent::Start).unwrap();
    println!("after Start        : {s:?}");
    println!("timeout in Running : {:?}", s.timeout());
    println!("Done + Reset       : {:?}", JobState::Done.on(JobEvent::Reset));
    println!("Idle + Finish      : {}", JobState::Idle.on(JobEvent::Finish).unwrap_err());
    for r in JobState::TRANSITIONS {
        println!("{r:?}");
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use JobEvent::*;
    use JobState::*;

    const ALL_STATES: [JobState; 4] = [Idle, Running, Done, Failed];
    const ALL_EVENTS: [JobEvent; 4] = [Start, Finish, Crash, Reset];

    /// 遷移表とは別に、人が手で書いた正解表(オラクル)
    fn oracle(s: JobState, e: JobEvent) -> Option<(JobState, Option<&'static str>)> {
        match (s, e) {
            (Idle, Start) => Some((Running, None)),
            (Running, Finish) => Some((Done, None)),
            (Idle | Running, Crash) => Some((Failed, None)),
            (Done | Failed, Reset) => Some((Idle, Some("reset"))),
            _ => None,
        }
    }

    #[test]
    fn all_16_pairs_match_the_oracle() {
        for s in ALL_STATES {
            for e in ALL_EVENTS {
                assert_eq!(s.on(e).ok(), oracle(s, e), "{s:?} + {e:?}");
            }
        }
    }

    #[test]
    fn rejected_carries_state_and_event() {
        let err = Done.on(Start).unwrap_err();
        assert_eq!(err, Rejected { state: Done, event: Start });
        assert_eq!(err.to_string(), "event Start is not allowed in state Done");
    }

    #[test]
    fn timeout_only_in_running() {
        assert_eq!(Running.timeout(), Some((Failed, 30)));
        for s in [Idle, Done, Failed] {
            assert_eq!(s.timeout(), None);
        }
    }

    #[test]
    fn table_has_one_row_per_source_line() {
        assert_eq!(JobState::TRANSITIONS.len(), 5);
        assert_eq!(JobState::TRANSITIONS[2], ("Idle | Running", "Failed", "Crash"));
        assert_eq!(JobState::TRANSITIONS[4], ("Running", "Failed", "after 30"));
    }
}

実測（出題者の環境: rustc 1.96.0 / cargo 1.96.0 / edition 2024 / Apple M1 8GB / macOS 26.5.1、2026-10-02）

cargo run -q:

📋 コピーafter Start        : Running
timeout in Running : Some((Failed, 30))
Done + Reset       : Ok((Idle, Some("reset")))
Idle + Finish      : event Finish is not allowed in state Idle
("Idle", "Running", "Start")
("Running", "Done", "Finish")
("Idle | Running", "Failed", "Crash")
("Done | Failed", "Idle", "Reset")
("Running", "Failed", "after 30")

cargo test -q の末尾: test result: ok. 4 passed; 0 failed。cargo clippy --all-targets は警告 0 件。ソースは 167 行（テスト込み）。

D1 の回答: tt マンチャを選ぶのは「行の書式が混ざるから」。弱点は 126 行目で出る

• 採った理由: R5 の after 行を on 行と同じ表に混ぜる要件があるから。ここが (B) の限界で、tt マンチャを使う唯一の正当な理由です。「on 行だけの表」なら (B) を使うのが正解で、tt マンチャを選ぶ理由はありません
• 却下した (B): 2000 行が通る強さは魅力ですが、after 行を混ぜられない
• 却下した (C): 設計としては健全。ただし「1行ごとに遷移を書く表」という DSL の見た目を崩す。前提が変わったら判断が変わる: 遷移が 125 行を超える表を扱う、または #![recursion_limit] を利用者に上げさせたくない場合は (C) に切り替える
• 再帰上限の読み方: 既定の recursion_limit は 128。今回は1行につき再帰が1段、入口と終端で数段使うので、行数 + 数段で上限に当たる（上の実測: 125 行まで可・126 行で不可）。#![recursion_limit = "256"] を crate の先頭に置けば伸ばせるが、今日は 256 での上限は測っていない

D2 の回答: 検査はマクロの内側に入れる

on と timeout に #[deny(unused_variables, unreachable_patterns)] を付けて生成します。

• 代償: lint を deny にすると、利用者は意図して未使用の束縛を書けなくなる（例: _ や Failed if cond のような拡張）。今回の DSL ではそのような書き方を許していないので問題にならない
• 測った効果: Runing => Done on Finish; と書いたとき、deny を付けない版は警告だけでコンパイルが通る。deny を付けた版は error: unused variable: Runing` で落ちる（どちらも実測）。2重定義 Running => Failed on Finish; の追加は error: unreachable pattern`（実測）

D3 の回答: paste は使わない

• 採らなかった理由: paste は手続き的マクロの依存で、外部クレートなしの要件に反する。名前を呼び出し側が書く手間（state JobState）は1か所だけ
• 前提が変わったら: 状態機械を20個以上定義するなら、名前の組み立てを任せる価値が出る。その場合も、まず次月の「マクロ②（手続き的マクロ）」で、paste を使わず自作する選択肢と比べる

🪜 Step-by-Step 解説

Step 1: 入口の規則は宣言だけを受け取る

📋 コピー(state $State:ident { $($S:ident),+ $(,)? }
 event $Event:ident { $($E:ident),+ $(,)? }
 $($table:tt)*) => { ... };

$($table:tt)* は「残りのトークンを全部」受け取ります。tt（token tree）は1つのトークン、または対になった括弧の中身全部で、どんな入力でも必ず一致するので、解析を後回しにするのに使えます。入口では遷移表を読まず、そのまま @munch へ渡します。

Step 2: @munch — 1行食べて、残りを渡す

📋 コピー(@munch $State:ident $Event:ident [$($on:tt)*] [$($after:tt)*] [$($row:tt)*]
 $from:pat => $to:ident on $ev:ident ; $($rest:tt)*) => {
    fsm!(@munch $State $Event
        [$($on)* ($from, $Event::$ev) => Ok(($State::$to, None)),]
        [$($after)*]
        [$($row)* (stringify!($from), stringify!($to), stringify!($ev)),]
        $($rest)*);
};

• 先頭の @munch は規則を選ぶための目印で、入口の規則（state ... で始まる）と衝突しません
• [$($on:tt)*] がアキュムレータ。呼び出しのたびに $($on)* に新しい腕を足して、次の呼び出しへ渡します。1行ごとに配列の前後へ足すだけで、途中の腕を書き換えることはしません
• 食べた行は $($rest)* から消えるので、入力は1行ずつ短くなり、必ず終端の規則に着く

Step 3: 終端でまとめて impl を出す

📋 コピー(@munch $State:ident $Event:ident [$($on:tt)*] [$($after:tt)*] [$($row:tt)*]) => {
    impl $State {
        pub fn on(self, ev: $Event) -> Result<...> {
            use {$State::*, $Event::*};
            match (self, ev) {
                $($on)*
                (state, event) => Err(Rejected { state, event }),
            }
        }
        ...
    }
};

溜めた腕を match の中に展開するのは、終端の規則だけです。途中の規則は match の枠を知らないまま腕だけを運びます。これがアキュムレータの基本形です。

Step 4: pat を match の腕にそのまま置く

($from, $Event::$ev) => ... で $from は Idle | Running のような**最上位の | を含むパターン**を1つの塊として運びます。edition 2021 以降の pat はこの形に一致します。edition 2018 の挙動に戻す pat_param を使うと Idle | Running が通らない（実測は後述）。

Step 5: 裸の名前が列挙子に見える仕組みと、その裏返しの危険

use {$State::*, $Event::*}; を関数の中に書くと、Idle は JobState::Idle に解決されます。**この use が無いと**、Idle は新しい変数名として扱われ、どの状態にも一致する腕になります。逆に、use があっても列挙子にない名前（typo）は変数の束縛になる。ここが R7(a) の原因で、#[deny(unused_variables)] が止める仕組みです。

Step 6: 表の行を stringify! で作る

stringify!($from) は pat の塊をソースの見た目どおりの文字列にします（Idle | Running）。after 行は concat!("after ", stringify!($n)) で "after 30" にします。TRANSITIONS は定数なので、実行時の確保はありません。

Step 7: オラクルと照合する

all_16_pairs_match_the_oracle は、oracle 関数（人が手で書いた match）と、マクロが生成した on を 16 組すべてで突き合わせます。マクロの出力をマクロ自身の出力で検証しないのが要点で、TRANSITIONS（マクロが作る表）と on（マクロが作る関数）を比べるテストでは、両方が同じ誤りを持っていても通ってしまいます。

🧭 設計思想・なぜこう書くのか

マクロは「書式の読み取り」だけを担当し、意味は型に任せる

今回、マクロがやっているのは「行をばらして match の腕に並べ直す」ことだけです。状態遷移の意味（その事象で遷移してよいか）は、生成された match と Result が持っています。遷移表の誤りの検出は unreachable_patterns と unused_variables、型の検査は列挙型に任せ、マクロに独自の検査を書かない。Day 058 で見た「マクロをやめる」の延長で、マクロの責務を最小にすると壊れ方が減ります。

判断の記録: 今日の問題の作り方

実装の途中で、最初は要件に after が無く、(B) の平らな版で全部書けることに気づきました。それでは tt マンチャを使う理由が無く、問題として成立しないので、混在行を要件に足しています。

🚨 コンパイルエラーが出た場合

どれも出題者の環境（rustc 1.96.0）で実際に出たものを短縮しています。

警告1: 遷移元の typo は、deny が無いと警告だけで通る（R7(a)）

Runing => Done on Finish; と書くと、deny なしの版では次の警告が出て、コンパイルは通ります。

読み方: 「Runing という新しい変数を作ったが使っていない」＝列挙子ではなく変数の束縛として読まれた。この腕は (何でも, Finish) に一致するので、Done への遷移があらゆる状態で起きるようになります。deny 付きの版では同じ内容が error: unused variable: Runing`` になります。

エラー2: 2重定義（R7(b)）

Running => Done on Finish; の後ろに Running => Failed on Finish; を足すと、deny 付きの版で error: unreachable pattern。後ろの行が前の行に隠れて決して使われないことを示します。どちらを残すかはマクロでは決められません。

エラー3: 事象名の typo は、元から E0599

on Finsh; → error[E0599]: no variant, associated function, or constant named Finsh found for enum JobEvent`。コンパイラが Finish を候補に挙げます。遷移先の typo（Dne`）も同じ E0599 です。

エラー4: セミコロンを忘れた

Running => Done on Finish（; なし）→ 次の行の Idle が来た時点で error: no rules expected Idle`、補足に while trying to match meta-variable $note:literal。**どの規則のどの位置で止まったか**が補足に出るので、エラー位置ではなく**この補足を読む**のが tt マンチャのデバッグの基本です。メモ付きの規則（$note:literal` が期待される規則）で失敗が報告されるのは、最後に試した規則の位置が出るため。

エラー5: 遷移が 126 行を超えた

error: recursion limit reached while expanding fsm!`（126 行では stringify! の展開で、127 行以降は fsm! の展開で出た。どちらも実測）。対処は #![recursion_limit = "256"]` か、D1 の (C) への切り替え。

エラー6: pat_param に変えた

$from:pat_param にすると Idle | Running => ... が error: no rules expected |`（補足: while trying to match =>）になります。**pat は edition 2021 以降で最上位の | を含み、pat_param` は含まない**ためです。

🌐 他言語との比較

Go は状態機械を switch と定数で書くのが普通で、表から生成するなら外部の生成ツールになります。Rust は同じことを言語内で、利用者のコードと同じ型検査にかけられるのが違いです。ただし今日は他言語での実測はしていません（表は言語の仕様に関する一般的な整理です）。

🛠 実務での使いどころ

• プロトコルの状態機械（接続・認証・再送）を表の形で宣言し、match の書き漏れをコンパイラに見つけさせる。既存のクレートでは rust-fsm や statig などがあるが、今日は比較していないので、実務で使う前に両者の機能（階層状態・非同期対応など）と自作を比べること
• **「宣言の表」＋「生成された TRANSITIONS」**は、遷移図（Graphviz など）の自動出力や、ドキュメントとコードのずれの検出に使える
• 実務では「on 行だけの表」なら平らな繰り返し (B) が堅い。tt マンチャは、行の書式が混ざる DSL や、前の行を見て次を決める DSL のためにとっておく

⚠️ よくある誤解・ミス

📖 一次資料（参照日: 2026-10-02。記述は各資料の要旨で、原文の引用ではありません）

• The Little Book of Rust Macros（tt muncher・internal rules・push-down accumulation の章）: https://veykril.github.io/tlborm/
• The Rust Reference「Macros By Example」（フラグメント指定子 pat・pat_param・literal、edition による pat の違い、再帰）: https://doc.rust-lang.org/reference/macros-by-example.html
• The Rust Reference「Patterns」（識別子パターンが束縛になる規則）: https://doc.rust-lang.org/reference/patterns.html

注意: 今日は上記ページを取得し直して照合していません。記述は出題者の既存知識と、実際にコンパイルして得た挙動（上の実測）に基づいています。参照した資料の記述と食い違う場合は、実測を優先して資料側を確認してください。

🔭 今日扱わなかった範囲（次回以降）

3 問の自己点検（/ai-smell-audit 相当）

• 同じ指示を AI に出せば数時間で出るか: コード自体は出る。出ないのは、「平らな版で全部書けてしまう」ことに気づいて要件を足した判断と、typo が警告で通るという実測、2000 行と 126 行の境目の数字
• AI の指示だけでは出ない部分: D1 の測定（125/126 行・2000 行）、D2 の「deny あり／なし」の比較、判断の記録
• 世界の実物に対する割合: 状態機械クレートの機能（階層・ガード・非同期・図の出力など）のうち、今日は遷移・タイムアウト・表の出力の3つだけ。実在クレートは未確認なので割合は数えていない

➡️ 次のステップ

• 発展: Idle => Running on Start if ready; のようなガード付き遷移を足す。if は pat の follow-set に含まれるので、$from:pat if $g:expr と書ける。ただし pat の中にガードが吸い込まれないかを確かめる
• 次回予告: マクロ① の5問目（設計・アーキテクチャ）— 「マクロにするか、関数・型にするか」の判断を、今週書いた4つのマクロ（hashmap!・count!・fsm! など）で通して行う

🎯 自己評価（解いた後に記入）

自分の回答

気づき・メモ