## The Module System to Control Scope and Privacy

Rust has a feature that’s often referred to as “the module system,” but it
encompasses a few more features than modules. In this section, we’ll talk about:

* Modules, a way to organize code and control the privacy of paths
* Paths, a way to name items
* `use`, a keyword to bring a path into scope
* `pub`, a keyword to make items public
* Renaming items when bringing them into scope with the `as` keyword
* Using external packages
* Nested paths to clean up large `use` lists
* Using the glob operator to bring everything in a module into scope
* How to split modules into individual files

First up, modules. Modules let us organize code into groups. Listing 7-1 has an
example of some code that defines a module named `sound` that contains a
function named `guitar`.

<span class="filename">Filename: src/main.rs</span>

```rust
mod sound {
    fn guitar() {
        // Function body code goes here
    }
}

fn main() {

}
```

<span class="caption">Listing 7-1: A `sound` module containing a `guitar`
function and a `main` function</span>

We’ve defined two functions, `guitar` and `main`. We’ve defined the `guitar`
function within a `mod` block. This block defines a module named `sound`.

To organize code into a hierarchy of modules, you can nest modules inside of
other modules, as shown in Listing 7-2:

<span class="filename">Filename: src/main.rs</span>

```rust
mod sound {
    mod instrument {
        mod woodwind {
            fn clarinet() {
                // Function body code goes here
            }
        }
    }

    mod voice {

    }
}

fn main() {

}
```

<span class="caption">Listing 7-2: Modules inside modules</span>

In this example, we defined a `sound` module in the same way as we did in
Listing 7-1. We then defined two modules within the `sound` module named
`instrument` and `voice`. The `instrument` module has another module defined
within it, `woodwind`, and that module contains a function named `clarinet`.

We mentioned in the [“Packages and Crates for Making Libraries and
Executables”][packages]<!-- ignore --> section that *src/main.rs* and
*src/lib.rs* are called *crate roots*. They are called crate roots because the
contents of either of these two files form a module named `crate` at the root
of the crate’s module tree. So in Listing 7-2, we have a module tree that looks
like Listing 7-3:

```text
crate
└── sound
    ├── instrument
    │   └── woodwind
    └── voice
```

<span class="caption">Listing 7-3: The module tree for the code in Listing
7-2</span>

This tree shows how some of the modules nest inside one another (such as
`woodwind` nests inside `instrument`) and how some modules are siblings to
each other (`instrument` and `voice` are both defined within `sound`). The
entire module tree is rooted under the implicit module named `crate`.

This tree might remind you of the directory tree of the filesystem you have on
your computer; this is a very apt comparison! Just like directories in a
filesystem, you place code inside whichever module will create the organization
you’d like. Another similarity is that to refer to an item in a filesystem or a
module tree, you use its *path*.

### Paths for Referring to an Item in the Module Tree

If we want to call a function, we need to know its *path*. “Path” is a synonym
for “name” in a way, but it evokes that filesystem metaphor. Additionally,
functions, structs, and other items may have multiple paths that refer to the
same item, so “name” isn’t quite the right concept.

A *path* can take two forms:

* An *absolute path* starts from a crate root by using a crate name or a
  literal `crate`.
* A *relative path* starts from the current module and uses `self`, `super`, or
  an identifier in the current module.

Both absolute and relative paths are followed by one or more identifiers
separated by double colons (`::`).

How do we call the `clarinet` function in the `main` function in Listing 7-2?
That is, what’s the path of the `clarinet` function? In Listing 7-4, let’s
simplify our code a bit by removing some of the modules, and we’ll show two
ways to call the `clarinet` function from `main`. This example won’t compile
just yet, we’ll explain why in a bit.

<span class="filename">Filename: src/main.rs</span>

```rust,ignore,does_not_compile
mod sound {
    mod instrument {
        fn clarinet() {
            // Function body code goes here
        }
    }
}

fn main() {
    // Absolute path
    crate::sound::instrument::clarinet();

    // Relative path
    sound::instrument::clarinet();
}
```

<span class="caption">Listing 7-4: Calling the `clarinet` function in a
simplified module tree from the `main` function using absolute and relative
paths</span>

