rust
/
book
mirror of https://github.com/rust-lang/book
1
0
Fork 0
Code Issues Releases Wiki Activity

Merge pull request #1608 from rust-lang/appendices 

Appendices
This commit is contained in:
Carol (Nichols || Goulding) 2018-11-02 13:41:07 -04:00 committed by GitHub
parent f5e224348e 363216c9c9
commit 4c8180c9f5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
15 changed files with 268 additions and 679 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

0
2018-edition/convert-quotes.sh Normal file → Executable file
View File

9
2018-edition/src/SUMMARY.md
View File

@ -126,8 +126,7 @@
- [A - Keywords](appendix-01-keywords.md)
- [B - Operators and Symbols](appendix-02-operators.md)
- [C - Derivable Traits](appendix-03-derivable-traits.md)
- [D - Macros](appendix-04-macros.md)
- [E - Translations](appendix-05-translation.md)
- [F - How Rust is Made and “Nightly Rust”](appendix-06-nightly-rust.md)
- [G - Other useful tools](appendix-07-other-useful-tools.md)
- [H - Editions](appendix-08-editions.md)
- [D - Useful Development Tools](appendix-04-useful-development-tools.md)
- [E - Editions](appendix-05-editions.md)
- [F - Translations](appendix-06-translation.md)
- [G - How Rust is Made and “Nightly Rust”](appendix-07-nightly-rust.md)

4
2018-edition/src/appendix-01-keywords.md
View File

@ -84,7 +84,7 @@ fn match(needle: &str, haystack: &str) -> bool {
}
```
You'll get this error:
You’ll get this error:
```text
error: expected identifier, found keyword `match`
@ -113,5 +113,5 @@ Note the `r#` prefix on both the function name as well as the call.
This feature is useful for a few reasons, but the primary motivation was
inter-edition situations. For example, `try` is not a keyword in the 2015
edition, but is in the 2018 edition. So if you have a library that is written
in Rust 2015 and has a `try` function, to call it in Rust 2018, you'll need
in Rust 2015 and has a `try` function, to call it in Rust 2018, you’ll need
to use the raw identifier.

3
2018-edition/src/appendix-03-derivable-traits.md
View File

@ -33,7 +33,8 @@ it can’t provide appropriate default behavior for you.
The list of derivable traits provided in this appendix is not comprehensive:
libraries can implement `derive` for their own traits, making the list of
traits you can use `derive` with truly open-ended. Implementing `derive`
involves using a procedural macro, which is covered in Appendix D.
involves using a procedural macro, which is covered in the “Macros” section of
Chapter 19.
### `Debug` for Programmer Output

478
2018-edition/src/appendix-04-macros.md
View File

