Stabilize param_attrs in Rust 1.39.0

[c410-f3r]

Stabilization proposal

I propose that we stabilize #![feature(param_attrs)].

Tracking issue: #60406
Version: 1.39 (2019-09-26 => beta, 2019-11-07 => stable).

What is stabilized

It is now possible to add outer attributes like #[cfg(..)] on formal parameters of functions, closures, and function pointer types. For example:

fn len(
    #[cfg(windows)] slice: &[u16],
    #[cfg(not(windows))] slice: &[u8],
) -> usize {
    slice.len()
}

What isn't stabilized

• Documentation comments like /// Doc on parameters.

• Code expansion of a user-defined #[proc_macro_attribute] macro used on parameters.

• Built-in attributes other than cfg, cfg_attr, allow, warn, deny, and forbid. Currently, only the lints unused_variables and unused_mut have effect and may be controlled on parameters.

Motivation

The chief motivations for stabilizing param_attrs include:

• Finer conditional compilation with #[cfg(..)] and linting control of variables.

• Richer macro DSLs created by users.

• External tools and compiler internals can take advantage of the additional information that the parameters provide.

For more examples, see the RFC.

Reference guide

In the grammar of function and function pointer, the grammar of variadic tails (...) and parameters are changed respectively from:

FnParam = { pat:Pat ":" }? ty:Type;
VaradicTail = "...";

into:

FnParam = OuterAttr* { pat:Pat ":" }? ty:Type;
VaradicTail = OuterAttr* "...";

The grammar of a closure parameter is changed from:

ClosureParam = pat:Pat { ":" ty:Type }?;

into:

ClosureParam = OuterAttr* pat:Pat { ":" ty:Type }?;

More generally, where there's a list of formal (value) parameters separated or terminated by , and delimited by ( and ). Each parameter in that list may optionally be prefixed by OuterAttr+.

Note that in all cases, OuterAttr* applies to the whole parameter and not just the pattern. This distinction matters in pretty printing and in turn for macros.

History

• On 2018-10-15, @Robbepop proposes RFC 2565, "Attributes in formal function parameter position".

• On 2019-04-30, RFC 2565 is merged and the tracking issue is made.

• On 2019-06-12, a partial implementation was completed. The implementation was done in #60669 by @c410-f3r and the PR was reviewed by @petrochenkov and @Centril.

• On 2019-07-29, #61238 was fixed in #61856. The issue fixed was that lint attributes on function args had no effect. The PR was written by @c410-f3r and reviewed by @matthewjasper, @petrochenkov, and @oli-obk.

• On 2019-08-02, a bug #63210 was filed wherein the attributes on formal parameters would not be passed to macros. The issue was about forgetting to call the relevant method in fn print_arg in the pretty printer. In #63212, written by @Centril on 2019-08-02 and reviewed by @davidtwco, the issue aforementioned was fixed.

• This PR stabilizes param_attrs.

Tests

• On Rust 2018, attributes aren't permitted on function parameters without a pattern in trait definitions.

• All attributes that should be allowed. This includes cfg, cfg_attr, and lints check attributes.

• Built-in attributes, which should be forbidden, e.g., #[test], are.

• cfg and cfg_attr are properly evaluated.

• unused_mut and unused_variables are correctly applied to parameter patterns.

• Pretty printing takes formal parameter attributes into account.

Possible future work

• Custom attributes inside function parameters aren't currently supported but it is something being worked on internally.

• Since documentation comments are syntactic sugar for #[doc(...)], it is possible to allow literal /// Foo comments on function parameters.

This report is a collaborative work with @Centril.

[Centril]

r? @Centril

[Centril]

Dear language team and the community at large. The above report gives an overview of the #[attr] param: type feature. I propose that we indeed do stabilize the feature accordingly.

@rfcbot merge

[rfcbot]

Team member @Centril has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Centril
• @cramertj
• @eddyb
• @joshtriplett
• @nikomatsakis
• @pnkfelix
• @scottmcm
• @withoutboats

Concerns:

• Regression of #63210 param attributes not showing in proc-macro TokenStream #64282 resolved by Stabilize param_attrs in Rust 1.39.0 #64010 (comment)

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[Centril]

r=me on the code changes itself when FCP completes.

