Merge pull request #927 from ehuss/unified-fn-grammar

Update grammar for parser unification.

src/items/associated-items.md

@@ -1,5 +1,12 @@
 # Associated Items
 
+> **<sup>Syntax</sup>**\
+> _AssociatedItem_ :\
+> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> (\
+> &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; [_MacroInvocationSemi_]\
+> &nbsp;&nbsp; &nbsp;&nbsp; | ( [_Visibility_]<sup>?</sup> ( [_TypeAlias_] | [_ConstantItem_] | [_Function_] ) )\
+> &nbsp;&nbsp; )
+
 *Associated Items* are the items declared in [traits] or defined in
 [implementations]. They are called this because they are defined on an associate
 type &mdash; the type in the implementation. They are a subset of the kinds of
@@ -79,21 +86,6 @@ let _: f64 = f64::from_i32(42);
 
 ### Methods
 
-> _Method_ :\
-> &nbsp;&nbsp; [_FunctionQualifiers_] `fn` [IDENTIFIER]&nbsp;[_GenericParams_]<sup>?</sup>\
-> &nbsp;&nbsp; &nbsp;&nbsp; `(` _SelfParam_ (`,` [_FunctionParam_])<sup>\*</sup> `,`<sup>?</sup> `)`\
-> &nbsp;&nbsp; &nbsp;&nbsp; [_FunctionReturnType_]<sup>?</sup> [_WhereClause_]<sup>?</sup>\
-> &nbsp;&nbsp; &nbsp;&nbsp; [_BlockExpression_]
->
-> _SelfParam_ :\
-> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> ( _ShorthandSelf_ | _TypedSelf_ )
->
-> _ShorthandSelf_ :\
-> &nbsp;&nbsp;  (`&` | `&` [_Lifetime_])<sup>?</sup> `mut`<sup>?</sup> `self`
->
-> _TypedSelf_ :\
-> &nbsp;&nbsp; `mut`<sup>?</sup> `self` `:` [_Type_]
-
 Associated functions whose first parameter is named `self` are called *methods*
 and may be invoked using the [method call operator], for example, `x.foo()`, as
 well as the usual function call notation.
@@ -227,6 +219,8 @@ If a type `Item` has an associated type `Assoc` from a trait `Trait`, then
 associated type definition. Furthermore, if `Item` is a type parameter, then
 `Item::Assoc` can be used in type parameters.
 
+Associated types must not include [generic parameters] or [where clauses].
+
 ```rust
 trait AssociatedType {
     // Associated type declaration
@@ -340,19 +334,16 @@ fn main() {
 }
 ```
 
-[_BlockExpression_]: ../expressions/block-expr.md
-[_FunctionParam_]: functions.md
-[_FunctionQualifiers_]: functions.md
-[_FunctionReturnType_]: functions.md
-[_GenericParams_]: generics.md
-[_Lifetime_]: ../trait-bounds.md
-[_Type_]: ../types.md#type-expressions
-[_WhereClause_]: generics.md#where-clauses
+[_ConstantItem_]: constant-items.md
+[_Function_]: functions.md
+[_MacroInvocationSemi_]: ../macros.md#macro-invocation
+[_OuterAttribute_]: ../attributes.md
+[_TypeAlias_]: type-aliases.md
+[_Visibility_]: ../visibility-and-privacy.md
 [`Arc<Self>`]: ../special-types-and-traits.md#arct
 [`Box<Self>`]: ../special-types-and-traits.md#boxt
 [`Pin<P>`]: ../special-types-and-traits.md#pinp
 [`Rc<Self>`]: ../special-types-and-traits.md#rct
-[_OuterAttribute_]: ../attributes.md
 [traits]: traits.md
 [type aliases]: type-aliases.md
 [inherent implementations]: implementations.md#inherent-implementations
