Module System

BAB 28: Module System: Visibility & Privacy

Visibilitas item di Rust baku privat per modul, dan bab ini mengukur pub, pub(crate), pub(super), field privat, serta error E0603 dan E0616.

Fungsi rahasia di dalam sebuah modul bisa dipanggil oleh fungsi lain di modul yang sama, tetapi tidak oleh kode di luar modul itu, walaupun semuanya ditulis dalam 1 berkas. Rust memeriksa batas modul, bukan batas berkas, sehingga mod tidak berhenti sebagai alat pengelompokan: deklarasi itu menetapkan siapa yang boleh memanggil apa.

Buku resmi Rust menyebut alasan di balik aturan ini dengan kalimat "code within a module is private by default. Private items are internal implementation details not available for outside use". Artinya setiap fungsi, struct, dan field baru tertutup sampai pemilik kode membukanya sendiri. Kode yang tidak membuka apa pun tetap bisa berjalan, dan justru itu keadaan yang paling aman untuk memulai.

Setelah bab ini selesai, kamu dapat menentukan item mana yang boleh dipakai modul lain, memilih antara pub, pub(crate), dan pub(super) sesuai jangkauan yang dibutuhkan, menjelaskan kenapa field struct bisa tetap privat walaupun structnya pub, serta membaca E0603, E0616, E0451, dan E0449 sebagai 4 kesalahan seputar visibilitas. Semua contoh dijalankan dengan rustc 1.100.0 pada folder /tmp/latihan-rust/bab28.

Privasi baku: 1 berkas, 2 tingkat akses

Contoh pertama menunjukkan keadaan bawaan Rust tanpa 1 pun kata pub yang berlebihan.

RSRUST
mod dalam {
    fn rahasia() -> i32 {
        42
    }

    pub fn umum() -> i32 {
        rahasia() + 1
    }
}

fn main() {
    println!("{}", dalam::umum());
}
CodeTEXT
43

rahasia dan umum berada di modul yang sama, sehingga umum boleh memanggil rahasia tanpa syarat tambahan. Yang membedakan keduanya adalah siapa di luar modul yang boleh ikut memanggil. umum ditandai pub, jadi kode di crate root boleh memanggilnya. rahasia tanpa penanda apa pun hanya terlihat di dalam mod dalam beserta modul turunannya.

Perhatikan bahwa mod dalam sendiri tidak ditandai pub, tetapi main tetap bisa memanggil dalam::umum(). Penyebabnya, main berada di crate root, dan crate root adalah modul tempat dalam dideklarasikan. Privasi berarti "terlihat dari modul ini dan turunannya", dan modul induk selalu memenuhi syarat untuk item yang dideklarasikan langsung di dalamnya.

pub pada fungsi tidak membuka modulnya

Kesalahan pertama muncul ketika pub dipasang pada fungsi, tetapi modul yang membungkusnya tetap tertutup.

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

fn main() {
    println!("{}", luar::dalam::halo());
}
CodeTEXT
error[E0603]: module `dalam` is private
  --> pub_saja_tidak_cukup.rs:10:26
   |
10 |     println!("{}", luar::dalam::halo());
   |                          ^^^^^  ---- function `halo` is not publicly re-exported
   |                          |
   |                          private module
   |
