cctg: rust07 Packages, Crates, and Modules

程式都會遇到 scope 的問題，在某一個時間點，compiler 知道些變數，允許呼叫哪些函數，變數引用是什麼？

rust 有 module system

packages: 是 cargo 的功能，可建立、測試、分享 crate
crates 是一個 module 的樹狀結構，有 library 或 binary project
modules 和 use: 允許你控制 scope 及 privacy of paths
paths: 對 struct, function, module 命名的方法

Packages and Crate

crate 是 binary 或是 library
crate root 一份描述如何建構 create 的文件
一個 Package 是一個或多個 crates
Package 透過 Cargo.toml 用來描述建構 crates
package 可包含 0 或 1 個 library crate，不能超過。可包含多個 binary crates。至少要包含一個 crate (library 或 binary 都可以)

cargo new 就是在產生一個新的 package

$ cargo new my-project
     Created binary (application) `my-project` package

cargo package 預設就是在 Cargo.toml 同一層的目錄中，有包含 src 目錄，且裡面有 main.rs 時， cargo 就知道這個 package 帶有一個跟 package 同名的 binary crate，且 src/main.rs 就是 crate root。另外如果 src/lib.rs，其 package 帶有同名的 library crate，且 src/lib.rs 是 crate root。 crate root 檔案將會傳給 rust 用來建構 library 或是 binary。

package 可包含 0 或 1 個 library crate，不能超過。可包含多個 binary crates。至少要包含一個 crate (library 或 binary 都可以)

如果 package 同時包含 src/main.rs 及 src/lib.rs，就是帶有兩個 crate: 一個同名 library，一個同名 binary。package 可帶有多個 binary crate，要將其檔案放在 src/bin 目錄，每個檔案都是一個獨立的 binary crate。

Defining Modules to Control Scope and Privacy

module system

module: 組織 code 與控制路徑私有性的方法
paths: 命名 items 的方法
use: 將某個 path 帶入 scope
pub: 開放 items，讓 items 變成公有
as: 將 item 引入 scope 時，用來 rename
external packages
glob operator: 將 module 的所有內容引入 scope
將不同 module 分割到獨立的檔案中

module 可組織程式碼，將 crate 分組，增加 readability 與 reuse 便利性。module 也可以控制 privacy of items，item 可以是 public (可被 outside code 使用)，或是 private，只是 internal implementation。

以下是 restaurant 的 library crate 範例

在一個餐廳可分兩個部分：front of house 及 back of house。front of house 包含 seating customers, 收單的 servers，payment，製作飲料的 bartenders。back of house 包含chef，在廚房燒菜，洗碗機，及負責管理的 managers。

首先建立一個新的 library

cargo new --lib restaurant

修改 src/lib.rs

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() {}
    }
}

modules 可包含其他 items 的定義：structs, enums, constants, traits, functions

module 可將相關的定義放在一起。

src/main.rs, src/lib.rs 分別稱為 crate roots

以上就是產生了這樣的 module tree。類似 file system 的目錄樹，另一個類似的地方，是需要用 path 來找到適當的 module 或 item。

crate
 └── front_of_house
     ├── hosting
     │   ├── add_to_waitlist
     │   └── seat_at_table
     └── serving
         ├── take_order
         ├── serve_order
         └── take_payment

Paths for Referring to an item in the Module Tree

rust 以 path 在module tree 中定位 item，如果要呼叫某個 function 就必須要知道他的 path

path 有兩種形式，兩種都有一或多個 identifiers，id 之間以 :: 區隔

absolute path: 從 crate root 開始，以 crate 開頭
relative path: 從目前的 module 開始，以 self, super 或目前的 module 的 id 開始

mod front_of_house {
    mod hosting {
        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();
}

在編譯時，會發生 error ，這是 privacy 的問題

error[E0603]: function `add_to_waitlist` is private
 --> src/lib.rs:9:37
  |
9 |     crate::front_of_house::hosting::add_to_waitlist();
  |                                     ^^^^^^^^^^^^^^^

error[E0603]: function `add_to_waitlist` is private
  --> src/lib.rs:12:30
   |
12 |     front_of_house::hosting::add_to_waitlist();
   |                              ^^^^^^^^^^^^^^^

rust 的所有 items: funcitons, methods, structs, enums, modules, constants 預設都是 private。在 parent module 的 items 不能使用 child modules 裡面的 private items。但 child modules 的 items 可以使用 ancestor modules 的 items。原因是 child modules 會 wrap & hide implementation details，但 child modules 可看到跟其定義相同的 context 的其他 items。

rust 會隱藏 inner implementation details，因此我們可知道如何在不影響 outer code 的狀況下，改變 inner code。可利用 pub keyword 讓 item 變成 public。

Exposing Paths with `pub`

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

// 因為 eat_at_restaurant 跟 front_of_house 是相同的 module，故可直接使用 front_of_house
pub fn eat_at_restaurant() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();
}

Starting Relative Paths with `super`

super 類似 filesystem 的 .. 用途，代表 parent module。

backofhouse 跟 serve_order 在相同的 module

fn serve_order() {}

mod back_of_house {
    fn fix_incorrect_order() {
        cook_order();

        // super 就等同於 crate
        super::serve_order();
    }

    fn cook_order() {}
}

Making Structs and Enums Public

如果在 struct 定義前面加上 pub，可讓 struct 變成 public，但 struct 裡面的欄位還是 private。必須單獨每一個欄位分開設定 pub

mod back_of_house {
    pub struct Breakfast {
        pub toast: String,
        seasonal_fruit: String,
    }

    // 為 Breakfast 增加 public method: summer
    impl Breakfast {
        pub fn summer(toast: &str) -> Breakfast {
            Breakfast {
                toast: String::from(toast),
                seasonal_fruit: String::from("peaches"),
            }
        }
    }
}

pub fn eat_at_restaurant() {
    // Order a breakfast in the summer with Rye toast 訂早餐
    let mut meal = back_of_house::Breakfast::summer("Rye");

    // Change our mind about what bread we'd like 修改餐點
    meal.toast = String::from("Wheat");
    println!("I'd like {} toast please", meal.toast);

    // The next line won't compile if we uncomment it; we're not allowed
    // to see or modify the seasonal fruit that comes with the meal
    // 無法修改 seasonal_fruit，因為該欄位是 private
    // meal.seasonal_fruit = String::from("blueberries");
}

對於將 enum 設定為 public，只需要在定義的地方加上 pub，就會讓所有 variants 都是 public

mod back_of_house {
    pub enum Appetizer {
        Soup,
        Salad,
    }
}

pub fn eat_at_restaurant() {
    let order1 = back_of_house::Appetizer::Soup;
    let order2 = back_of_house::Appetizer::Salad;
}

Bringing Paths info Scope with `use`

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

// 原本在使用 hosting，必須要透過 相對或絕對路徑
// 透過 use 宣告後，後面就可直接使用 hosting
use crate::front_of_house::hosting;

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

use 要使用相對路徑有一點點不同，路徑必須要用 self 開頭。不過目前實測，如果不寫 self 也沒有問題。

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

// self 也可以不寫
//use self::front_of_house::hosting;
use front_of_house::hosting;

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

Creating Idiomatic `use` Paths

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

// use 可以將 add_to_waitlist 引入，這樣後面的程式，就可以直接呼叫這個 fn
// 但這樣是不好的寫法
// 因為使用 add_to_waitlist 時，感覺 add_to_waitlist 是定義在這個 module 裡面
// 而上面 hosting::add_to_waitlist(); 這樣的呼叫方式
// 比較清楚知道，add_to_waitlist 是定義在其他地方
use crate::front_of_house::hosting::add_to_waitlist;

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