@ -1,478 +0,0 @@
## Appendix D: Macros
We’ve used macros like `println!` throughout this book but haven’t fully
explored what a macro is and how it works. This appendix explains macros as
follows:
* What macros are and how they differ from functions
* How to define a declarative macro to do metaprogramming
* How to define a procedural macro to create custom `derive` traits
We’re covering the details of macros in an appendix because they’re still
evolving in Rust. Macros have changed and, in the near future, will change at a
quicker rate than the rest of the language and standard library since Rust 1.0,
so this section is more likely to become out-of-date than the rest of the book.
Due to Rust’s stability guarantees, the code shown here will continue to work
with future versions, but there may be additional capabilities or easier ways
to write macros that weren’t available at the time of this publication. Bear
that in mind when you try to implement anything from this appendix.
### The Difference Between Macros and Functions
Fundamentally, macros are a way of writing code that writes other code, which
is known as *metaprogramming*. In Appendix C, we discussed the `derive`
attribute, which generates an implementation of various traits for you. We’ve
also used the `println!` and `vec!` macros throughout the book. All of these
macros *expand* to produce more code than the code you’ve written manually.
Metaprogramming is useful for reducing the amount of code you have to write and
maintain, which is also one of the roles of functions. However, macros have
some additional powers that functions don’t have.
A function signature must declare the number and type of parameters the
function has. Macros, on the other hand, can take a variable number of
parameters: we can call `println!("hello")` with one argument or
`println!("hello {}", name)` with two arguments. Also, macros are expanded
before the compiler interprets the meaning of the code, so a macro can, for
example, implement a trait on a given type. A function can’t, because it gets
called at runtime and a trait needs to be implemented at compile time.
The downside to implementing a macro instead of a function is that macro
definitions are more complex than function definitions because you’re writing
Rust code that writes Rust code. Due to this indirection, macro definitions are
generally more difficult to read, understand, and maintain than function
definitions.
Another difference between macros and functions is that macro definitions
aren’t namespaced within modules like function definitions are. To prevent
unexpected name clashes when using external crates, you have to explicitly
bring the macros into the scope of your project at the same time as you bring
the external crate into scope, using the `#[macro_use]` annotation. The
following example would bring all the macros defined in the `serde` crate into
the scope of the current crate:
```rust,ignore
#[macro_use]
extern crate serde;
```
If `extern crate` was able to bring macros into scope by default without this
explicit annotation, you would be prevented from using two crates that happened
to define macros with the same name. In practice, this conflict doesn’t occur
often, but the more crates you use, the more likely it is.
There is one last important difference between macros and functions: you must
define or bring macros into scope *before* you call them in a file, whereas you
can define functions anywhere and call them anywhere.
### Declarative Macros with `macro_rules!` for General Metaprogramming
The most widely used form of macros in Rust are *declarative macros*. These are
also sometimes referred to as *macros by example*, *`macro_rules!` macros*, or
just plain *macros*. At their core, declarative macros allow you to write
something similar to a Rust `match` expression. As discussed in Chapter 6,
`match` expressions are control structures that take an expression, compare the
resulting value of the expression to patterns, and then run the code associated
with the matching pattern. Macros also compare a value to patterns that have
code associated with them; in this situation, the value is the literal Rust
source code passed to the macro, the patterns are compared with the structure
of that source code, and the code associated with each pattern is the code that
replaces the code passed to the macro. This all happens during compilation.
To define a macro, you use the `macro_rules!` construct. Let’s explore how to
use `macro_rules!` by looking at how the `vec!` macro is defined. Chapter 8
covered how we can use the `vec!` macro to create a new vector with particular
values. For example, the following macro creates a new vector with three
integers inside:
```rust
let v: Vec<u32> = vec![1, 2, 3];
```
We could also use the `vec!` macro to make a vector of two integers or a vector
of five string slices. We wouldn’t be able to use a function to do the same
because we wouldn’t know the number or type of values up front.
Let’s look at a slightly simplified definition of the `vec!` macro in Listing
D-1.
```rust
#[macro_export]
macro_rules! vec {
( $( $x:expr ),* ) => {
{
let mut temp_vec = Vec::new();
$(
temp_vec.push($x);
)*
temp_vec
}
};
}
```
<span class="caption">Listing D-1: A simplified version of the `vec!` macro
definition</span>
> Note: The actual definition of the `vec!` macro in the standard library
> includes code to preallocate the correct amount of memory up front. That code
> is an optimization that we don’t include here to make the example simpler.
The `#[macro_export]` annotation indicates that this macro should be made
available whenever the crate in which we’re defining the macro is imported.
Without this annotation, even if someone depending on this crate uses the
`#[macro_use]` annotation, the macro wouldn’t be brought into scope.
We then start the macro definition with `macro_rules!` and the name of the
macro we’re defining *without* the exclamation mark. The name, in this case
`vec`, is followed by curly brackets denoting the body of the macro definition.
The structure in the `vec!` body is similar to the structure of a `match`
expression. Here we have one arm with the pattern `( $( $x:expr ),* )`,
followed by `=>` and the block of code associated with this pattern. If the
pattern matches, the associated block of code will be emitted. Given that this
is the only pattern in this macro, there is only one valid way to match; any
other will be an error. More complex macros will have more than one arm.
Valid pattern syntax in macro definitions is different than the pattern syntax
covered in Chapter 18 because macro patterns are matched against Rust code
structure rather than values. Let’s walk through what the pieces of the pattern
in Listing D-1 mean; for the full macro pattern syntax, see [the reference].
[the reference]: ../../reference/macros.html
First, a set of parentheses encompasses the whole pattern. Next comes a dollar
sign (`$`) followed by a set of parentheses, which captures values that match
the pattern within the parentheses for use in the replacement code. Within
`$()` is `$x:expr`, which matches any Rust expression and gives the expression
the name `$x`.
The comma following `$()` indicates that a literal comma separator character
could optionally appear after the code that matches the code captured in `$()`.
The `*` following the comma specifies that the pattern matches zero or more of
whatever precedes the `*`.
When we call this macro with `vec![1, 2, 3];`, the `$x` pattern matches three
times with the three expressions `1`, `2`, and `3`.
Now let’s look at the pattern in the body of the code associated with this arm:
the `temp_vec.push()` code within the `$()*` part is generated for each part
that matches `$()` in the pattern, zero or more times depending on how many
times the pattern matches. The `$x` is replaced with each expression matched.
When we call this macro with `vec![1, 2, 3];`, the code generated that replaces
this macro call will be the following:
```rust,ignore
let mut temp_vec = Vec::new();
temp_vec.push(1);
temp_vec.push(2);
temp_vec.push(3);
temp_vec
```
We’ve defined a macro that can take any number of arguments of any type and can
generate code to create a vector containing the specified elements.
Given that most Rust programmers will *use* macros more than *write* macros, we
won’t discuss `macro_rules!` any further. To learn more about how to write
macros, consult the online documentation or other resources, such as [“The
Little Book of Rust Macros”][tlborm].
[tlborm]: https://danielkeep.github.io/tlborm/book/index.html
### Procedural Macros for Custom `derive`
The second form of macros is called *procedural macros* because they’re more
like functions (which are a type of procedure). Procedural macros accept some
Rust code as an input, operate on that code, and produce some Rust code as an
output rather than matching against patterns and replacing the code with other
code as declarative macros do. At the time of this writing, you can only define
procedural macros to allow your traits to be implemented on a type by
specifying the trait name in a `derive` annotation.
We’ll create a crate named `hello_macro` that defines a trait named
`HelloMacro` with one associated function named `hello_macro`. Rather than
making our crate users implement the `HelloMacro` trait for each of their
types, we’ll provide a procedural macro so users can annotate their type with
`#[derive(HelloMacro)]` to get a default implementation of the `hello_macro`
function. The default implementation will print `Hello, Macro! My name is
TypeName!` where `TypeName` is the name of the type on which this trait has
been defined. In other words, we’ll write a crate that enables another
programmer to write code like Listing D-2 using our crate.
<span class="filename">Filename: src/main.rs</span>
```rust,ignore
extern crate hello_macro;
#[macro_use]
extern crate hello_macro_derive;
use hello_macro::HelloMacro;
#[derive(HelloMacro)]
struct Pancakes;
fn main() {
Pancakes::hello_macro();
}
```
<span class="caption">Listing D-2: The code a user of our crate will be able to
write when using our procedural macro</span>
This code will print `Hello, Macro! My name is Pancakes!` when we’re done. The
first step is to make a new library crate, like this:
```text
$ cargo new hello_macro --lib
```
Next, we’ll define the `HelloMacro` trait and its associated function:
<span class="filename">Filename: src/lib.rs</span>
```rust
pub trait HelloMacro {
fn hello_macro();
}
```
We have a trait and its function. At this point, our crate user could implement
the trait to achieve the desired functionality, like so:
```rust,ignore
extern crate hello_macro;
use hello_macro::HelloMacro;
struct Pancakes;
impl HelloMacro for Pancakes {
fn hello_macro() {
println!("Hello, Macro! My name is Pancakes!");
}
}
fn main() {
Pancakes::hello_macro();
}
```
However, they would need to write the implementation block for each type they
wanted to use with `hello_macro`; we want to spare them from having to do this
work.
Additionally, we can’t yet provide a default implementation for the
`hello_macro` function that will print the name of the type the trait is
implemented on: Rust doesn’t have reflection capabilities, so it can’t look up
the type’s name at runtime. We need a macro to generate code at compile time.
The next step is to define the procedural macro. At the time of this writing,
procedural macros need to be in their own crate. Eventually, this restriction
might be lifted. The convention for structuring crates and macro crates is as
follows: for a crate named `foo`, a custom derive procedural macro crate is
called `foo_derive`. Let’s start a new crate called `hello_macro_derive` inside
our `hello_macro` project:
```text
$ cargo new hello_macro_derive --lib
```
Our two crates are tightly related, so we create the procedural macro crate
within the directory of our `hello_macro` crate. If we change the trait
definition in `hello_macro`, we’ll have to change the implementation of the
procedural macro in `hello_macro_derive` as well. The two crates will need to
be published separately, and programmers using these crates will need to add
both as dependencies and bring them both into scope. We could instead have the
`hello_macro` crate use `hello_macro_derive` as a dependency and reexport the
procedural macro code. But the way we’ve structured the project makes it
possible for programmers to use `hello_macro` even if they don’t want the
`derive` functionality.
We need to declare the `hello_macro_derive` crate as a procedural macro crate.
We’ll also need functionality from the `syn` and `quote` crates, as you’ll see
in a moment, so we need to add them as dependencies. Add the following to the
*Cargo.toml* file for `hello_macro_derive`:
<span class="filename">Filename: hello_macro_derive/Cargo.toml</span>
```toml
[lib]
proc-macro = true
[dependencies]
syn = "0.14.4"
quote = "0.6.3"
```
To start defining the procedural macro, place the code in Listing D-3 into your
*src/lib.rs* file for the `hello_macro_derive` crate. Note that this code won’t
compile until we add a definition for the `impl_hello_macro` function.
<span class="filename">Filename: hello_macro_derive/src/lib.rs</span>
```rust,ignore
extern crate proc_macro;
extern crate syn;
#[macro_use]
extern crate quote;
use proc_macro::TokenStream;
#[proc_macro_derive(HelloMacro)]
pub fn hello_macro_derive(input: TokenStream) -> TokenStream {
// Construct a representation of Rust code as a syntax tree
// that we can manipulate
let ast = syn::parse(input).unwrap();
// Build the trait implementation
impl_hello_macro(&ast)
}
```
<span class="caption">Listing D-3: Code that most procedural macro crates will
need to have for processing Rust code</span>
Notice the way we’ve split the functions in D-3; this will be the same for
almost every procedural macro crate you see or create, because it makes writing
a procedural macro more convenient. What you choose to do in the place where
the `impl_hello_macro` function is called will be different depending on your
procedural macro’s purpose.
We’ve introduced three new crates: `proc_macro`, [`syn`], and [`quote`]. The
`proc_macro` crate comes with Rust, so we didn’t need to add that to the
dependencies in *Cargo.toml*. The `proc_macro` crate allows us to convert Rust
code into a string containing that Rust code. The `syn` crate parses Rust code
from a string into a data structure that we can perform operations on. The
`quote` crate takes `syn` data structures and turns them back into Rust code.
These crates make it much simpler to parse any sort of Rust code we might want
to handle: writing a full parser for Rust code is no simple task.
[`syn`]: https://crates.io/crates/syn
[`quote`]: https://crates.io/crates/quote
The `hello_macro_derive` function will get called when a user of our library
specifies `#[derive(HelloMacro)]` on a type. The reason is that we’ve annotated
the `hello_macro_derive` function here with `proc_macro_derive` and specified
the name, `HelloMacro`, which matches our trait name; that’s the convention
most procedural macros follow.
This function first converts the `input` from a `TokenStream` to a data
structure that we can then interpret and perform operations on. This is where
`syn` comes into play. The `parse` function in `syn` takes a `TokenStream` and
returns a `DeriveInput` struct representing the parsed Rust code. The following
code shows the relevant parts of the `DeriveInput` struct we get from parsing
the string `struct Pancakes;`:
```rust,ignore
DeriveInput {
// --snip--
ident: Ident(
"Pancakes"
),
body: Struct(
Unit
)
}
```
The fields of this struct show that the Rust code we’ve parsed is a unit struct
with the `ident` (identifier, meaning the name) of `Pancakes`. There are more
fields on this struct for describing all sorts of Rust code; check the [`syn`
documentation for `DeriveInput`][syn-docs] for more information.
[syn-docs]: https://docs.rs/syn/0.11.11/syn/struct.DeriveInput.html
At this point, we haven’t defined the `impl_hello_macro` function, which is
where we’ll build the new Rust code we want to include. But before we do, note
that its output is also a `TokenStream` which is added to the code that our
crate users write, so when they compile their crate, they’ll get extra
functionality that we provide.
You might have noticed that we’re calling `unwrap` to panic if the call to the
`syn::parse`function fails here. Panicking on errors is necessary in procedural
macro code because `proc_macro_derive` functions must return `TokenStream`
rather than `Result` to conform to the procedural macro API. We’ve chosen to
simplify this example by using `unwrap`; in production code, you should provide
more specific error messages about what went wrong by using `panic!` or `expect`.
Now that we have the code to turn the annotated Rust code from a `TokenStream`
into a `DeriveInput` instance, let’s generate the code that implements the
`HelloMacro` trait on the annotated type:
<span class="filename">Filename: hello_macro_derive/src/lib.rs</span>
```rust,ignore
fn impl_hello_macro(ast: &syn::DeriveInput) -> TokenStream {
let name = &ast.ident;
let gen = quote! {
impl HelloMacro for #name {
fn hello_macro() {
println!("Hello, Macro! My name is {}", stringify!(#name));
}
}
};
gen.into()
}
```
We get an `Ident` struct instance containing the name (identifier) of the
annotated type using `ast.ident`. The code in Listing D-2 specifies that the
`name` will be `Ident("Pancakes")`.
The `quote!` macro lets us write the Rust code that we want to return, but the
direct result of its execution is not what is expected by the compiler and needs
to be converted to a `TokenStream` by calling the `into` method. `into` consumes
this intermediate representation and returns a value of the required type.
This macro also provides some very cool templating mechanics; we can write
`#name`, and `quote!` will replace it with the value in the variable named
`name`. You can even do some repetition similar
to the way regular macros work. Check out [the `quote` crate’s docs][quote-docs]
for a thorough introduction.
[quote-docs]: https://docs.rs/quote
We want our procedural macro to generate an implementation of our `HelloMacro`
trait for the type the user annotated, which we can get by using `#name`. The
trait implementation has one function, `hello_macro`, whose body contains the
functionality we want to provide: printing `Hello, Macro! My name is` and then
the name of the annotated type.
The `stringify!` macro used here is built into Rust. It takes a Rust
expression, such as `1 + 2`, and at compile time turns the expression into a
string literal, such as `"1 + 2"`. This is different than `format!` or
`println!`, which evaluate the expression and then turn the result into a
`String`. There is a possibility that the `#name` input might be an expression
to print literally, so we use `stringify!`. Using `stringify!` also saves an
allocation by converting `#name` to a string literal at compile time.
At this point, `cargo build` should complete successfully in both `hello_macro`
and `hello_macro_derive`. Let’s hook up these crates to the code in Listing D-2
to see the procedural macro in action! Create a new binary project in your
*projects* directory using `cargo new pancakes`. We need to add
`hello_macro` and `hello_macro_derive` as dependencies in the `pancakes`
crate’s *Cargo.toml*. If you’re publishing your versions of `hello_macro` and
`hello_macro_derive` to *https://crates.io/*, they would be regular
dependencies; if not, you can specify them as `path` dependencies as follows:
```toml
[dependencies]
hello_macro = { path = "../hello_macro" }
hello_macro_derive = { path = "../hello_macro/hello_macro_derive" }
```
Put the code from Listing D-2 into *src/main.rs*, and run `cargo run`: it
should print `Hello, Macro! My name is Pancakes!` The implementation of the
`HelloMacro` trait from the procedural macro was included without the
`pancakes` crate needing to implement it; the `#[derive(HelloMacro)]` added the
trait implementation.
### The Future of Macros
In the future, Rust will expand declarative and procedural macros. Rust will
use a better declarative macro system with the `macro` keyword and will add
more types of procedural macros for more powerful tasks than just `derive`.
These systems are still under development at the time of this publication;
please consult the online Rust documentation for the latest information.