@@ -367,3 +358,5 @@ fn main() {
 [method call operator]: ../expressions/method-call-expr.md
 [path]: ../paths.md
 [regular function parameters]: functions.md#attributes-on-function-parameters
+[generic parameters]: generics.md
+[where clauses]: generics.md#where-clauses

src/items/constant-items.md

@@ -2,7 +2,7 @@
 
 > **<sup>Syntax</sup>**\
 > _ConstantItem_ :\
-> &nbsp;&nbsp; `const` ( [IDENTIFIER] | `_` ) `:` [_Type_] `=` [_Expression_] `;`
+> &nbsp;&nbsp; `const` ( [IDENTIFIER] | `_` ) `:` [_Type_] ( `=` [_Expression_] )<sup>?</sup> `;`
 
 A *constant item* is an optionally named _[constant value]_ which is not associated
 with a specific memory location in the program. Constants are essentially inlined
@@ -38,6 +38,8 @@ const BITS_N_STRINGS: BitsNStrings<'static> = BitsNStrings {
 };
 ```
 
+The constant expression may only be omitted in a [trait definition].
+
 ## Constants with Destructors
 
 Constants can contain destructors. Destructors are run when the value goes out
@@ -91,6 +93,7 @@ m!(const _: () = (););
 [constant value]: ../const_eval.md#constant-expressions
 [free]: ../glossary.md#free-item
 [static lifetime elision]: ../lifetime-elision.md#static-lifetime-elision
+[trait definition]: traits.md
 [IDENTIFIER]: ../identifiers.md
 [underscore imports]: use-declarations.md#underscore-imports
 [_Type_]: ../types.md#type-expressions

src/items/external-blocks.md

@@ -10,25 +10,8 @@
 > _ExternalItem_ :\
 > &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> (\
 > &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; [_MacroInvocationSemi_]\
-> &nbsp;&nbsp; &nbsp;&nbsp; | ( [_Visibility_]<sup>?</sup> ( _ExternalStaticItem_ | _ExternalFunctionItem_ ) )\
+> &nbsp;&nbsp; &nbsp;&nbsp; | ( [_Visibility_]<sup>?</sup> ( [_StaticItem_] | [_Function_] ) )\
 > &nbsp;&nbsp; )
->
-> _ExternalStaticItem_ :\
-> &nbsp;&nbsp; `static` `mut`<sup>?</sup> [IDENTIFIER] `:` [_Type_] `;`
->
-> _ExternalFunctionItem_ :\
-> &nbsp;&nbsp; `fn` [IDENTIFIER]&nbsp;[_GenericParams_]<sup>?</sup>\
-> &nbsp;&nbsp; `(` ( _NamedFunctionParameters_ | _NamedFunctionParametersWithVariadics_ )<sup>?</sup> `)`\
-> &nbsp;&nbsp; [_FunctionReturnType_]<sup>?</sup> [_WhereClause_]<sup>?</sup> `;`
->
-> _NamedFunctionParameters_ :\
-> &nbsp;&nbsp; _NamedFunctionParam_ ( `,` _NamedFunctionParam_ )<sup>\*</sup> `,`<sup>?</sup>
->
-> _NamedFunctionParam_ :\
-> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> ( [IDENTIFIER] | `_` ) `:` [_Type_]
->
-> _NamedFunctionParametersWithVariadics_ :\
-> &nbsp;&nbsp; ( _NamedFunctionParam_ `,` )<sup>\*</sup> _NamedFunctionParam_ `,` [_OuterAttribute_]<sup>\*</sup> `...`
 
 External blocks provide _declarations_ of items that are not _defined_ in the
 current crate and are the basis of Rust's foreign function interface. These are
@@ -46,9 +29,10 @@ token stream.
 ## Functions
 
 Functions within external blocks are declared in the same way as other Rust
-functions, with the exception that they may not have a body and are instead
+functions, with the exception that they must not have a body and are instead
 terminated by a semicolon. Patterns are not allowed in parameters, only
-[IDENTIFIER] or `_` may be used.
+[IDENTIFIER] or `_` may be used. Function qualifiers (`const`, `async`,
+`unsafe`, and `extern`) are not allowed.
 
 Functions within external blocks may be called by Rust code, just like
 functions defined in Rust. The Rust compiler automatically translates between
@@ -109,12 +93,15 @@ There are also some platform-specific ABI strings:
 
 ## Variadic functions
 
-Functions within external blocks may be variadic by specifying `...` after one
-or more named arguments in the argument list:
+Functions within external blocks may be variadic by specifying `...` as the
+last argument. There must be at least one parameter before the variadic
+parameter. The variadic parameter may optionally be specified with an
+identifier.
 
 ```rust
