BAB 18: Module System: Path & Item
Path di Rust tersusun dari segmen yang dipisah :: dan dimulai dari crate, self, atau super, sehingga nama sama di 2 modul tetap bisa dibedakan.
Nama cetak bisa berdiri di 3 modul berbeda dalam satu program, dan kompilator tidak pernah salah memilih selama setiap pemanggilan menyebut jalurnya. Rust menyebut jalur itu path, dan path adalah satu-satunya cara program menunjuk item yang tidak berada di modul yang sedang ditulis.
Bab ini membahas item, cara path disusun, dan 3 titik awal yang dipakai Rust untuk membacanya. Setelah bab ini selesai, kamu dapat menulis path absolut dengan crate::, menaiki modul induk dengan super::, dan membaca pesan E0425, E0433, serta E0603 sebagai kesalahan path, bukan kesalahan logika. Semua contoh dikompilasi dengan rustc 1.100.0 di folder /tmp/latihan-rust/bab18.
Item: satuan yang punya nama dan path
Item adalah bagian penyusun crate yang diberi nama, misalnya fungsi, struct, enum, konstanta, dan modul itu sendiri. Rust Reference memisahkan item menjadi beberapa jenis, antara lain modul, fungsi, struct, enum, trait, const, static, dan type alias. Setiap jenis item bisa dirujuk lewat nama, dan nama itu selalu bisa ditulis lengkap sebagai path.
Pembedaan ini penting karena path bekerja sama untuk semua jenis item. Path yang menunjuk fungsi dan path yang menunjuk struct ditulis dengan aturan yang sama, hanya bagian akhirnya yang berbeda.
mod geometri {
pub const SATUAN: &str = "cm";
pub struct Titik {
pub x: i32,
pub y: i32,
}
pub enum Bentuk {
Persegi(i32),
}
}
fn main() {
let t = crate::geometri::Titik { x: 3, y: 4 };
let b = geometri::Bentuk::Persegi(5);
println!("titik ({}, {}) dalam {}", t.x, t.y, geometri::SATUAN);
match b {
crate::geometri::Bentuk::Persegi(s) => println!("persegi sisi {} luas {}", s, s * s),
}
}
titik (3, 4) dalam cm
persegi sisi 5 luas 25
Baris crate::geometri::Titik { x: 3, y: 4 } memakai path untuk memanggil konstruktor struct, geometri::Bentuk::Persegi(5) memakai path untuk varian enum, dan geometri::SATUAN memakai path untuk konstanta. Ketiganya berakhir di item yang berbeda jenis, tetapi bentuk path-nya seragam: nama modul, pemisah ::, lalu nama item.
Contoh di atas memakai mod yang ditulis langsung di dalam berkas agar cukup 1 berkas. Cara memecah modul ke berkas sendiri dibahas di bab tentang module.
Path: segmen yang dipisah ::
Rust Reference mendefinisikan path sebagai urutan 1 segmen atau lebih yang dipisahkan token ::, dan path dipakai untuk merujuk item, nilai, tipe, makro, serta atribut. Karena itu path dipakai untuk lebih dari modul: tipe i32 yang ditulis di parameter fungsi juga sebuah path pendek dengan 1 segmen, dan println! adalah makro yang dirujuk lewat path 1 segmen.
Segmen pertama menentukan arti seluruh path. Rust mengenal 4 bentuk segmen pembuka: nama item biasa, crate, self, dan super. Kalau segmen pertama berupa nama biasa, Rust mencarinya mulai dari modul tempat kode itu ditulis. Kalau segmen pertama crate, pencarian dimulai dari akar crate.
mod laporan {
pub fn cetak() {
println!("laporan tercetak");
}
}
fn main() {
crate::laporan::cetak();
laporan::cetak();
}
laporan tercetak
laporan tercetak
Kedua pemanggilan menghasilkan baris yang sama karena keduanya menunjuk fungsi yang sama. crate::laporan::cetak() menempuh 3 segmen dari akar, sedangkan laporan::cetak() hanya 2 segmen karena main sendiri berada di akar crate, sehingga laporan bisa dicari langsung di situ.
Path absolut dimulai dari crate
Path yang dibuka dengan crate disebut absolut. Panjangnya tidak berubah walaupun dipindah ke modul sedalam apa pun, karena titik mulainya selalu akar crate. Sifat ini membuat path absolut aman dipakai di kode yang sering dipindah.
mod luar {
pub fn judul() -> &'static str {
"daftar nilai"
}
pub mod dalam {
pub fn tampil() {
println!("{}", super::judul());
println!("{}", crate::luar::judul());
}
}
}
fn main() {
luar::dalam::tampil();
self::luar::dalam::tampil();
}
daftar nilai
daftar nilai
daftar nilai
daftar nilai
Fungsi tampil berada 2 tingkat di bawah akar, dan tetap bisa memanggil judul lewat crate::luar::judul() tanpa menghitung naik berapa tingkat. Di main, self::luar::dalam::tampil() juga berhasil karena self di akar crate menunjuk akar crate itu sendiri, jadi hasilnya sama dengan crate::.
Ada 1 bentuk lain yang perlu dikenali walaupun jarang ditulis tangan, yaitu path yang dibuka dengan :: ganda. Rust Reference menyebut perbedaan edition di titik ini: pada edition 2015, path yang dibuka :: dibaca dari crate root, sedangkan sejak edition 2018 path tersebut dibaca dari crate yang terdaftar di extern prelude. Crate baru memakai edition 2021 atau 2024 secara bawaan, sehingga ::std::mem::swap menunjuk crate std, bukan modul std di dalam crate sendiri. Untuk kode harian, crate:: lebih jelas maksudnya dan tidak berubah arti antar edition.
super dan self menunjuk modul lain
super menaiki 1 tingkat ke modul induk. Rust Reference menyatakan super dalam path menunjuk modul induk, dan hanya boleh dipakai pada segmen pembuka, mungkin setelah self di depan. Pengulangan super::super:: juga diizinkan untuk mencapai kakek dari modul sekarang. self bergerak ke arah sebaliknya: ia menunjuk modul tempat kode ditulis, sehingga self:: memaksa pencarian hanya di modul sendiri. Berkas p6_super_self.rs memakai keduanya dalam 1 program.
mod hitung {
pub fn dua_kali(n: i32) -> i32 {
n * 2
}
pub fn empat_kali(n: i32) -> i32 {
self::dua_kali(self::dua_kali(n))
}
}
mod atas {
pub fn nama() -> &'static str {
"modul atas"
}
pub mod tengah {
pub mod dalam {
pub fn panggil() {
println!("dari {}", super::super::nama());
}
}
}
}
fn main() {
println!("{}", hitung::empat_kali(5));
crate::atas::tengah::dalam::panggil();
}
20
dari modul atas
Dari dalam, super menunjuk tengah dan super::super menunjuk atas, sehingga nama bisa dipanggil. Kalau super dihilangkan, kompilator mencari nama di modul dalam saja dan tidak menemukannya, seperti ditunjukkan pada bagian kesalahan pertama di bawah.
empat_kali(5) memanggil dua_kali 2 kali bertingkat, sehingga 5 menjadi 10 lalu 20. Penulisan self::dua_kali membuat maksud kode eksplisit: yang dipanggil adalah fungsi di modul hitung, bukan fungsi bernama sama di tempat lain. super dan self hanya mengubah titik mula pencarian, sedangkan segmen sesudahnya tetap dibaca dari kiri ke kanan.
Pohon module dan arah path
Modul membentuk pohon, dan setiap path adalah rute dari 1 titik di pohon itu menuju titik lain. Diagram berikut menunjukkan pohon module dari contoh super di atas, dengan path yang makin panjang 1 segmen pada tiap tingkat.
Membaca diagram itu cukup dengan 1 aturan: setiap panah turun menambah 1 segmen pada path, sehingga path terpanjang dimiliki item terdalam. Path yang ditulis dari akar selalu turun, karena itu tidak perlu menghitung berapa tingkat yang sudah dilewati.
Kesalahan 1: memanggil nama tanpa path
Kesalahan yang paling sering muncul saat mulai memakai modul adalah memanggil nama item seolah item itu berada di modul yang sama. Berkas e1_tanpa_path.rs memanggil cetak() dari main padahal cetak berada di dalam mod laporan.
mod laporan {
pub fn cetak() {
println!("laporan tercetak");
}
}
fn main() {
cetak();
}
error[E0425]: cannot find function `cetak` in this scope
--> e1_tanpa_path.rs:8:5
|
8 | cetak();
| ^^^^^ not found in this scope
|
help: consider importing this function
|
1 + use laporan::cetak;
|
error: aborting due to 1 previous error
For more information about this error, try `rustc --explain E0425`.
Kode E0425 berarti nama itu tidak ada di scope yang sedang dibaca, dan penyebabnya di sini adalah modul laporan tidak dibuka. Perbaikannya bisa dengan menulis path lengkap laporan::cetak() atau dengan mendatangkan nama itu ke scope lewat use, yang dibahas di bab tersendiri. Perhatikan bahwa pesan error menunjuk baris 8 kolom 5, yaitu tepat di huruf pertama nama fungsi.
Kesalahan 2: segmen path yang tidak ada
Kesalahan kedua muncul saat 1 segmen path salah tulis. Berkas e2_salah_nama.rs memakai crate::lapor::cetak() sementara modulnya bernama laporan.
mod laporan {
pub fn cetak() {
println!("laporan tercetak");
}
}
fn main() {
crate::lapor::cetak();
}
error[E0433]: cannot find module or crate `lapor` in the crate root
--> e2_salah_nama.rs:8:12
|
8 | crate::lapor::cetak();
| ^^^^^ use of unresolved module or unlinked crate `lapor`
|
help: you might be missing a crate named `lapor`, add it to your project and import it in your code
|
1 + extern crate lapor;
|
error: aborting due to 1 previous error
For more information about this error, try `rustc --explain E0433`.
Halaman resmi E0433 menjelaskan kode ini sebagai pemakaian crate, modul, atau tipe yang tidak dideklarasikan, dan menyarankan memeriksa ejaan sebelum menambah dependensi. Saran extern crate pada keluaran di atas menyesatkan untuk kasus ini: yang salah bukan crate yang hilang, melainkan 1 huruf pada nama modul. Perbaikan yang benar adalah mengembalikan lapor menjadi laporan.
Kesalahan 3: item ada tetapi tertutup
Kesalahan ketiga terlihat seperti path yang salah padahal path-nya benar. Berkas e3_bukan_pub.rs memanggil crate::laporan::cetak() pada fungsi yang ditulis tanpa pub.
mod laporan {
fn cetak() {
println!("laporan tercetak");
}
}
fn main() {
crate::laporan::cetak();
}
error[E0603]: function `cetak` is private
--> e3_bukan_pub.rs:8:21
|
8 | crate::laporan::cetak();
| ^^^^^ private function
|
note: the function `cetak` is defined here
--> e3_bukan_pub.rs:2:5
|
2 | fn cetak() {
| ^^^^^^^^^^
error: aborting due to 1 previous error
For more information about this error, try `rustc --explain E0603`.
E0603 membedakan 2 hal yang mudah dicampur: nama item ditemukan, tetapi aksesnya ditolak. Item di dalam modul bersifat privat secara bawaan, sehingga pub dibutuhkan agar bisa dipanggil dari luar. Pada ketiga contoh benar sebelumnya, pub selalu ada di depan fn, dan itulah yang membuat path-nya bisa ditembus. Aturan pub, pub(crate), dan pub(super) dibahas di bab tentang visibility.
Latihan
- Buat modul
nilaiberisi fungsirata_rata(a: f64, b: f64) -> f64, lalu panggil dengan path absolut darimain. - Tambahkan modul
dalamdi dalamnilai, panggilrata_ratadari situ memakaisuper::. - Tulis path yang salah dengan sengaja, catat kode error yang muncul, lalu perbaiki.
- Pindahkan
mainke dalam modul lain, lalu tentukan path mana yang harus diubah dan mana yang tidak.
Ringkasan
Item adalah bagian crate yang diberi nama, dan path adalah rute menuju item itu berupa segmen yang dipisah ::. Path absolut dibuka dengan crate sehingga tetap sah dari kedalaman mana pun, sedangkan super menaiki modul induk dan boleh diulang, serta self menunjuk modul tempat kode ditulis. 3 kode error menandai 3 kegagalan path yang berbeda: E0425 saat nama tidak ada di scope, E0433 saat 1 segmen tidak ditemukan, dan E0603 saat item ditemukan tetapi tidak boleh diakses.
Referensi
- The Rust Reference. Paths.
- The Rust Programming Language. Paths for Referring to an Item in the Module Tree.
- The Rust Reference. Items.
- rustc. Error code E0433.