Skip to content

Commit bc1a637

Browse files
matthewjaspermatthewjasper
committed
Fix merge conflict
2 parents 7c8ff20 + 75aee62 commit bc1a637

12 files changed

+494
-61
lines changed

Diff for: ‎README.md

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# The Rust Language Reference
2+
3+
This document is the primary reference for the Rust programming language.
4+
5+
This document is not normative. It may include details that are specific
6+
to `rustc` itself, and should not be taken as a specification for the
7+
Rust language. We intend to produce such a document someday, but this is
8+
what we have for now.
9+
10+
## Dependencies
11+
12+
- rustc (the Rust compiler).
13+
- mdbook (use `cargo install mdbook` to install it).
14+
15+
## Build steps
16+
17+
First, go to the repository folder and test the code snippets to catch
18+
compilation errors:
19+
20+
```bash
21+
cd reference
22+
mdbook test
23+
```
24+
25+
And then generate the book:
26+
27+
```bash
28+
mdbook build
29+
```
30+
31+
The generated HTML will be in the `docs` folder.

Diff for: ‎src/SUMMARY.md

+3
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88

99
- [Lexical structure](lexical-structure.md)
1010
- [Input format](input-format.md)
11+
- [Keywords](keywords.md)
1112
- [Identifiers](identifiers.md)
1213
- [Comments](comments.md)
1314
- [Whitespace](whitespace.md)
@@ -58,3 +59,5 @@
5859
[Appendix: Influences](influences.md)
5960

6061
[Appendix: As-yet-undocumented Features](undocumented.md)
62+
63+
[Appendix: Glossory](glossory.md)

Diff for: ‎src/attributes.md

+21
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,26 @@
11
# Attributes
22

