Skip to content

Commit cf0ecbd

Browse files
ehussehuss
committed
Grammar: Functions, methods, impl, traits, extern.
These all are intertwined with the "function" definition. Updates grammar for: - Functions and methods - Extern blocks - Implementation - Traits
1 parent 38a98e0 commit cf0ecbd

File tree

5 files changed

+192
-7
lines changed

5 files changed

+192
-7
lines changed

‎src/items/external-blocks.md‎

Lines changed: 39 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,31 @@
11
# External blocks
22

3+
> **<sup>Syntax</sup>**\
4+
> _ExternBlock_ :\
5+
> &nbsp;&nbsp; `extern` [_Abi_]<sup>?</sup> `{`\
6+
> &nbsp;&nbsp; &nbsp;&nbsp; [_InnerAttribute_]<sup>\*</sup>\
7+
> &nbsp;&nbsp; &nbsp;&nbsp; _ExternalItem_<sup>\*</sup>\
8+
> &nbsp;&nbsp; `}`
9+
>
10+
> _ExternalItem_ :\
11+
> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup>\
12+
> &nbsp;&nbsp; [_Visibility_]<sup>?</sup>\
13+
> &nbsp;&nbsp; ( _ExternalStaticItem_ | _ExternalFunctionItem_ )
14+
>
15+
> _ExternalStaticItem_ :\
16+
> &nbsp;&nbsp; `static` `mut`<sup>?</sup> [IDENTIFIER] `:` [_Type_] `;`
17+
>
18+
> _ExternalFunctionItem_ :\
19+
> &nbsp;&nbsp; `fn` [IDENTIFIER]&nbsp;[_Generics_]<sup>?</sup>\
20+
> &nbsp;&nbsp; `(` [_FunctionParameters_]<sup>?</sup> | _FunctionParametersWithVariadics_ ) `)`\
21+
> &nbsp;&nbsp; [_FunctionReturnType_]<sup>?</sup> [_WhereClause_]<sup>?</sup> `;`
22+
>
23+
> _FunctionParametersWithVariadics_ :\
24+
> &nbsp;&nbsp; ( [_FunctionParam_] `,` )<sup>\*</sup> _VariadicFunctionParam_
25+
>
26+
> _VariadicFunctionParam_ :\
27+
> &nbsp;&nbsp; [_FunctionParam_] `,` `...`
28+
329
External blocks form the basis for Rust's foreign function interface.
430
Declarations in an external block describe symbols in external, non-Rust
531
libraries.
@@ -23,8 +49,6 @@ extern {
2349

2450
A number of [attributes] control the behavior of external blocks.
2551

26-
[attributes]: attributes.html#ffi-attributes
27-
2852
By default external blocks assume that the library they are calling uses the
2953
standard C ABI on the specific platform. Other ABIs may be specified using an
3054
`abi` string, as shown here:
@@ -81,3 +105,16 @@ It is valid to add the `link` attribute on an empty extern block. You can use
81105
this to satisfy the linking requirements of extern blocks elsewhere in your
82106
code (including upstream crates) instead of adding the attribute to each extern
83107
block.
108+
109+
[IDENTIFIER]: identifiers.html
110+
[_Abi_]: items/functions.html
111+
[_FunctionParam_]: items/functions.html
112+
[_FunctionParameters_]: items/functions.html
113+
[_FunctionReturnType_]: items/functions.html
114+
[_Generics_]: items/generics.html
115+
[_InnerAttribute_]: attributes.html
116+
[_OuterAttribute_]: attributes.html
117+
[_Type_]: types.html
118+
[_Visibility_]: visibility-and-privacy.html
119+
[_WhereClause_]: items/generics.html#where-clauses
120+
[attributes]: attributes.html#ffi-attributes

‎src/items/functions.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,33 @@
11
# Functions
22

3+
> **<sup>Syntax</sup>**\
4+
> _Function_:\
5+
> &nbsp;&nbsp; _FunctionFront_ `fn` [IDENTIFIER]&nbsp;[_Generics_]<sup>?</sup>\
6+
> &nbsp;&nbsp; &nbsp;&nbsp; `(` _FunctionParameters_<sup>?</sup> `)`\
7+
> &nbsp;&nbsp; &nbsp;&nbsp; _FunctionReturnType_<sup>?</sup> [_WhereClause_]<sup>?</sup>\
8+
> &nbsp;&nbsp; &nbsp;&nbsp; _BlockWithInnerAttributes_
9+
>
10+
> _FunctionFront_:\
11+
> &nbsp;&nbsp; `unsafe`<sup>?</sup> (`extern` _Abi_<sup>?</sup>)<sup>?</sup>
12+
>
13+
> _Abi_:\
14+
> &nbsp;&nbsp; [STRING_LITERAL] | [RAW_STRING_LITERAL]
15+
>
16+
> _FunctionParameters_:\
17+
> &nbsp;&nbsp; _FunctionParam_ (`,` _FunctionParam_)<sup>\*</sup> `,`<sup>?</sup>
18+
>
19+
> _FunctionParam_ :\
20+
> &nbsp;&nbsp; [_Pattern_] `:` [_Type_]
21+
>
22+
> _FunctionReturnType_:\
23+
> &nbsp;&nbsp; `->` [_Type_]
24+
>
25+
> _BlockWithInnerAttributes_ :\
26+
> &nbsp;&nbsp; `{`\
27+
> &nbsp;&nbsp; &nbsp;&nbsp; [_InnerAttribute_]<sup>\*</sup>\
28+
> &nbsp;&nbsp; &nbsp;&nbsp; [_Statement_]<sup>\*</sup>\
29+
> &nbsp;&nbsp; `}`
30+
331
A _function_ consists of a [block], along with a name and a set of parameters.
432
Other than a name, all these are optional. Functions are declared with the
533
keyword `fn`. Functions may declare a set of *input* [*variables*][variables]
@@ -138,6 +166,15 @@ attributes], [`must_use`], [the procedural macro attributes], [the testing
138166
attributes], and [the optimization hint
139167
attributes].
140168

