7 Rustのモジュールシステム

[lemonadern]

https://doc.rust-jp.rs/book-ja/ch07-00-managing-growing-projects-with-packages-crates-and-modules.html

[lemonadern]

Rustには、どの詳細を公開するか、どの詳細を非公開にするか、どの名前がプログラムのそれぞれのスコープにあるか、といったコードのまとまりを保つためのたくさんの機能があります。 これらの機能は、まとめて「モジュールシステム」と呼ばれることがあり、以下のようなものが含まれます。

• パッケージ: クレートのビルド・テスト・共有ができるCargoの機能
• クレート: ライブラリか実行可能ファイルを生成する、木構造をしたモジュール群
• モジュール と use: これを使うことで、パスの構成、スコープ、公開するか否かを決定
• パス: 要素（例えば構造体や関数やモジュール）に名前をつける方法

[lemonadern]

クレート

• 関連した機能を一つのスコープにまとめる
• ある機能が複数のプロジェクト間で共有されやすいようにする

例) randクレートのトレイトRngにアクセスするときはrand::Rngでアクセスする
⇨ 自分のプロジェクトで定義したRngとの衝突を防げる

[lemonadern]

特徴

• 一つのパッケージには、1つ以上のクレートを含む
• クレートはバイナリ・ライブラリのどちらか
• クレートルート（Crate Root）

  • Rustコンパイラの開始点となり、クレートのルートモジュールを作るソースファイルのこと

  • Cargoは、クレートルートファイルをrustcに渡すことでビルドを行う
• デフォルトでは、src/main.rs は、[パッケージ名]バイナリクレートのクレートルート
• デフォルトでは、src/lib.rs は、[パッケージ名]ライブラリクレートのクレートルート

[lemonadern]

モジュール

• クレート内のコードをグループ化できる機能
• 可読性・再利用性を上げるのに役立つ
• プライバシー（pub,private）の制御もできる

mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}
        fn seat_at_table() {}
    }

    mod serving {
        fn take_order() {}
        fn serve_order() {}
        fn take_payment() {}
    }
}

• モジュールは、mod キーワードで定義する
• モジュール内には、モジュール・構造体・enum・定数・トレイト・関数などを配置できる

crate // `crate`というモジュール
 └── front_of_house
     ├── hosting
     │   ├── add_to_waitlist
     │   └── seat_at_table
     └── serving
         ├── take_order
         ├── serve_order
         └── take_payment

• クレートのモジュールツリーのrootに、中身がcrateというモジュールを生成するので、crate rootと呼ぶ

[lemonadern]

パス

• モジュールツリー内の要素にアクセスするためには、パスを利用する
• 絶対パスと相対パスがある

絶対パス

• クレートの名前か、crateという文字列を指定して、クレートルートからツリーを辿る

// Absolute path
// 絶対パス
crate::front_of_house::hosting::add_to_waitlist();

相対パス

• self・super か、今いるモジュール内に存在する識別子を指定して、現在のモジュールからツリーを辿る

今いるモジュール内にあるモジュールからアクセスする

// Relative path
// 相対パス
front_of_house::hosting::add_to_waitlist();

super によって親のモジュールへアクセスする

fn serve_order() {}

mod back_of_house {
    fn fix_incorrect_order() {
        cook_order();
        super::serve_order(); // super を利用した呼び出し
    }

    fn cook_order() {}
}

[lemonadern]

絶対パス・相対パスのどちらを利用するか

要素を定義するコードを、その要素を使うコードと別々に動かすか一緒に動かすか、どちらが起こりそうかによって決めるのが良いです。

例えば、front_of_houseモジュールとeat_at_restaurant関数をcustomer_experienceというモジュールに移動させると、add_to_waitlistへの絶対パスを更新しないといけませんが、相対パスは有効なままです。 しかし、eat_at_restaurant関数だけをdiningというモジュールに移動させると、add_to_waitlistへの絶対パスは同じままですが、相対パスは更新しないといけないでしょう。 コードの定義と、その要素の呼び出しは独立に動かしそうなので、絶対パスのほうが好ましいです。

わかりそうでわからんから、コード書きながら考える

[lemonadern]

モジュールシステムのプライバシー

• Rustのプライバシーでは、デフォルトであらゆる要素が非公開
• 親モジュールから子モジュールの要素を利用することはできない （⇨実装詳細の隠蔽）
• 子モジュールから祖先のモジュールを利用できる（⇨子は、自分が定義された文脈を見ることができるため）
• 子モジュールを祖先に対して公開するときは、pub キーワードによって要素を公開する

[lemonadern]

mod front_of_house {
    pub mod hosting { // 公開
        pub fn add_to_waitlist() {} // 公開
    }
}