3+
> **<sup>Syntax</sup>**
4+
> _Attribute_ :
5+
> &nbsp;&nbsp; _InnerAttribute_ | _OuterAttribute_
6+
>
7+
> _InnerAttribute_ :
8+
> &nbsp;&nbsp; `#![` MetaItem `]`
9+
>
10+
> _OuterAttribute_ :
11+
> &nbsp;&nbsp; `#[` MetaItem `]`
12+
>
13+
> _MetaItem_ :
14+
> &nbsp;&nbsp; &nbsp;&nbsp; IDENTIFIER
15+
> &nbsp;&nbsp; | IDENTIFIER `=` LITERAL
16+
> &nbsp;&nbsp; | IDENTIFIER `(` _MetaSeq_ `)`
17+
> &nbsp;&nbsp; | IDENTIFIER `(` _MetaSeq_ `,` `)`
18+
>
19+
> _MetaSeq_ :
20+
> &nbsp;&nbsp; &nbsp;&nbsp; EMPTY
21+
> &nbsp;&nbsp; | _MetaItem_
22+
> &nbsp;&nbsp; | _MetaSeq_ `,` _MetaItem_
23+
324
Any item declaration may have an _attribute_ applied to it. Attributes in Rust
425
are modeled on Attributes in ECMA-335, with the syntax coming from ECMA-334
526
(C#). An attribute is a general, free-form metadatum that is interpreted

Diff for: ‎src/comments.md

+110-5
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,125 @@
11
# Comments
22

3+
> **<sup>Lexer</sup>**
4+
> LINE_COMMENT :
5+
> &nbsp;&nbsp; &nbsp;&nbsp; `//` (~[`/` `!`] | `//`) ~`\n`<sup>\*</sup>
6+
> &nbsp;&nbsp; | `//`
7+
>
8+
> BLOCK_COMMENT :
9+
> &nbsp;&nbsp; &nbsp;&nbsp; `/*` (~[`*` `!`] | `**` | _BlockCommentOrDoc_)
10+
> (_BlockCommentOrDoc_ | ~`*/`)<sup>\*</sup> `*/`
11+
> &nbsp;&nbsp; | `/**/`
12+
> &nbsp;&nbsp; | `/***/`
13+
>
14+
> OUTER_LINE_DOC :
15+
> &nbsp;&nbsp; `//!` ~[`\n` _IsolatedCR_]<sup>\*</sup>
16+
>
17+
> OUTER_BLOCK_DOC :
18+
> &nbsp;&nbsp; `/*!` ( _BlockCommentOrDoc_ | ~[`*/` _IsolatedCR_] )<sup>\*</sup> `*/`
19+
>
20+
> INNER_LINE_DOC :
21+
> &nbsp;&nbsp; `///` (~`/` ~[`\n` _IsolatedCR_]<sup>\*</sup>)<sup>?</sup>
22+
>
23+
> INNER_BLOCK_DOC :
24+
> &nbsp;&nbsp; `/**` (~`*` | _BlockCommentOrDoc_ )
25+
> (_BlockCommentOrDoc_ | ~[`*/` _IsolatedCR_])<sup>\*</sup> `*/`
26+
>
27+
> _BlockCommentOrDoc_ :
28+
> &nbsp;&nbsp; &nbsp;&nbsp; BLOCK_COMMENT
29+
> &nbsp;&nbsp; | OUTER_BLOCK_DOC
30+
> &nbsp;&nbsp; | INNER_BLOCK_DOC
31+
>
32+
> _IsolatedCR_ :
33+
> &nbsp;&nbsp; _A `\r` not followed by a `\n`_
34+
35+
## Non-doc comments
36+
337
Comments in Rust code follow the general C++ style of line (`//`) and
438
block (`/* ... */`) comment forms. Nested block comments are supported.
539

6-
Line comments beginning with exactly _three_ slashes (`///`), and block
7-
comments (`/** ... */`), are interpreted as a special syntax for `doc`
8-
[attributes]. That is, they are equivalent to writing
40+
Non-doc comments are interpreted as a form of whitespace.
41+
42+
## Doc comments
43+
44+
Line doc comments beginning with exactly _three_ slashes (`///`), and block
45+
doc comments (`/** ... */`), both inner doc comments, are interpreted as a
46+
special syntax for `doc` [attributes]. That is, they are equivalent to writing
947
`#[doc="..."]` around the body of the comment, i.e., `/// Foo` turns into
10-
`#[doc="Foo"]`.
48+
`#[doc="Foo"]` and `/** Bar */` turns into `#[doc="Bar"]`.
1149

1250
Line comments beginning with `//!` and block comments `/*! ... */` are
1351
doc comments that apply to the parent of the comment, rather than the item
1452
that follows. That is, they are equivalent to writing `#![doc="..."]` around
1553
the body of the comment. `//!` comments are usually used to document
1654
modules that occupy a source file.
1755

18-
Non-doc comments are interpreted as a form of whitespace.
56+
Isolated CRs (`\r`), i.e. not followed by LF (`\n`), are not allowed in doc
57+
comments.
58+
59+
## Examples
60+
61+
```rust
62+
//! A doc comment that applies to the implicit anonymous module of this crate
63+
64+
pub mod outer_module {
65+
66+
//! - Inner line doc
67+
//!! - Still an inner line doc (but with a bang at the beginning)
68+
69+
/*! - Inner block doc */
70+
/*!! - Still an inner block doc (but with a bang at the beginning) */
71+
72+
// - Only a comment
73+
/// - Outer line doc (exactly 3 slashes)
74+
//// - Only a comment
75+
76+
/* - Only a comment */
77+
/** - Outer block doc (exactly) 2 asterisks */
78+
/*** - Only a comment */
79+
80+
pub mod inner_module {}
81+
82+
pub mod nested_comments {
83+
/* In Rust /* we can /* nest comments */ */ */
84+
85+
// All three types of block comments can contain or be nested inside
86+
// any other type:
87+
88+
/* /* */ /** */ /*! */ */
89+
/*! /* */ /** */ /*! */ */
90+
/** /* */ /** */ /*! */ */
91+
pub mod dummy_item {}
92+
}
93+
94+
pub mod degenerate_cases {
95+
// empty inner line doc
96+
//!
97+
98+
// empty inner block doc
99+
/*!*/
100+
101+
// empty line comment
102+
//
103+
104+
// empty outer line doc
105+
///
106+
107+
// empty block comment
108+
/**/
109+
110+
pub mod dummy_item {}
111+
112+
// empty 2-asterisk block isn't a doc block, it is a block comment
113+
/***/
114+
115+
}
116+
117+
/* The next one isn't allowed because outer doc comments
118+
require an item that will receive the doc */
119+
120+
/// Where is my item?
121+
# mod boo {}
122+
}
123+
```
19124

20125
[attributes]: attributes.html

Diff for: ‎src/crates-and-source-files.md

+34-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,16 @@
11
# Crates and source files
22

3+
> **<sup>Syntax</sup>**
4+
> _Crate_ :
5+
> &nbsp;&nbsp; UTF8BOM<sup>?</sup>
6+
> &nbsp;&nbsp; SHEBANG<sup>?</sup>
7+
> &nbsp;&nbsp; [_InnerAttribute_]<sup>\*</sup>
8+
> &nbsp;&nbsp; [_Item_]<sup>\*</sup>
9+
10+
> **<sup>Lexer</sup>**
11+
> UTF8BOM : `\uFEFF`
12+
> SHEBANG : `#!` ~[`[` `\n`] ~`\n`<sup>*</sup>
13+
314
Although Rust, like any other language, can be implemented by an interpreter as
415
well as a compiler, the only existing implementation is a compiler,
516
and the language has
@@ -59,6 +70,24 @@ A crate that contains a `main` function can be compiled to an executable. If a
5970
`main` function is present, its return type must be `()`
6071
("[unit]") and it must take no arguments.
6172

73+
The optional [_UTF8 byte order mark_] (UTF8BOM production) indicates that the
74+
file is encoded in UTF8. It can only occur at the beginning of the file and
75+
is ignored by the compiler.
76+
77+
A source file can have a [_shebang_] (SHEBANG production), which indicates
78+
to the operating system what program to use to execute this file. It serves
79+
essentially to treat the source file as an executable script. The shebang
80+
can only occur at the beginning of the file (but after the optional
81+
_UTF8BOM_). It is ignored by the compiler. For example:
82+
83+
```text,ignore
84+
#!/usr/bin/env rustx
85+
86+
fn main() {
87+
println!("Hello!");
88+
}
89+
```
90+
6291
[^phase-distinction]: This distinction would also exist in an interpreter.
6392
Static checks like syntactic analysis, type checking, and lints should
6493
happen before the program is executed regardless of when it is executed.
@@ -70,4 +99,8 @@ A crate that contains a `main` function can be compiled to an executable. If a
7099
[module]: items.html#modules
71100
[module path]: paths.html
72101
[attributes]: items-and-attributes.html
73-
[unit]: types.html#tuple-types
102+
[unit]: types.html#tuple-types
103+
[_InnerAttribute_]: attributes.html
104+
[_Item_]: items.html
105+
[_shebang_]: https://en.wikipedia.org/wiki/Shebang_(Unix)
106+
[_utf8 byte order mark_]: https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8

Diff for: ‎src/expressions.md

+21-5
Original file line numberDiff line numberDiff line change
@@ -84,9 +84,13 @@ The following expressions can create mutable lvalues:
8484
### Temporary lifetimes
8585

8686
When using an rvalue in most lvalue contexts, a temporary unnamed lvalue is
87-
created and used instead. The lifetime of temporary values is typically the
88-
innermost enclosing statement; the tail expression of a block is considered
89-
part of the statement that encloses the block.
87+
created and used instead. The lifetime of temporary values is typically
88+
89+
- the innermost enclosing statement; the tail expression of a block is
90+
considered part of the statement that encloses the block, or
91+
- the condition expression or the loop conditional expression if the
92+
temporary is created in the condition expression of an `if` or an `if`/`else`
93+
or in the loop conditional expression of a `while` expression.
9094

9195
When a temporary rvalue is being created that is assigned into a `let`
9296
declaration, however, the temporary is created with the lifetime of the
@@ -107,6 +111,18 @@ Here are some examples:
107111
method-call. Here we are assuming that `foo()` is an `&self` method
108112
defined in some trait, say `Foo`. In other words, the expression
109113
`temp().foo()` is equivalent to `Foo::foo(&temp())`.
114+
- `let x = if foo(&temp()) {bar()} else {baz()};`. The expression `temp()` is
115+
an rvalue. As the temporary is created in the condition expression
116+
of an `if`/`else`, it will be freed at the end of the condition expression
117+
(in this example before the call to `bar` or `baz` is made).
118+
- `let x = if temp().must_run_bar {bar()} else {baz()};`.
119+
Here we assume the type of `temp()` is a struct with a boolean field
120+
`must_run_bar`. As the previous example, the temporary corresponding to
121+
`temp()` will be freed at the end of the condition expression.
122+
- `while foo(&temp()) {bar();}`. The temporary containing the return value from
123+
the call to `temp()` is created in the loop conditional expression. Hence it
124+
will be freed at the end of the loop conditional expression (in this example
125+
before the call to `bar` if the loop body is executed).
110126
- `let x = &temp()`. Here, the same temporary is being assigned into
111127
`x`, rather than being passed as a parameter, and hence the
112128
temporary's lifetime is considered to be the enclosing block.
@@ -503,7 +519,7 @@ assert_eq!(unit_x.0, 1.0);
503519
A _call expression_ consists of an expression followed by a parenthesized
504520
expression-list. It invokes a function, providing zero or more input variables.
505521
If the function eventually returns, then the expression completes. For
506-
[non-function types](types.html#function-types), the expression f(...) uses the
522+
[non-function types](types.html#function-item-types), the expression f(...) uses the
507523
method on one of the `std::ops::Fn`, `std::ops::FnMut` or `std::ops::FnOnce`
508524
traits, which differ in whether they take the type by reference, mutable
509525
reference, or take ownership respectively. An automatic borrow will be taken if
@@ -962,7 +978,7 @@ well as the following additional casts. Here `*T` means either `*const T` or
962978
| `*T` where `T: Sized` | Numeric type | Pointer to address cast |
963979
| Integer type | `*V` where `V: Sized` | Address to pointer cast |
964980
| `&[T; n]` | `*const T` | Array to pointer cast |
965-
| [Function pointer](types.html#function-types) | `*V` where `V: Sized` | Function pointer to pointer cast |
981+
| [Function pointer](types.html#function-pointer-types) | `*V` where `V: Sized` | Function pointer to pointer cast |
966982
| Function pointer | Integer | Function pointer to address cast |
967983

968984
\* or `T` and `V` are compatible unsized types, e.g., both slices, both the

Diff for: ‎src/glossory.md

+87
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Glossary
2+
3+
### Abstract Syntax Tree
4+
5+
An ‘abstract syntax tree’, or ‘AST’, is an intermediate representation of
6+
the structure of the program when the compiler is compiling it.
7+
8+
### Arity
9+
10+
Arity refers to the number of arguments a function or operation takes.
11+
For example, `(2, 3)` and `(4, 6)` have arity 2, and`(8, 2, 6)` has arity 3.
12+
13+
### Array
14+
15+
An array, sometimes also called a fixed-size array or an inline array, is a value
16+
describing a collection of elements, each selected by an index that can be computed
17+
at run time by the program. It occupies a contiguous region of memory.
18+
19+
### Bound
20+
21+
Bounds are constraints on a type or trait. For example, if a bound
22+
is placed on the argument a function takes, types passed to that function
23+
must abide by that constraint.
24+
25+
### Combinator
26+
27+
Combinators are higher-order functions that apply only functions and
28+
earlier defined combinators to provide a result from its arguments.
29+
They can be used to manage control flow in a modular fashion.
30+
31+
### Dispatch
32+
33+
Dispatch is the mechanism to determine which specific version of code is actually
34+
run when it involves polymorphism. Two major forms of dispatch are static dispatch and
35+
dynamic dispatch. While Rust favors static dispatch, it also supports dynamic dispatch
36+
through a mechanism called ‘trait objects’.
37+
38+
### Dynamically Sized Type
39+
40+
A dynamically sized type (DST) is a type without a statically known size or alignment.
41+
42+
### Expression
43+
44+
An expression is a combination of values, constants, variables, operators
45+
and functions that evaluate to a single value, with or without side-effects.
46+
47+
For example, `2 + (3 * 4)` is an expression that returns the value 14.
48+
49+
### Prelude
50+
51+
Prelude, or The Rust Prelude, is a small collection of items - mostly traits - that are
52+
imported into very module of every crate. The traits in the prelude are pervasive.
53+
54+
### Slice
55+
56+
A slice is dynamically-sized view into a contiguous sequence, written as `[T]`.
57+
58+
It is often seen in its borrowed forms, either mutable or shared. The shared
59+
slice type is `&[T]`, while the mutable slice type is `&mut [T]`, where `T` represents
60+
the element type.
61+
62+
### Statement
63+
64+
A statement is the smallest standalone element of a programming language
65+
that commands a computer to perform an action.
66+
67+
### String literal
68+
69+
A string literal is a string stored directly in the final binary, and so will be
70+
valid for the `'static` duration.
71+
72+
Its type is `'static` duration borrowed string slice, `&'static str`.
73+
74+
### String slice
75+
76+
A string slice is the most primitive string type in Rust, written as `str`. It is
77+
often seen in its borrowed forms, either mutable or shared. The shared
78+
string slice type is `&str`, while the mutable string slice type is `&mut str`.
79+
80+
Strings slices are always valid UTF-8.
81+
82+
### Trait
83+
84+
A trait is a language item that is used for describing the functionalities a type must provide.
85+
It allow a type to make certain promises about its behavior.
86+
87+
Generic functions and generic structs can exploit traits to constrain, or bound, the types they accept.

0 commit comments

Comments
 (0)