mirror of
https://github.com/rust-lang-cn/book-cn.git
synced 2025-01-23 23:50:25 +08:00
Ship ch 7 to nostarch
This commit is contained in:
Carol (Nichols || Goulding)
parent
aaf1fc15b8
commit
46d88b4448
@ -3,46 +3,49 @@
|
||||
|
||||
# Modules
|
||||
|
||||
When you write a program in Rust, your code might start off living solely in
|
||||
the `main` function. As your code grows, you eventually move functionality out
|
||||
into functions, both for re-use and for nicer organization. By splitting your
|
||||
code up into smaller chunks, each chunk is easier to understand on its own. So
|
||||
what happens when you start having too many functions? Rust has a module system
|
||||
that tackles both the problem of wanting to be able to re-use code and the
|
||||
problem of keeping your code organized.
|
||||
When you start writing programs in Rust, your code might live solely in the
|
||||
`main` function. As your code grows, you’ll eventually move functionality out
|
||||
into other functions, both for re-use and for better organization. By splitting
|
||||
your code up into smaller chunks, each chunk is easier to understand on its
|
||||
own. But what happens if find yourself with too many functions? Rust has a
|
||||
module system that handles the problem of wanting to to re-use code while
|
||||
keeping your code organized.
|
||||
|
||||
In the same way that you extract lines of code into a function, you can extract
|
||||
functions (and other code like structs and enums too) into different modules. A
|
||||
*module* is a namespace that contains definitions of functions or types, and
|
||||
those definitions can be visible outside their module or not. Here's an
|
||||
overview of how the bits fit together:
|
||||
you can choose whether those definitions are visible outside their module
|
||||
(public) or not (private). Here’s an overview of how modules work:
|
||||
|
||||
* `mod` declares a new module.
|
||||
* Everything starts off as private, but the `pub` keyword makes it public.
|
||||
* The `use` keyword allows you to bring modules, or definitions inside of them,
|
||||
into scope so that it's easier to refer to them.
|
||||
* You declare a new module with the keyword `mod`
|
||||
* By default, everything is set as private, but you can use the `pub` keyword
|
||||
to make the module public, and therefore visible outside of the namespace.
|
||||
* The `use` keyword allows you to bring modules, or the definitions inside
|
||||
modules, into scope so that it’s easier to refer to them.
|
||||
|
||||
We'll take a look at each of these parts and see how they fit into the whole.
|
||||
We’ll take a look at each of these parts and see how they fit into the whole.
|
||||
|
||||
## `mod` and the Filesystem
|
||||
|
||||
Every module in Rust starts with the `mod` keyword. In this next example, we'll
|
||||
start again by making a new project with Cargo. This time, instead of a binary,
|
||||
we're going to make a library: a project that other people would pull into their
|
||||
projects as a dependency. We saw this with the `rand` crate in Chapter 2.
|
||||
We’ll start our module example by making a new project with Cargo, but instead
|
||||
of creating a binary crate, we’re going to make a library crate: a project that
|
||||
other people can pull into their projects as a dependency. We saw this with the
|
||||
`rand` crate in Chapter 2.
|
||||
|
||||
Imagine that we're creating a library to provide some general networking
|
||||
functionality, and we decide to call our library `communicator`. To create this
|
||||
library, we won't use the `--bin` option like we have before. This is because
|
||||
by default cargo will create a library:
|
||||
We’ll create a skeleton of a library that provides some general networking
|
||||
functionality; we’re going to concentrate on the organization of the modules
|
||||
and functions, but not worry about what code goes in the function bodies. We’ll
|
||||
call our library `communicator`. By default, cargo will create a library unless
|
||||
another type of project is specified, so if we leave off the `--bin` option
|
||||
that we’ve been using so far our project will be a library:
|
||||
|
||||
```bash
|
||||
$ cargo new communicator
|
||||
$ cd communicator
|
||||
```
|
||||
|
||||
Notice that Cargo generated `src/lib.rs` instead of `src/main.rs` for us, and
|
||||
inside it we'll find this:
|
||||
Notice that Cargo generated *src/lib.rs* instead of *src/main.rs*. Inside
|
||||
*src/lib.rs* we’ll find this:
|
||||
|
||||
Filename: src/lib.rs
|
||||
|
||||
@ -55,14 +58,25 @@ mod tests {
|
||||
}
|
||||
```
|
||||
|
||||
This is an empty test to help us get our library started, instead of the binary
|
||||
that says "Hello, world!" that we get with the `--bin` option. Let's ignore the
|
||||
`#[]` stuff and `mod tests` for a little bit, but we'll make sure to leave it
|
||||
in `src/lib.rs` for later.
|
||||
Cargo creates an empty test to help us get our library started, rather
|
||||
than the “Hello, world!” binary that we get with the `--bin` option. We’ll look
|
||||
at the `#[]` and `mod tests` syntax a little later, but for now just make sure
|
||||
to leave it in your *src/lib.rs*.
|
||||
|
||||
We're going to look at different ways we could choose to organize our library's
|
||||
code, any of which could make sense depending on exactly what we were trying to
|
||||
do. To start, add this code at the beginning of the file:
|
||||
Since we don’t have a *src/main.rs*, there’s nothing for Cargo to execute with
|
||||
the `cargo run` command. Therefore, we will be using the `cargo build` command
|
||||
to only compile our library crate’s code.
|
||||
|
||||
We’re going to look at different options for organizing your library’s code
|
||||
which will be suitable in a variety of situations, depending on the intentions
|
||||
you have for your code.
|
||||
|
||||
### Module Definitions
|
||||
|
||||
For our `communicator` networking library, we’re first going to define a module
|
||||
named `network` that contains the definition of a function called `connect`.
|
||||
Every module definition in Rust starts with the `mod` keyword. Add this code to
|
||||
the beginning of the *lib.rs* file, above the test code:
|
||||
|
||||
Filename: src/lib.rs
|
||||
|
||||
@ -73,14 +87,16 @@ mod network {
|
||||
}
|
||||
```
|
||||
|
||||
This is our first module declaration. We use the `mod` keyword, followed by the
|
||||
name of the module, and then a block of code in curly braces. Everything inside
|
||||
this block is inside the namespace `network`. In this case, we have a single
|
||||
function, `connect`. If we wanted to try and call this function from outside
|
||||
the `network` module, we would say `network::connect()` rather than `connect()`.
|
||||
After the `mod` keyword, we put the name of the module, `network`, then a block
|
||||
of code in curly braces. Everything inside this block is inside the namespace
|
||||
`network`. In this case, we have a single function, `connect`. If we wanted to
|
||||
call this function from a script outside the `network` module, we would need to
|
||||
specify the module and use the namespace syntax `::`, like so:
|
||||
`network::connect()`, rather than just `connect()`.
|
||||
|
||||
We could have multiple modules, side-by-side. For example, if we wanted a
|
||||
`client` module:
|
||||
We can also have multiple modules, side-by-side, in the same *src/lib.rs* file.
|
||||
For example, to have a `client` module too, that also has a function named
|
||||
`connect`, we can add:
|
||||
|
||||
Filename: src/lib.rs
|
||||
|
||||
@ -96,10 +112,21 @@ mod client {
|
||||
}
|
||||
```
|
||||
|
||||
Now we have a `network::connect` function and a `client::connect` function.
|
||||
<caption>
|
||||
Listing 7-1: The `network` module and the `client` module defined side-by-side
|
||||
in *src/lib.rs*
|
||||
</caption>
|
||||
|
||||
And we can put modules inside of modules. If we wanted to have `client` be
|
||||
within `network`:
|
||||
Now we have a `network::connect` function and a `client::connect` function.
|
||||
These can have completely different functionality, and the function names do
|
||||
not conflict with each other since they’re in different modules.
|
||||
|
||||
We can also put modules inside of modules. This can be useful as your modules
|
||||
grow to keep related functionality organized together and separate
|
||||
functionality apart. The choice of how you organize your code depends on how
|
||||
you think about the relationship between the parts of your code. For instance,
|
||||
the `client` code and its `connect` function might make more sense to users of
|
||||
our library if it was inside the `network` namespace instead, like so:
|
||||
|
||||
Filename: src/lib.rs
|
||||
|
||||
@ -115,11 +142,20 @@ mod network {
|
||||
}
|
||||
```
|
||||
|
||||
This gives us `network::connect` and `network::client::connect`.
|
||||
<caption>
|
||||
Listing 7-2: Moving the `client` module inside of the `network` module
|
||||
</caption>
|
||||
|
||||
In this way, modules form a tree. The contents of `src/lib.rs` are at the root
|
||||
of the project's tree, and the submodules form the leaves. Here's what our
|
||||
first example looks like when thought of this way:
|
||||
In your *src/lib.rs* file, replace the existing `mod network` and `mod client`
|
||||
definitions with this one that has the `client` module as an inner module of
|
||||
`network`. Now we have the functions `network::connect` and
|
||||
`network::client::connect`: again, the two functions named `connect` don’t
|
||||
conflict with each other since they’re in different namespaces.
|
||||
|
||||
In this way, modules form a hierarchy. The contents of `src/lib.rs` are at the
|
||||
topmost level, and the submodules are at lower levels. Here’s what the
|
||||
organization of our example from Listing 7-1 looks like when thought of this
|
||||
way:
|
||||
|
||||
```text
|
||||
communicator
|
||||
@ -127,7 +163,7 @@ communicator
|
||||
└── client
|
||||
```
|
||||
|
||||
And here's the second:
|
||||
And here’s the example from Listing 7-2:
|
||||
|
||||
```text
|
||||
communicator
|
||||
@ -135,13 +171,20 @@ communicator
|
||||
└── client
|
||||
```
|
||||
|
||||
More complicated projects can have a lot of modules.
|
||||
You can see that in Listing 7-2, `client` is a child of the `network` module,
|
||||
rather than a sibling. More complicated projects can have a lot of modules, and
|
||||
they’ll need to be orgnaized logically in order to keep track of them. What
|
||||
“logically” means in your project is up to you and depends on how you and users
|
||||
of your library think about your project’s domain. Use the techniques we’ve
|
||||
shown here to create side-by-side modules and nested modules in whatever
|
||||
structure you would like.
|
||||
|
||||
### Putting Modules in Another File
|
||||
### Moving Modules to Other Files
|
||||
|
||||
Modules form a hierarchical, tree-like structure. So does another thing:
|
||||
file systems! The module system is the way that we split larger Rust projects up
|
||||
into multiple files. Let's imagine we have a module layout like this:
|
||||
Modules form a hierarchical structure, much like another structure in computing
|
||||
that you’re used to: file systems! We can use Rust’s module system along with
|
||||
multiple files to split Rust projects up so that not everything lives in
|
||||
*src/lib.rs*. For this example, we will start with this code in *src/lib.rs*:
|
||||
|
||||
File: src/lib.rs
|
||||
|
||||
@ -162,8 +205,26 @@ mod network {
|
||||
}
|
||||
```
|
||||
|
||||
Let's extract the `client` module into another file. First, we need to change
|
||||
our code in `src/lib.rs`:
|
||||
<caption>
|
||||
Listing 7-3: Three modules, `client`, `network`, and `network::server` all
|
||||
defined in *src/lib.rs*
|
||||
</caption>
|
||||
|
||||
which has this module hierarchy:
|
||||
|
||||
```text
|
||||
communicator
|
||||
├── client
|
||||
└── network
|
||||
└── server
|
||||
```
|
||||
|
||||
If these modules had many functions, and each function was getting long, we
|
||||
would have to scroll through this file to find the code we wanted to work with.
|
||||
This would be a good reason to pull each of the `client`, `network`, and
|
||||
`server` modules out of *src/lib.rs* and into their own files. Let’s start by
|
||||
extracting the `client` module into another file. First, replace the `client`
|
||||
module code in *src/lib.rs* with the following:
|
||||
|
||||
File: src/lib.rs
|
||||
|
||||
@ -181,9 +242,17 @@ mod network {
|
||||
}
|
||||
```
|
||||
|
||||
We still say `mod client`, but instead of curly braces, we have a semicolon.
|
||||
This lets Rust know that we have a module, but it's in another file with that
|
||||
module's name. Open up `src/client.rs` and put this in it:
|
||||
<!-- I will add wingdings/ghosting in libreoffice /Carol -->
|
||||
|
||||
We’re still *defining* the `client` module here, but by removing the curly
|
||||
braces and definitions inside the `client` module and replacing them with a
|
||||
semicolon, we’re letting Rust know to look in another location for the code
|
||||
defined inside that module.
|
||||
|
||||
So now we need to create the external file with that module name. Create a
|
||||
`client.rs` file in your *src/* directory, then open it up and enter the
|
||||
following, which is the `connect` function in the `client` module that we
|
||||
removed in the previous step:
|
||||
|
||||
File: src/client.rs
|
||||
|
||||
@ -192,13 +261,19 @@ fn connect() {
|
||||
}
|
||||
```
|
||||
|
||||
Note that we don't need a `mod` declaration in this file. `mod` is for
|
||||
declaring a new module, and we've already declared this module in `src/lib.rs`.
|
||||
This file provides the _contents_ of the `client` module. If we put a `mod
|
||||
client` here, we'd be giving the `client` module its own submodule named
|
||||
`client`!
|
||||
Note that we don’t need a `mod` declaration in this file; that’s because we
|
||||
already declared the `client` module with `mod` in `src/lib.rs`. This file just
|
||||
provides the *contents* of the `client` module. If we put a `mod client` here,
|
||||
we’d be giving the `client` module its own submodule named `client`!
|
||||
|
||||
Now, everything should compile successfully, but with a few warnings:
|
||||
Rust only knows to look in *src/lib.rs* by default. If we want to add more
|
||||
files to our project, we need to tell Rust in *src/lib.rs* to look in other
|
||||
files; this is why `mod client` needs to be defined in *src/lib.rs* and can’t
|
||||
be defined in *src/client.rs*.
|
||||
|
||||
Now, everything should compile successfully, though you’ll get a few warnings.
|
||||
Remember to use `cargo build` instead of `cargo run` since we have a library
|
||||
crate rather than a binary crate:
|
||||
|
||||
```bash
|
||||
$ cargo build
|
||||
@ -223,11 +298,13 @@ warning: function is never used: `connect`, #[warn(dead_code)] on by default
|
||||
| ^
|
||||
```
|
||||
|
||||
Don't worry about those warnings for now; we'll clear them up in a future
|
||||
section. They're just warnings, we've built things successfully!
|
||||
These warnings tell us that we have functions that are never used. Don’t worry
|
||||
about those warnings for now; we’ll address them later in the chapter. The good
|
||||
news is that they’re just warnings; our project was built successfully!
|
||||
|
||||
Let's extract the `network` module into its own file next, using the same
|
||||
pattern. Change `src/lib.rs` to look like this:
|
||||
Let’s extract the `network` module into its own file next, using the same
|
||||
pattern. In `src/lib.rs`, delete the body of the `network` module and add a
|
||||
semicolon to the declaration, like so:
|
||||
|
||||
Filename: src/lib.rs
|
||||
|
||||
@ -237,7 +314,7 @@ mod client;
|
||||
mod network;
|
||||
```
|
||||
|
||||
And then put this in `src/network.rs`
|
||||
Then create a new `src/network.rs` file and enter the following:
|
||||
|
||||
Filename: src/network.rs
|
||||
|
||||
@ -251,10 +328,15 @@ mod server {
|
||||
}
|
||||
```
|
||||
|
||||
And then run `cargo build` again. Success! We have one more module to extract:
|
||||
`server`. Unfortunately, our current tactic of extracting a module into a file
|
||||
named after that module won't work. Let's try it anyway. Modify
|
||||
`src/network.rs` to look like this:
|
||||
Notice that we still have a `mod` declaration within this module file;
|
||||
this is because we still want `server` to be a sub-module of `network`.
|
||||
|
||||
Now run `cargo build` again. Success! We have one more module to extract:
|
||||
`server`. Because it’s a sub-module—that is, a module within a module—our
|
||||
current tactic of extracting a module into a file named after that module won’t
|
||||
work. We’re going to try anyway so that we can see the error. First change
|
||||
*src/network.rs* to have `mod server;` instead of the `server` module’s
|
||||
contents:
|
||||
|
||||
Filename: src/network.rs
|
||||
|
||||
@ -265,7 +347,8 @@ fn connect() {
|
||||
mod server;
|
||||
```
|
||||
|
||||
Put this in `src/server.rs`
|
||||
Then create a `src/server.rs` file and enter the contents of the `server`
|
||||
module that we extracted:
|
||||
|
||||
Filename: src/server.rs
|
||||
|
||||
@ -274,7 +357,7 @@ fn connect() {
|
||||
}
|
||||
```
|
||||
|
||||
When we try to `cargo build`, we'll get an error:
|
||||
When we try to `cargo build`, we’ll get this error:
|
||||
|
||||
```bash
|
||||
$ cargo build
|
||||
@ -297,35 +380,40 @@ note: ... or maybe `use` the module `server` instead of possibly redeclaring it
|
||||
| ^^^^^^
|
||||
```
|
||||
|
||||
This error is actually pretty helpful. It points out something we didn't know
|
||||
that we could do yet:
|
||||
<caption>
|
||||
Listing 7-4: Error when trying to extract the `server` submodule into
|
||||
*src/server.rs*
|
||||
</caption>
|
||||
|
||||
The error says we `cannot declare a new module at this location` and is
|
||||
pointing to the `mod server;` line in `src/network.rs`. So `src/network.rs` is
|
||||
different than `src/lib.rs` somehow; let’s keep reading to understand why.
|
||||
|
||||
The note in the middle of Listing 7-4 is actually pretty helpful, as it points
|
||||
out something we haven’t yet talked about doing:
|
||||
|
||||
> note: maybe move this module `network` to its own directory via
|
||||
`network/mod.rs`
|
||||
|
||||
Here's the problem: in our case, we have different names for our modules:
|
||||
`client` and `network::server`. But what if we had `client` and
|
||||
`network::client`, or `server` and `network::server`? Having two modules at
|
||||
different places in the module hierarchy have the same name is completely
|
||||
valid, but then which module would the files `src/client.rs` and
|
||||
`src/server.rs`, respectively, be for?
|
||||
|
||||
Instead of continuing to follow the same file naming pattern we used
|
||||
previously, we can do what the error suggests. We'll make a new _directory_,
|
||||
move `src/server.rs` into it, and change `src/network.rs` to
|
||||
`src/network/mod.rs`. Then, when we try to build:
|
||||
previously, we can do what the note suggests:
|
||||
|
||||
1. Make a new *directory* named *network*, the parent module’s name
|
||||
2. Move the *src/network.rs* file into the new *network* directory and rename
|
||||
it so that it is now *src/network/mod.rs*
|
||||
3. Move the submodule file *src/server.rs* into the *network* directory
|
||||
|
||||
Here are commands to carry out these steps:
|
||||
|
||||
```bash
|
||||
$ mkdir src/network
|
||||
$ mv src/server.rs src/network
|
||||
$ mv src/network.rs src/network/mod.rs
|
||||
$ cargo build
|
||||
Compiling communicator v0.1.0 (file:///projects/communicator)
|
||||
<warnings>
|
||||
$
|
||||
$ mv src/server.rs src/network
|
||||
```
|
||||
|
||||
It works! So now our module layout looks like this:
|
||||
Now if we try to `cargo build`, compilation will work (we’ll still have
|
||||
warnings though). Our module layout still looks like this, which is exactly the
|
||||
same as it did when we had all the code in *src/lib.rs* in Listing 7-3:
|
||||
|
||||
```text
|
||||
communicator
|
||||
@ -334,7 +422,7 @@ communicator
|
||||
└── server
|
||||
```
|
||||
|
||||
And the corresponding file layout looks like this:
|
||||
The corresponding file layout now looks like this:
|
||||
|
||||
```text
|
||||
├── src
|
||||
@ -345,10 +433,47 @@ And the corresponding file layout looks like this:
|
||||
│ └── server.rs
|
||||
```
|
||||
|
||||
So when we wanted to extract the `network::server` module, why did we have to
|
||||
also change the *src/network.rs* file into the *src/network/mod.rs* file, and
|
||||
also put the code for `network::server` in the `network` directory in
|
||||
*src/network/server.rs*, instead of just being able to extract the
|
||||
*network::server* into *src/server.rs*? The reason is that Rust wouldn’t be
|
||||
able to tell that `server` was supposed to be a submodule of `network` if the
|
||||
*server.rs* file was in the *src* directory. To make it clearer why Rust can’t
|
||||
tell, let’s consider a different example where we have this module hierarchy
|
||||
with all the definitions in *src/lib.rs*:
|
||||
|
||||
```text
|
||||
communicator
|
||||
├── client
|
||||
└── network
|
||||
└── client
|
||||
```
|
||||
|
||||
In this example, we have three modules again, `client`, `network`, and
|
||||
`network::client`. If we follow the same steps we originally did above for
|
||||
extracting modules into files, for the `client` module we would create
|
||||
*src/client.rs*. For the `network` module, we would create *src/network.rs*.
|
||||
Then we wouldn’t be able to extract the `network::client` module into a
|
||||
*src/client.rs* file, because that already exists for the top-level `client`
|
||||
module! If we put the code in both the `client` and `network::client` modules
|
||||
in the *src/client.rs* file, Rust would not have any way to know whether the
|
||||
code was for `client` or for `network::client`.
|
||||
|
||||
Therefore, once we wanted to extract a file for the `network::client` submodule
|
||||
of the `network` module, we needed to create a directory for the `network`
|
||||
module instead of a *src/network.rs* file. The code that is in the `network`
|
||||
module then goes into the *src/network/mod.rs* file, and the submodule
|
||||
`network::client` can have its own *src/network/client.rs* file. Now the
|
||||
top-level *src/client.rs* is unambiguously the code that belongs to the
|
||||
`client` module.
|
||||
|
||||
### Rules of Module File Systems
|
||||
|
||||
In summary, these are the rules of modules with regards to files:
|
||||
|
||||
* If a module named `foo` has no submodules, you should put the declarations in
|
||||
the `foo` module in a file named `foo.rs`.
|
||||
* If a module named `foo` has no submodules, you should put the declarations
|
||||
for `foo` in a file named `foo.rs`.
|
||||
* If a module named `foo` does have submodules, you should put the declarations
|
||||
for `foo` in a file named `foo/mod.rs`.
|
||||
* The first two rules apply recursively, so that if a module named `foo` has a
|
||||
@ -361,19 +486,23 @@ In summary, these are the rules of modules with regards to files:
|
||||
│ └── mod.rs (contains the declarations in `foo`, including `mod bar`)
|
||||
```
|
||||
|
||||
* The modules themselves should be declared in their parent module's file using
|
||||
* The modules themselves should be declared in their parent module’s file using
|
||||
the `mod` keyword.
|
||||
|
||||
Next, we'll talk about the `pub` keyword, and get rid of those warnings!
|
||||
Next, we’ll talk about the `pub` keyword, and get rid of those warnings!
|
||||
|
||||
## Controlling Visibility with `pub`
|
||||
|
||||
At the end of the last section, we had a project, `communicator`, and when we compiled it, we got some strange warnings:
|
||||
We resolved the error messages shown in Listing 7-4 by moving the `network` and
|
||||
`network::server` code into the *src/network/mod.rs* and
|
||||
*src/network/server.rs* files, respectively. At that point, `cargo build` was
|
||||
able to build our project, but we still get some warning messages about the
|
||||
`client::connect`, `network::connect`, and `network::server::connect` functions
|
||||
not being used:
|
||||
|
||||
```bash
|
||||
Compiling communicator v0.1.0 (file:///projects/communicator)
|
||||
warning: function is never used: `connect`, #[warn(dead_code)] on by default
|
||||
--> src/client.rs:1:1
|
||||
src/client.rs:1:1
|
||||
|
|
||||
1 | fn connect() {
|
||||
| ^
|
||||
@ -391,13 +520,16 @@ warning: function is never used: `connect`, #[warn(dead_code)] on by default
|
||||
| ^
|
||||
```
|
||||
|
||||
Why does this happen? After all, we're building a library. What if these three
|
||||
functions are the public interface that we want our *users* to use? We won't
|
||||
necessarily be using them within our own project, but the point of creating them
|
||||
is that they *will* be used by another project. Let's try using them as if we
|
||||
were another project using our library to see what happens and understand why
|
||||
we're getting these unused function warnings. Create a `src/main.rs` file with
|
||||
this code:
|
||||
So why are we receiving these warnings? After all, we’re building a library
|
||||
with functions that are intended to be used by our *users*, and not necessarily
|
||||
by us within our own project, so it shouldn’t matter that these `connect`
|
||||
functions go unused. The point of creating them is that they will be used by
|
||||
another project and not our own.
|
||||
|
||||
To understand why this program invokes these warnings, let’s try using the
|
||||
`connect` library as if we were another project, calling it externally. We can
|
||||
do that by creating a binary crate in the same directory as our library crate,
|
||||
by making a `src/main.rs` file containing this code:
|
||||
|
||||
Filename: src/main.rs
|
||||
|
||||
@ -409,22 +541,19 @@ fn main() {
|
||||
}
|
||||
```
|
||||
|
||||
We need the `extern crate` line to bring our `communicator` library crate into
|
||||
scope, because our package actually now contains *two* crates. Cargo treats
|
||||
src/main.rs as the crate root of a binary crate, and we also have our existing
|
||||
library crate. This pattern is quite common for executable crates: most
|
||||
functionality is in a library crate, and the executable crate uses that
|
||||
library. This way, other programs can also use the library crate, and it’s a
|
||||
nice separation of concerns.
|
||||
We use the `extern crate` command to bring the `communicator` library crate
|
||||
into scope, because our package actually now contains *two* crates. Cargo
|
||||
treats *src/main.rs* as the root file of a binary crate, which is separate from
|
||||
the existing library crate whose root file is *src/lib.rs*. This pattern is
|
||||
quite common for executable projects: most functionality is in a library crate,
|
||||
and the binary crate uses that library crate. This way, other programs can also
|
||||
use the library crate, and it’s a nice separation of concerns.
|
||||
|
||||
Our binary crate right now just calls our library's `connect` function from
|
||||
the `client` module; we picked that one since it's the first warning in our
|
||||
build output above. Invoking `cargo build` will now give us an error after the
|
||||
warnings:
|
||||
Our binary crate right now just calls our library’s `connect` function from the
|
||||
`client` module. However, invoking `cargo build` will now give us an error
|
||||
after the warnings:
|
||||
|
||||
```bash
|
||||
$ cargo build
|
||||
Compiling communicator v0.1.0 (file:///projects/communicator)
|
||||
error: module `client` is private
|
||||
--> src/main.rs:4:5
|
||||
|
|
||||
@ -432,19 +561,30 @@ error: module `client` is private
|
||||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
```
|
||||
|
||||
Ah ha! The `client` module is private. This is the first time we've run into
|
||||
the concepts of 'public' and 'private' in the context of Rust. There's no
|
||||
keyword to make something private; that's the default state. In this default
|
||||
state, no one else could possibly use it, so if we don't use it within our
|
||||
library crate, Rust will warn us that it's unused. Once we tell Rust something
|
||||
is public, Rust knows that we intend for code external to our crate to use it,
|
||||
and Rust considers theoretical external usage that is now possible to count as
|
||||
being used. Thus, when something is marked as public, Rust will stop warning us
|
||||
that it is unused.
|
||||
Ah ha! This tells us that the `client` module is private, and this is the crux
|
||||
of the warnings. It’s also the first time we’ve run into the concepts of
|
||||
*public* and *private* in the context of Rust. The default state of all code in
|
||||
Rust is private: no one else is allowed to use the code. If you don’t use a
|
||||
private function within your own program, since your own program is the only
|
||||
code allowed to use that function, Rust will warn you that the function has
|
||||
gone unused.
|
||||
|
||||
To tell Rust we want to make something public, we add the `pub` keyword. This
|
||||
keyword goes before the declaration of the item we want to make public. Let's
|
||||
modify `src/lib.rs` to make the `client` module public to fix the error we got:
|
||||
Once we specify that a function like `client::connect` is public, not only will
|
||||
our call to that function from our binary crate be allowed, the warning that
|
||||
the function is unused will go away. Marking something public lets Rust know
|
||||
that we intend for the function to be used by code outside of our program. Rust
|
||||
considers the theoretical external usage that’s now possible as the function
|
||||
“being used.” Thus, when something is marked as public, Rust will not require
|
||||
that it’s used in our own program and will stop warning that the item is
|
||||
unused.
|
||||
|
||||
### Making a Function Public
|
||||
|
||||
To tell Rust to make something public, we add the `pub` keyword to the start of
|
||||
the declaration of the item we want to make public. We’ll focus on fixing the
|
||||
warning that tells us that `client::connect` has gone unused for now, as well
|
||||
as the “module `client` is private” error from our binary crate. Modify
|
||||
`src/lib.rs` to make the `client` module public, like so:
|
||||
|
||||
Filename: src/lib.rs
|
||||
|
||||
@ -454,11 +594,9 @@ pub mod client;
|
||||
mod network;
|
||||
```
|
||||
|
||||
The `pub` goes right before `mod`. Let's try building again:
|
||||
The `pub` goes right before `mod`. Let’s try building again:
|
||||
|
||||
```bash
|
||||
$ cargo build
|
||||
Compiling communicator v0.1.0 (file:///projects/communicator)
|
||||
<warnings>
|
||||
error: function `connect` is private
|
||||
--> src/main.rs:4:5
|
||||
@ -468,8 +606,8 @@ error: function `connect` is private
|
||||
```
|
||||
|
||||
Hooray! We have a different error! Yes, different error messages are a cause
|
||||
for celebration. The new error says "function `connect` is private", so let's
|
||||
edit `src/client.rs` to make `client::connect` public:
|
||||
for celebration. The new error says “function `connect` is private”, so let’s
|
||||
edit `src/client.rs` to make `client::connect` public too:
|
||||
|
||||
Filename: src/client.rs
|
||||
|
||||
@ -481,8 +619,6 @@ pub fn connect() {
|
||||
And run `cargo build` again:
|
||||
|
||||
```bash
|
||||
cargo build
|
||||
Compiling communicator v0.1.0 (file:///projects/communicator)
|
||||
warning: function is never used: `connect`, #[warn(dead_code)] on by default
|
||||
--> src/network/mod.rs:1:1
|
||||
|
|
||||
@ -496,18 +632,18 @@ warning: function is never used: `connect`, #[warn(dead_code)] on by default
|
||||
| ^
|
||||
```
|
||||
|
||||
It compiled! And the warning about `client::connect` not being used is gone!
|
||||
It compiled, and the warning about `client::connect` not being used is gone!
|
||||
|
||||
Making functions public isn't the only way to fix unused code warnings: if
|
||||
we *didn't* want these functions to be part of our public API and we got these
|
||||
warnings, the warnings could be alerting us to code we no longer needed and
|
||||
could safely delete. They could also be alerting us to a bug, if we
|
||||
had just accidentally removed all places within our library where we called
|
||||
this function.
|
||||
Unused code warnings don’t always indicate that something needs to be made
|
||||
public: if you *didn’t* want these functions to be part of your public API,
|
||||
unused code warnings could be alerting you to code you no longer needed and can
|
||||
safely delete. They could also be alerting you to a bug, if you had just
|
||||
accidentally removed all places within your library where this function is
|
||||
called.
|
||||
|
||||
However, we *do* want the other two functions to be part of our crate's public
|
||||
API, so let's mark them as `pub` as well to get rid of the remaining warnings.
|
||||
Modify `src/network/mod.rs` to be:
|
||||
In our case though, we *do* want the other two functions to be part of our
|
||||
crate’s public API, so let’s mark them as `pub` as well to try to get rid of
|
||||
the remaining warnings. Modify `src/network/mod.rs` to be:
|
||||
|
||||
Filename: src/network/mod.rs
|
||||
|
||||
@ -521,8 +657,6 @@ mod server;
|
||||
And compile:
|
||||
|
||||
```bash
|
||||
$ cargo build
|
||||
Compiling communicator v0.1.0 (file:///projects/communicator)
|
||||
warning: function is never used: `connect`, #[warn(dead_code)] on by default
|
||||
--> src/network/mod.rs:1:1
|
||||
|
|
||||
@ -536,11 +670,12 @@ warning: function is never used: `connect`, #[warn(dead_code)] on by default
|
||||
| ^
|
||||
```
|
||||
|
||||
Hmmm, it says this is still dead, even though it's `pub`. While the function is
|
||||
public within the module, the `network` module it's in is not public. We're
|
||||
working from the interior of the library out this time, as opposed to with
|
||||
`client` where we worked from the outside in. Let's change `src/lib.rs` to add
|
||||
the same fix though, by making `network` public like `client` is:
|
||||
Hmmm, we’re still getting an unused function warning even though
|
||||
`network::connect` is set to `pub`. This is because the function is public
|
||||
within the module, but the `network` module that the function resides in is not
|
||||
public. We’re working from the interior of the library out this time, where
|
||||
with `client::connect` we worked from the outside in. We need to change
|
||||
`src/lib.rs` to make `network` public too:
|
||||
|
||||
Filename: src/lib.rs
|
||||
|
||||
@ -553,8 +688,6 @@ pub mod network;
|
||||
Now if we compile, that warning is gone:
|
||||
|
||||
```bash
|
||||
$ cargo build
|
||||
Compiling communicator v0.1.0 (file:///projects/communicator)
|
||||
warning: function is never used: `connect`, #[warn(dead_code)] on by default
|
||||
--> src/network/server.rs:1:1
|
||||
|
|
||||
@ -562,19 +695,21 @@ warning: function is never used: `connect`, #[warn(dead_code)] on by default
|
||||
| ^
|
||||
```
|
||||
|
||||
Only one last warning! Try to fix this one on your own!
|
||||
Only one warning left! Try to fix this one on your own!
|
||||
|
||||
### Privacy Rules
|
||||
|
||||
Overall, these are the rules for item visibility:
|
||||
|
||||
1. If an item is public, then it can be accessed through any of its
|
||||
1. If an item is public, it can be accessed through any of its
|
||||
parent modules.
|
||||
2. If an item is private, it may be accessed by the current module and its
|
||||
2. If an item is private, it may be accessed only by the current module and its
|
||||
child modules.
|
||||
|
||||
Let's look at a few more examples to get some practice. What if we had this
|
||||
code in a new project's `src/lib.rs`:
|
||||
### Privacy Examples
|
||||
|
||||
Let’s look at a few more examples to get some practice. Create a new libary
|
||||
project and enter the code in Listing 7-5 into your new project’s `src/lib.rs`:
|
||||
|
||||
Filename: src/lib.rs
|
||||
|
||||
@ -599,49 +734,55 @@ fn try_me() {
|
||||
}
|
||||
```
|
||||
|
||||
Before you try to compile this code, make a guess about which lines in
|
||||
`try_me` will have errors.
|
||||
Before you try to compile this code, make a guess about which lines in `try_me`
|
||||
function will have errors. Then try compiling to see if you were right, and read
|
||||
on for discussion of the errors!
|
||||
|
||||
Ready? Let's talk through them!
|
||||
#### Looking at the Errors
|
||||
|
||||
The `try_me` function is in the root module of our project. The module named
|
||||
`outermost` is private, but the second rule says we're allowed to access it
|
||||
since `outermost` is in our current, root module.
|
||||
`outermost` is private, but the second privacy rule says the `try_me` function
|
||||
is allowed to access the `outermost` module since `outermost` is in the current
|
||||
(root) module, as is `try_me`.
|
||||
|
||||
The function call `outermost::middle_function()` will work. `middle_function`
|
||||
is public, and we are accessing it through its parent module, `outermost`,
|
||||
which we just determined we can access in the previous paragraph.
|
||||
The call to `outermost::middle_function` will work. This is because
|
||||
`middle_function` is public, and `try_me` is accessing `middle_function`
|
||||
through its parent module, `outermost` We determined in the previous paragraph
|
||||
that this module is accessible.
|
||||
|
||||
`outermost::middle_secret_function()` will cause a compilation error.
|
||||
`middle_secret_function` is private, so the second rule applies. Our current
|
||||
root module is neither the current module of `middle_secret_function`
|
||||
(`outermost` is), nor is it a child module of the current module of
|
||||
`middle_secret_function`.
|
||||
The call to `outermost::middle_secret_function` will cause a compilation error.
|
||||
`middle_secret_function` is private, so the second rule applies. The root
|
||||
module is neither the current module of `middle_secret_function` (`outermost`
|
||||
is), nor is it a child module of the current module of `middle_secret_function`.
|
||||
|
||||
The module named `inside` is private and has no child modules, so it can only
|
||||
be accessed by its current module, `outermost`. That means the `try_me`
|
||||
function is not allowed to call `outermost::inside::inner_function()` or
|
||||
`outermost::inside::secret_function()`.
|
||||
function is not allowed to call `outermost::inside::inner_function` or
|
||||
`outermost::inside::secret_function` either.
|
||||
|
||||
Here are some changes to try making with this code. Try each one, make a guess
|
||||
about what will be allowed or not, compile to see if you're right, and use the
|
||||
rules to understand why.
|
||||
#### Fixing the Errors
|
||||
|
||||
Here are some suggestions for changing the code in an attempt to fix the
|
||||
errors. Before you try each one, make a guess as to whether it will fix the
|
||||
errors, then compile to see if you’re right and use the privacy rules to
|
||||
understand why.
|
||||
|
||||
* What if the `inside` module was public?
|
||||
* What if `outside` was public and `inside` was private?
|
||||
* What if, in the body of `inner_function`, we called
|
||||
* What if, in the body of `inner_function`, you called
|
||||
`::outermost::middle_secret_function()`? (The two colons at the beginning
|
||||
mean that we want to refer to the namespaces starting from the root
|
||||
namespace.)
|
||||
|
||||
Feel free to design more experiments and try them out!
|
||||
|
||||
Next, let's talk about bringing items into a scope with the `use` keyword.
|
||||
Next, let’s talk about bringing items into a scope with the `use` keyword.
|
||||
|
||||
## Importing Names with `use`
|
||||
## Importing Names
|
||||
|
||||
We've seen how we can call functions defined within a module by using the
|
||||
module name as part of the call, like this:
|
||||
We’ve covered how to call functions defined within a module using the module
|
||||
name as part of the call, as in the call to the `namespaces` function shown
|
||||
here in Listing 7-6.
|
||||
|
||||
Filename: src/main.rs
|
||||
|
||||
@ -659,9 +800,19 @@ fn main() {
|
||||
}
|
||||
```
|
||||
|
||||
However, referring to the fully qualified name can get quite lengthy, as we see
|
||||
in that example. To solve this issue, Rust has a keyword, `use`. It works like
|
||||
this:
|
||||
<caption>
|
||||
Listing 7-6: Calling a function by fully specifying its enclosing module’s
|
||||
namespaces
|
||||
</caption>
|
||||
|
||||
As you can see, referring to the fully qualified name can get quite lengthy.
|
||||
Luckily, Rust has a keyword to make these calls more concise.
|
||||
|
||||
### Concise Imports with `use`
|
||||
|
||||
Rust’s `use` keyword works to shorten lengthy function calls by bringing the
|
||||
modules of the function you want to call into a scope. Here’s an example of
|
||||
bringing the `a::series::of` namespace into a binary crate’s root scope:
|
||||
|
||||
Filename: src/main.rs
|
||||
|
||||
@ -681,10 +832,16 @@ fn main() {
|
||||
}
|
||||
```
|
||||
|
||||
We can `use` a module, and that will bring its name into scope. This allows us
|
||||
to shorten our function call, only requiring us to type the final module name,
|
||||
not the entire chain of them. `use` is quite powerful and can bring all kinds
|
||||
of things into scope. For example, we could `use` the function itself:
|
||||
The line `use a::series::of;` has made it so that anywhere in this scope that
|
||||
we would want to refer to the `of` namespace, instead of having to say
|
||||
`a::series::of`, we can replace that with `of`.
|
||||
|
||||
The `use` keyword brings only what we have specified into scope; it does not
|
||||
bring children of modules into scope. That’s why we still have to say
|
||||
`of::namespaces` when we want to call the `namespaces` function.
|
||||
|
||||
We could have chosen to bring the function itself into scope, by instead
|
||||
specifying the function in the `use` as follows:
|
||||
|
||||
```rust
|
||||
pub mod a {
|
||||
@ -702,10 +859,13 @@ fn main() {
|
||||
}
|
||||
```
|
||||
|
||||
Enums also form this kind of namespace; we can import an enum's variants with
|
||||
`use` as well. For any kind of `use` statement, if you are importing multiple
|
||||
items from one namespace, you can list them using curly braces and commas in
|
||||
the last position, like so:
|
||||
This allows us to exclude any of the modules and just reference the function at
|
||||
the callsite.
|
||||
|
||||
Since enums also form this kind of namespace, we can import an enum’s variants
|
||||
with `use` as well. For any kind of `use` statement, if you’re importing
|
||||
multiple items from one namespace, you can list them using curly braces and
|
||||
commas in the last position, like so:
|
||||
|
||||
```rust
|
||||
enum TrafficLight {
|
||||
@ -719,13 +879,14 @@ use TrafficLight::{Red, Yellow};
|
||||
fn main() {
|
||||
let red = Red;
|
||||
let yellow = Yellow;
|
||||
let green = TrafficLight::Green; // because we didn't use TrafficLight::Green
|
||||
let green = TrafficLight::Green; // because we didn’t `use` TrafficLight::Green
|
||||
}
|
||||
```
|
||||
|
||||
### Glob Imports with `*`
|
||||
|
||||
If you'd like to import all the items in a namespace at once, you can use `*`:
|
||||
To import all the items in a namespace at once, we can use the `*` syntax. For
|
||||
example:
|
||||
|
||||
```rust
|
||||
enum TrafficLight {
|
||||
@ -743,14 +904,15 @@ fn main() {
|
||||
}
|
||||
```
|
||||
|
||||
The `*` is called a 'glob', and it will import everything that's visible inside
|
||||
The `*` is called a *glob*, and it will import everything that’s visible inside
|
||||
of the namespace. Globs should be used sparingly: they are convenient, but you
|
||||
might also pull in more things than you expected and cause naming conflicts.
|
||||
|
||||
### Using `super` to Access a Parent Module
|
||||
|
||||
Remember when we created our crate that Cargo made a `tests` module for us?
|
||||
Let's talk about that now. It was in `src/lib.rs`:
|
||||
As you now know, when you create a library crate, Cargo makes a `tests` module
|
||||
for you. Let’s go into more detail about that now. In your `communicator`
|
||||
project, open `src/lib.rs`.
|
||||
|
||||
Filename: src/lib.rs
|
||||
|
||||
@ -767,14 +929,24 @@ mod tests {
|
||||
}
|
||||
```
|
||||
|
||||
We'll explain more about testing in Chapter XX, but parts of this should make
|
||||
We’ll explain more about testing in Chapter 12, but parts of this should make
|
||||
sense now: we have a module named `tests` that lives next to our other modules
|
||||
and contains one function named `it_works`. Even though there are special
|
||||
annotations, the `tests` module is just another module!
|
||||
annotations, the `tests` module is just another module! So our module hierarchy
|
||||
looks like this:
|
||||
|
||||
Since tests are for exercising the code within our library, let's try to call
|
||||
```text
|
||||
communicator
|
||||
├── client
|
||||
├── network
|
||||
| └── client
|
||||
└── tests
|
||||
```
|
||||
|
||||
|
||||
Tests are for exercising the code within our library, so let’s try to call
|
||||
our `client::connect` function from this `it_works` function, even though
|
||||
we're not going to be checking any functionality right now:
|
||||
we’re not going to be checking any functionality right now:
|
||||
|
||||
Filename: src/lib.rs
|
||||
|
||||
@ -806,35 +978,41 @@ warning: function is never used: `connect`, #[warn(dead_code)] on by default
|
||||
| ^
|
||||
```
|
||||
|
||||
Why doesn't this compile? It's not because we don't have `communicator::` in
|
||||
front of the function like we had in `src/main.rs`: we are definitely within
|
||||
the `communicator` library crate here. The reason is that paths anywhere except
|
||||
in a `use` statement are relative to the current module (In a `use` statement,
|
||||
they're relative to the crate root by default). Our `tests` module doesn't have
|
||||
a `client` module in its scope!
|
||||
The compilation failed, but why? We don’t need to place `communicator::` in
|
||||
front of the function like we did in `src/main.rs` because we are definitely
|
||||
within the `communicator` library crate here. The reason is that paths are
|
||||
always relative to the current module, which here is `tests`. The only
|
||||
exception is in a `use` statement, where paths are relative to the crate root
|
||||
by default. Our `tests` module needs the `client` module in its scope!
|
||||
|
||||
So how do we get back up one module? We can either use leading colons to say
|
||||
that we want to start from the root and list the whole path:
|
||||
So how do we get back up one module in the module hierarchy to be able to call
|
||||
the `client::connect` function in the `tests` module? In the `tests` module, we
|
||||
can either use leading colons to let Rust know that we want to start from the
|
||||
root and list the whole path:
|
||||
|
||||
```rust,ignore
|
||||
::client::connect();
|
||||
```
|
||||
|
||||
Or we can use `super` to move up one module in the hierarchy:
|
||||
Or we can use `super` to move up one module in the hierarchy from our current
|
||||
module:
|
||||
|
||||
```rust,ignore
|
||||
super::client::connect();
|
||||
```
|
||||
|
||||
If we were deep in the module hierarchy, starting from the root every time
|
||||
would get long. Plus, if we rearrange our modules by moving a subtree to
|
||||
another place, there might be a lot of places the path would need to be updated
|
||||
if we always used the path from the root.
|
||||
These two options don’t look all that different in this example, but if you’re
|
||||
deeper in a module hierarchy, starting from the root every time would get long.
|
||||
In those cases, using `super` to get from the current module to sibling modules
|
||||
is a good shortcut. Plus, if you’ve specified the path from the root in many
|
||||
places in your code and then you rearrange your modules by moving a subtree to
|
||||
another place, you’d end up needing to update the path in a lot of places,
|
||||
which would be tedious.
|
||||
|
||||
It would also be annoying to have to type `super::` all the time in each test,
|
||||
but we now have a tool for that solution: `use`! `super::` is special and
|
||||
changes the path we give to `use` so that it is relative to the parent module
|
||||
instead of to the root module.
|
||||
but you’ve already seen the tool for that solution: `use`! The `super::`
|
||||
functionality changes the path you give to `use` so that it is relative to the
|
||||
parent module instead of to the root module.
|
||||
|
||||
For these reasons, in the `tests` module especially, `use super::something` is
|
||||
usually the way to go. So now our test looks like this:
|
||||
@ -867,6 +1045,11 @@ test tests::it_works ... ok
|
||||
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured
|
||||
```
|
||||
|
||||
## Summary
|
||||
|
||||
Now you know techniques for organizing your code! Use these to group related
|
||||
functionality together, keep files from getting too long, and present a tidy
|
||||
public API to users of your library.
|
||||
|
||||
Next, let’s look at some collection data structures in the standard library
|
||||
that you can make use of in your nice, neat code!
|
||||
|
||||
Loading…
Reference in New Issue
Block a user