note: the module `dalam` is defined here
  --> pub_saja_tidak_cukup.rs:2:5
   |
 2 |     mod dalam {
   |     ^^^^^^^^^

error: aborting due to 1 previous error

Pesan itu memisahkan 2 hal yang sering dianggap 1: fungsinya sudah pub, tetapi modulnya masih privat. Untuk mencapai halo, pemanggil harus melewati 2 pintu, yaitu luar::dalam dan halo itu sendiri. Selama salah satu pintu tertutup, jalurnya tetap ditolak. Perbaikannya adalah menulis pub mod dalam, dan bukan menghapus pub pada fungsinya.

Catatan kompilator "function halo is not publicly re-exported" menunjuk jalan keluar yang lain, yaitu pub use di modul luar. Bentuk itu dibahas pada bab berikutnya, karena pub use memang dibuat untuk memendekkan jalur yang panjang sekaligus membukanya.

Tingkat visibilitas selain pub

Rust mengenal 4 tingkat visibilitas, dan Reference Rust menuliskannya cukup rinci. pub(in path) membuat item terlihat di dalam path yang diberikan, dengan syarat path itu menunjuk ke modul leluhur. pub(crate) membuat item terlihat di dalam crate saat ini. pub(super) membuat item terlihat oleh modul induk, dan setara dengan pub(in super). pub(self) membuat item terlihat oleh modul saat ini, setara dengan pub(in self) atau tanpa pub sama sekali.

Tingkat pub(crate) berguna untuk kode yang dipakai bersama antar modul di dalam 1 crate, tetapi tidak boleh dipakai crate lain.

RSRUST
mod pembantu {
    pub(crate) fn hitung(a: i32) -> i32 {
        a * 2
    }
}

mod layanan {
    pub fn jalankan(a: i32) -> i32 {
        crate::pembantu::hitung(a) + 1
    }
}

fn main() {
    println!("layanan: {}", layanan::jalankan(10));
    println!("pembantu: {}", pembantu::hitung(5));
}
CodeTEXT
layanan: 21
pembantu: 10

pembantu::hitung dipanggil dari 2 tempat berbeda, yaitu mod layanan dan main di crate root. Keduanya masih di dalam 1 crate, sehingga pub(crate) cukup. Kalau crate ini nanti dipecah menjadi library dan binary, fungsi itu tetap tidak terlihat oleh crate lain, dan itu memang batas yang diinginkan untuk fungsi bantu internal.

pub(super) membatasi ke modul induk

pub(super) lebih sempit daripada pub(crate). Item hanya terbuka 1 tingkat ke atas, yaitu ke modul induk tempat item itu ditulis.

RSRUST
mod induk {
    pub mod anak {
        pub(super) fn hanya_induk() -> &'static str {
            "dipanggil dari induk"
        }

        pub fn terbuka() -> &'static str {
            hanya_induk()
        }
    }

    pub fn panggil() -> &'static str {
        anak::hanya_induk()
    }
}

fn main() {
    println!("{}", induk::panggil());
    println!("{}", induk::anak::terbuka());
}
CodeTEXT
dipanggil dari induk
dipanggil dari induk

Kedua baris keluar dengan teks yang sama, tetapi jalurnya berbeda. Baris pertama memanggil hanya_induk langsung dari mod induk, dan itu diizinkan karena pub(super) membuka 1 tingkat ke atas. Baris kedua memanggil terbuka yang publik, lalu terbuka memanggil hanya_induk dari dalam modulnya sendiri.

1 fungsi pub(super) di dalam mod anak bisa dipanggil dari mod anak dan mod induk, sedangkan crate root menerima error E0603

Jangkauan 1 fungsi pub(super) pada 3 modul pemanggil.

Gambar di atas menegaskan batas yang tidak terlihat dari kode: crate root berada di luar jangkauan. Kalau main mencoba memanggil fungsi itu langsung, kompilator menolaknya.

RSRUST
mod induk {
    pub mod anak {
        pub(super) fn hanya_induk() {}
    }
}

fn main() {
    induk::anak::hanya_induk();
}
CodeTEXT
error[E0603]: function `hanya_induk` is private
 --> salah_pub_super.rs:8:18
  |
8 |     induk::anak::hanya_induk();
  |                  ^^^^^^^^^^^ private function
  |
note: the function `hanya_induk` is defined here
 --> salah_pub_super.rs:3:9
  |
3 |         pub(super) fn hanya_induk() {}
  |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^

error: aborting due to 1 previous error