192
2018-edition/src/appendix-04-useful-development-tools.md Normal file
View File

@ -0,0 +1,192 @@
# D - Useful Development Tools
In this appendix, we’ll talk about tools provided by the Rust project that are
useful when developing Rust code.
## Automatic Formatting with `rustfmt`
The tool `rustfmt` reformats your code according to the community code style.
Many projects use `rustfmt` to prevent arguments about which style to use when
writing Rust: everyone formats their code with the tool!
The `rustfmt` tool is not yet at the quality of a version 1.0 release, but
a preview is available for you to use in the meantime. Please give it a try and
let us know how it goes!
To install `rustfmt`:
```text
$ rustup component add rustfmt-preview
```
This will give you both `rustfmt` and `cargo-fmt`, similar to how Rust gives
you both `rustc` and `cargo`. To take any Cargo project and format it:
```text
$ cargo fmt
```
Running this command will reformat all of the Rust code in the current crate.
This should only change the code style, not the code semantics. For more
information on `rustfmt`, see [its documentation][rustfmt].
[rustfmt]: https://github.com/rust-lang-nursery/rustfmt
## Fix Up Your Code with `rustfix`
If you’ve written code in Rust, you’ve probably seen compiler warnings. For
example, consider this code:
<span class="filename">Filename: src/main.rs</span>
```rust
fn do_something() {}
fn main() {
for i in 0..100 {
do_something();
}
}
```
Here, we’re calling the `do_something` function 100 times, but we never use the
variable `i` in the body of the `for` loop. Rust warns us about that:
```text
$ cargo build
Compiling myprogram v0.1.0 (file:///projects/myprogram)
warning: unused variable: `i`
--> src/main.rs:4:9
|
4 | for i in 1..100 {
| ^ help: consider using `_i` instead
|
= note: #[warn(unused_variables)] on by default
Finished dev [unoptimized + debuginfo] target(s) in 0.50s
```
The warning suggests that we use `_i` as a name instead: the underscore
indicates that we intend for this variable to be unused. We can automatically
apply that suggestion using the `rustfix` tool by running the command `cargo
fix`:
```text
$ cargo fix
Checking myprogram v0.1.0 (file:///projects/myprogram)
Fixing src/main.rs (1 fix)
Finished dev [unoptimized + debuginfo] target(s) in 0.59s
```
If we look at *src/main.rs* again, we’ll see that `cargo fix` has changed the
code:
<span class="filename">Filename: src/main.rs</span>
```rust
fn do_something() {}
fn main() {
for _i in 0..100 {
do_something();
}
}
```
The `for` loop variable is now named `_i`, and the warning will no longer
appear.
The `cargo fix` command can also be used to transition your code between
different editions of Rust. Editions are covered in Appendix E.
## More Lints with `clippy`
The `clippy` tool is a collection of lints to catch common mistakes and improve
your Rust code.
The `clippy` tool is not yet at the quality of a version 1.0 release, but a
preview is available for you to use in the meantime. Please give it a try and
let us know how it goes!
To install `clippy`:
```text
$ rustup component add clippy-preview
```
To take any Cargo project and run clippy’s lints on it:
```text
$ cargo clippy
```
For example, if you write a program that uses an approximation of a mathematical constant such as pi, as this program does:
<span class="filename">Filename: src/main.rs</span>
```rust
fn main() {
let x = 3.1415;
let r = 8.0;
println!("the area of the circle is {}", x * r * r);
}
```
Running `cargo clippy` on this project will result in this error:
```text
error: approximate value of `f{32, 64}::consts::PI` found. Consider using it directly
--> src/main.rs:2:13
|
2 | let x = 3.1415;
| ^^^^^^
|
= note: #[deny(clippy::approx_constant)] on by default
= help: for further information visit https://rust-lang-nursery.github.io/rust-clippy/v0.0.212/index.html#approx_constant
```
This lets you know that Rust has this constant defined more precisely, and that
your program would be more correct if you used the constant instead. This code
doesn’t result in any errors or warnings from `clippy`:
<span class="filename">Filename: src/main.rs</span>
```rust
fn main() {
let x = std::f64::consts::PI;
let r = 8.0;
println!("the area of the circle is {}", x * r * r);
}
```
For more information on `clippy`, see [its documentation][clippy].
[clippy]: https://github.com/rust-lang-nursery/rust-clippy
## IDE Integration Using the Rust Language Server
To help IDE integration, the Rust project distributes the `rls`, which stands
for the Rust Language Server. This tool speaks the [Language Server
Protocol][lsp], which is a specification for IDEs and programming languages to
communicate with each other. The `rls` can be used by different clients, such
as [the Rust plugin for Visual Studio: Code][vscode].
[lsp]: http://langserver.org/
[vscode]: https://marketplace.visualstudio.com/items?itemName=rust-lang.rust
The `rls` is not yet at the quality of a version 1.0 release, but a preview is
available for you to use in the meantime. Please give it a try and let us know
how it goes!
To install the `rls`:
```text
$ rustup component add rls-preview
```
Then install the language server support in your particular IDE, and you will
gain abilities such as autocompletion, jump to definition, and inline errors.
For more information on the `rls`, see [its documentation][rls].
[rls]: https://github.com/rust-lang-nursery/rls

