Module System

BAB 29: Module System: Use, Import, Re-export

Use membuat nama lokal untuk jalur panjang, as mengganti nama import, dan pub use mengekspor ulang item agar jalurnya pendek bagi pemakai modul.

Setelah modul dan visibilitas diatur, jalur seperti crate::geometri::titik::asal() muncul berkali-kali di 1 berkas. Reference Rust menyebut deklarasi use sebagai cara membuat "one or more local name bindings synonymous with some other path", dan kalimat itu menjelaskan batas kemampuannya: use hanya menambah nama lokal, tidak memindahkan item dan tidak mengubah visibilitas apa pun.

Pemisahan itu penting karena 2 masalah sering tertukar. Jalur yang panjang adalah masalah penulisan, dan use menyelesaikannya. Item yang tidak terlihat adalah masalah visibilitas, dan use tidak bisa menembusnya. Buku resmi Rust menegaskan hal yang sama dengan kalimat "Paths brought into scope with use also check privacy, like any other paths."

Setelah bab ini selesai, kamu dapat memendekkan jalur dengan use, memecah modul ke berkas terpisah, memakai as untuk mengganti nama import, membaca E0432 dan E0252 sebagai 2 kesalahan import yang paling sering muncul, serta membuat re-export dengan pub use supaya pemakai modul tidak perlu menulis jalur dalam. Semua contoh dijalankan dengan rustc 1.100.0 pada folder /tmp/latihan-rust/bab29.

use memendekkan jalur

Contoh pertama memakai use untuk mengambil 2 nama dari modul yang sama, yaitu fungsi asal dan struct Titik.

RSRUST
mod geometri {
    pub mod titik {
        pub struct Titik {
            pub x: i32,
            pub y: i32,
        }

        pub fn asal() -> Titik {
            Titik { x: 0, y: 0 }
        }
    }
}

use geometri::titik::{asal, Titik};

fn main() {
    let t: Titik = asal();
    println!("{} {}", t.x, t.y);
}
CodeTEXT
0 0

Baris use geometri::titik::{asal, Titik}; mengambil 2 nama sekaligus dengan kurung kurawal. Setelah baris itu, Titik dan asal bisa ditulis tanpa awalan, sama seperti item yang dideklarasikan langsung di crate root. Tanpa use, kedua baris di main harus ditulis let t: geometri::titik::Titik = geometri::titik::asal();.

Kurung kurawal itu bukan hiasan. Menulis 2 baris use terpisah untuk modul yang sama juga sah, tetapi bentuk gabungan membuat asal kedua nama terlihat dalam 1 baris. Untuk modul yang menyumbang banyak nama, bentuk gabungan lebih mudah diperiksa saat membaca ulang.

Modul di berkas terpisah

Modul yang tumbuh besar biasanya dipindah ke berkas sendiri. Deklarasi mod matematika; dengan titik koma, tanpa kurung kurawal, memberi tahu kompilator bahwa isi modul ada di berkas lain.

RSRUST
mod matematika;

use matematika::luas;

fn main() {
    println!("{}", luas(3, 4));
}

Berkas matematika.rs di folder yang sama berisi isi modulnya.

RSRUST
pub fn luas(panjang: i32, lebar: i32) -> i32 {
    panjang * lebar
}
CodeTEXT
12

Kedua berkas dikompilasi dengan 1 perintah, yaitu rustc main.rs, dan kompilator mencari matematika.rs di folder yang sama dengan main.rs. Fungsi luas ditandai pub karena dipanggil dari crate root, sedangkan mod matematika; sendiri tidak perlu pub selama hanya dipakai di dalam crate itu.

Perhatikan bahwa main.rs tidak menuliskan isi modul, hanya deklarasinya. Pola ini yang dipakai proyek dengan banyak berkas: 1 berkas induk memuat daftar mod, dan setiap modul menempati berkasnya sendiri.

Jalur crate, self, dan super

Di dalam modul bersarang, 3 awalan jalur dipakai untuk menunjuk tempat yang berbeda. crate:: menunjuk akar crate, self:: menunjuk modul saat ini, dan super:: menunjuk modul induk.

RSRUST
mod luar {
    pub fn nama() -> &'static str {
        "luar"
    }

    pub mod dalam {
        pub fn nama_dalam() -> &'static str {
            "dalam"
        }

        pub fn jalur() -> String {
            format!("{} > {}", super::nama(), self::nama_dalam())
        }
    }
}

fn main() {
    println!("{}", crate::luar::dalam::jalur());
}
CodeTEXT
luar > dalam

Fungsi jalur berada di mod dalam, sehingga super::nama() naik 1 tingkat ke mod luar dan self::nama_dalam() menunjuk fungsi di modulnya sendiri. Sementara itu main memakai crate:: untuk memulai dari akar crate. Tanpa crate::, jalur luar::dalam::jalur() juga sah dari crate root, karena nama luar berada di scope yang sama dengan main.

as mengganti nama import