Perhatikan bahwa seluruh jalur induk::anak::hanya_induk bisa ditulis, karena induk dan anak sama-sama publik. Yang ditolak hanya langkah terakhir, sebab hanya_induk tidak terlihat dari crate root. Kesalahan visibilitas selalu menunjuk ke 1 mata rantai yang tertutup, bukan ke seluruh jalur.

Field struct punya visibilitas sendiri

Struct publik tidak otomatis membuka field-nya. Setiap field punya penanda sendiri, dan itulah yang membuat struct bisa menyimpan data internal tanpa dibaca pemanggil.

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

    impl Titik {
        pub fn baru(x: i32, y: i32) -> Titik {
            Titik { x, y }
        }

        pub fn x(&self) -> i32 {
            self.x
        }
    }
}

fn main() {
    let t = geometri::Titik::baru(3, 4);
    println!("x lewat method: {}", t.x());
    println!("x lewat field: {}", t.x);
}
CodeTEXT
error[E0616]: field `x` of struct `Titik` is private
  --> salah_field.rs:21:37
   |
21 |     println!("x lewat field: {}", t.x);
   |                                     ^ private field
   |
help: a method `x` also exists, call it with parentheses
   |
21 |     println!("x lewat field: {}", t.x());
   |                                      ++

error: aborting due to 1 previous error

Kompilator tidak hanya menolak, tetapi menunjukkan perbaikan yang tersedia. Method x() mengembalikan nilai field yang sama, dan method itu publik. Pola ini lazim dipakai untuk menjaga field tetap privat sambil menyediakan akses baca terkontrol.

Kalau field memang boleh ditulis pemanggil, penandanya ditambahkan pada field, bukan pada struct.

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

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

Membuka field juga membuka pembuatan nilai lewat literal Titik { x: 1, y: 2 }. Konsekuensinya, validasi yang biasanya dilakukan konstruktor bisa dilewati sepenuhnya.

Kalau hanya sebagian field yang dibuka, literal dari luar modul ditolak.

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

    impl Titik {
        pub fn baru(x: i32, y: i32) -> Titik {
            Titik { x, y }
        }

        pub fn y(&self) -> i32 {
            self.y
        }
    }
}

fn main() {
    let t = geometri::Titik::baru(1, 2);
    println!("{} {}", t.x, t.y());

    let u = geometri::Titik { x: 5, y: 6 };
    println!("{}", u.x);
}
CodeTEXT
error[E0451]: field `y` of struct `Titik` is private
  --> salah_literal.rs:22:37
   |
22 |     let u = geometri::Titik { x: 5, y: 6 };
   |                                     ^ private field

error: aborting due to 1 previous error

Kombinasi pub pada struct, pub pada sebagian field, dan field privat yang diisi konstruktor adalah cara paling ringkas untuk menyimpan nilai yang harus selalu valid. Pemanggil membaca x kapan saja, tetapi tidak bisa membuat Titik dengan y sembarangan.

Varian enum tidak punya penanda sendiri

Enum berbeda dari struct di titik ini. Reference Rust menyebut varian enum pada pub enum juga publik secara bawaan, sehingga penanda pub di depan varian justru ditolak.

RSRUST
mod status {
    pub enum Status {
        Menunggu,
        Selesai,
    }
}

fn main() {
    let s = status::Status::Menunggu;

    match s {
        status::Status::Menunggu => println!("menunggu"),
        status::Status::Selesai => println!("selesai"),
    }
}
CodeTEXT
warning: variant `Selesai` is never constructed
 --> enum_varian.rs:4:9
  |
