Fix modules notes and formatting

This commit is contained in:
Marcello 2021-08-13 19:00:10 +02:00
parent 9e59eeeea4
commit dd447cfbcc

View file

@ -40,25 +40,25 @@ These features, sometimes collectively referred to as the module system, include
### Packages & Crates
A crate is a binary or library. The crate root is a source file that the Rust compiler starts from and makes up the root module of he crate.
A crate is a binary or library. The crate root is a source file that the Rust compiler starts from and makes up the root module of he crate.
A package is one or more crates that provide a set of functionality. A package contains a `Cargo.toml` file that describes how to build those crates.
Several rules determine what a package can contain. A package must contain `zero` or `one` **library crates** (`lib` ?), and no more.
Several rules determine what a package can contain. A package must contain `zero` or `one` **library crates** (`lib` ?), and no more.
It can contain as many `binary` crates as youd like, but it must contain at least one crate (either library or binary).
If a package contains `src/main.rs` and `src/lib.rs`, it has two crates: a library and a binary, both with the same name as the package.
If a package contains `src/main.rs` and `src/lib.rs`, it has two crates: a library and a binary, both with the same name as the package.
A package can have multiple binary crates by placing files in the `src/bin` directory: each file will be a separate binary crate.
A crate will group related functionality together in a scope so the functionality is easy to share between multiple projects.
Cargo follows a convention that `src/main.rs` is the crate root of a binary crate with the same name as the package.
Cargo follows a convention that `src/main.rs` is the crate root of a binary crate with the same name as the package.
Likewise, Cargo knows that if the package directory contains `src/lib.rs`, the package contains a library crate with the same name as the package, and `src/lib.rs` is its crate root.
### Modules
Modules allow to organize code within a crate into groups for readability and easy reuse. Modules also control the privacy of items, which is whether an item can be used by outside code (*public*) or is an internal implementation detail and not available for outside use (*private*).
Define a module by starting with the `mod` keyword and then specify the name of the moduleand place curly brackets around the body of the module.
Define a module by starting with the `mod` keyword and then specify the name of the moduleand place curly brackets around the body of the module.
Inside modules, it's possible to have other modules. Modules can also hold definitions for other items, such as structs, enums, constants, traits, or functions.
### Paths
@ -80,10 +80,12 @@ crate::module::function(); // abs path (same crate)
### Public vs Private
Modules arent useful only for organizing the code. They also define Rusts privacy boundary: the line that encapsulates the implementation details external code isnt allowed to know about, call, or rely on. So, to make an item like a function or struct private, put it in a module.
Modules arent useful only for organizing the code. They also define Rusts privacy boundary:
the line that encapsulates the implementation details external code isnt allowed to know about, call, or rely on.
So, to make an item like a function or struct private, put it in a module.
The way privacy works in Rust is that all items (functions, methods, structs, enums, modules, and constants) are *private by default*.
Items in a parent module cant use the private items inside child modules, but items in child modules can use the items in their ancestor modules.
The way privacy works in Rust is that all items (functions, methods, structs, enums, modules, and constants) are *private by default*.
Items in a parent module cant use the private items inside child modules, but items in child modules can use the items in their ancestor modules.
The reason is that child modules wrap and hide their implementation details, but the child modules can see the context in which theyre defined.
```rs
@ -99,8 +101,9 @@ pub mod public_module {
mod file_level_module; // define a module for the whole file (same name as file)
```
It's possible to use `pub` to designate *structs* and *enums* as public, but there are a few extra details.
If `pub` is used before a struct definition, this makes the struct public, but the structs fields will still be private. It's possible make each field public or not on a case-by-case basis.
It's possible to use `pub` to designate *structs* and *enums* as public, but there are a few extra details.
If `pub` is used before a struct definition, this makes the struct public, but the structs fields will still be private.
It's possible make each field public or not on a case-by-case basis.
In contrast, if an enum is made public, all of its variants are then public.
@ -108,8 +111,8 @@ In contrast, if an enum is made public, all of its variants are then public.
```rs
use <crate_name>::module; // import module (abs path, other crate)
use crate::module; // s (abs path, same crate)
use self::module; // // import module (rel path, same crate)
use crate::module; // import module (abs path, same crate)
use self::module; // import module (rel path, same crate)
use <crate_name>::module as alias; // import module w/ aliass
pub use <crate_name>::module; // re-exporting (import and make available to others)
@ -124,9 +127,17 @@ module::function(); // use func w/ shorter path
```txt
src
|_main.rs --> app entrypoint
|_lib.rs --> export module-folders
|_main.rs --> default executable file
|_lib.rs --> default library file
|__module
| |_mod.rs --> export module-files
| |_file.rs
| |_mod.rs --> export submodules
| |_submodule.rs --> submodule
```
```rs
// main.rs
mod module; // delcare module direcotry as a module
// mod.rs
pub mod sub_module; // declare sub_module file as a module
```