Nama yang diimpor bisa diganti dengan as. Ini berguna saat 2 modul menyumbang nama yang sama, atau saat nama aslinya terlalu umum untuk dibaca tanpa konteks.

RSRUST
use std::collections::HashMap as Peta;
use std::fmt::Result as FmtResult;

fn tulis() -> FmtResult {
    Ok(())
}

fn main() {
    println!("{:?}", tulis());

    let mut p: Peta<&str, i32> = Peta::new();
    p.insert("a", 1);
    println!("{}", p.len());
}
CodeTEXT
Ok(())
1

Peta adalah nama lokal untuk HashMap, dan FmtResult adalah nama lokal untuk std::fmt::Result. Kedua tipe aslinya tidak berubah: nilai yang dikembalikan tulis tetap std::fmt::Result, dan Peta tetap HashMap dengan hasher bawaannya. Penggantian nama hanya berlaku di berkas yang memuat baris use itu.

Rust by Example mencatat fungsi as ini dengan kalimat "You can use the as keyword to bind imports to a different name". Karena nama lokal dan nama asli hidup di namespace yang sama, mengganti nama juga menjadi jalan keluar saat 2 import bertabrakan, dan itu dibahas lagi di bagian tentang E0252.

Glob dengan tanda bintang

Tanda bintang mengimpor semua item publik dari sebuah modul. Bentuk ini sering dipakai untuk prelude, yaitu kumpulan trait yang hampir selalu dibutuhkan.

RSRUST
mod alat {
    pub fn satu() -> i32 {
        1
    }

    pub fn dua() -> i32 {
        2
    }

    pub const TIGA: i32 = 3;
}

use alat::*;

fn main() {
    println!("{}", satu() + dua() + TIGA);
}
CodeTEXT
6

Fungsi satu, fungsi dua, dan konstanta TIGA bisa dipanggil tanpa awalan setelah use alat::*;. Yang ikut hanya item publik, sehingga fungsi privat di mod alat tetap tidak bisa dipakai.

Glob menghemat penulisan, tetapi menyembunyikan asal nama: pembaca tidak tahu TIGA berasal dari modul mana tanpa membuka baris import. Untuk modul kecil dengan 3 item, daftar nama eksplisit lebih jelas. Glob lebih masuk akal untuk prelude yang isinya puluhan trait dan memang dipakai bersamaan.

use hanya berlaku di scope-nya

use menambah nama pada scope tempat deklarasi itu ditulis, bukan pada seluruh berkas. Contoh berikut menaruh use di dalam blok, lalu memakai jalur penuh setelah blok selesai.

RSRUST
fn main() {
    {
        use std::collections::BTreeSet;

        let s: BTreeSet<i32> = BTreeSet::from([3, 1, 2]);
        println!("{:?}", s);
    }

    let s: std::collections::BTreeSet<i32> = std::collections::BTreeSet::from([9]);
    println!("{:?}", s);
}
CodeTEXT
{1, 2, 3}
{9}

Di dalam blok, BTreeSet bisa ditulis pendek. Setelah blok berakhir, nama itu tidak ada lagi, sehingga baris berikutnya harus memakai jalur penuh. Buku resmi Rust menyebutnya sebagai batas yang disengaja: "use only creates the shortcut for the particular scope in which the use occurs".

BTreeSet juga mengurutkan isinya sendiri, dan hasil {1, 2, 3} pada baris pertama menunjukkan hal itu walaupun nilai dimasukkan dalam urutan 3, 1, 2. Perilaku itu berasal dari struktur datanya, bukan dari use.

Import yang tidak ditemukan

Kesalahan pertama muncul saat jalur di baris use menunjuk modul yang tidak ada.

RSRUST
mod geometri {
    pub mod titik {
        pub fn asal() -> i32 {
            0
        }
    }
}

use geometri::lingkaran::asal;

fn main() {
    println!("{}", asal());
}
CodeTEXT
error[E0432]: unresolved import `geometri::lingkaran`
 --> salah_path.rs:9:15
  |
9 | use geometri::lingkaran::asal;
  |               ^^^^^^^^^ could not find `lingkaran` in `geometri`

error: aborting due to 1 previous error

Kompilator menandai bagian yang gagal, yaitu lingkaran, bukan seluruh baris. Modul geometri memang ada, dan asal memang ada di geometri::titik, tetapi lingkaran tidak pernah dideklarasikan. Perbaikannya adalah membetulkan nama modulnya, bukan menambah pub di mana pun.

Kesalahan ini juga muncul kalau modulnya ada tetapi tidak terlihat. Dalam keadaan itu, pesannya berganti menjadi E0603 seperti pada bab sebelumnya, karena masalahnya visibilitas dan bukan nama yang salah.

Nama ganda dan import tak terpakai

Kesalahan kedua muncul saat 2 import menghasilkan nama lokal yang sama.

RSRUST
mod a {
    pub fn proses() -> i32 {
        1
    }
}

mod b {
    pub fn proses() -> i32 {
        2
    }
}

use a::proses;
use b::proses;

fn main() {
    println!("{}", proses());
}
CodeTEXT
error[E0252]: the name `proses` is defined multiple times
  --> salah_ganda.rs:14:5
   |
13 | use a::proses;
   |     --------- previous import of the value `proses` here
14 | use b::proses;
   |     ^^^^^^^^^ `proses` reimported here
   |
   = note: `proses` must be defined only once in the value namespace of this module
help: you can use `as` to change the binding name of the import
   |
14 | use b::proses as other_proses;
   |               +++++++++++++++

warning: unused import: `b::proses`
  --> salah_ganda.rs:14:5
   |
14 | use b::proses;
   |     ^^^^^^^^^
   |
   = note: `#[warn(unused_imports)]` (part of `#[warn(unused)]`) on by default

error: aborting due to 1 previous error; 1 warning emitted

Kompilator menunjukkan baris import pertama sebagai pemilik nama, lalu menolak yang kedua. Solusi yang disarankan ada di blok help, yaitu use b::proses as other_proses;. Alternatif lain adalah memakai jalur penuh untuk salah satu fungsi, misalnya b::proses(), dan hanya mengimpor 1 nama.

Perhatikan bahwa program yang sama juga menghasilkan peringatan unused_imports untuk baris yang ditolak. Peringatan itu bukan penyebab kegagalan, tetapi menandakan hal yang berguna: import yang tidak pernah dipakai memang layak dihapus.

Peringatan yang sama muncul pada import yang sah tetapi tidak dipakai di mana pun.

RSRUST
use std::collections::HashMap;

fn main() {
    println!("{}", 1);
}
CodeTEXT
warning: unused import: `std::collections::HashMap`
 --> salah_tidak_dipakai.rs:1:5
  |
1 | use std::collections::HashMap;
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = note: `#[warn(unused_imports)]` (part of `#[warn(unused)]`) on by default

warning: 1 warning emitted


1

Program tetap berjalan dan mencetak 1. Peringatan ini berguna saat merapikan kode, karena import yang tertinggal setelah refactor akan langsung terlihat.

pub use untuk re-export

use biasa membuat nama lokal yang privat. Dengan menambahkan pub, nama itu ikut diekspor ulang, sehingga pemakai modul bisa memakai jalur pendek yang sama.

RSRUST
mod dalam {
    pub mod inti {
        pub fn hitung() -> i32 {
            7
        }
    }
}

pub use dalam::inti::hitung;

fn main() {
    println!("{}", hitung());
}
CodeTEXT
7

Tanpa pub use, pemanggil harus menulis dalam::inti::hitung(). Dengan 1 baris re-export, jalur yang terlihat dari luar menjadi hitung() di crate root. Rust By Example menjelaskan gunanya dengan kalimat "You can also use pub use to re-export an item from a module, so it can be accessed through the module's public interface".

Buku resmi Rust menyebut teknik ini sebagai re-exporting, dan tujuannya adalah penyusunan tampilan modul, dengan jalur pendek sebagai efek sampingnya. Modul bisa disusun dalam beberapa lapisan di dalam, lalu lapisan luar mengekspor ulang nama yang memang ingin dipakai orang lain. Isi dalam tetap bebas berubah selama nama yang diekspor ulang tidak berubah.

Pada crate biner, pub use tetap sah tetapi pemakainya hanya kode di dalam crate itu sendiri. Manfaat sebenarnya terasa pada crate library, karena crate lain hanya melihat nama yang diekspor ulang itu.

Latihan

  1. Pindahkan mod geometri pada contoh pertama ke berkas geometri.rs, lalu ubah main.rs menjadi mod geometri; dan pastikan keluarannya tetap 0 0.
  2. Tambahkan use geometri::titik::Titik as T; pada berkas itu dan ganti anotasi tipe Titik menjadi T.
  3. Ubah salah_ganda.rs memakai saran kompilator, lalu panggil kedua fungsi dan cetak hasilnya.
  4. Buat pub use yang mengekspor ulang 2 fungsi sekaligus dengan bentuk pub use dalam::inti::{hitung, kurangi};, dan tulis fungsi kurangi sendiri.

Ringkasan

use membuat nama lokal untuk jalur yang sudah ada, dan nama itu hanya berlaku di scope tempat deklarasi ditulis. Bentuk kurung kurawal mengimpor beberapa nama sekaligus, as mengganti nama lokal, dan tanda bintang mengimpor semua item publik dengan konsekuensi asal nama menjadi kabur. Untuk modul di berkas terpisah, mod nama; dengan titik koma menghubungkan berkas induk dengan berkas modul. Import yang salah nama ditolak sebagai E0432, 2 import dengan nama yang sama ditolak sebagai E0252 beserta saran as, dan import yang tidak dipakai hanya menghasilkan peringatan. pub use mengekspor ulang nama sehingga pemakai modul mendapat jalur pendek tanpa membuka susunan modul di dalamnya.

Referensi

  1. The Rust Reference. Use declarations.
  2. The Rust Programming Language. Bringing Paths Into Scope with the use Keyword.
  3. Rust By Example. The use declaration.