Separating Modules into Different Files

In Rust, modules are a fundamental way to organize code within a crate. As projects grow, keeping all code in a single file (like `main.rs` or `lib.rs`) becomes unwieldy. Separating modules into different files enhances readability, maintainability, reusability, and allows for better team collaboration by avoiding large, monolithic files.

Rust's module system is closely tied to its file system. When you declare a module using the `mod` keyword, Rust looks for its definition in one of two places:

1. As a separate file with the same name: If you declare `mod my_module;` in a file (e.g., `src/main.rs`), Rust will look for the code belonging to `my_module` in `src/my_module.rs`.
2. As a directory containing a `mod.rs` file: If you declare `mod my_module;` and `my_module.rs` doesn't exist, Rust will then look for a directory named `src/my_module/` which must contain a `mod.rs` file. This `mod.rs` file then contains the code for `my_module` and can, in turn, declare sub-modules within that directory.

This two-pronged approach provides flexibility in structuring your project:

* Flat Structure: For simpler modules that don't have sub-modules, a single `.rs` file is often sufficient (`src/my_module.rs`).
* Hierarchical Structure: For complex modules that contain their own sub-modules, using a directory with a `mod.rs` file is preferred (`src/my_module/mod.rs`). Any sub-modules declared within `src/my_module/mod.rs` would then reside in files like `src/my_module/sub_module.rs` or directories like `src/my_module/another_sub_module/mod.rs`.

Key Concepts:

* `mod` keyword: Used to declare a module. When followed by a semicolon (e.g., `mod my_module;`), it tells Rust to load the module's contents from an external file or directory.
* `pub` keyword: By default, all items (functions, structs, enums, etc.) within a module are private to that module. To make an item visible to parent modules or other parts of the crate, you must mark it with `pub`.
* `use` keyword: After a module is declared and its items are public, you can bring them into the current scope using the `use` keyword, similar to `import` in other languages. This allows you to refer to items directly without their full module path.
* Crate Root: The `main.rs` (for executables) or `lib.rs` (for libraries) file is considered the crate root. All modules within your crate ultimately derive from this root.

Best Practices:

* Use `snake_case` for module and file names.
* Organize related functionalities into distinct modules.
* Keep modules relatively small and focused on a single responsibility.
* Use `pub` sparingly; expose only what's necessary for the module's public API.

// The following code demonstrates a common project structure.
// To run this example, create a new Rust project `cargo new module_separation_example`
// Then, create the following files and directories inside the `src/` directory.

// --- src/main.rs ---
// This is our crate root. It declares the top-level modules.
mod math_operations; // Rust will look for `src/math_operations.rs`
mod utilities;       // Rust will look for `src/utilities/mod.rs`

fn main() {
    println!("--- Math Operations ---");
    // We can use items from `math_operations` because they are `pub`
    let sum = math_operations::add(10, 5);
    println!("10 + 5 = {}", sum);
    let product = math_operations::multiply(10, 5);
    println!("10 * 5 = {}", product);

    println!("\n--- Utilities ---");
    // We use `utilities::text_processing::` because `text_processing` is a submodule
    // of `utilities`, and `capitalize_first_letter` is a function within it.
    let formatted_text = utilities::text_processing::capitalize_first_letter("hello rustaceans!");
    println!("Formatted: {}", formatted_text);
    
    // `log_message` is directly in the `utilities` module
    utilities::log_message("This is a message from the utilities module.");
}

// --- src/math_operations.rs ---
// This file contains the `math_operations` module.
// Declared in `main.rs` as `mod math_operations;`

pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

pub fn multiply(a: i32, b: i32) -> i32 {
    a * b
}

// --- src/utilities/mod.rs ---
// This file defines the `utilities` module, declared in `main.rs` as `mod utilities;`.
// It also declares a submodule `text_processing` within itself.

pub mod text_processing; // Rust will look for `src/utilities/text_processing.rs`

pub fn log_message(message: &str) {
    println!("LOG: {}", message);
}

// --- src/utilities/text_processing.rs ---
// This file contains the `text_processing` submodule, declared in `src/utilities/mod.rs`.

pub fn capitalize_first_letter(s: &str) -> String {
    let mut c = s.chars();
    match c.next() {
        None => String::new(),
        Some(first) => first.to_uppercase().to_string() + c.as_str(),
    }
}