RustBrock/Paths.md

Paths

Paths for Referring to an Item in the Module Tree

to show the rust compiler where to find an item in a module tree we use a path similar to navigating a filesystem, where the function is located

A path can be two forms:

• Absolute path - the full path starting from a crate root to the code of an external crate, the absolute path begins with the crate name and for code form the current crate it starts with the literal crate
• Relative path - starts from the current module and uses self, super, or an identifier in the current module Both types of paths are followed by one or more identifiers separated by ::

module tree for example

crate
 └── front_of_house
     ├── hosting
     │   ├── add_to_waitlist
     │   └── seat_at_table
     └── serving
         ├── take_order
         ├── serve_order
         └── take_payment

    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();

these are both calls to different parts of a different module from the parent crate named crate this is equivalent to /front_of_house/hosting/add_to_waitlist in another language where the first / is the crate root or the ./

choose the pathing based off your requirements/future organization of code preference is to specify absolute paths because more likely to move code definitions and item calls independently of each other

rust will be able to tell the difference between a private function and a wrong path error

any function, method, struct, enum, module and constants are private by default

child modules can use parent modules but parent modules cannot use child modules

child modules wrap their implementation to those above but not to itself or below

you use pub keyword to expose to the parent module this is done so that you know what breaks your code

this is valid and allows for the outermost crate to access the function add_to_watlist through the root defined front_of_house module

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

it is called by crate::front_of_house::hosting::add_to_waitlist(); from the sister module/function if it was up another level then front_of_house would need a pub

can be called by the relative path front_of_house::hosting::add_to_waitlist();

the public API that is determined by the developer is the contract with the users through other crates. There are many considerations to your public api to make it easier for people to depend on your crate These details and considerations are more concretely outlined in the The Rust API Guidelines

Starting Relative Paths with super

can contract relative paths starting at the parent rather than the root of the crate

This is done by using the super keyword at the start of the path it is equivalent to the .. syntax useful for accessing items that we know are in the parent module which can make rearranging the module tree easier when the module is closely related to the parent but may be moved in the future

    super::deliver_order();

deliver order now can be located else where in the parent module and not forced to be in the child module