5 This document is the primary reference for the Rust programming language grammar. It
6 provides only one kind of material:
8 - Chapters that formally define the language grammar.
10 This document does not serve as an introduction to the language. Background
11 familiarity with the language is assumed. A separate [guide] is available to
12 help acquire such background.
14 This document also does not serve as a reference to the [standard] library
15 included in the language distribution. Those libraries are documented
16 separately by extracting documentation attributes from their source code. Many
17 of the features that one might expect to be language features are library
18 features in Rust, so what you're looking for may be there, not here.
21 [standard]: std/index.html
25 Rust's grammar is defined over Unicode codepoints, each conventionally denoted
26 `U+XXXX`, for 4 or more hexadecimal digits `X`. _Most_ of Rust's grammar is
27 confined to the ASCII range of Unicode, and is described in this document by a
28 dialect of Extended Backus-Naur Form (EBNF), specifically a dialect of EBNF
29 supported by common automated LL(k) parsing tools such as `llgen`, rather than
30 the dialect given in ISO 14977. The dialect can be defined self-referentially
35 rule : nonterminal ':' productionrule ';' ;
36 productionrule : production [ '|' production ] * ;
38 term : element repeats ;
39 element : LITERAL | IDENTIFIER | '[' productionrule ']' ;
40 repeats : [ '*' | '+' ] NUMBER ? | NUMBER ? | '?' ;
45 - Whitespace in the grammar is ignored.
46 - Square brackets are used to group rules.
47 - `LITERAL` is a single printable ASCII character, or an escaped hexadecimal
48 ASCII code of the form `\xQQ`, in single quotes, denoting the corresponding
49 Unicode codepoint `U+00QQ`.
50 - `IDENTIFIER` is a nonempty string of ASCII letters and underscores.
51 - The `repeat` forms apply to the adjacent `element`, and are as follows:
52 - `?` means zero or one repetition
53 - `*` means zero or more repetitions
54 - `+` means one or more repetitions
55 - NUMBER trailing a repeat symbol gives a maximum repetition count
56 - NUMBER on its own gives an exact repetition count
58 This EBNF dialect should hopefully be familiar to many readers.
60 ## Unicode productions
62 A few productions in Rust's grammar permit Unicode codepoints outside the ASCII
63 range. We define these productions in terms of character properties specified
64 in the Unicode standard, rather than in terms of ASCII-range codepoints. The
65 section [Special Unicode Productions](#special-unicode-productions) lists these
68 ## String table productions
70 Some rules in the grammar — notably [unary
71 operators](#unary-operator-expressions), [binary
72 operators](#binary-operator-expressions), and [keywords](#keywords) — are
73 given in a simplified form: as a listing of a table of unquoted, printable
74 whitespace-separated strings. These cases form a subset of the rules regarding
75 the [token](#tokens) rule, and are assumed to be the result of a
76 lexical-analysis phase feeding the parser, driven by a DFA, operating over the
77 disjunction of all such string table entries.
79 When such a string enclosed in double-quotes (`"`) occurs inside the grammar,
80 it is an implicit reference to a single member of such a string table
81 production. See [tokens](#tokens) for more information.
87 Rust input is interpreted as a sequence of Unicode codepoints encoded in UTF-8.
88 Most Rust grammar rules are defined in terms of printable ASCII-range
89 codepoints, but a small number are defined in terms of Unicode properties or
90 explicit codepoint lists. [^inputformat]
92 [^inputformat]: Substitute definitions for the special Unicode productions are
93 provided to the grammar verifier, restricted to ASCII range, when verifying the
94 grammar in this document.
96 ## Special Unicode Productions
98 The following productions in the Rust grammar are defined in terms of Unicode
99 properties: `ident`, `non_null`, `non_eol`, `non_single_quote` and
104 The `ident` production is any nonempty Unicode[^non_ascii_idents] string of
107 [^non_ascii_idents]: Non-ASCII characters in identifiers are currently feature
108 gated. This is expected to improve soon.
110 - The first character has property `XID_start`
111 - The remaining characters have property `XID_continue`
113 that does _not_ occur in the set of [keywords](#keywords).
115 > **Note**: `XID_start` and `XID_continue` as character properties cover the
116 > character ranges used to form the more familiar C and Java language-family
119 ### Delimiter-restricted productions
121 Some productions are defined by exclusion of particular Unicode characters:
123 - `non_null` is any single Unicode character aside from `U+0000` (null)
124 - `non_eol` is `non_null` restricted to exclude `U+000A` (`'\n'`)
125 - `non_single_quote` is `non_null` restricted to exclude `U+0027` (`'`)
126 - `non_double_quote` is `non_null` restricted to exclude `U+0022` (`"`)
131 comment : block_comment | line_comment ;
132 block_comment : "/*" block_comment_body * "*/" ;
133 block_comment_body : [block_comment | character] * ;
134 line_comment : "//" non_eol * ;
137 **FIXME:** add doc grammar?
142 whitespace_char : '\x20' | '\x09' | '\x0a' | '\x0d' ;
143 whitespace : [ whitespace_char | comment ] + ;
149 simple_token : keyword | unop | binop ;
150 token : simple_token | ident | literal | symbol | whitespace token ;
155 <p id="keyword-table-marker"></p>
158 |----------|----------|----------|----------|---------|
159 | abstract | alignof | as | become | box |
160 | break | const | continue | crate | do |
161 | else | enum | extern | false | final |
162 | fn | for | if | impl | in |
163 | let | loop | macro | match | mod |
164 | move | mut | offsetof | override | priv |
165 | proc | pub | pure | ref | return |
166 | Self | self | sizeof | static | struct |
167 | super | trait | true | type | typeof |
168 | unsafe | unsized | use | virtual | where |
169 | while | yield | | | |
172 Each of these keywords has special meaning in its grammar, and all of them are
173 excluded from the `ident` rule.
179 literal : [ string_lit | char_lit | byte_string_lit | byte_lit | num_lit | bool_lit ] lit_suffix ?;
182 The optional `lit_suffix` production is only used for certain numeric literals,
183 but is reserved for future extension. That is, the above gives the lexical
184 grammar, but a Rust parser will reject everything but the 12 special cases
185 mentioned in [Number literals](reference.html#number-literals) in the
188 #### Character and string literals
191 char_lit : '\x27' char_body '\x27' ;
192 string_lit : '"' string_body * '"' | 'r' raw_string ;
194 char_body : non_single_quote
195 | '\x5c' [ '\x27' | common_escape | unicode_escape ] ;
197 string_body : non_double_quote
198 | '\x5c' [ '\x22' | common_escape | unicode_escape ] ;
199 raw_string : '"' raw_string_body '"' | '#' raw_string '#' ;
201 common_escape : '\x5c'
202 | 'n' | 'r' | 't' | '0'
204 unicode_escape : 'u' '{' hex_digit+ 6 '}';
206 hex_digit : 'a' | 'b' | 'c' | 'd' | 'e' | 'f'
207 | 'A' | 'B' | 'C' | 'D' | 'E' | 'F'
209 oct_digit : '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' ;
210 dec_digit : '0' | nonzero_dec ;
211 nonzero_dec: '1' | '2' | '3' | '4'
212 | '5' | '6' | '7' | '8' | '9' ;
215 #### Byte and byte string literals
218 byte_lit : "b\x27" byte_body '\x27' ;
219 byte_string_lit : "b\x22" string_body * '\x22' | "br" raw_byte_string ;
221 byte_body : ascii_non_single_quote
222 | '\x5c' [ '\x27' | common_escape ] ;
224 byte_string_body : ascii_non_double_quote
225 | '\x5c' [ '\x22' | common_escape ] ;
226 raw_byte_string : '"' raw_byte_string_body '"' | '#' raw_byte_string '#' ;
233 num_lit : nonzero_dec [ dec_digit | '_' ] * float_suffix ?
234 | '0' [ [ dec_digit | '_' ] * float_suffix ?
235 | 'b' [ '1' | '0' | '_' ] +
236 | 'o' [ oct_digit | '_' ] +
237 | 'x' [ hex_digit | '_' ] + ] ;
239 float_suffix : [ exponent | '.' dec_lit exponent ? ] ? ;
241 exponent : ['E' | 'e'] ['-' | '+' ] ? dec_lit ;
242 dec_lit : [ dec_digit | '_' ] + ;
245 #### Boolean literals
248 bool_lit : [ "true" | "false" ] ;
251 The two values of the boolean type are written `true` and `false`.
257 | '#' | '[' | ']' | '(' | ')' | '{' | '}'
261 Symbols are a general class of printable [token](#tokens) that play structural
262 roles in a variety of grammar productions. They are catalogued here for
263 completeness as the set of remaining miscellaneous printable tokens that do not
264 otherwise appear as [unary operators](#unary-operator-expressions), [binary
265 operators](#binary-operator-expressions), or [keywords](#keywords).
270 expr_path : [ "::" ] ident [ "::" expr_path_tail ] + ;
271 expr_path_tail : '<' type_expr [ ',' type_expr ] + '>'
274 type_path : ident [ type_path_tail ] + ;
275 type_path_tail : '<' type_expr [ ',' type_expr ] + '>'
284 expr_macro_rules : "macro_rules" '!' ident '(' macro_rule * ')' ';'
285 | "macro_rules" '!' ident '{' macro_rule * '}' ;
286 macro_rule : '(' matcher * ')' "=>" '(' transcriber * ')' ';' ;
287 matcher : '(' matcher * ')' | '[' matcher * ']'
288 | '{' matcher * '}' | '$' ident ':' ident
289 | '$' '(' matcher * ')' sep_token? [ '*' | '+' ]
290 | non_special_token ;
291 transcriber : '(' transcriber * ')' | '[' transcriber * ']'
292 | '{' transcriber * '}' | '$' ident
293 | '$' '(' transcriber * ')' sep_token? [ '*' | '+' ]
294 | non_special_token ;
297 # Crates and source files
299 **FIXME:** grammar? What production covers #![crate_id = "foo"] ?
301 # Items and attributes
308 item : vis ? mod_item | fn_item | type_item | struct_item | enum_item
309 | const_item | static_item | trait_item | impl_item | extern_block_item ;
319 mod_item : "mod" ident ( ';' | '{' mod '}' );
320 mod : [ view_item | item ] * ;
326 view_item : extern_crate_decl | use_decl ';' ;
329 ##### Extern crate declarations
332 extern_crate_decl : "extern" "crate" crate_name
333 crate_name: ident | ( ident "as" ident )
336 ##### Use declarations
339 use_decl : vis ? "use" [ path "as" ident
342 path_glob : ident [ "::" [ path_glob
344 | '{' path_item [ ',' path_item ] * '}' ;
346 path_item : ident | "self" ;
353 #### Generic functions
361 ##### Unsafe functions
369 #### Diverging functions
388 const_item : "const" ident ':' type '=' expr ';' ;
394 static_item : "static" ident ':' type '=' expr ';' ;
412 extern_block_item : "extern" '{' extern_block '}' ;
413 extern_block : [ foreign_fn ] * ;
416 ## Visibility and Privacy
421 ### Re-exporting and Visibility
423 See [Use declarations](#use-declarations).
428 attribute : '#' '!' ? '[' meta_item ']' ;
429 meta_item : ident [ '=' literal
430 | '(' meta_seq ')' ] ? ;
431 meta_seq : meta_item [ ',' meta_seq ] ? ;
434 # Statements and expressions
439 stmt : decl_stmt | expr_stmt ;
442 ### Declaration statements
445 decl_stmt : item | let_decl ;
448 #### Item declarations
452 #### Variable declarations
455 let_decl : "let" pat [':' type ] ? [ init ] ? ';' ;
456 init : [ '=' ] expr ;
459 ### Expression statements
462 expr_stmt : expr ';' ;
468 expr : literal | path | tuple_expr | unit_expr | struct_expr
469 | block_expr | method_call_expr | field_expr | array_expr
470 | idx_expr | range_expr | unop_expr | binop_expr
471 | paren_expr | call_expr | lambda_expr | while_expr
472 | loop_expr | break_expr | continue_expr | for_expr
473 | if_expr | match_expr | if_let_expr | while_let_expr
477 #### Lvalues, rvalues and temporaries
481 #### Moved and copied types
483 **FIXME:** Do we want to capture this in the grammar as different productions?
485 ### Literal expressions
487 See [Literals](#literals).
493 ### Tuple expressions
496 tuple_expr : '(' [ expr [ ',' expr ] * | expr ',' ] ? ')' ;
505 ### Structure expressions
508 struct_expr : expr_path '{' ident ':' expr
509 [ ',' ident ':' expr ] *
516 ### Block expressions
519 block_expr : '{' [ stmt ';' | item ] *
523 ### Method-call expressions
526 method_call_expr : expr '.' ident paren_expr_list ;
529 ### Field expressions
532 field_expr : expr '.' ident ;
535 ### Array expressions
538 array_expr : '[' "mut" ? array_elems? ']' ;
540 array_elems : [expr [',' expr]*] | [expr ';' expr] ;
543 ### Index expressions
546 idx_expr : expr '[' expr ']' ;
549 ### Range expressions
552 range_expr : expr ".." expr |
558 ### Unary operator expressions
561 unop_expr : unop expr ;
562 unop : '-' | '*' | '!' ;
565 ### Binary operator expressions
568 binop_expr : expr binop expr | type_cast_expr
569 | assignment_expr | compound_assignment_expr ;
570 binop : arith_op | bitwise_op | lazy_bool_op | comp_op
573 #### Arithmetic operators
576 arith_op : '+' | '-' | '*' | '/' | '%' ;
579 #### Bitwise operators
582 bitwise_op : '&' | '|' | '^' | "<<" | ">>" ;
585 #### Lazy boolean operators
588 lazy_bool_op : "&&" | "||" ;
591 #### Comparison operators
594 comp_op : "==" | "!=" | '<' | '>' | "<=" | ">=" ;
597 #### Type cast expressions
600 type_cast_expr : value "as" type ;
603 #### Assignment expressions
606 assignment_expr : expr '=' expr ;
609 #### Compound assignment expressions
612 compound_assignment_expr : expr [ arith_op | bitwise_op ] '=' expr ;
615 ### Grouped expressions
618 paren_expr : '(' expr ')' ;
624 expr_list : [ expr [ ',' expr ]* ] ? ;
625 paren_expr_list : '(' expr_list ')' ;
626 call_expr : expr paren_expr_list ;
629 ### Lambda expressions
632 ident_list : [ ident [ ',' ident ]* ] ? ;
633 lambda_expr : '|' ident_list '|' expr ;
639 while_expr : [ lifetime ':' ] ? "while" no_struct_literal_expr '{' block '}' ;
645 loop_expr : [ lifetime ':' ] ? "loop" '{' block '}';
648 ### Break expressions
651 break_expr : "break" [ lifetime ] ?;
654 ### Continue expressions
657 continue_expr : "continue" [ lifetime ] ?;
663 for_expr : [ lifetime ':' ] ? "for" pat "in" no_struct_literal_expr '{' block '}' ;
669 if_expr : "if" no_struct_literal_expr '{' block '}'
672 else_tail : "else" [ if_expr | if_let_expr
676 ### Match expressions
679 match_expr : "match" no_struct_literal_expr '{' match_arm * '}' ;
681 match_arm : attribute * match_pat "=>" [ expr "," | '{' block '}' ] ;
683 match_pat : pat [ '|' pat ] * [ "if" expr ] ? ;
686 ### If let expressions
689 if_let_expr : "if" "let" pat '=' expr '{' block '}'
696 while_let_expr : [ lifetime ':' ] ? "while" "let" pat '=' expr '{' block '}' ;
699 ### Return expressions
702 return_expr : "return" expr ? ;
707 **FIXME:** is this entire chapter relevant here? Or should it all have been covered by some production already?
719 #### Machine-dependent integer types
731 ### Array, and Slice types
754 closure_type := [ 'unsafe' ] [ '<' lifetime-list '>' ] '|' arg-list '|'
755 [ ':' bound-list ] [ '->' type ]
756 lifetime-list := lifetime | lifetime ',' lifetime-list
757 arg-list := ident ':' type | ident ':' type ',' arg-list
758 bound-list := bound | bound '+' bound-list
759 bound := path | lifetime
776 **FIXME:** this is probably not relevant to the grammar...
778 # Memory and concurrency models
780 **FIXME:** is this entire chapter relevant here? Or should it all have been covered by some production already?
784 ### Memory allocation and lifetime
794 ### Communication between threads