pub fn eat_at_restaurant() {
    // Absolute path
    // 絶対パス
    crate::front_of_house::hosting::add_to_waitlist(); // アクセスできる

    // Relative path
    // 相対パス
    front_of_house::hosting::add_to_waitlist(); // アクセスできる
}

[lemonadern]

構造体・enum の公開

構造体

• 構造体を公開しても、フィールドは非公開のままになる
• 外部モジュールからフィールドへのアクセスを許容する場合は、フィールドに個別に pub キーワードをつけて公開する必要がある

enum

• enum を公開すると、その variant は全て公開される

なぜ？

enumはヴァリアントが公開されてないとあまり便利ではないのですが、毎回enumのすべてのヴァリアントにpubをつけるのは面倒なので、enumのヴァリアントは標準で公開されるようになっているのです。 構造体はフィールドが公開されていなくても便利なことが多いので、構造体のフィールドは、pubがついてない限り標準で非公開という通常のルールに従うわけです。

enum はvariant が公開されていないとあまり便利ではない
構造体はフィールドが公開されていなくても便利なことが多い

[lemonadern]

use

• use キーワードによって、パスをスコープへ持ち込む
• 同じ名前の要素を2つ以上持ち込むことはできない

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use self::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
    hosting::add_to_waitlist();
    hosting::add_to_waitlist();
}

• 関数まで指定することで持ち込むこともできるが、慣例的ではない
  • use で指定するのはモジュール名までにすることで、利用するときにモジュール内に定義されていないということが分かるから
  • 別のモジュール同士で同じ名前の関数があった時、名前のバッティングを防ぐ

use std::collections::HashMap;

fn main() {
    let mut map = HashMap::new();
    map.insert(1, 2);
}

• 一方、構造体やenumを持ち込むときは、フルパスを書くのが慣例的
  • 自然に発生した風習

[lemonadern]

構造体やEnumでも、同じ名前のものがあるときは親モジュールによって区別して参照する

use std::fmt;
use std::io;

fn function1() -> fmt::Result {
    // --snip--
    // （略）
}

fn function2() -> io::Result<()> {
    // --snip--
    // （略）
}

[lemonadern]

as キーワードによって別名をつけて持ち込むという選択肢もある

use std::fmt::Result;
use std::io::Result as IoResult;

fn function1() -> Result {
    // --snip--
}

fn function2() -> IoResult<()> {
    // --snip--
}

[lemonadern]

pub use による 再公開 (re-expoting)

• pub use [パス]とすることで、そのモジュールでスコープを公開できる
• 持ち込むだけでなく、外部へ公開もするので、再公開(re-exporting)とよばれる

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
    hosting::add_to_waitlist();
    hosting::add_to_waitlist();
}

[lemonadern]

再公開は、あなたのコードの内部構造と、あなたのコードを呼び出すプログラマーたちのその領域に関しての見方が異なるときに有用です。

例えば、レストランの比喩では、レストランを経営している人は「接客部門 (front of house)」と「後方部門 (back of house)」のことについて考えるでしょう。 しかし、レストランを訪れるお客さんは、そのような観点からレストランの部門について考えることはありません。 pub useを使うことで、ある構造でコードを書きつつも、別の構造で公開するということが可能になります。

[lemonadern]

ネストしたパスをまとめてuse する

• 親が同じだがスコープに持ち込むポイントが異なるuseの記述をまとめることができる

パスに同じprefixを持つ場合

// before
use std::cmp::Ordering;
use std::io;

// after
use std::{cmp::Ordering, io};

片方がもう一つのサブパスであるような場合

// before
use std::io;
use std::io::Write;

// after
use std::io::{self, Write};

[lemonadern]

glob 演算子を利用して、全ての公開要素を持ち込むこともできる

use std::collections::*;

• スコープ内の名前がわかりにくくなる
• テストの際、あらゆる要素をtestsモジュールへと持ち込むときに使われる（らしい）

[lemonadern]

モジュールのファイル分割

• モジュール単位でファイル分割することができる
• クレートルートのファイルで、mod [モジュール名]; とすると、モジュールの中身が同名の別ファイルから読み込まれる

[lemonadern]

分割前のコード

mod front_of_house;

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
    hosting::add_to_waitlist();
    hosting::add_to_waitlist();
}

[lemonadern]

分割後のコード

src/
├── front_of_house
│   └── hosting.rs
├── front_of_house.rs
└── lib.rs

src/lib.rs

mod front_of_house;

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
    hosting::add_to_waitlist();
    hosting::add_to_waitlist();
}

src/front_of_house.rs

pub mod hosting;

src/front_of_house/hosting.rs

pub fn add_to_waitlist() {}

[lemonadern]

mod モジュール名;とする
ブロックの中に書いていた定義を、モジュール名.rsで記述する

ネストするときは、モジュール名/モジュール名1.rsなどとする
モジュール名.rsには、mod モジュール名1;と記述する