169+
[IDENTIFIER]: identifiers.html
170+
[RAW_STRING_LITERAL]: tokens.html#raw-string-literals
171+
[STRING_LITERAL]: tokens.html#string-literals
172+
[_Generics_]: items/generics.html
173+
[_InnerAttribute_]: attributes.html
174+
[_Pattern_]: patterns.html
175+
[_Statement_]: statements.html
176+
[_Type_]: types.html
177+
[_WhereClause_]: items/generics.html#where-clauses
141178
[external blocks]: items/external-blocks.html
142179
[path]: paths.html
143180
[block]: expressions/block-expr.html

‎src/items/implementations.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,49 @@
11
# Implementations
22

3+
> **<sup>Syntax</sup>**\
4+
> _Implementation_ :\
5+
> &nbsp;&nbsp; _InherentImpl_ | _TraitImpl_
6+
>
7+
> _InherentImpl_ :\
8+
> &nbsp;&nbsp; `impl` [_GenericsDecl_] [_Type_] [_WhereClause_]<sup>?</sup> `{`\
9+
> &nbsp;&nbsp; &nbsp;&nbsp; [_InnerAttribute_]<sup>\*</sup>\
10+
> &nbsp;&nbsp; &nbsp;&nbsp; _InherentImplItem_<sup>\*</sup>\
11+
> &nbsp;&nbsp; `}`
12+
>
13+
> _InherentImplItem_ :\
14+
> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup>\
15+
> &nbsp;&nbsp; [_Visibility_]<sup>?</sup>\
16+
> &nbsp;&nbsp; ( [_ConstantItem_] | _Method_ )
17+
>
18+
> _TraitImpl_ :\
19+
> &nbsp;&nbsp; `unsafe`<sup>?</sup> `impl` [_GenericsDecl_] `!`<sup>?</sup>
20+
> [_TypePath_] `for` [_Type_]\
21+
> &nbsp;&nbsp; [_WhereClause_]<sup>?</sup>\
22+
> &nbsp;&nbsp; `{`\
23+
> &nbsp;&nbsp; &nbsp;&nbsp; [_InnerAttribute_]<sup>\*</sup>\
24+
> &nbsp;&nbsp; &nbsp;&nbsp; _TraitImplItem_<sup>\*</sup>\
25+
> &nbsp;&nbsp; `}`
26+
>
27+
> _ImplItem_ :\
28+
> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup>\
29+
> &nbsp;&nbsp; [_Visibility_]<sup>?</sup>\
30+
> &nbsp;&nbsp; ( [_TypeAlias_] | [_ConstantItem_] | _Method_ )
31+
>
32+
> _Method_:\
33+
> &nbsp;&nbsp; _MethodType_ [_BlockWithInnerAttributes_]
34+
>
35+
> _MethodType_:\
36+
> &nbsp;&nbsp; [_FunctionFront_] `fn` [IDENTIFIER]&nbsp;[_Generics_]<sup>?</sup>\
37+
> &nbsp;&nbsp; &nbsp;&nbsp; `(` _MethodParameters_<sup>?</sup> `)`\
38+
> &nbsp;&nbsp; &nbsp;&nbsp; [_FunctionReturnType_]<sup>?</sup> [_WhereClause_]<sup>?</sup>
39+
>
40+
> _MethodParameters_:\
41+
> &nbsp;&nbsp; (_SelfParam_ | [_FunctionParam_] ) (`,` [_FunctionParam_])<sup>\*</sup> `,`<sup>?</sup>
42+
>
43+
> _SelfParam_:\
44+
> &nbsp;&nbsp; &nbsp;&nbsp; (`&` | `&` [_Lifetime_])<sup>?</sup> `mut`<sup>?</sup> `self`\
45+
> &nbsp;&nbsp; | `mut`<sup>?</sup> `self` (`:` [_Type_])<sup>?</sup>
46+
347
An _implementation_ is an item that associates items with an _implementing type_.
448
Implementations are defined with the keyword `impl` and contain functions
549
that belong to an instance of the type that is being implemented or to the
@@ -59,6 +103,9 @@ The path to the associated items is `<` followed by a path to the implementing
59103
type followed by `as` followed by a path to the trait followed by `>` as a path
60104
component followed by the associated item's path component.
61105

