LearnixOS 書籍：Bitflags マクロの実装ガイド

キーボードショートカット

Bitflags マクロの導入

プロシージャルマクロとは？

• 定義: 「入力から出力へどのように置換するか」を指定する規則またはパターン。
  • 関数同様、入力を出力にマップしますが、ソースコードそのものに作用します。
• Rust の proc-macro 特徴:
  • 初期のコード（

    TokenStream

    ）を操作可能にする。
  • ソースコードをトークン化し、

    TokenTree

    ノードのシーケンスとして扱う。

基本的な実装例

#[proc_macro]
pub fn custom_proc_macro(input: TokenStream) -> TokenStream {
    eprintln!("{:?}", input);
    input // 同じものを返す（多くの場合は異なるコードを生成する）
}

トークンストリーム (

TokenStream

) とは？

• 文字列ではなくトークン単位で処理することで、初期のコードレベルでの操作が可能。

• TokenTree

  ノードのシーケンスを含みます。

  • Group

    : ブレースなどのデリミター付きストリーム

  • Ident

    : 識別子（例：変数名）

  • Punct

    : 句読点文字（例：

    +

    ,

    ,

    ）

  • Literal

    : リテラル文字、文字列、数値

デバッグ出力の例

TokenStream [
    Ident { ident: "struct", ... },
    Ident { ident: "Example", ... },
    Group {
        delimiter: Brace,
        stream: TokenStream [
            Ident { ident: "a", ... },
            Punct { ch: ':', ... },
            Ident { ident: "i32", ... },
            Comma,
        ],
    },
]

マクロの動作原理（展開）

• コンパイル時に評価される関数。
• コンパイラ視点：ターゲット言語を別の言語へマップするのではなく、同じ言語内で置換。

例：宣言的マクロの展開

// 定義
macro_rules! square {
    ($num:expr) => { $num * $num };
}

// 使用
fn foo() -> u32 {
    let x: u32 = 42;
    square!(x) // 実質的に：x * x
}

関数ではできないこと：コンテキスト依存の制御流

• 宣言的マクロが実現できる抽象化（例：ループからの抜出）。

macro_rules! unwrap_or_break {
    ($e:expr) => {
        match $e {
            Some(v) => v,
            None => break, // コンパイル時に入れ子された文脈 (`break`) を理解可能
        }
    };
}

// 関数実装だとエラーになる：None -> break は外部のスコープ参照が必要
fn unwrap_or_break<T>(e: Option<T>) -> T {
    match e {
        Some(v) => v,
        None => panic!("Error"), // ここでは break を使用できない
    }
}

マクロの種類

#[proc_macro]

TokenStream

#[proc_macro_derive]

derive

#[proc_macro_attribute]

Syn と Quote の導入

背景と必要性

• プロシージャルマクロでは直接

  TokenStream

  を解析するのは複雑。
• Syn: Rust の構文ツリーを**AST（抽象構文木）**に変換する。
• Quote: データ (

  TokenStream

  ) をコードのように見える形式に変換する。

AST とは？

• プログラムの構文構造を表す木構造。
• 操作しやすいデータ構造にするために、簡略化された Python の例：

current = 0
for item in items:
    if item > current:
        current = item

Syn で利用可能な主要 AST タイプ

• syn::File

  : 完全な Rust ソースファイル。

• syn::Attribute

  : 属性（例：

  #[derive]

  ）。

• syn::Item

  : モジュール内にある項目（定数、列挙体、関数、構造体など）。

• syn::Expr

  : 式（割り当て文、スライスリテラルなど）。

重要: AST のフィールド順序はソースコードの順序と一致する。これにより解析後の再構築が容易になる。

Quote と ToTokens

• Quoting: コードのように見せるが裏ではデータ (

  TokenStream

  ) として扱われる。
• ToTraits:

  quote!

  で使用可能なためのトレイト。

// クオートされた式（実際には TokenStream に変換される）
quote! { struct Foo { bar: () } }

// 変数をトークンに変換する例
let mut item_fn = syn::parse_macro_input!(input as syn::ItemFn);
item_fn.sig.ident = Ident::new("with_change_{}", ...);