The first way we’re calling the `clarinet` function from the `main` function
uses an absolute path. Because `clarinet` is defined within the same crate as
`main`, we use the `crate` keyword to start an absolute path. Then we include
each of the modules until we make our way to `clarinet`. This is similar to
specifying the path `/sound/instrument/clarinet` to run the program at that
location on your computer; using the `crate` name to start from the crate root
is like using `/` to start from the filesystem root in your shell.

The second way we’re calling the `clarinet` function from the `main` function
uses a relative path. The path starts with the name `sound`, a module defined
at the same level of the module tree as the `main` function. This is similar to
specifying the path `sound/instrument/clarinet` to run the program at that
location on your computer; starting with a name means that the path is relative.

We mentioned that Listing 7-4 won’t compile yet, let’s try to compile it and
find out why not! The error we get is shown in Listing 7-5.

```text
$ cargo build
   Compiling sampleproject v0.1.0 (file:///projects/sampleproject)
error[E0603]: module `instrument` is private
  --> src/main.rs:11:19
   |
11 |     crate::sound::instrument::clarinet();
   |                   ^^^^^^^^^^

error[E0603]: module `instrument` is private
  --> src/main.rs:14:12
   |
14 |     sound::instrument::clarinet();
   |            ^^^^^^^^^^
```

<span class="caption">Listing 7-5: Compiler errors from building the code in
Listing 7-4</span>

The error messages say that module `instrument` is private. We can see that we
have the correct paths for the `instrument` module and the `clarinet` function,
but Rust won’t let us use them because they’re private. It’s time to learn
about the `pub` keyword!

### Modules as the Privacy Boundary

Earlier, we talked about the syntax of modules and that they can be used for
organization. There’s another reason Rust has modules: modules are the *privacy
boundary* in Rust. If you want to make an item like a function or struct
private, you put it in a module. Here are the privacy rules:

* All items (functions, methods, structs, enums, modules, and constants) are
  private by default.
* You can use the `pub` keyword to make an item public.
* You aren’t allowed to use private code defined in modules that are children
  of the current module.
* You are allowed to use any code defined in ancestor modules or the current
  module.

In other words, items without the `pub` keyword are private as you look “down”
the module tree from the current module, but items without the `pub` keyword
are public as you look “up” the tree from the current module. Again, think of a
filesystem: if you don’t have permissions to a directory, you can’t look into
it from its parent directory. If you do have permissions to a directory, you
can look inside it and any of its ancestor directories.

### Using the `pub` Keyword to Make Items Public

The error in Listing 7-5 said the `instrument` module is private. Let’s mark
the `instrument` module with the `pub` keyword so that we can use it from the
`main` function. This change is shown in Listing 7-6, which still won’t
compile, but we’ll get a different error:

<span class="filename">Filename: src/main.rs</span>

```rust,ignore,does_not_compile
mod sound {
    pub mod instrument {
        fn clarinet() {
            // Function body code goes here
        }
    }
}

fn main() {
    // Absolute path
    crate::sound::instrument::clarinet();

    // Relative path
    sound::instrument::clarinet();
}
```

<span class="caption">Listing 7-6: Declaring the `instrument` module as `pub`
so that we’re allowed to use it from `main`</span>

Adding the `pub` keyword in front of `mod instrument` makes the module public.
With this change, if we’re allowed to access `sound`, we can access
`instrument`. The contents of `instrument` are still private; making the module
public does not make its contents public. The `pub` keyword on a module lets
code in its parent module refer to it.

The code in Listing 7-6 still results in an error, though, as shown in Listing
7-7:

```text
$ cargo build
   Compiling sampleproject v0.1.0 (file:///projects/sampleproject)
error[E0603]: function `clarinet` is private
  --> src/main.rs:11:31
   |
11 |     crate::sound::instrument::clarinet();
   |                               ^^^^^^^^

error[E0603]: function `clarinet` is private
  --> src/main.rs:14:24
   |
14 |     sound::instrument::clarinet();
   |                        ^^^^^^^^
```

<span class="caption">Listing 7-7: Compiler errors from building the code in
Listing 7-6</span>

The errors now say that the `clarinet` function is private. The privacy rules
apply to structs, enums, functions, and methods as well as modules.

Let’s make the `clarinet` function public as well by adding the `pub` keyword
before its definition, as shown in Listing 7-8:

