From bfbff85259c02349560f8cc3223677cb55607b07 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sat, 22 May 2021 10:29:19 -0500 Subject: [PATCH 1/2] Document extended key-value attributes --- src/attributes.md | 38 +++++++++++++++++++++++++++++++------- 1 file changed, 31 insertions(+), 7 deletions(-) diff --git a/src/attributes.md b/src/attributes.md index d6ce2531b..3e97fa6a5 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -13,7 +13,7 @@ > > _AttrInput_ :\ >       [_DelimTokenTree_]\ ->    | `=` [_LiteralExpression_]_without suffix_ +>    | `=` [_Expression_] An _attribute_ is a general, free-form metadatum that is interpreted according to name, convention, language, and compiler version. Attributes are modeled @@ -26,7 +26,7 @@ the bang after the hash, apply to the thing that follows the attribute. The attribute consists of a path to the attribute, followed by an optional delimited token tree whose interpretation is defined by the attribute. Attributes other than macro attributes also allow the input to be an equals -sign (`=`) followed by a literal expression. See the [meta item +sign (`=`) followed by a expression. See the [meta item syntax](#meta-item-attribute-syntax) below for more details. Attributes can be classified into the following kinds: @@ -94,7 +94,7 @@ attributes]. It has the following grammar: > **Syntax**\ > _MetaItem_ :\ >       [_SimplePath_]\ ->    | [_SimplePath_] `=` [_LiteralExpression_]_without suffix_\ +>    | [_SimplePath_] `=` [_Expression_]\ >    | [_SimplePath_] `(` _MetaSeq_? `)` > > _MetaSeq_ :\ @@ -102,10 +102,34 @@ attributes]. It has the following grammar: > > _MetaItemInner_ :\ >       _MetaItem_\ ->    | [_LiteralExpression_]_without suffix_ +>    | [_Expression_] + +Expressions in meta items must macro-expand to literal expressions, which must not +include integer or float type suffixes. Expressions which are not literal expressions +will be syntactically accepted (and can be passed to proc-macros), but will be rejected after parsing. + +Note that if the attribute appears within another macro, it will be expanded +after that outer macro. For example, the following code will expand the +`Serialize` proc-macro first, which must preserve the `include_str!` call in +order for it to be expanded: + +```rust ignore +#[derive(Serialize)] +struct Foo { + #[doc = include_str!("x.md")] + x: u32 +} +``` -Literal expressions in meta items must not include integer or float type -suffixes. +Additionally, macros in attributes will be expanded only after all other attributes applied to the item: + +```rust ignore +#[macro_attr1] // expanded first +#[doc = mac!()] // `mac!` is expanded fourth. +#[macro_attr2] // expanded second +#[derive(MacroDerive1, MacroDerive2)] // expanded third +fn foo() {} +``` Various built-in attributes use different subsets of the meta item syntax to specify their inputs. The following grammar rules show some commonly used @@ -255,7 +279,7 @@ The following is an index of all built-in attributes. [The Rustdoc Book]: ../rustdoc/the-doc-attribute.html [The Unstable Book]: ../unstable-book/index.html [_DelimTokenTree_]: macros.md -[_LiteralExpression_]: expressions/literal-expr.md +[_Expression_]: expressions.md [_SimplePath_]: paths.md#simple-paths [`allow`]: attributes/diagnostics.md#lint-check-attributes [`automatically_derived`]: attributes/derive.md#the-automatically_derived-attribute From efb2c1cab0302a985030a94adafae9e630a7894d Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sun, 23 May 2021 15:44:16 -0500 Subject: [PATCH 2/2] fix typo Co-authored-by: Vadim Petrochenkov --- src/attributes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/attributes.md b/src/attributes.md index 3e97fa6a5..857cd7d72 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -26,7 +26,7 @@ the bang after the hash, apply to the thing that follows the attribute. The attribute consists of a path to the attribute, followed by an optional delimited token tree whose interpretation is defined by the attribute. Attributes other than macro attributes also allow the input to be an equals -sign (`=`) followed by a expression. See the [meta item +sign (`=`) followed by an expression. See the [meta item syntax](#meta-item-attribute-syntax) below for more details. Attributes can be classified into the following kinds: