第16章 公開APIと外部パッケージ.

pub mod shop;

// ここに1行足せ（Cartをクレートルートから公開し直す）
pub use crate::shop::cart::Cart; 

pub mod cart;

pub struct Cart {
    prices: Vec<u32>,
}

impl Cart {
    pub fn new(prices: Vec<u32>) -> Self {
        Cart { prices }
    }

    /// 送料込みの合計金額（3000円以上は送料無料）
    pub fn total(&self) -> u32 {
        let mut sum = 0;
        for price in &self.prices {
            sum += price;
        }

        if sum >= 3000 { sum } else { sum + 500 }
    }
}

use playground::Cart;

fn main() {
    let cart = Cart::new(vec![980, 1250]);
    println!("お支払い金額: {}円", cart.total());
}

use宣言にpubを付けたpub useが再エクスポートです。第14章で学んだとおりuseは名前をそのスコープへ持ち込む宣言でしたが、pubが付くと、持ち込んだ名前をそのスコープの外へも公開します。

今回pub use crate::shop::cart::Cart;を書いた場所はクレートルートなので、Cartはクレートルートの名前としても公開されます。結果として、使う側はplayground::Cartと書けるようになります。

crate（ライブラリ）
├── shop
│   └── cart
│       └── Cart      // 定義されている場所
└── Cart              // pub use で開いた入口（同じ型を指す）

何が良いのか
この1行がないと、使う側は定義されている場所まで自分でたどることになります。

利点は短さだけではありません。使う側が書くパスと、作る側の内部構造が切り離されることが本質です。あとでcartを別のモジュールへ移しても、lib.rsのpub useの行を直せば済み、使う側のコードは無傷です。再エクスポートなしの場合は、内部を動かすたびに使う側が壊れます。

あくまで別名
pub useは型を移動させるわけではありません。Cartが定義されている場所はcrate::shop::cart::Cartのままで、playground::Cartはそこへの入口が1つ増えただけです。今回はpub mod shopと公開してあるので、use playground::shop::cart::Cart;と長いほうのパスで書いても動きます。この「長いほうの道」を塞ぐ方法が、次の問題02です。

// pubを付けていないので、priceモジュール自体は外から見えない
mod price;

// 使ってほしいものだけをクレートルートで公開する
pub use crate::price::Receipt;

pub struct Receipt {
    pub total: u32,
}

impl Receipt {
    pub fn issue(prices: &[u32]) -> Self {
        let mut sum = 0;
        for price in prices {
            sum += price;
        }

        Receipt { total: sum }
    }
}

use playground::price::Receipt; 
use playground::Receipt; 

fn main() {
    let receipt = Receipt::issue(&[980, 1250]);
    println!("合計: {}円", receipt.total);
}

エラーはmodule 'price' is private（E0603）で、指されているのはパスのpriceの部分です。Receiptではありません。

lib.rsのmod price;にはpubが付いていません。第13章で学んだとおり、pubが付いていないモジュールはクレートの外から見えないので、playground::price::...というパスはpriceのところで止まります。問題01との違いはここだけです。

それなのにReceiptは使える
不思議に見えるかもしれません。priceが見えないのに、その中にあるReceiptはplayground::Receiptとして使えます。

crate（ライブラリ）
├── price             // 非公開 → この道は通れない
│   └── Receipt       // pub
└── Receipt           // pub use で開いた入口 → こちらは通れる

再エクスポートが隠すのは経路であって、項目そのものではありません。pub useはプライバシーの連鎖を短絡させ、非公開のモジュールの中にある公開された項目へ、別の道を1本だけ開けます。開いていない道（playground::price::Receipt）は塞がったままです。

これが公開APIの設計
問題01の構成では、使う側は短いパスと長いパスのどちらでも書けました。この問題の構成では、短いパスしか存在しません。

いちばん下の形なら、priceというモジュール名を変えようが、中を2つに分割しようが、pub useの行さえ直せば外への約束は変わりません。外に見せたいものだけをpub useで通し、モジュール自体は非公開のままにするというのが、ライブラリを作るときの定番の形です。

pubが付いた項目しか通せない
price.rsのReceiptにはpubが付いています。ここを非公開にすると、同じクレートの中であってもpub useできずE0364になります。隠せるのは経路だけなので、通したい項目そのものにはpubが必要です。

// ここに1行足せ（regexクレートのRegexを持ち込む）
use regex::Regex; 

fn main() {
    // 商品コード（英大文字1文字 + ハイフン + 数字4桁）の形式かどうかを判定する
    let code_pattern = Regex::new(r"^[A-Z]-[0-9]{4}$").unwrap();

    for code in ["A-1234", "12345"] {
        println!("{code} は商品コードの形式か: {}", code_pattern.is_match(code));
    }
}

自分で書いていない外部パッケージを使う手順は2段階です。

1つ目はCargoへの指示です。これを見てCargoがcrates.ioからパッケージを取得し、コンパイルして、自分のクレートから使えるように渡してくれます。2つ目は第14章で学んだuseそのもので、外部のクレートだからといって特別な書き方はありません。

