Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

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();
            }
        }
    }
}
Master Rust with Deep Grasping Methodology!Learn More