106+
[Unsafe traits] require the trait implementation to begin with the `unsafe`
107+
keyword.
108+
62109
```rust
63110
# #[derive(Copy, Clone)]
64111
# struct Point {x: f64, y: f64};
@@ -143,9 +190,26 @@ attributes must come before any associated items. That attributes that have
143190
meaning here are [`cfg`], [`deprecated`], [`doc`], and [the lint check
144191
attributes].
145192

193+
[IDENTIFIER]: identifiers.html
194+
[_BlockWithInnerAttributes_]: items/functions.html
195+
[_ConstantItem_]: items/constant-items.html
196+
[_Generics_]: items/generics.html
197+
[_FunctionFront_]: items/functions.html
198+
[_FunctionParam_]: items/functions.html
199+
[_FunctionReturnType_]: items/functions.html
200+
[_GenericsDecl_]: types.html#type-parameters
201+
[_InnerAttribute_]: attributes.html
202+
[_Lifetime_]: trait-bounds.html
203+
[_OuterAttribute_]: attributes.html
204+
[_Type_]: types.html
205+
[_TypeAlias_]: items/type-aliases.html
206+
[_TypePath_]: paths.html#paths-in-types
207+
[_Visibility_]: visibility-and-privacy.html
208+
[_WhereClause_]: items/generics.html#where-clauses
146209
[trait]: items/traits.html
147210
[attributes]: attributes.html
148211
[`cfg`]: conditional-compilation.html
149212
[`deprecated`]: attributes.html#deprecation
150213
[`doc`]: attributes.html#documentation
151214
[the lint check attributes]: attributes.html#lint-check-attributes
215+
[Unsafe traits]: items/traits.html#unsafe-traits

‎src/items/traits.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,25 @@
11
# Traits
22

3+
> **<sup>Syntax</sup>**\
4+
> _Trait_ :\
5+
> &nbsp;&nbsp; `unsafe`<sup>?</sup> `trait` [IDENTIFIER]&nbsp;
6+
> [_GenericsDecl_]<sup>?</sup>
7+
> [_WhereClause_]<sup>?</sup> `{`\
8+
> &nbsp;&nbsp;&nbsp;&nbsp; _TraitItem_<sup>\*</sup>\
9+
> &nbsp;&nbsp; `}`
10+
>
11+
> _TraitItem_ :\
12+
> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> (_TraitMethod_ | _TraitConst_ | _TraitType_)
13+
>
14+
> _TraitMethod_ :\
15+
> &nbsp;&nbsp; [_MethodType_] `;` | [_Method_]
16+
>
17+
> _TraitConst_ :\
18+
> &nbsp;&nbsp; `const` [IDENTIFIER] ( ( `:` [_Type_] ) ( `=` [_Expression_] )<sup>?</sup> )<sup>?</sup> `;`
19+
>
20+
> _TraitType_ :\
21+
> &nbsp;&nbsp; `type` [IDENTIFIER] ( `:` [_TypeParamBounds_] )<sup>?</sup> `;`
22+
323
A _trait_ describes an abstract interface that types can implement. This
424
interface consists of [associated items], which come in three varieties:
525

@@ -115,6 +135,23 @@ let circle = Box::new(circle) as Box<dyn Circle>;
115135
let nonsense = circle.radius() * circle.area();
116136
```
117137