なぜ2段階なのか
2つは目的が別なので、忘れたときの症状も違います。

useは名前を短くするためのものなので、なくても書けます。実際、useを消してlet code_pattern = regex::Regex::new(..)と書いても動きます。第14章の慣習どおり、構造体などの型は項目そのものまで持ち込むのが一般的なので、ここではuse regex::Regex;としました。

バージョンの"1"の意味
regex = "1"は「1.0.0以上2.0.0未満」という要件です。この範囲であれば互換性が保たれる約束（セマンティックバージョニング）になっているので、細かい版を指定せずに書くのが普通です。手で書く代わりにcargo add regexと実行すれば、Cargoが適切な行を追記してくれます。

このコードが何をしているか
Regex::new(..)は正規表現をコンパイルしてResultを返します（第12章）。今回のパターンは文字列リテラルとして正しいことが分かっているので、unwrapで取り出しています。r"..."は生文字列リテラルで、\をエスケープせずに書ける記法です。正規表現そのものはRustの話ではないので、ここでは「外部のクレートを1つ使ってみる」という部分だけ押さえてください。

use std::collections::HashMap; 

fn main() {
    // 商品ごとの在庫数
    let mut stock = HashMap::new();
    stock.insert("りんご", 3);
    stock.insert("みかん", 12);

    println!("りんごの在庫: {}個", stock["りんご"]);
    println!("みかんの在庫: {}個", stock["みかん"]);
}

エラーはuse of undeclared type 'HashMap'（E0433）です。HashMapは標準ライブラリのstd::collectionsにある型で、使うにはuse std::collections::HashMap;が要ります。

問題03の表と並べると、標準ライブラリの位置付けがはっきりします。

stdクレートは、特別な指定をしない限り常にコンパイラへ渡されます。そのため依存として宣言する必要がありません。ですが、渡されていることと、名前が短く書けることは別の話です。stdの中にある項目を裸の名前で使いたければ、外部パッケージとまったく同じようにuseが要ります。

StringやVecにuseが要らない理由
ここまでStringもVecもuseなしで使ってきました。これらはプレリュードと呼ばれる、あらかじめ自動で取り込まれる項目群に入っているためです。stdの中でも特によく使うものだけが選ばれていて、HashMapはそこに入っていません。

「useが要るかどうか」はプレリュードに入っているかどうかで決まる、と考えると混乱しません。

エラーメッセージが答えを教えてくれる
今回のエラーには、次のヒントが付いています。

help: consider importing this struct
  |
1 + use std::collections::HashMap;

コンパイラがHashMapという名前を持つ項目を探し出して、必要なuseの行をそのまま提示してくれます。「型名は分かるがどこにあるか分からない」というときは、とりあえず書いてコンパイルし、この助言を読むのが速い方法です。

// 内部のモジュールを読み込め（クレートの外へは見せないこと）
mod cart; 
mod price; 

// 公開APIを整えよ（Cartとwith_taxをクレートルートから使えるようにする）
pub use crate::cart::Cart; 
pub use crate::price::tax::with_tax; 

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

    fn sample() -> Cart {
        let mut cart = Cart::new();
        cart.add("コーヒー豆", 1200);
        cart.add("マグカップ", 800);
        cart
    }

    #[test]
    fn test_count() {
        let cart = sample();
        assert_eq!(cart.count(), 2);
    }

    #[test]
    fn test_find_price() {
        let cart = sample();
        assert_eq!(cart.find_price("コーヒー豆"), Some(1200));
        assert_eq!(cart.find_price("ビール"), None);
    }

    #[test]
    fn test_with_tax() {
        assert_eq!(with_tax(1000), 1100);
        assert_eq!(with_tax(105), 115);
    }

    #[test]
    fn test_total_with_shipping() {
        // 小計2000円 → 税込2200円 → 3000円未満なので送料500円
        assert_eq!(sample().total(), 2700);
    }

    #[test]
    fn test_total_free_shipping() {
        let mut cart = sample();
        cart.add("電気ケトル", 5000);
        // 小計7000円 → 税込7700円 → 3000円以上なので送料無料
        assert_eq!(cart.total(), 7700);
    }
}

// 商品を表す構造体Itemを定義せよ（name: String / price: u32）
struct Item { 
    name: String, 
    price: u32, 
} 

// 買い物カートを表す構造体Cartを定義せよ（items: Vec<Item>）
pub struct Cart { 
    items: Vec<Item>, 
} 

// Cartのimplブロックにnew・add・count・find_price・totalを定義せよ
// totalはpriceモジュールの関数を使い、消費税 → 送料の順に足すこと
impl Cart { 
    pub fn new() -> Self { 
        Cart { items: Vec::new() } 
    } 

    pub fn add(&mut self, name: &str, price: u32) { 
        self.items.push(Item { 
            name: String::from(name), 
            price, 
        }); 
    } 

    pub fn count(&self) -> usize { 
        self.items.len() 
    } 

