Rust Nested Module

A nested module in Rust is a module defined within the lexical scope of another module, establishing a hierarchical namespace tree for code organization and encapsulation. Nested modules create strict privacy boundaries, requiring explicit visibility modifiers to expose internal items to parent or external scopes.

Inline Declaration

Nested modules can be defined inline within a single file using nested mod blocks. By default, a nested module and its contents are private to its immediate parent module.

mod parent_module {
    // The nested module is private to `parent_module` by default
    pub mod child_module {
        // The function must also be marked `pub` to be accessible
        pub fn nested_function() {
            println!("Accessed nested function");
        }
    }
}

fn main() {
    // Path resolution uses the `::` operator
    parent_module::child_module::nested_function();
}

Visibility and Privacy Rules

Rust enforces strict privacy rules across module boundaries. A parent module cannot access private items within its nested child modules, but a nested child module can access all items (public or private) in its parent module. To control access, Rust provides granular visibility modifiers:

pub: Makes the item visible to any scope that can access the module.
pub(super): Restricts visibility to the immediate parent module.
pub(crate): Restricts visibility to the current crate.
pub(in path): Restricts visibility to a specific ancestor module defined by the provided path (e.g., pub(in crate::outer::inner)).

mod outer {
    fn private_outer_fn() {}

    pub mod inner {
        pub(super) fn restricted_fn() {
            // Child can access parent's private items implicitly
            super::private_outer_fn(); 
        }
        
        pub mod deep_inner {
            // Visible only within the `outer` module
            pub(in crate::outer) fn deeply_restricted_fn() {}
        }
    }

    pub fn access_inner() {
        // Parent can access child's `pub(super)` items
        inner::restricted_fn();
        // Parent can access descendant's `pub(in crate::outer)` items
        inner::deep_inner::deeply_restricted_fn();
    }
}

File System Mapping

When codebases grow, nested modules are typically extracted into separate files. Rust maps the module hierarchy to the directory structure. To nest a module via the file system, the parent module must declare the child module using mod child_module; without a block. Given the following module tree: crate::parent::child Directory Structure:

src/
├── lib.rs
├── parent.rs
└── parent/
    └── child.rs

File Contents:

// src/lib.rs (Crate Root)
pub mod parent; // Declares the parent module

// src/parent.rs
pub mod child; // Declares the nested child module

// src/parent/child.rs
pub fn nested_function() {} // Actual implementation

Note: In older Rust editions (pre-2018), src/parent.rs would instead be named src/parent/mod.rs.

Path Resolution

Navigating nested module trees requires specific path keywords:

Absolute paths begin from the crate root using the crate keyword.
Relative paths begin from the current module using self, super, or the identifier of a sibling module.

mod level_one {
    pub fn root_level_fn() {}

    pub mod level_two {
        pub mod level_three {
            pub fn deep_fn() {
                // Relative path stepping up two levels
                super::super::root_level_fn();
                
                // Absolute path from the crate root
                crate::level_one::root_level_fn();
            }
        }
    }
}