[phansch]

Been waiting for this 🎉

Currently, only the lints unused_variables and unused_mut have effect, and may be controlled, on parameters.

How does that work? Was it a deliberate decision somewhere in the code or a coincidental result of the implementation? I'm just asking to find out if there's something we should be aware of with tool lints in Clippy.

[nikomatsakis]

Question for @Centril and @c410-f3r --

You mention that procedural macros are not stabilized. Is there a test showing what happens when a procedural macro is applied? I presume that it generates a feature gate? Or is it considered an error?

Similarly, is there a test for lints that are intended to be disallowed?

[nikomatsakis]

(Also, I should add, thanks for all your work on this. ❤️ )

[c410-f3r]

@phansch

According to the RFC, this reduced number of allowed lint was initially proposed to be part of a minimum viable product. Nevertheless, more lints can be added in future releases.

@nikomatsakis

Currently, the compiler shows the the attribute 'some_proc_macro_attribute' is currently unknown to the compiler and may have meaning added to it in the future error. With #63468, it will be changed to expected an inert attribute, found an attribute macro and the message itself behaves as a feature gate.

[Centril]

@nikomatsakis

You mention that procedural macros are not stabilized. Is there a test showing what happens when a procedural macro is applied? I presume that it generates a feature gate? Or is it considered an error?

https://github.com/rust-lang/rust/blob/master/src/test/ui/rfc-2565-param-attrs/param-attrs-builtin-attrs.rs sorta addresses this by using #[test] but I've hardened the tests somewhat in #64031.

Similarly, is there a test for lints that are intended to be disallowed?

The RFC does not specify a specific list of lints that should or should not be allowed but the two lints that are tested and accounted for seemed the most important. We'd need to do a deeper audit of all the lints to see which others could be relevant and that's probably not worth the time at the moment.

[Centril]

How does that work? Was it a deliberate decision somewhere in the code or a coincidental result of the implementation? I'm just asking to find out if there's something we should be aware of with tool lints in Clippy.

@phansch Reading #61856 is probably most relevant for Clippy development.

[bors]

⌛ Testing commit 299d696 with merge 6c468ee...

[bors]

💥 Test timed out

[Centril]

@bors retry

[yanfenglee]

When Custom attributes inside function parameters available? Is there a plan?

[c410-f3r]

It is currently possible to parse custom attributes using procedural macros but they can't be present in the final TokenStream output.

[yanfenglee]

It is currently possible to parse custom attributes using procedural macros but they can't be present in the final TokenStream output.

Thanks for your reply, i don't quite understand "they can't be present in the final TokenStream output.", i want implement like this:

#[post("/path/{id}")]
async fn post_data(data: &PostData, #[path_varible("id")]id: i32, #[header("token")] token: String) -> Result<String, Error> {}

Is this possible?

[c410-f3r]

Taking into consideration that #[post] is a procedural macro created by you, then yes. It is possible to parse #[path_varible("id")] and #[header("token")].

Thanks for your reply, i don't quite understand "they can't be present in the final TokenStream output.", i want implement like this:

#[post] is a procedural attribute macro that has the following signature: fn post(attrs: TokenStream, item: TokenStream) -> TokenStream;. Although [path_varible("id")] and #[header("token")] are present in item, they shouldn't be present in the TokenStream output.

Take a look at https://doc.rust-lang.org/reference/procedural-macros.html to learn more about procedural macros, use the syn crate for parsing and the quote crate for building tokens.

[yanfenglee]

Taking into consideration that #[post] is a procedural macro created by you, then yes. It is possible to parse #[path_varible("id")] and #[header("token")].

Thanks for your reply, i don't quite understand "they can't be present in the final TokenStream output.", i want implement like this:

#[post] is a procedural attribute macro that has the following signature: fn post(attrs: TokenStream, item: TokenStream) -> TokenStream;. Although [path_varible("id")] and #[header("token")] are present in item, they shouldn't be present in the TokenStream output.

Take a look at https://doc.rust-lang.org/reference/procedural-macros.html to learn more about procedural macros, use the syn crate for parsing and the quote crate for building tokens.

Thank you very much, i have already implemented #[post], and can not find examples used on function parameters, i will try later, thanks again