> ## 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.
# 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.
```rust theme={"dark"}
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)`).
```rust theme={"dark"}
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:**
```text theme={"dark"}
src/
├── lib.rs
├── parent.rs
└── parent/
└── child.rs
```
**File Contents:**
```rust theme={"dark"}
// 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.
```rust theme={"dark"}
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();
}
}
}
}
```
Tired of Poor Rust Skills? Fix That With Deep Grasping!
Learn More