<span class="filename">Filename: src/main.rs</span>

```rust
mod sound {
    pub mod instrument {
        pub fn clarinet() {
            // Function body code goes here
        }
    }
}

fn main() {
    // Absolute path
    crate::sound::instrument::clarinet();

    // Relative path
    sound::instrument::clarinet();
}
```

<span class="caption">Listing 7-8: Adding the `pub` keyword to both `mod
instrument` and `fn clarinet` lets us call the function from `main`</span>

This will now compile! Let’s look at both the absolute and the relative path
and double check why adding the `pub` keyword lets us use these paths in `main`.

In the absolute path case, we start with `crate`, the root of our crate. From
there, we have `sound`, and it is a module that is defined in the crate root.
The `sound` module isn’t public, but because the `main` function is defined in
the same module that `sound` is defined, we’re allowed to refer to `sound` from
`main`. Next is `instrument`, which is a module marked with `pub`. We can
access the parent module of `instrument`, so we’re allowed to access
`instrument`. Finally, `clarinet` is a function marked with `pub` and we can
access its parent module, so this function call works!

In the relative path case, the logic is the same as the absolute path except
for the first step. Rather than starting from the crate root, the path starts
from `sound`. The `sound` module is defined within the same module as `main`
is, so the relative path starting from the module in which `main` is defined
works. Then because `instrument` and `clarinet` are marked with `pub`, the rest
of the path works and this function call is valid as well!

### Starting Relative Paths with `super`

You can also construct relative paths beginning with `super`. Doing so is like
starting a filesystem path with `..`: the path starts from the *parent* module,
rather than the current module. This is useful in situations such as the
example in Listing 7-9, where the function `clarinet` calls the function
`breathe_in` by specifying its path to start with `super`:

<span class="filename">Filename: src/lib.rs</span>

```rust
# fn main() {}
#
mod instrument {
    fn clarinet() {
        super::breathe_in();
    }
}

fn breathe_in() {
    // Function body code goes here
}
```

<span class="caption">Listing 7-9: Calling a function using a relative path
starting with `super` to look in the parent module</span>

The `clarinet` function is in the `instrument` module, so we can use `super` to
go to the parent module of `instrument`, which in this case is `crate`, the
root. From there, we look for `breathe_in`, and find it. Success!

The reason you might want to choose a relative path starting with `super`
rather than an absolute path starting with `crate` is that using `super` may
make it easier to update your code to have a different module hierarchy, if the
code defining the item and the code calling the item are moved together. For
example, if we decide to put the `instrument` module and the `breathe_in`
function into a module named `sound`, we would only need to add the `sound`
module, as shown in Listing 7-10.

<span class="filename">Filename: src/lib.rs</span>

```rust
mod sound {
    mod instrument {
        fn clarinet() {
            super::breathe_in();
        }
    }

    fn breathe_in() {
        // Function body code goes here
    }
}
```

<span class="caption">Listing 7-10: Adding a parent module named `sound`
doesn’t affect the relative path `super::breathe_in`</span>

The call to `super::breathe_in` from the `clarinet` function will continue to
work in Listing 7-10 as it did in Listing 7-9, without needing to update the
path. If instead of `super::breathe_in` we had used `crate::breathe_in` in the
`clarinet` function, when we add the parent `sound` module, we would need to
update the `clarinet` function to use the path `crate::sound::breathe_in`
instead. Using a relative path can mean fewer updates are necessary when
rearranging modules.

### Using `pub` with Structs and Enums

You can designate structs and enums to be public in a similar way as we’ve
shown with modules and functions, with a few additional details.

If you use `pub` before a struct definition, you make the struct public.
However, the struct’s fields are still private. You can choose to make each
field public or not on a case-by-case basis. In Listing 7-11, we’ve defined a
public `plant::Vegetable` struct with a public `name` field but a private `id`
field.

<span class="filename">Filename: src/main.rs</span>

```rust
mod plant {
    pub struct Vegetable {
        pub name: String,
        id: i32,
    }

    impl Vegetable {
        pub fn new(name: &str) -> Vegetable {
            Vegetable {
                name: String::from(name),
                id: 1,
            }
        }
    }
}

fn main() {
    let mut v = plant::Vegetable::new("squash");

    v.name = String::from("butternut squash");
    println!("{} are delicious", v.name);

    // The next line won't compile if we uncomment it:
    // println!("The ID is {}", v.id);
}
```