-extern {
+extern "C" {
     fn foo(x: i32, ...);
+    fn with_name(format: *const u8, args: ...);
 }
 ```
 
@@ -189,15 +176,13 @@ restrictions as [regular function parameters].
 [functions]: functions.md
 [statics]: static-items.md
 [_Abi_]: functions.md
-[_FunctionReturnType_]: functions.md
-[_GenericParams_]: generics.md
+[_Function_]: functions.md
 [_InnerAttribute_]: ../attributes.md
 [_MacroInvocationSemi_]: ../macros.md#macro-invocation
 [_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax
 [_MetaNameValueStr_]: ../attributes.md#meta-item-attribute-syntax
 [_OuterAttribute_]: ../attributes.md
-[_Type_]: ../types.md#type-expressions
+[_StaticItem_]: static-items.md
 [_Visibility_]: ../visibility-and-privacy.md
-[_WhereClause_]: generics.md#where-clauses
 [attributes]: ../attributes.md
 [regular function parameters]: functions.md#attributes-on-function-parameters

src/items/functions.md

@@ -5,25 +5,42 @@
 > &nbsp;&nbsp; _FunctionQualifiers_ `fn` [IDENTIFIER]&nbsp;[_GenericParams_]<sup>?</sup>\
 > &nbsp;&nbsp; &nbsp;&nbsp; `(` _FunctionParameters_<sup>?</sup> `)`\
 > &nbsp;&nbsp; &nbsp;&nbsp; _FunctionReturnType_<sup>?</sup> [_WhereClause_]<sup>?</sup>\
-> &nbsp;&nbsp; &nbsp;&nbsp; [_BlockExpression_]
+> &nbsp;&nbsp; &nbsp;&nbsp; ( [_BlockExpression_] | `;` )
 >
 > _FunctionQualifiers_ :\
-> &nbsp;&nbsp; _AsyncConstQualifiers_<sup>?</sup> `unsafe`<sup>?</sup> (`extern` _Abi_<sup>?</sup>)<sup>?</sup>
->
-> _AsyncConstQualifiers_ :\
-> &nbsp;&nbsp; `async` | `const`
+> &nbsp;&nbsp; `const`<sup>?</sup> `async`[^async-edition]<sup>?</sup> `unsafe`<sup>?</sup> (`extern` _Abi_<sup>?</sup>)<sup>?</sup>
 >
 > _Abi_ :\
 > &nbsp;&nbsp; [STRING_LITERAL] | [RAW_STRING_LITERAL]
 >
 > _FunctionParameters_ :\
-> &nbsp;&nbsp; _FunctionParam_ (`,` _FunctionParam_)<sup>\*</sup> `,`<sup>?</sup>
+> &nbsp;&nbsp; &nbsp;&nbsp; _SelfParam_ `,`<sup>?</sup>\
+> &nbsp;&nbsp; | (_SelfParam_ `,`)<sup>?</sup> _FunctionParam_ (`,` _FunctionParam_)<sup>\*</sup> `,`<sup>?</sup>
+>
+> _SelfParam_ :\
+> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> ( _ShorthandSelf_ | _TypedSelf_ )
+>
+> _ShorthandSelf_ :\
+> &nbsp;&nbsp;  (`&` | `&` [_Lifetime_])<sup>?</sup> `mut`<sup>?</sup> `self`
+>
+> _TypedSelf_ :\
+> &nbsp;&nbsp; `mut`<sup>?</sup> `self` `:` [_Type_]
 >
 > _FunctionParam_ :\
-> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> [_Pattern_] `:` [_Type_]
+> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> (
+>   _FunctionParamPattern_ | `...` | [_Type_] [^fn-param-2015]
+> )
+>
+> _FunctionParamPattern_ :\
+> &nbsp;&nbsp; [_Pattern_] `:` ( [_Type_] | `...` )
 >
 > _FunctionReturnType_ :\
 > &nbsp;&nbsp; `->` [_Type_]
+>
+> [^async-edition]: The `async` qualifier is not allowed in the 2015 edition.
+>
+> [^fn-param-2015]: Function parameters with only a type are only allowed
+>   in an associated function of a [trait item] in the 2015 edition.
 
 A _function_ consists of a [block], along with a name and a set of parameters.
 Other than a name, all these are optional. Functions are declared with the
@@ -43,13 +60,25 @@ fn answer_to_life_the_universe_and_everything() -> i32 {
 }
 ```
 
-As with `let` bindings, function arguments are irrefutable [patterns], so any
+## Function parameters
+
+As with `let` bindings, function parameters are irrefutable [patterns], so any
 pattern that is valid in a let binding is also valid as an argument:
 
 ```rust
 fn first((value, _): (i32, i32)) -> i32 { value }
 ```
 
+If the first parameter is a _SelfParam_, this indicates that the function is a
+[method]. Functions with a self parameter may only appear as an [associated
+function] in a [trait] or [implementation].
+
+A parameter with the `...` token indicates a [variadic function], and may only
+be used as the last parameter of a [external block] function. The variadic
+parameter may have an optional identifier, such as `args: ...`.
+
+## Function body
+
 The block of a function is conceptually wrapped in a block that binds the
 argument patterns and then `return`s the value of the function's block. This
 means that the tail expression of the block, if evaluated, ends up being
@@ -67,6 +96,9 @@ return {
 };
 ```
 
+Functions without a body block are terminated with a semicolon. This form
+may only appear in a [trait] or [external block].
+
 ## Generic functions
 
 A _generic function_ allows one or more _parameterized types_ to appear in its
@@ -187,6 +219,9 @@ Functions qualified with the `const` keyword are [const functions], as are
 [tuple struct] and [tuple variant] constructors. _Const functions_  can be
 called from within [const context]s.
 
+Const functions are not allowed to be [async](#async-functions), and cannot
+use the [`extern` function qualifier](#extern-function-qualifier).
+
 ## Async functions
 
 Functions may be qualified as async, and this can also be combined with the
@@ -342,6 +377,7 @@ fn foo_oof(#[some_inert_attribute] arg: u8) {
 [STRING_LITERAL]: ../tokens.md#string-literals
 [_BlockExpression_]: ../expressions/block-expr.md
 [_GenericParams_]: generics.md
+[_Lifetime_]: ../trait-bounds.md
 [_Pattern_]: ../patterns.md
 [_Type_]: ../types.md#type-expressions
 [_WhereClause_]: generics.md#where-clauses
@@ -372,3 +408,8 @@ fn foo_oof(#[some_inert_attribute] arg: u8) {
 [`link_section`]: ../abi.md#the-link_section-attribute
 [`no_mangle`]: ../abi.md#the-no_mangle-attribute
 [built-in attributes]: ../attributes.html#built-in-attributes-index
+[trait item]: traits.md
+[method]: associated-items.md#methods
+[associated function]: associated-items.md#associated-functions-and-methods
+[implementation]: implementations.md
+[variadic function]: external-blocks.md#variadic-functions

src/items/implementations.md

@@ -7,29 +7,17 @@
 > _InherentImpl_ :\
 > &nbsp;&nbsp; `impl` [_GenericParams_]<sup>?</sup>&nbsp;[_Type_]&nbsp;[_WhereClause_]<sup>?</sup> `{`\
 > &nbsp;&nbsp; &nbsp;&nbsp; [_InnerAttribute_]<sup>\*</sup>\
-> &nbsp;&nbsp; &nbsp;&nbsp; _InherentImplItem_<sup>\*</sup>\
+> &nbsp;&nbsp; &nbsp;&nbsp; [_AssociatedItem_]<sup>\*</sup>\
 > &nbsp;&nbsp; `}`
 >
-> _InherentImplItem_ :\
-> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> (\
-> &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; [_MacroInvocationSemi_]\
-> &nbsp;&nbsp; &nbsp;&nbsp; | ( [_Visibility_]<sup>?</sup> ( [_ConstantItem_] | [_Function_] | [_Method_] ) )\
-> &nbsp;&nbsp; )
->
 > _TraitImpl_ :\
 > &nbsp;&nbsp; `unsafe`<sup>?</sup> `impl` [_GenericParams_]<sup>?</sup> `!`<sup>?</sup>
 >              [_TypePath_] `for` [_Type_]\
 > &nbsp;&nbsp; [_WhereClause_]<sup>?</sup>\
 > &nbsp;&nbsp; `{`\
 > &nbsp;&nbsp; &nbsp;&nbsp; [_InnerAttribute_]<sup>\*</sup>\
-> &nbsp;&nbsp; &nbsp;&nbsp; _TraitImplItem_<sup>\*</sup>\
+> &nbsp;&nbsp; &nbsp;&nbsp; [_AssociatedItem_]<sup>\*</sup>\
 > &nbsp;&nbsp; `}`
->
-> _TraitImplItem_ :\
-> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> (\
-> &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; [_MacroInvocationSemi_]\
-> &nbsp;&nbsp; &nbsp;&nbsp; | ( [_Visibility_]<sup>?</sup> ( [_TypeAlias_] | [_ConstantItem_] | [_Function_] | [_Method_] ) )\
-> &nbsp;&nbsp; )
 
 An _implementation_ is an item that associates items with an _implementing type_.
 Implementations are defined with the keyword `impl` and contain functions
@@ -52,7 +40,7 @@ the _associated items_ to the implementing type.
 
 Inherent implementations associate the contained items to the
 implementing type.  Inherent implementations can contain [associated
-functions] (including methods) and [associated constants]. They cannot
+functions] (including [methods]) and [associated constants]. They cannot
 contain associated type aliases.
 
 The [path] to an associated item is any path to the implementing type,
@@ -281,17 +269,11 @@ attributes must come before any associated items. That attributes that have
 meaning here are [`cfg`], [`deprecated`], [`doc`], and [the lint check
 attributes].
 
-[_ConstantItem_]: constant-items.md
-[_Function_]: functions.md
+[_AssociatedItem_]: associated-items.md
 [_GenericParams_]: generics.md
 [_InnerAttribute_]: ../attributes.md
-[_MacroInvocationSemi_]: ../macros.md#macro-invocation
-[_Method_]: associated-items.md#methods
-[_OuterAttribute_]: ../attributes.md
-[_TypeAlias_]: type-aliases.md
 [_TypePath_]: ../paths.md#paths-in-types
 [_Type_]: ../types.md#type-expressions
-[_Visibility_]: ../visibility-and-privacy.md
 [_WhereClause_]: generics.md#where-clauses
 [trait]: traits.md
 [associated constants]: associated-items.md#associated-constants
@@ -303,6 +285,7 @@ attributes].
 [`deprecated`]: ../attributes/diagnostics.md#the-deprecated-attribute
 [`doc`]: ../../rustdoc/the-doc-attribute.html
 [generic parameters]: generics.md
+[methods]: associated-items.md#methods
 [path]: ../paths.md
 [the lint check attributes]: ../attributes/diagnostics.md#lint-check-attributes
 [Unsafe traits]: traits.md#unsafe-traits

src/items/static-items.md

@@ -3,7 +3,7 @@
 > **<sup>Syntax</sup>**\
 > _StaticItem_ :\
 > &nbsp;&nbsp; `static` `mut`<sup>?</sup> [IDENTIFIER] `:` [_Type_]
->              `=` [_Expression_] `;`
+>              ( `=` [_Expression_] )<sup>?</sup> `;`
 
 A *static item* is similar to a [constant], except that it represents a precise
 memory location in the program. All references to the static refer to the same
@@ -23,6 +23,9 @@ statics:
 * The type must have the `Sync` trait bound to allow thread-safe access.
 * Constants cannot refer to statics.
 
+The initializer expression must be omitted in an [external block], and must be
+provided for free static items.
+
 ## Mutable statics
 
 If a static item is declared with the `mut` keyword, then it is allowed to be
@@ -73,6 +76,7 @@ following are true:
 [constant]: constant-items.md
 [`drop`]: ../destructors.md
 [constant expression]: ../const_eval.md#constant-expressions
+[external block]: external-blocks.md
 [interior mutable]: ../interior-mutability.md
 [IDENTIFIER]: ../identifiers.md
 [_Type_]: ../types.md#type-expressions