    pub fn find_price(&self, name: &str) -> Option<u32> { 
        for item in &self.items { 
            if item.name == name { 
                return Some(item.price); 
            } 
        } 

        None
    } 

    pub fn total(&self) -> u32 { 
        let mut subtotal = 0; 
        for item in &self.items { 
            subtotal += item.price; 
        } 

        let taxed = crate::price::tax::with_tax(subtotal); 
        crate::price::with_shipping(taxed) 
    } 
} 

// taxの中身を src/price/tax.rs から読み込め
pub mod tax; 

// 送料の計算に使う定数を定義せよ（このモジュールの中だけで使う）
//   送料が無料になる金額: 3000
//   送料: 500
const FREE_SHIPPING_LINE: u32 = 3000; 
const SHIPPING_FEE: u32 = 500; 

// 税込価格を受け取り、3000円未満なら送料を足して返す関数with_shippingを定義せよ
pub fn with_shipping(price: u32) -> u32 { 
    if price >= FREE_SHIPPING_LINE { 
        price 
    } else { 
        price + SHIPPING_FEE 
    } 
} 

// 消費税率の定数TAX_RATEを定義せよ（10）
const TAX_RATE: u32 = 10; 

// 価格を受け取り、消費税を足した金額（端数切り捨て）を返す関数with_taxを定義せよ
pub fn with_tax(price: u32) -> u32 { 
    price * (100 + TAX_RATE) / 100
} 

プロジェクト構成編で学んだものが、ほぼすべて登場しました。

出来上がったモジュールツリーは次の形です。

crate（ライブラリ）
├── cart              // 非公開
│   ├── Item          // 非公開
│   └── Cart          // pub
├── price             // 非公開
│   ├── FREE_SHIPPING_LINE / SHIPPING_FEE  // 非公開
│   ├── with_shipping // pub
│   └── tax           // pub
│       ├── TAX_RATE  // 非公開
│       └── with_tax  // pub
├── Cart              // pub use
├── with_tax          // pub use
└── tests             // use super::* でクレートルートの名前を拾う

pubは1段ずつ、必要なところにだけ
この問題でいちばん間違えやすいのがpubの付け方です。pubは1段しか開かないので、外から使われる経路上のものには1つずつ付ける必要があります。

メソッドのpubは特に忘れがちです。pub struct Cartと書いてもメソッドは非公開のままなので、テストから呼ぶとE0624（method 'add' is private）になります。第13章の問題04で見た「構造体を公開してもフィールドは非公開」と同じ、1段ずつの原則です。

Itemと定数を非公開にできる理由
Itemはcartの中だけで使い、FREE_SHIPPING_LINEはpriceの中だけで使うので、どちらもpubが要りません。非公開のままにできたものが多いほど、あとから自由に変えられる部分が多いということです。たとえばItemにフィールドを1つ足しても、このライブラリを使う人には何の影響もありません。

with_shippingにだけpubが要る理由
同じ「内部で使うだけの関数」でも、with_shippingにはpubが必要でした。呼び出し元のcartがpriceの子孫ではないからです。第13章の問題06で確かめたとおり、非公開の項目が見えるのは、それを定義したモジュールとその子孫だけです。cartとpriceは兄弟なので、この関係にあてはまりません。

外に出したくないが同じクレートの中からは呼びたい、という意図をより正確に書くならpub(crate) fn with_shippingとします。今回はprice自体が非公開なので、pubでもクレートの外には漏れません。

パスの書き方
totalの中ではcrate::price::tax::with_tax(..)と絶対パスで書きました。第14章の問題01のとおり、絶対パスは書いている場所に依存しないので、既定の選択として無難です。useで短くするなら次のように書けます。

use crate::price::{self, tax};

// ...

    pub fn total(&self) -> u32 {
        let mut subtotal = 0;
        for item in &self.items {
            subtotal += item.price;
        }

        price::with_shipping(tax::with_tax(subtotal))
    }

use crate::price::{self, tax};は、第14章の問題03の表で挙げた波括弧の書き方です。selfがprice自身、taxがその子を指すので、1行で両方を持ち込めます。

テストが見ているもの
mod testsの中のuse super::*;が拾うのは、親であるクレートルートの名前です。cartやpriceの中身を直接見ているわけではありません。pub useを2行書いてはじめて、クレートルートにCartとwith_taxという名前ができ、テストがそれを使えるようになります。

裏を返せば、このテストは公開APIをそのまま使う形になっています。使う人が書くのと同じコードでテストしているので、公開APIの使い勝手もここで確かめられます。

テストでは守れない設計もある
mod cart;をpub mod cart;に変えても、テストは全部通ります。内部を隠せているかどうかは、テストでは検出できません。同じように、Itemにpubを付けても、with_shippingをpubのまま外に見せてもテストは通ります。

だからこそ、公開APIの形は自分で意識して決める必要があります。判断の基準はいつも同じで、「これは外との約束にしてよいか」です。約束にしたものは、あとから変えると使う側が壊れます。迷ったら隠しておき、必要になってからpub useで通すほうが安全です。