<span class="caption">Listing 7-11: A struct with some public fields and some
private fields</span>

Because the `name` field of the `plant::Vegetable` struct is public, in `main`
we can write and read to the `name` field by using dot notation. We’re not
allowed to use the `id` field in `main` because it’s private. Try uncommenting
the line printing the `id` field value to see what error you get! Also note
that because `plant::Vegetable` has a private field, the struct needs to
provide a public associated function that constructs an instance of `Vegetable`
(we’ve used the conventional name `new` here). If `Vegetable` didn’t have such
a function, we wouldn’t be able to create an instance of `Vegetable` in `main`
because we’re not allowed to set the value of the private `id` field in `main`.

In contrast, if you make a public enum, all of its variants are public. You
only need the `pub` before the `enum` keyword, as shown in Listing 7-12.

<span class="filename">Filename: src/main.rs</span>

```rust
mod menu {
    pub enum Appetizer {
        Soup,
        Salad,
    }
}

fn main() {
    let order1 = menu::Appetizer::Soup;
    let order2 = menu::Appetizer::Salad;
}
```

<span class="caption">Listing 7-12: Designating an enum as public makes all its
variants public</span>

Because we made the `Appetizer` enum public, we’re able to use the `Soup` and
`Salad` variants in `main`.

There’s one more situation involving `pub` that we haven’t covered, and that’s
with our last module system feature: the `use` keyword. Let’s cover `use` by
itself, and then we’ll show how `pub` and `use` can be combined.

### The `use` Keyword to Bring Paths into a Scope

You may have been thinking that many of the paths we’ve written to call
functions in the listings in this chapter are long and repetitive. For example,
in Listing 7-8, whether we chose the absolute or relative path to the
`clarinet` function, every time we wanted to call `clarinet` we had to specify
`sound` and `instrument` too. Luckily, there’s a way to bring a path into a
scope once and then call the items in that path as if they’re local items: with
the `use` keyword. In Listing 7-13, we bring the `crate::sound::instrument`
module into the scope of the `main` function so that we only have to specify
`instrument::clarinet` to call the `clarinet` function in `main`.

<span class="filename">Filename: src/main.rs</span>

```rust
mod sound {
    pub mod instrument {
        pub fn clarinet() {
            // Function body code goes here
        }
    }
}

use crate::sound::instrument;

fn main() {
    instrument::clarinet();
    instrument::clarinet();
    instrument::clarinet();
}
```

<span class="caption">Listing 7-13: Bringing a module into scope with `use` and
an absolute path to shorten the path we have to specify to call an item within
that module</span>

Adding `use` and a path in a scope is similar to creating a symbolic link in
the filesystem. By adding `use crate::sound::instrument` in the crate root,
`instrument` is now a valid name in that scope as if the `instrument` module
had been defined in the crate root. We can now reach items in the `instrument`
module through the older, full paths, or we can reach items through the new,
shorter path that we’ve created with `use`. Paths brought into scope with `use`
also check privacy, like any other paths.

If you want to bring an item into scope with `use` and a relative path, there’s
a small difference from directly calling the item using a relative path:
instead of starting from a name in the current scope, you must start the path
given to `use` with `self`. Listing 7-14 shows how to specify a relative path
to get the same behavior as Listing 7-13 that used an absolute path.

<span class="filename">Filename: src/main.rs</span>

```rust
mod sound {
    pub mod instrument {
        pub fn clarinet() {
            // Function body code goes here
        }
    }
}

use self::sound::instrument;

fn main() {
    instrument::clarinet();
    instrument::clarinet();
    instrument::clarinet();
}
```

<span class="caption">Listing 7-14: Bringing a module into scope with `use` and
a relative path starting with `self`</span>

Starting relative paths with `self` when specified after `use` might not be
necessary in the future; it’s an inconsistency in the language that people are
working on eliminating.

Choosing to specify absolute paths with `use` can make updates easier if the
code calling the items moves to a different place in the module tree but the
code defining the items does not, as opposed to when they moved together in the
changes we made in Listing 7-10. For example, if we decide to take the code
from Listing 7-13, extract the behavior in the `main` function to a function
called `clarinet_trio`, and move that function into a module named
`performance_group`, the path specified in `use` wouldn’t need to change, as
shown in Listing 7-15.