2 |     pub enum Status {
  |              ------ variant in this enum
3 |         Menunggu,
4 |         Selesai,
  |         ^^^^^^^
  |
  = note: `#[warn(dead_code)]` (part of `#[warn(unused)]`) on by default

warning: 1 warning emitted


menunggu

Peringatan di atas bukan kesalahan visibilitas, tetapi tetap berguna: varian Selesai tidak pernah dibuat, sehingga match di program itu hanya menjalankan 1 cabang. Kalau variannya ditandai pub satu per satu, kompilasi berhenti lebih awal.

RSRUST
mod status {
    pub enum Status {
        Menunggu,
        pub Selesai,
    }
}

fn main() {
    let _ = status::Status::Selesai;
}
CodeTEXT
error[E0449]: visibility qualifiers are not permitted here
 --> salah_varian_pub.rs:4:9
  |
4 |         pub Selesai,
  |         ^^^ help: remove the qualifier
  |
  = note: enum variants and their fields always share the visibility of the enum they are in

error: aborting due to 1 previous error

Catatan kompilator menyatakan aturannya dengan tegas: varian dan field-nya selalu ikut visibilitas enum. Untuk menyembunyikan sebagian varian, satu-satunya jalan adalah menurunkan visibilitas enum itu sendiri atau memindahkan varian tersebut ke enum lain di modul yang lebih sempit.

Fungsi privat antar modul bersaudara

Modul yang bersaudara tidak saling membuka. Contoh berikut memakai 2 modul sejajar, dan fungsi privat di modul pertama tidak bisa dipanggil dari modul kedua.

RSRUST
mod a {
    fn rahasia() -> i32 {
        9
    }

    pub fn bungkus() -> i32 {
        rahasia()
    }
}

mod b {
    pub fn coba() -> i32 {
        crate::a::rahasia()
    }
}

fn main() {
    println!("{} {}", a::bungkus(), b::coba());
}
CodeTEXT
error[E0603]: function `rahasia` is private
  --> salah_saudara.rs:13:19
   |
13 |         crate::a::rahasia()
   |                   ^^^^^^^ private function
   |
note: the function `rahasia` is defined here
  --> salah_saudara.rs:2:5
   |
 2 |     fn rahasia() -> i32 {
   |     ^^^^^^^^^^^^^^^^^^^

error: aborting due to 1 previous error

Jalur crate::a::rahasia memang mengarah ke fungsi yang benar, dan mod a sendiri terlihat dari crate root. Yang tidak terpenuhi adalah syarat kedua: rahasia tidak pub, jadi tidak ada modul lain yang boleh memanggilnya. a::bungkus tetap bekerja karena berada di modul yang sama dengan rahasia.

Latihan

  1. Buka salah_saudara.rs dengan pub(crate) fn rahasia, lalu catat apa yang berubah pada keluaran program.
  2. Buat mod akun berisi pub struct Akun dengan field email publik dan sandi_hash privat, serta method verifikasi(&self, sandi: &str) -> bool yang selalu mengembalikan false sebagai kerangka.
  3. Tambahkan pub mod pada pub_saja_tidak_cukup.rs lalu jalankan, dan tulis keluaran barunya.
  4. Ubah pub(super) pada contoh induk::anak menjadi pub(crate), lalu panggil dari main. Jelaskan kenapa sekarang berhasil.

Ringkasan

Setiap item di Rust privat secara bawaan, dan 1 item hanya bisa dipanggil kalau item itu sendiri terbuka serta seluruh modul pada jalurnya juga terbuka. pub membuka ke seluruh crate dan luar crate, pub(crate) membatasi ke crate saat ini, pub(super) membatasi ke modul induk, dan tanpa penanda berarti hanya modul itu beserta turunannya. Field struct punya penanda sendiri, sehingga struct publik bisa menyimpan data privat, dan pembuatan lewat literal dari luar modul ditolak sebagai E0451 sementara pembacaan field privat ditolak sebagai E0616. Varian enum tidak bisa ditandai 1 per 1, karena visibilitasnya selalu mengikuti enum, dan penulisan pub di depan varian ditolak sebagai E0449.

Referensi

  1. The Rust Reference. Visibility and privacy.
  2. The Rust Programming Language. Control Scope and Privacy with Modules.
  3. Rust By Example. Visibility.