quote! { #item_fn }.into() // `#` で変数を挿入

マクロの設計：Bitfields

要件と仕様

数値をフラグとして表現する（例：

u8

u16

• Getter: フラグ値の取得 (

  get_*

  )。
• Setter: フラグ値の設定 (

  set_*, new()

  )。
• Clearer: フラグのリセット (`clear_*)。

機能拡張機能（Attribute）

生成される関数を制御するメタデータ：

1. Permission:

   r

   (Read),

   w

   (Write),

   c

   (Clear value)。
2. FlagType: ユーザー定義の列挙体などを指定 (

   flag_type = MyEnum

   )。
   • デフォルトは幅に合わせた基本型（例：6 ビット ->

     u8

     ）。
3. DontShift: 絶対値で扱いたい場合の設定 (

   dont_shift

   )。
4. Helper Attributes: 生成されるコードのカスタマイズ。

#[bitfields]
struct MyFlags {
    #[flag(r)] // リードオンリー、オフセット 0-2
    a: B2,
    
    #[flag(rwc(10))] // レッド・ライト・クリア（値 10）、オフセット 3-7
    b: B5,
}

マクロの実装プロセス

設計思想：スモールステップで進める

実装を開始する前に、単純な例から機能を手作業で作成し、それを一般化すること。

1. 初期のビット演算ロジック

• マスキング: フラグ以外のビットをゼロにする。
• シフト:
  • リード時：フラグ位置へ右シフト (

    >>

    )。
  • ライト時：フラグ位置へ左シフト (

    <<

    )。

// マスク生成（全 1 から必要ない分を除去）
let mask = (u8::MAX >> (u8::BITS - width as u32)) << offset;

// リード値の取得
let val = (raw_value & mask) >> offset;

2. データ構造と定義

• FlagAttribute

  :

  r

  ,

  w

  ,

  c

  ,

  flag_type

  ,

  dont_shift

  などを格納。

• FlagMeta

  : ビット幅 (

  width

  ) と表現型 (

  repr_ty: u8/u16/...

  ) を格納。

• BitField

  : 単一のフラグフィールドのメタ情報。

3. 属性解析（Parse）

• syn::Attribute

  の

  Meta

  パートから情報を抽出。
• フォーク (

  input.fork()

  ) を用いて、成功/失敗を問わずストリームの正確な位置に戻せるようにする。

// 簡略化されたパーサーの概念実装
fn try_parse<T>(input: ParseStream, ..) -> Option<syn::Result<T>> {
    let fork = input.fork();
    match fork.parse::<T>() {
        Ok(parsed) => {
            // 成功：元の位置に戻し、解析されたデータを返す
            Some(Ok(parsed))
        },
        Err(_) => {
            // 失敗：エラーカウンター増やし、何もしない（フォークを放棄）
            None 
        }
    }
}

4. 構造体の解析と変換

• syn::ItemStruct

  を解析し、フィールドごとに情報を抽出。
• コメント属性（

  #[doc]

  ）と Flag 属性を分離。
• フィールドのオフセットを動的に計算し続ける。

impl<'a> BitField<'a> {
    pub fn new(field: &Field, offset: usize) -> syn::Result<Self> {
        // ... 属性解析、メタデータ抽出 ...
        Ok(BitField { 
            attr, vis, name, meta, offset, .. 
        })
    }
}

5. コード生成（Quote）

• チェック関数: リリースビルドでは無効だが、デバッグ用で値の範囲を確認。
• アクセサ生成:

  get_

  ,

  set_

  ,

  clear_

  を自動生成。

  • bool

    型の場合、

    is_*

    に名前を変更する。
• 安全な参照: 完全修飾名（例：

  ::core::ptr::read_volatile

  ）を使用し、コンパイル時エラーを回避。

// 簡略化された生成ロジック
impl<'a> BitFields<'a> {
    fn fn_read(&self, field: &BitField) -> TokenStream2 {
        // ... チェック処理、シフト処理 ...
        quote! {
            #[inline]
            pub fn get_#field_name(&self) -> #ty {
                unsafe { 
                    let val = self.0 as #repr_ty;
                    let mask = ...;
                    ((val & mask) >> offset) as #ty
                }
            }
        }
    }
}

6. 補助機能の実装

• From

  Trait: 構造体と内部型 (

  u8

  など) の相互変換。

• Debug

  Trait: フラグ状態を可視化するためのフォーマッター。
• Builder Pattern:

  flag1().flag2()

  のようなチェーン式設定の実装。

7. マクロ本体の統合

• 入力を受け取り、解析（またはエラー生成）を行う。
• 成功時はコードを返す。

#[proc_macro_attribute]
pub fn bitfields(_attr: TokenStream, item: TokenStream) -> TokenStream {
    let struct_def = parse_quote!(struct MyStruct { fields: ... });
    // BitFields::try_from(&struct_def).map(|...| quote!{#bitfields})
    // .unwrap_or_else(|e| e.into_compile_error())
}

まとめ

• プロシージャルマクロは、コンパイル時にコードを生成・置換する強力な機能。

• syn

  と

  quote

  を併用することで、複雑な構文ツリーの解析と再生成が容易になる。
• ビット操作とメタデータ駆動のデザインパターンによって、柔軟かつ安全なマクロを実装できる。