<span class="filename">Filename: src/main.rs</span>

```rust
mod sound {
    pub mod instrument {
        pub fn clarinet() {
            // Function body code goes here
        }
    }
}

mod performance_group {
    use crate::sound::instrument;

    pub fn clarinet_trio() {
        instrument::clarinet();
        instrument::clarinet();
        instrument::clarinet();
    }
}

fn main() {
    performance_group::clarinet_trio();
}
```

<span class="caption">Listing 7-15: The absolute path doesn’t need to be
updated when moving the code that calls the item</span>

In contrast, if we made the same change to the code in Listing 7-14 that
specifies a relative path, we would need to change `use
self::sound::instrument` to `use super::sound::instrument`. Choosing whether
relative or absolute paths will result in fewer updates can be a guess if
you’re not sure how your module tree will change in the future, but your
authors tend to specify absolute paths starting with `crate` because code
defining and calling items is more likely to be moved around the module tree
independently of each other, rather than together as we saw in Listing 7-10.

### Idiomatic `use` Paths for Functions vs. Other Items

In Listing 7-13, you may have wondered why we specified `use
crate::sound::instrument` and then called `instrument::clarinet` in `main`,
rather than the code shown in Listing 7-16 that has the same behavior:

<span class="filename">Filename: src/main.rs</span>

```rust
mod sound {
    pub mod instrument {
        pub fn clarinet() {
            // Function body code goes here
        }
    }
}

use crate::sound::instrument::clarinet;

fn main() {
    clarinet();
    clarinet();
    clarinet();
}
```

<span class="caption">Listing 7-16: Bringing the `clarinet` function into
scope with `use`, which is unidiomatic</span>

For functions, it’s considered idiomatic to specify the function’s parent
module with `use`, and then specify the parent module when calling the
function. Doing so rather than specifying the path to the function with `use`,
as Listing 7-16 does, makes it clear that the function isn’t locally defined,
while still minimizing repetition of the full path.

For structs, enums, and other items, specifying the full path to the item with
`use` is idiomatic. For example, Listing 7-17 shows the idiomatic way to bring
the standard library’s `HashMap` struct into scope.

<span class="filename">Filename: src/main.rs</span>

```rust
use std::collections::HashMap;

fn main() {
    let mut map = HashMap::new();
    map.insert(1, 2);
}
```

<span class="caption">Listing 7-17: Bringing `HashMap` into scope in an
idiomatic way</span>

In contrast, the code in Listing 7-18 that brings the parent module of
`HashMap` into scope would not be considered idiomatic. There’s not a strong
reason for this idiom; this is the convention that has emerged and folks have
gotten used to reading and writing.

<span class="filename">Filename: src/main.rs</span>

```rust
use std::collections;

fn main() {
    let mut map = collections::HashMap::new();
    map.insert(1, 2);
}
```

<span class="caption">Listing 7-18: Bringing `HashMap` into scope in an
unidiomatic way</span>

The exception to this idiom is if the `use` statements would bring two items
with the same name into scope, which isn’t allowed. Listing 7-19 shows how to
bring two `Result` types that have different parent modules into scope and
refer to them.

<span class="filename">Filename: src/lib.rs</span>

```rust
use std::fmt;
use std::io;

fn function1() -> fmt::Result {
#     Ok(())
}

fn function2() -> io::Result<()> {
#     Ok(())
}
```

<span class="caption">Listing 7-19: Bringing two types with the same name into
the same scope requires using their parent modules</span>

If instead we specified `use std::fmt::Result` and `use std::io::Result`, we’d
have two `Result` types in the same scope and Rust wouldn’t know which one we
meant when we used `Result`. Try it and see what compiler error you get!

### Renaming Types Brought Into Scope with the `as` Keyword

There’s another solution to the problem of bringing two types of the same name
into the same scope: we can specify a new local name for the type by adding
`as` and a new name after the `use`. Listing 7-20 shows another way to write
the code from Listing 7-19 by renaming one of the two `Result` types using `as`.

<span class="filename">Filename: src/lib.rs</span>