當 use structs, enums, 其他 items 時，最好指定 full path。例如指定使用標準函式庫的 HashMap

use std::collections::HashMap;

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

唯一的例外是，在 scope 中，使用了兩個相同名稱的 items，這時必須要加上 parent module，用來區分 items

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

fn function1() -> fmt::Result {
}

fn function2() -> io::Result<()> {
}

Providing New Names with `as`

使用相同名稱的 items 有另一種解決方法，就是用 as 加上替代的 new local name

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

fn function1() -> Result {
}

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

Re-exporting Names with `pub` `use`

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

// 在 use 前面再加上 pub
// 就等於將 hosting 變成 public，外面的 code 也可以直接使用 hosting::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();
}

Re-exporting 在程式碼的 internal structure 跟外面呼叫你的 code 的方法不同時，會很有用。例如餐廳，營運者很容易了解 "front of house" "back of house" 的意義。但客戶可能不懂這兩個名詞，這時候，可以透過 pub use 調整結構。

Using External Packages

先前專案有使用 rand 這個 external package，是在 Cargo.toml 裡面加上 rand

[dependencies]
rand = "0.5.5"

加上 rand 的定義後，等於將 rand 帶入這個 package 的 scope。透過 use 引用 Rng

use rand::Rng;
fn main() {
    let secret_number = rand::thread_rng().gen_range(1, 101);
}

Rust community 將許多 library packages 都放在 https://crates.io，

標準函式庫 std 也是一個 crate。但因為 std 是在 rust language 裡面，所以不需要另外在 Cargo.toml 裡面填寫到 dependencies 中。

Using Nested Paths to Clean Up Large `use` Lists

如果同時要使用兩個以上的 module，但 std:: 會一直重複。

use std::cmp::Ordering;
use std::io;

改用這個方式

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

另一個例子

use std::io;
use std::io::Write;

// 改為
use std::io::{self, Write};

The Glob Operator

如果想使用某個 path 的所有 public items，就用 *

use std::collections::*;

Separating Modules info Different Files

先前的範例都是將多個 module 定義在一個檔案中。可以將 module 分在不同檔案。

修改 src/lib.rs

// 定義在 src/front_of_house.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/frontofhouse.rs

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

可再進一步分離 hosting

修改 src/frontofhouse.rs

pub mod hosting;

新增 src/frontofhouse/hosting.rs

pub fn add_to_waitlist() {}

References

The Rust Programming Language

中文版

中文版 2

cctg

2020/3/30

rust07 Packages, Crates, and Modules

Packages and Crate

Defining Modules to Control Scope and Privacy

Paths for Referring to an item in the Module Tree

Exposing Paths with `pub`

Starting Relative Paths with `super`

Making Structs and Enums Public

Bringing Paths info Scope with `use`

Creating Idiomatic `use` Paths

Providing New Names with `as`

Re-exporting Names with `pub` `use`

Using External Packages

Using Nested Paths to Clean Up Large `use` Lists

The Glob Operator

Separating Modules info Different Files

References

沒有留言:

張貼留言

analytics

Creative Commons License

2020/3/30

rust07 Packages, Crates, and Modules

Packages and Crate

Defining Modules to Control Scope and Privacy

Paths for Referring to an item in the Module Tree

Exposing Paths with pub

Starting Relative Paths with super

Making Structs and Enums Public

Bringing Paths info Scope with use

Creating Idiomatic use Paths

Providing New Names with as

Re-exporting Names with pub use

Using External Packages

Using Nested Paths to Clean Up Large use Lists

The Glob Operator

Separating Modules info Different Files

References

沒有留言:

張貼留言

Exposing Paths with `pub`

Starting Relative Paths with `super`

Bringing Paths info Scope with `use`

Creating Idiomatic `use` Paths

Providing New Names with `as`

Re-exporting Names with `pub` `use`

Using Nested Paths to Clean Up Large `use` Lists