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
```

```rust
    // 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
```rust
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](https://rust-lang.github.io/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

```rust
    super::deliver_order();
```
deliver order now can be located else where in the parent module and not forced to be in the child module