```rust
use std::fmt::Result;
use std::io::Result as IoResult;

fn function1() -> Result {
#     Ok(())
}
fn function2() -> IoResult<()> {
#     Ok(())
}
```

<span class="caption">Listing 7-20: Renaming a type when it’s brought into
scope with the `as` keyword</span>

In the second `use` statement, we chose the new name `IoResult` for the
`std::io::Result` type, which won’t conflict with the `Result` from `std::fmt`
that we’ve also brought into scope. This is also considered idiomatic; choosing
between the code in Listing 7-19 and Listing 7-20 is up to you.

### Re-exporting Names with `pub use`

When you bring a name into scope with the `use` keyword, the name being
available in the new scope is private. If you want to enable code calling your
code to be able to refer to the type as if it was defined in that scope just as
your code does, you can combine `pub` and `use`. This technique is called
*re-exporting* because you’re bringing an item into scope but also making that
item available for others to bring into their scope.

For example, Listing 7-21 shows the code from Listing 7-15 with the `use`
within the `performance_group` module changed to `pub use`.

<span class="filename">Filename: src/main.rs</span>

```rust
mod sound {
    pub mod instrument {
        pub fn clarinet() {
            // Function body code goes here
        }
    }
}

mod performance_group {
    pub use crate::sound::instrument;

    pub fn clarinet_trio() {
        instrument::clarinet();
        instrument::clarinet();
        instrument::clarinet();
    }
}

fn main() {
    performance_group::clarinet_trio();
    performance_group::instrument::clarinet();
}
```

<span class="caption">Listing 7-21: Making a name available for any code to use
from a new scope with `pub use`</span>

By using `pub use`, the `main` function can now call the `clarinet` function
through this new path with `performance_group::instrument::clarinet`. If we
hadn’t specified `pub use`, the `clarinet_trio` function can call
`instrument::clarinet` in its scope but `main` wouldn’t be allowed to take
advantage of this new path.

### Using External Packages

In Chapter 2, we programmed a guessing game. That project used an external
package, `rand`, to get random numbers. To use `rand` in our project, we added
this line to *Cargo.toml*:

<span class="filename">Filename: Cargo.toml</span>

```toml
[dependencies]
rand = "0.5.5"
```

Adding `rand` as a dependency in *Cargo.toml* tells Cargo to download the
`rand` package and its dependencies from *https://crates.io* and make its code
available to our project.

Then, to bring `rand` definitions into the scope of our package, we added a
`use` line starting with the name of the package, `rand`, and listing the items
we wanted to bring into scope. Recall that in the [“Generating a Random
Number”][rand]<!-- ignore --> section in Chapter 2, we brought the `Rng` trait
into scope and called the `rand::thread_rng` function:

```rust,ignore
use rand::Rng;

fn main() {
    let secret_number = rand::thread_rng().gen_range(1, 101);
}
```

There are many packages that members of the community have published on
*https://crates.io*, and pulling any of them into your package involves these
same steps: listing them in your package’s *Cargo.toml* and bringing items
defined in them into a scope in your package with `use`.

Note that the standard library (`std`) is also a crate that’s external to your
package. Because the standard library is shipped with the Rust language, you
don’t need to change *Cargo.toml* to include `std`, but you refer to it in
`use` to bring items the standard library defines into your package’s scope,
such as with `HashMap`:

```rust
use std::collections::HashMap;
```

This is an absolute path starting with `std`, the name of the standard library
crate.

### Nested Paths for Cleaning Up Large `use` Lists

When you use many items defined by the same package or in the same module,
listing each item on its own line can take up a lot of vertical space in your
files. For example, these two `use` statements we had in Listing 2-4 in the
Guessing Game both bring items from `std` into scope:

<span class="filename">Filename: src/main.rs</span>

```rust
use std::cmp::Ordering;
use std::io;
// ---snip---
```

We can use nested paths to bring the same items into scope in one line instead
of two, by specifying the common part of the path, then two colons, then curly
brackets around a list of the parts of the paths that differ, as shown in
Listing 7-22.

<span class="filename">Filename: src/main.rs</span>

```rust
use std::{cmp::Ordering, io};
// ---snip---
```

<span class="caption">Listing 7-22: Specifying a nested path to bring multiple
items with the same prefix into scope in one line instead of two</span>