56
2018-edition/src/appendix-05-editions.md Normal file
View File

@ -0,0 +1,56 @@
# Appendix E - Editions
Way back in Chapter 1, we saw that `cargo new` adds a bit of metadata to your
*Cargo.toml* about an `edition`. This appendix talks about what that means!
The Rust language and compiler have a six-week release cycle. This means users
get a constant stream of new features. Other programming languages release
larger changes less often; Rust chooses to release smaller updates more
frequently. After a while, all of those tiny changes add up. But from release
to release, it can be hard to look back and say “Wow, between Rust 1.10 and
Rust 1.31, Rust has changed a lot!”
Every two or three years, the Rust team produces a new *edition* of Rust.
Each edition brings together the features that have landed into a clear
package with fully updated documentation and tooling. New editions ship
as part of the usual six-week release process.
This serves different purposes for different people:
* For active Rust users, it brings together incremental changes into an
easy-to-understand package.
* For non-users, it signals that some major advancements have landed, which
might make Rust worth another look.
* For those developing Rust itself, it provides a rallying point for the
project as a whole.
At the time of writing, there are two editions: Rust 2015 and Rust 2018.
This book is written using Rust 2018 edition idioms.
The `edition` key in *Cargo.toml* indicates which edition your code should be
compiled under. If the key does not exist, it defaults to `2015` for backwards
compatibility reasons.
Each project can choose to opt in to an edition other than the default 2015
edition. By doing so, editions can contain incompatible changes, such as adding
a new keyword that might conflict with identifiers in code or turning warnings
into errors. But unless you opt in to those changes, your code will continue to
compile even as you upgrade the version of the Rust compiler that you use. All
Rust compiler versions support any edition that existed prior to that
compiler’s release, and they can link crates of any supported editions
together. Edition changes only affect the way the compiler initially parses
code. Therefore, if you’re using Rust 2015 and one of your dependencies uses
Rust 2018, your project will compile and be able to use that dependency. The
opposite situation, where your project uses Rust 2018 and a dependency uses
Rust 2015, works as well.
To be clear: most features will be available on all editions. Developers using
any edition of Rust will continue to see improvements as new stable releases
are made. In some cases, however, mainly when new keywords are added, there may
be new features that are only available in later editions. You only need to
switch editions if you want to take advantage of such features.
For more details, the [Edition
Guide](https://rust-lang-nursery.github.io/edition-guide/) is a complete
book about editions, including how to automatically upgrade your code to
a new edition via `cargo fix`.

2
2018-edition/src/appendix-05-translation.md → 2018-edition/src/appendix-06-translation.md
View File

@ -1,4 +1,4 @@
## Appendix E: Translations of the Book
## Appendix F: Translations of the Book
For resources in languages other than English. Most are still in progress; see
[the Translations label][label] to help or let us know about a new translation!

2
2018-edition/src/appendix-06-nightly-rust.md → 2018-edition/src/appendix-07-nightly-rust.md
View File

@ -1,4 +1,4 @@
# Appendix F - How Rust is Made and “Nightly Rust”
# Appendix G - How Rust is Made and “Nightly Rust”
This appendix is about how Rust is made and how that affects you as a Rust
developer.

124
2018-edition/src/appendix-07-other-useful-tools.md
View File

@ -1,124 +0,0 @@
# G - Other useful tools
In this appendix, we'll talk about some additional tools that are provided by
the Rust project, and are useful when developing Rust code.
## Automatic formatting with `rustfmt`
`rustfmt` is a tool that can re-format your code according to community
norms. Many projects use `rustfmt` to prevent arguments about which style to
use when writing Rust: just do what the tool does!
`rustfmt` is not at 1.0 yet, but a preview is available for you to use in
the meantime. Please give it a try and let us know how it goes!
To install `rustfmt`:
```shell
$ rustup component add rustfmt-preview
```
This will give you both `rustfmt` and `cargo-fmt`, similar to how Rust gives
you both `rustc` and `cargo`. To take any Cargo project and format it:
```shell
$ cargo fmt
```
## Fix up your code with `rustfix`
If you’ve written code in Rust before, you’ve probably seen a compiler
warning before. For example, consider this code:
```rust
fn do_something() {}
fn main() {
for i in 0..100 {
do_something();
}
}
```
Here, we’re calling do_something a hundred times. But we never use the
variable i. And so Rust warns:
```text
> cargo build
Compiling myprogram v0.1.0 (file:///projects/myprogram)
warning: unused variable: `i`
--> src\main.rs:4:9
|
4 | for i in 1..100 {
| ^ help: consider using `_i` instead
|
= note: #[warn(unused_variables)] on by default
Finished dev [unoptimized + debuginfo] target(s) in 0.50s
```
See how it suggests that we use `_i` as a name instead? We can automatically
apply that suggestion with cargo fix:
```console
> cargo fix
Checking myprogram v0.1.0 (file:///projects/myprogram)
Fixing src\main.rs (1 fix)
Finished dev [unoptimized + debuginfo] target(s) in 0.59s
```
If we look at `src\main.rs` again, we’ll see that the code has changed:
```rust
fn do_something() {}
fn main() {
for _i in 0..100 {
do_something();
}
}
```
We’re now using `_i`, and the warning will no longer appear.
`cargo fix` can also be used to transition your code between different editions
of Rust. Editions are covered in Appendix H.
## More lints with `clippy`
`clippy` is a bunch of lints to catch common mistakes and improve your Rust
code.
`clippy` is not at 1.0 yet, but a preview is available for you to use in the
meantime. Please give it a try and let us know how it goes!
To install `clippy`:
```shell
$ rustup component add clippy-preview
```
To take any Cargo project and run clippy's lints on it:
```shell
$ cargo clippy
```
## IDE integration with the Rust Language Server
To help IDE integration, the Rust project distributes `rls`, the Rust
Language Server, as in <http://langserver.org/>. This can be used by
different clients, such as [the Rust plugin for Visual Studio:
Code](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust).
The `rls` is not at 1.0 yet, but a preview is available for you to use in the
meantime. Please give it a try and let us know how it goes!
To install the `rls`:
```shell
$ rustup component add rls-preview
```
Then, install the language server support in your particular IDE, and it
should all work.

58
2018-edition/src/appendix-08-editions.md
View File

@ -1,58 +0,0 @@
# Appendix H - Editions
Way back in Chapter 1, we saw that `cargo new` adds a bit of metadata to your
`Cargo.toml` about an `edition`. We can finally talk about what that means!
In Appendix F, we talked about Rust's six-week release cycle. This means that
users get a constant stream of new features. This is much faster than updates
for other languages, but this also means that each update is smaller. After a
while, all of those tiny changes add up. But, from release to release, it can
be hard to look back and say "Wow, between Rust 1.10 and Rust 1.31, Rust has
changed a lot!"
Every two or three years, the Rust team produces a new *edition* of Rust.
Each edition brings together the features that have landed into a clear
package, with fully updated documentation and tooling. New editions ship
through the usual release process.
This serves different purposes for different people:
* For active Rust users, it brings together incremental changes into an
easy-to-understand package.
* For non-users, it signals that some major advancements have landed, which
might make Rust worth another look.
* For those developing Rust itself, it provides a rallying point for the
project as a whole.
At the time of writing, there are two editions: Rust 2015, and Rust 2018.
This book assumes Rust 2018; see the "second edition" for Rust 2015 specific
details.
## Compatibility
Speaking of there being multiple editions, the `edition = "2018"` key in
`Cargo.toml` indicates which edition your code should be compiled under. If
the key does not exist, it defaults to `2015`, for backwards compatibility
reasons.
This opt in enables editions to contain incompatible changes, like adding a
new keyword that might conflict with identifiers in code, or turning warnings
into errors. A Rust compiler will support all editions that existed prior to
the compiler's release, and can link crates of any supported editions
together. Edition changes only affect the way the compiler initially parses
the code. Therefore, if you're using Rust 2015, and one of your dependencies
uses Rust 2018, it all works just fine. The opposite situation works as well.
Just to be clear: most features will be available on all editions. People
using any edition of Rust will continue to see improvements as new stable
releases are made. In some cases however, mainly when new keywords are added,
but sometimes for other reasons, there may be new features that are only
available in later editions. You only need to upgrade if you want to take
advantage of such features.
## Read More
For more details, the [Edition
Guide](https://rust-lang-nursery.github.io/edition-guide/) is a complete
book about editions, including how to automatically upgrade your code to
a new edition via `cargo fix`.

9
2018-edition/src/ch00-00-introduction.md
View File

@ -147,8 +147,8 @@ principles you might be familiar with.
Chapter 18 is a reference on patterns and pattern matching, which are powerful
ways of expressing ideas throughout Rust programs. Chapter 19 contains a
smorgasbord of advanced topics of interest, including unsafe Rust and more
about lifetimes, traits, types, functions, and closures.
smorgasbord of advanced topics of interest, including unsafe Rust, macros, and
more about lifetimes, traits, types, functions, and closures.
In Chapter 20, we’ll complete a project in which we’ll implement a low-level
multithreaded web server!
@ -156,7 +156,8 @@ multithreaded web server!
Finally, some appendixes contain useful information about the language in a
more reference-like format. Appendix A covers Rust’s keywords, Appendix B
covers Rust’s operators and symbols, Appendix C covers derivable traits
provided by the standard library, and Appendix D covers macros.
provided by the standard library, Appendix D covers some useful development
tools, and Appendix E explains Rust editions.
There is no wrong way to read this book: if you want to skip ahead, go for it!
You might have to jump back to earlier chapters if you experience any
@ -170,7 +171,7 @@ As such, we’ll provide many examples of code that doesn’t compile along with
the error message the compiler will show you in each situation. Know that if
you enter and run a random example, it may not compile! Make sure you read the
surrounding text to see whether the example you’re trying to run is meant to
error. Ferris will also help you distinguish code that isn't meant to work:
error. Ferris will also help you distinguish code that isn’t meant to work:
| Ferris | Meaning |
|------------------------------------------------------------------------|--------------------------------------------------|

4
2018-edition/src/ch01-02-hello-world.md
View File

@ -132,7 +132,7 @@ to indent with four spaces, not a tab.
Second, `println!` calls a Rust macro. If it called a function instead, it
would be entered as `println` (without the `!`). We’ll discuss Rust macros in
more detail in Appendix D. For now, you just need to know that using a `!`
more detail in Chapter 19. For now, you just need to know that using a `!`
means that you’re calling a macro instead of a normal function.
Third, you see the `"Hello, world!"` string. We pass this string as an argument
@ -166,7 +166,7 @@ $ ls
main main.rs
```
With PowerShell on Windows, you can use `ls` as well, but you'll see three files:
With PowerShell on Windows, you can use `ls` as well, but you’ll see three files:
```text
> ls

4
2018-edition/src/ch01-03-hello-cargo.md
View File

@ -80,8 +80,8 @@ this file, we’ll add other sections.
The next four lines set the configuration information Cargo needs to compile
your program: the name, the version, and who wrote it. Cargo gets your name and
email information from your environment, so if that information is not correct,
fix the information now and then save the file. We'll talk about the `edition`
key in Appendix H.
fix the information now and then save the file. We’ll talk about the `edition`
key in Appendix E.
The last line, `[dependencies]`, is the start of a section for you to list any
of your project’s dependencies. In Rust, packages of code are referred to as

2
2018-edition/src/ch17-03-oo-design-patterns.md
View File

@ -508,7 +508,7 @@ and `approve` methods on `Post`. Both methods delegate to the implementation of
the same method on the value in the `state` field of `Option` and set the new
value of the `state` field to the result. If we had a lot of methods on `Post`
that followed this pattern, we might consider defining a macro to eliminate the
repetition (see Appendix D for more on macros).
repetition (see the “Macros” section in Chapter 19).
By implementing the state pattern exactly as it’s defined for object-oriented
languages, we’re not taking as full advantage of Rust’s strengths as we could.