BAB 21: Module System: Inline Module
Inline module ditulis dengan mod lalu kurung kurawal di berkas yang sama, dan setiap tingkat module menambah 1 segmen path yang harus dibuka pub.
Satu berkas src/main.rs dapat memuat 3 tingkat module tanpa menambah satu berkas pun. Caranya dengan menulis mod, nama module, lalu kurung kurawal berisi item, bukan titik koma yang menunjuk berkas lain.
Bentuk itu disebut inline module. Reference Rust menyebutnya module item: module yang dikelilingi kurung kurawal, diberi nama, dan didahului kata kunci mod. Isinya boleh fungsi, konstanta, struct, atau module lain, dan module boleh bersarang tanpa batas.
Bab ini membahas bentuk inline module, aturan akses di setiap tingkat, dan 3 kode error yang muncul saat batas module tidak dibuka dengan pub. Setelah bab ini selesai, kamu dapat memecah 1 berkas menjadi beberapa module, memanggil isinya lewat path bertingkat, dan membaca E0425, E0603, serta E0428 sebagai kesalahan susunan module. Semua contoh dijalankan dengan rustc 1.100.0 pada package gudang di /tmp/latihan-rust/bab21.
Bentuk dasar: mod diikuti kurung kurawal
Kurung kurawal menggantikan titik koma pada deklarasi module. Isi module ditulis langsung di tempat itu, dan seluruh berkas tetap 1.
mod stok {
pub fn batas_minimal() -> u32 {
5
}
}
fn main() {
println!("batas: {}", stok::batas_minimal());
}
batas: 5
Nama fungsi di dalam module tidak berdiri sendiri lagi. Pemanggilan harus menyebut module asalnya, yaitu stok::batas_minimal(), karena crate root hanya mengenal nama stok. Kata kunci pub di depan fungsi menentukan apakah kode di luar stok boleh memanggilnya, dan aturan itu dibahas lewat error di bagian berikutnya.
Module bersarang dan kata kunci super
Module di dalam module menambah 1 segmen path untuk setiap tingkat. Program berikut memakai 2 tingkat module, lalu memanggil fungsi dari tingkat paling dalam.
mod stok {
pub mod rak {
pub fn jumlah() -> u32 {
12
}
pub fn lapor() {
println!("rak: {}, batas: {}", jumlah(), super::batas_minimal());
}
}
pub fn batas_minimal() -> u32 {
5
}
}
fn main() {
println!("batas: {}", stok::batas_minimal());
println!("rak: {}", stok::rak::jumlah());
stok::rak::lapor();
}
batas: 5
rak: 12
rak: 12, batas: 5
Ada 3 tingkat nama di program itu: crate root, stok, dan rak. Fungsi lapor memanggil jumlah tanpa path karena keduanya berada di module yang sama, lalu memakai super::batas_minimal() untuk naik 1 tingkat ke stok. Yang perlu diperhatikan, batas_minimal ditulis setelah mod rak, tetapi tetap bisa dipanggil dari dalam rak.
Urutan penulisan tidak berpengaruh karena nama item yang dideklarasikan langsung di dalam module punya cakupan dari awal module sampai akhir module. Aturan ini berbeda dari variabel lokal, yang baru ada setelah baris let dijalankannya.
Satu berkas, 3 tingkat module, dan path yang bertambah 1 segmen setiap turun 1 tingkat.
Memanggil nama tanpa path: E0425
Kesalahan pertama muncul saat nama di dalam module dipakai seolah berada di crate root. Program berikut menghapus bagian path-nya.
mod stok {
pub fn batas_minimal() -> u32 {
5
}
}
fn main() {
println!("batas: {}", batas_minimal());
}
error[E0425]: cannot find function `batas_minimal` in this scope
--> uji/tanpa_path.rs:8:27
|
8 | println!("batas: {}", batas_minimal());
| ^^^^^^^^^^^^^ not found in this scope
|
help: consider importing this function
|
1 + use stok::batas_minimal;
|
error: aborting due to 1 previous error
Pesan itu menyebut "in this scope", bukan "private", karena masalahnya bukan izin melainkan lokasi nama. pub pada batas_minimal hanya mengatur siapa yang boleh melihat dari luar module, bukan memindahkan nama fungsi ke scope main. Module adalah kotak tertutup: isinya hanya terlihat oleh kode yang menyebut path atau mengimpornya dengan use.
Perbaikannya 2 pilihan, yaitu menulis stok::batas_minimal() seperti pada contoh pertama, atau menambahkan use stok::batas_minimal; di atas main. Pilihan kedua membuat nama tersedia tanpa path, dan use itu hanya berlaku di module tempat ia ditulis.
pub membuka 1 tingkat, bukan seluruh jalur
Kesalahan kedua terjadi saat pub dipasang pada sebagian jalur saja. Program berikut memasang pub pada fungsi tetapi lupa pada module yang membungkusnya, lalu melakukan hal sebaliknya pada module kedua.
mod stok {
mod rak {
pub fn jumlah() -> u32 {
12
}
}
pub mod gudang {
fn batas_minimal() -> u32 {
5
}
}
}
fn main() {
println!("rak: {}", stok::rak::jumlah());
println!("batas: {}", stok::gudang::batas_minimal());
}
error[E0603]: module `rak` is private
--> uji/dua_privat.rs:16:31
|
16 | println!("rak: {}", stok::rak::jumlah());
| ^^^ ------ function `jumlah` is not publicly re-exported
| |
| private module
|
note: the module `rak` is defined here
--> uji/dua_privat.rs:2:5
|
2 | mod rak {
| ^^^^^^^
error[E0603]: function `batas_minimal` is private
--> uji/dua_privat.rs:17:41
|
17 | println!("batas: {}", stok::gudang::batas_minimal());
| ^^^^^^^^^^^^^ private function
|
note: the function `batas_minimal` is defined here
--> uji/dua_privat.rs:9:9
|
9 | fn batas_minimal() -> u32 {
| ^^^^^^^^^^^^^^^^^^^^^^^^^
error: aborting due to 2 previous errors
Kedua error memakai kode yang sama karena keduanya soal izin, bukan soal nama yang tidak ada. Pada kasus pertama, fungsi jumlah sudah pub, tetapi module rak tidak, sehingga jalur stok::rak tidak bisa dilewati dari luar. Kompilator menyebutnya "not publicly re-exported", istilah untuk item yang publik di dalam module privat.
Kasus kedua adalah kebalikannya: module gudang terbuka, sedangkan fungsi batas_minimal tetap privat. Perbaikannya menambahkan pub pada setiap segmen yang harus dilewati, yaitu pub mod rak dan pub fn batas_minimal. Aturan ini menjelaskan kenapa kode Rust sering menulis pub berkali-kali dalam 1 jalur.
Nama module hanya unik di dalam induknya
2 module di induk berbeda boleh memakai nama yang sama. gudang::rak dan toko::rak adalah 2 module berbeda karena induknya berbeda, dan keduanya bisa hidup dalam 1 crate.
mod gudang {
pub mod rak {
pub fn jumlah() -> u32 {
12
}
}
}
mod toko {
pub mod rak {
pub fn jumlah() -> u32 {
3
}
}
}
fn main() {
println!("rak gudang: {}", gudang::rak::jumlah());
println!("rak toko: {}", toko::rak::jumlah());
}
rak gudang: 12
rak toko: 3
Hasil itu menunjukkan hal yang sering terlewat: yang membuat 2 fungsi berbeda bukan namanya, melainkan path lengkapnya. Pemanggilan gudang::rak::jumlah() dan toko::rak::jumlah() menunjuk 2 fungsi yang tidak berhubungan walaupun nama akhirnya sama. Pola ini dipakai pustaka besar untuk memberi nama module sesuai konteks tanpa takut bentrok.
2 modul bernama sama di induk yang sama: E0428
Kesalahan ketiga muncul saat 2 module dengan nama sama ditulis pada tingkat yang sama. Program berikut mendeklarasikan mod stok 2 kali di crate root.
mod stok {
pub fn isi() -> u32 {
1
}
}
mod stok {
pub fn lain() -> u32 {
2
}
}
fn main() {
println!("{}", stok::isi());
}
error[E0428]: the name `stok` is defined multiple times
--> uji/dobel.rs:7:1
|
1 | mod stok {
| -------- previous definition of the module `stok` here
...
7 | mod stok {
| ^^^^^^^^ `stok` redefined here
|
= note: `stok` must be defined only once in the type namespace of this module
error: aborting due to 1 previous error
Pesan itu menyebut "type namespace" karena nama module menempati namespace tipe, tempat yang sama dengan nama struct dan enum. Kompilator tidak menggabungkan 2 blok mod stok, juga tidak memakai yang terakhir. Yang terjadi adalah penolakan, sehingga seluruh berkas gagal dibangun.
Kalau isi 2 module memang dibutuhkan, gabungkan keduanya menjadi 1 blok mod stok, atau pindahkan salah satunya ke module induk lain seperti pola gudang::rak dan toko::rak di bagian sebelumnya.
Module inline untuk menguji fungsi privat
Bentuk inline paling sering dipakai untuk tes. Module tests ditulis di berkas yang sama dengan kode yang diuji, diberi atribut #[cfg(test)], sehingga hanya ikut dikompilasi saat cargo test dijalankan.
fn total(harga: u32, jumlah: u32) -> u32 {
harga * jumlah
}
fn main() {
println!("total: {}", total(2500, 4));
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn total_4_barang() {
assert_eq!(total(2500, 4), 10000);
}
#[test]
fn total_barang_nol() {
assert_eq!(total(2500, 0), 0);
}
}
running 2 tests
test tests::total_4_barang ... ok
test tests::total_barang_nol ... ok
test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Nama tes di keluaran itu memuat tests::, yaitu nama module inline-nya, dan itu bukti bahwa module masuk pohon nama. Baris use super::*; membawa semua item dari module induk, sehingga total bisa dipanggil tanpa path. Tanpa baris itu, tes harus menulis crate::total(2500, 4).
Saat program dijalankan biasa, module tests tidak ikut dikompilasi dan program hanya mencetak total: 10000. Sifat ini yang membuat tes bisa menumpang di berkas yang sama tanpa menambah beban pada biner rilis.
Kapan memilih inline module
Inline module cocok untuk isi yang masih dekat dengan pemakainya: fungsi bantu kecil, tes, dan potongan kode yang hanya dipakai 1 berkas. Alasannya, seluruh isi tetap terbaca dalam 1 layar dan tidak ada berkas baru yang perlu dibuka saat menelusuri kesalahan.
Module yang tumbuh besar lebih baik dipindah ke berkas sendiri dengan mod nama; seperti pada bab sebelumnya. Batas praktisnya bukan jumlah baris, melainkan berapa sering module itu dipakai: kalau hanya dipakai 1 berkas, inline lebih ringkas, dan kalau dipakai beberapa berkas, berkas terpisah lebih mudah dicari lewat nama berkas.
Struktur folder tidak berubah karena inline module. Cargo tetap hanya melihat src/main.rs, dan mod di dalamnya tidak mencari berkas apa pun. Itu sebabnya kesalahan pada inline module selalu muncul sebagai error nama atau error izin, tidak pernah sebagai error berkas yang hilang.
Latihan
- Tulis
mod kasirberisipub fn total(harga: u32) -> u32yang memanggil fungsi privatpajak, lalu panggilkasir::total(10000)darimain. Hasil yang benar adalah11100untuk pajak 11 persen. - Tambahkan
mod kasirkedua di crate root, jalankanrustc, dan catat kode error yang muncul. Perbaiki dengan memindahkan module kedua ke dalam module induk lain. - Ubah setiap
pubpada contoh E0603 menjadipub(crate), lalu jelaskan mengapa error-nya hilang. - Tambahkan 1 tes di module
testsuntuktotal(2500, 1), jalankancargo test, dan pastikan keluaran menampilkan 3 nama tes.
Ringkasan
Inline module ditulis dengan mod lalu kurung kurawal, dan isinya hidup di berkas yang sama dengan pemakainya. Setiap tingkat module menambah 1 segmen path, dan setiap segmen yang dilewati dari luar harus dibuka dengan pub, sedangkan super dipakai untuk naik 1 tingkat. 3 error yang menandai kesalahan susunan itu adalah E0425 saat nama dipakai tanpa path, E0603 saat ada segmen yang masih privat, dan E0428 saat 2 module bernama sama muncul di induk yang sama.
Referensi
- The Rust Programming Language. Control Scope and Privacy with Modules.
- The Rust Reference. Modules.
- The Rust Programming Language. Paths for Referring to an Item in the Module Tree.
- The Rust Programming Language. Bringing Paths into Scope with the use Keyword.