In programs bringing many items into scope from the same package or module,
using nested paths can reduce the number of separate `use` statements needed by
a lot!

We can also deduplicate paths where one path is completely shared with part of
another path. For example, Listing 7-23 shows two `use` statements: one that
brings `std::io` into scope, and one that brings `std::io::Write` into scope:

<span class="filename">Filename: src/lib.rs</span>

```rust
use std::io;
use std::io::Write;
```

<span class="caption">Listing 7-23: Bringing two paths into scope in two `use`
statements where one is a sub-path of the other</span>

The common part between these two paths is `std::io`, and that’s the complete
first path. To deduplicate these two paths into one `use` statement, we can use
`self` in the nested path as shown in Listing 7-24.

<span class="filename">Filename: src/lib.rs</span>

```rust
use std::io::{self, Write};
```

<span class="caption">Listing 7-24: Deduplicating the paths from Listing 7-23
into one `use` statement</span>

This brings both `std::io` and `std::io::Write` into scope.

### Bringing All Public Definitions into Scope with the Glob Operator

If you’d like to bring *all* public items defined in a path into scope, you can
specify that path followed by `*`, the glob operator:

```rust
use std::collections::*;
```

This `use` statements brings all public items defined in `std::collections`
into the current scope.

Be careful with using the glob operator! It makes it harder to tell what names
are in scope and where a name your program uses was defined.

The glob operator is often used when testing to bring everything under test
into the `tests` module; we’ll talk about that in the [“How to Write
Tests”][writing-tests]<!-- ignore --> section of Chapter 11. The glob operator
is also sometimes used as part of the prelude pattern; see [the standard
library documentation](../std/prelude/index.html#other-preludes)<!-- ignore -->
for more information on that pattern.

### Separating Modules into Different Files

All of the examples in this chapter so far defined multiple modules in one
file. When modules get large, you may want to move their definitions to a
separate file to make the code easier to navigate.

For example, if we started from the code in Listing 7-8, we can move the
`sound` module to its own file *src/sound.rs* by changing the crate root file
(in this case, *src/main.rs*) to contain the code shown in Listing 7-25.

<span class="filename">Filename: src/main.rs</span>

```rust,ignore
mod sound;

fn main() {
    // Absolute path
    crate::sound::instrument::clarinet();

    // Relative path
    sound::instrument::clarinet();
}
```

<span class="caption">Listing 7-25: Declaring the `sound` module whose body
will be in *src/sound.rs*</span>

And *src/sound.rs* gets the definitions from the body of the `sound` module,
shown in Listing 7-26.

<span class="filename">Filename: src/sound.rs</span>

```rust
pub mod instrument {
    pub fn clarinet() {
        // Function body code goes here
    }
}
```

<span class="caption">Listing 7-26: Definitions inside the `sound` module in
*src/sound.rs*</span>

Using a semicolon after `mod sound` instead of a block tells Rust to load the
contents of the module from another file with the same name as the module.

To continue with our example and extract the `instrument` module to its own
file as well, we change *src/sound.rs* to contain only the declaration of the
`instrument` module:

<span class="filename">Filename: src/sound.rs</span>

```rust
pub mod instrument;
```

Then we create a *src/sound* directory and a file *src/sound/instrument.rs* to
contain the definitions made in the `instrument` module:

<span class="filename">Filename: src/sound/instrument.rs</span>

```rust
pub fn clarinet() {
    // Function body code goes here
}
```

The module tree remains the same and the function calls in `main` continue to
work without any modification, even though the definitions live in different
files. This lets you move modules to new files as they grow in size.

## Summary

Rust provides ways to organize your packages into crates, your crates into
modules, and to refer to items defined in one module from another by specifying
absolute or relative paths. These paths can be brought into a scope with a
`use` statement so that you can use a shorter path for multiple uses of the
item in that scope. Modules define code that’s private by default, but you can
choose to make definitions public by adding the `pub` keyword.

Next, we’ll look at some collection data structures in the standard library
that you can use in your nice, neat code.

[packages]: ch07-01-packages-and-crates-for-making-libraries-and-executables.html#packages-and-crates-for-making-libraries-and-executables
[rand]: ch02-00-guessing-game-tutorial.html#generating-a-random-number
[writing-tests]: ch11-01-writing-tests.html#how-to-write-tests
