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 familiarity.
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_rule : '(' matcher * ')' "=>" '(' transcriber * ')' ';' ;
286 matcher : '(' matcher * ')' | '[' matcher * ']'
287 | '{' matcher * '}' | '$' ident ':' ident
288 | '$' '(' matcher * ')' sep_token? [ '*' | '+' ]
289 | non_special_token ;
290 transcriber : '(' transcriber * ')' | '[' transcriber * ']'
291 | '{' transcriber * '}' | '$' ident
292 | '$' '(' transcriber * ')' sep_token? [ '*' | '+' ]
293 | non_special_token ;
296 # Crates and source files
298 **FIXME:** grammar? What production covers #![crate_id = "foo"] ?
300 # Items and attributes
307 item : vis ? mod_item | fn_item | type_item | struct_item | enum_item
308 | const_item | static_item | trait_item | impl_item | extern_block ;
318 mod_item : "mod" ident ( ';' | '{' mod '}' );
319 mod : [ view_item | item ] * ;
325 view_item : extern_crate_decl | use_decl ';' ;
328 ##### Extern crate declarations
331 extern_crate_decl : "extern" "crate" crate_name
332 crate_name: ident | ( ident "as" ident )
335 ##### Use declarations
338 use_decl : vis ? "use" [ path "as" ident
341 path_glob : ident [ "::" [ path_glob
343 | '{' path_item [ ',' path_item ] * '}' ;
345 path_item : ident | "self" ;
352 #### Generic functions
360 ##### Unsafe functions
368 #### Diverging functions
387 const_item : "const" ident ':' type '=' expr ';' ;
393 static_item : "static" ident ':' type '=' expr ';' ;
411 extern_block_item : "extern" '{' extern_block '}' ;
412 extern_block : [ foreign_fn ] * ;
415 ## Visibility and Privacy
420 ### Re-exporting and Visibility
422 See [Use declarations](#use-declarations).
427 attribute : '#' '!' ? '[' meta_item ']' ;
428 meta_item : ident [ '=' literal
429 | '(' meta_seq ')' ] ? ;
430 meta_seq : meta_item [ ',' meta_seq ] ? ;
433 # Statements and expressions
438 stmt : decl_stmt | expr_stmt ;
441 ### Declaration statements
444 decl_stmt : item | let_decl ;
447 #### Item declarations
451 #### Variable declarations
454 let_decl : "let" pat [':' type ] ? [ init ] ? ';' ;
455 init : [ '=' ] expr ;
458 ### Expression statements
461 expr_stmt : expr ';' ;
467 expr : literal | path | tuple_expr | unit_expr | struct_expr
468 | block_expr | method_call_expr | field_expr | array_expr
469 | idx_expr | range_expr | unop_expr | binop_expr
470 | paren_expr | call_expr | lambda_expr | while_expr
471 | loop_expr | break_expr | continue_expr | for_expr
472 | if_expr | match_expr | if_let_expr | while_let_expr
476 #### Lvalues, rvalues and temporaries
480 #### Moved and copied types
482 **FIXME:** Do we want to capture this in the grammar as different productions?
484 ### Literal expressions
486 See [Literals](#literals).
492 ### Tuple expressions
495 tuple_expr : '(' [ expr [ ',' expr ] * | expr ',' ] ? ')' ;
504 ### Structure expressions
507 struct_expr : expr_path '{' ident ':' expr
508 [ ',' ident ':' expr ] *
515 ### Block expressions
518 block_expr : '{' [ stmt ';' | item ] *
522 ### Method-call expressions
525 method_call_expr : expr '.' ident paren_expr_list ;
528 ### Field expressions
531 field_expr : expr '.' ident ;
534 ### Array expressions
537 array_expr : '[' "mut" ? array_elems? ']' ;
539 array_elems : [expr [',' expr]*] | [expr ';' expr] ;
542 ### Index expressions
545 idx_expr : expr '[' expr ']' ;
548 ### Range expressions
551 range_expr : expr ".." expr |
557 ### Unary operator expressions
560 unop_expr : unop expr ;
561 unop : '-' | '*' | '!' ;
564 ### Binary operator expressions
567 binop_expr : expr binop expr | type_cast_expr
568 | assignment_expr | compound_assignment_expr ;
569 binop : arith_op | bitwise_op | lazy_bool_op | comp_op
572 #### Arithmetic operators
575 arith_op : '+' | '-' | '*' | '/' | '%' ;
578 #### Bitwise operators
581 bitwise_op : '&' | '|' | '^' | "<<" | ">>" ;
584 #### Lazy boolean operators
587 lazy_bool_op : "&&" | "||" ;
590 #### Comparison operators
593 comp_op : "==" | "!=" | '<' | '>' | "<=" | ">=" ;
596 #### Type cast expressions
599 type_cast_expr : value "as" type ;
602 #### Assignment expressions
605 assignment_expr : expr '=' expr ;
608 #### Compound assignment expressions
611 compound_assignment_expr : expr [ arith_op | bitwise_op ] '=' expr ;
614 ### Grouped expressions
617 paren_expr : '(' expr ')' ;
623 expr_list : [ expr [ ',' expr ]* ] ? ;
624 paren_expr_list : '(' expr_list ')' ;
625 call_expr : expr paren_expr_list ;
628 ### Lambda expressions
631 ident_list : [ ident [ ',' ident ]* ] ? ;
632 lambda_expr : '|' ident_list '|' expr ;
638 while_expr : [ lifetime ':' ] "while" no_struct_literal_expr '{' block '}' ;
644 loop_expr : [ lifetime ':' ] "loop" '{' block '}';
647 ### Break expressions
650 break_expr : "break" [ lifetime ];
653 ### Continue expressions
656 continue_expr : "continue" [ lifetime ];
662 for_expr : [ lifetime ':' ] "for" pat "in" no_struct_literal_expr '{' block '}' ;
668 if_expr : "if" no_struct_literal_expr '{' block '}'
671 else_tail : "else" [ if_expr | if_let_expr
675 ### Match expressions
678 match_expr : "match" no_struct_literal_expr '{' match_arm * '}' ;
680 match_arm : attribute * match_pat "=>" [ expr "," | '{' block '}' ] ;
682 match_pat : pat [ '|' pat ] * [ "if" expr ] ? ;
685 ### If let expressions
688 if_let_expr : "if" "let" pat '=' expr '{' block '}'
690 else_tail : "else" [ if_expr | if_let_expr | '{' block '}' ] ;
696 while_let_expr : "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 procedure_type := 'proc' [ '<' lifetime-list '>' ] '(' arg-list ')'
757 [ ':' bound-list ] [ '->' type ]
758 lifetime-list := lifetime | lifetime ',' lifetime-list
759 arg-list := ident ':' type | ident ':' type ',' arg-list
760 bound-list := bound | bound '+' bound-list
761 bound := path | lifetime
778 **FIXME:** this this probably not relevant to the grammar...
780 # Memory and concurrency models
782 **FIXME:** is this entire chapter relevant here? Or should it all have been covered by some production already?
786 ### Memory allocation and lifetime
796 ### Communication between threads