138+
## Unsafe traits
139+
140+
Traits that begin with the `unsafe` keyword indicate that *implementing* the
141+
trait may be [unsafe]. It is safe to use a correctly implemented unsafe trait.
142+
The [trait implementation] must also include the `unsafe` keyword.
143+
144+
[`Sync`] and [`Send`] are examples of unsafe traits.
145+
146+
[IDENTIFIER]: identifiers.html
147+
[_Expression_]: expressions.html
148+
[_GenericsDecl_]: types.html#type-parameters
149+
[_Method_]: items/implementations.html
150+
[_MethodType_]: items/implementations.html
151+
[_OuterAttribute_]: attributes.html
152+
[_TypeParamBounds_]: trait-bounds.html
153+
[_Type_]: types.html
154+
[_WhereClause_]: items/generics.html#where-clauses
118155
[bounds]: trait-bounds.html
119156
[trait object]: types.html#trait-objects
120157
[explicit]: expressions/operator-expr.html#type-cast-expressions
@@ -125,3 +162,7 @@ let nonsense = circle.radius() * circle.area();
125162
[generics]: items/generics.html
126163
[where clauses]: items/generics.html#where-clauses
127164
[generic functions]: items/functions.html#generic-functions
165+
[unsafe]: unsafety.html
166+
[trait implementation]: items/implementations.html#trait-implementations
167+
[`Send`]: special-types-and-traits.html#send
168+
[`Sync`]: special-types-and-traits.html#sync

‎src/unsafety.md‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,15 @@ guarantees of Rust's static semantics.
66
The following language level features cannot be used in the safe subset of
77
Rust:
88

9-
- Dereferencing a [raw pointer](types.html#pointer-types).
10-
- Reading or writing a [mutable static variable](items/static-items.html#mutable-statics).
11-
- Reading a field of a [`union`](items/unions.html), or writing to a field of a
12-
union that isn't [`Copy`](special-types-and-traits.html#copy).
9+
- Dereferencing a [raw pointer].
10+
- Reading or writing a [mutable static variable].
11+
- Reading a field of a [`union`], or writing to a field of a
12+
union that isn't [`Copy`].
1313
- Calling an unsafe function (including an intrinsic or foreign function).
14-
- Implementing an unsafe trait.
14+
- Implementing an [unsafe trait].
15+
16+
[`Copy`]: special-types-and-traits.html#copy
17+
[`union`]: items/unions.html
18+
[mutable static variable]: items/static-items.html#mutable-statics
19+
[raw pointer]: types.html#pointer-types
20+
[unsafe trait]: items/traits.html#unsafe-traits

0 commit comments

Comments
 (0)