Rust modules

Modules are rust libraries.
The std::prelude module is included in the scope of every program.

Documentation

official docs	https://doc.rust-lang.org/reference/items/modules.html
cargo book: package layout	https://doc.rust-lang.org/cargo/guide/project-layout.html

Tutorials

rust module system

https://www.sheshbabu.com/posts/rust-module-system/

Examples

The core idea is that main.rs/lib.rs must directly/indirectly import all paths.

• crate is the root namespace of the crate
• mod allows access to a namespace, using namespace prefix, for modules in same-directory
• use merges a namespace (or elements from it) into the current namespace
• pub mod exposes module externally
• super, within use/mod refers to the parent scope

sample-1: (mod) use module from namespace

src/
  main.rs
  house.rs

src/main.rs

// main.rs

mod house;

fn main() {
    println!("{}", house::house_name());
}

house.rs / house/mod.rs

// house.rs  /  house/mod.rs

pub fn house_name() -> String {
    String:from("hi")
}

sample-2 (mod) use file from submodule

In order to use street::lamps::* from main.rs,
we must publish lamps from street.

src/
  main.rs
  street/
    mod.rs
    lamps.rs

main.rs

// main.rs

mod street;

fn main() {
    printlnt("{}", street::lamps::brightness());
}

street/mod.rs

// street/mod.rs

pub mod lamps;

street/lamps.rs

// street/lamps.rs

pub fn brightness() -> isize {
    100
}

sample-3 (use) use file from submodule

In order to use street::lamps::* from main.rs,
we must publish lamps from street.

src/
  street/
    mod.rs
    lamps.rs
  main.rs

src/main.rs

mod street;
use street::lamps::*;

fn main() {
    println!("{}", brightness());
}

src/street/mod.rs

// src/street/mod.rs

pub mod lamps;

src/street/lamp.rs

// src/street/lamp.rs

pub fn brightness() -> isize {
    100
}

Entrypoints

For modules to be compiled, they must be used (however indirectly) from:

• src/main.rs for executables
• src/lib.rs for libraries

Imports

• use merge namespace into current (ex. use foo; myfn();)
• mod enables you to access from namespace (ex. mod foo; foo::myfn();)

use (merge with current namespace)

use std::io;                      // merges objects from namespace into your own
use std::io::*;                   //
use std::fs::File;                // import 'File' only into current namespace
use std::fs::{File, DirBuilder};  // import multiple types/functions into current namespace

std::io::stdin()                  // you also can access objects directly from their namespace without `use`

mod enables access to submodules, 1-level deep, from current module.

// expose ./foo.rs or ./foo/mod.rs from current module
pub mod foo;

Access Control

By default, a module's code is public to itself and it's children,
but private to it's parents and/or callers.
The pub keyword exposes a module/function.

pub mod house {
    pub mod livingroom {   // `livingroom` is 'pub', it is exposed to it's parent `house`
        mod chair {        // access to house/livingroom/chair symbols, regardless of pub/private
            // ...
        }
    }
    mod bedroom {          // `bedroom` is not 'pub', `house` cannot refer to it
        // ...
    }
}