github_mirrors/rust-book-cn
1
0
Fork 0
mirror of https://github.com/rust-lang-cn/book-cn.git synced 2025-01-23 23:50:25 +08:00
Code Issues Packages Projects Releases Wiki Activity

Edits as a result of nostarch comments

Browse Source
This commit is contained in:
Carol (Nichols || Goulding) 2016-11-02 14:31:56 -04:00
parent fe2935312a
commit e05538b247
4 changed files with 384 additions and 212 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
src/ch07-00-modules.md
View File

@ -1,22 +1,23 @@
# 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.

278
src/ch07-01-mod-and-the-filesystem.md
View File

@ -1,22 +1,24 @@
## `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
@ -29,14 +31,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
@ -47,14 +60,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
@ -70,10 +85,20 @@ 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
@ -89,11 +114,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
@ -101,7 +135,7 @@ communicator
└── client
```
And here's the second:
And here's the example from Listing 7-2:
```text
communicator
@ -109,13 +143,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
@ -136,8 +177,25 @@ 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
@ -155,9 +213,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
@ -166,13 +232,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
@ -197,11 +269,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:
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
@ -211,7 +285,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
@ -225,10 +299,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
@ -239,7 +318,7 @@ 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
@ -248,7 +327,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
@ -271,35 +350,39 @@ 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
@ -308,7 +391,7 @@ communicator
└── server
```
And the corresponding file layout looks like this:
The corresponding file layout now looks like this:
```text
├── src
@ -319,10 +402,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

174
src/ch07-02-controlling-visibility-with-pub.md
View File

@ -1,11 +1,10 @@
## 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() {
| ^
@ -23,13 +22,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
@ -41,22 +43,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
|
@ -64,19 +63,28 @@ 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
@ -89,8 +97,6 @@ mod network;
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
@ -101,7 +107,7 @@ 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:
edit `src/client.rs` to make `client::connect` public too:
Filename: src/client.rs
@ -113,8 +119,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
|
@ -128,18 +132,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
@ -153,8 +157,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
|
@ -168,11 +170,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
@ -185,8 +188,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
|
@ -194,19 +195,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
@ -231,37 +234,42 @@ 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.)

117
src/ch07-03-importing-names-with-use.md
View File

@ -1,7 +1,8 @@
## 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
@ -19,9 +20,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
@ -41,10 +52,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 {
@ -62,10 +79,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 {
@ -79,13 +99,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 {
@ -109,8 +130,9 @@ 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
@ -127,12 +149,22 @@ 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:
@ -166,35 +198,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:
@ -227,6 +265,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!