Declarative macro_rules! attribute macros

text/3697-declarative-attribute-macros.md

@@ -53,9 +53,10 @@ indirectly (e.g. applied to a containing module or item).
 
 Note that a single macro can have both `attr` and non-`attr` rules. Attribute
 invocations can only match the `attr` rules, and non-attribute invocations can
-only match the non-`attr` rules.
+only match the non-`attr` rules. This allows adding `attr` rules to an existing
+macro without breaking backwards compatibility.
 
-For simplicity, an attribute macro may not recursively invoke its `attr` rules;
+For simplicity, no special syntax is given to allow an attribute macro to recursively invoke its `attr` rules;
 to recurse, invoke a non-`attr` rule or another macro.
 
 # Reference-level explanation
@@ -67,9 +68,15 @@ The grammar for macros is extended as follows:
 > &nbsp;&nbsp; ( `attr` _MacroMatcher_ )<sup>?</sup>  _MacroMatcher_ `=>` _MacroTranscriber_
 
 The first _MacroMatcher_ matches the attribute's arguments, which will be an
-empty token tree if not present. The second _MacroMatcher_ matches the entire
-construct the attribute was applied to, receiving precisely what a
-proc-macro-based attribute would in the same place.
+empty token tree if either not present (`#[myattr]`) or empty (`#[myattr()]`).
+The second _MacroMatcher_ matches the entire construct the attribute was
+applied to, receiving precisely what a proc-macro-based attribute would in the
+same place.
+
+Only a rule matching both the arguments to the attribute and the construct the
+attribute was applied to will apply. Note that the captures in both
+`MacroMatcher`s share the same namespace; attempting to use the same name for
+two captures will give a "duplicate matcher binding" error.
 
 This grammar addition is backwards compatible: previously, a _MacroRule_ could
 only start with `(`, `[`, or `{`, so the parser can easily distinguish the
@@ -79,6 +86,22 @@ Attribute macros declared using `macro_rules!` are
 [active](https://doc.rust-lang.org/reference/attributes.html#active-and-inert-attributes),
 just like those declared using proc macros.
 
+Adding `attr` rules to an existing macro is a semver-compatible change.
+
+# Drawbacks
+[drawbacks]: #drawbacks
+
+This feature will not be sufficient for *all* uses of proc macros in the
+ecosystem, and its existence may create social pressure for crate maintainers
+to switch even if the result is harder to maintain.
+
+Before stabilizing this feature, we should receive feedback from crate
+maintainers, and potentially make further improvements to `macro_rules` to make
+it easier to use for their use cases. This feature will provide motivation to
+evaluate many new use cases that previously weren't written using
+`macro_rules`, and we should consider quality-of-life improvements to better
+support those use cases.
+
 # Rationale and alternatives
 [rationale-and-alternatives]: #rationale-and-alternatives
 
@@ -108,6 +131,11 @@ construct they're applied to, rather than a combinatorial explosion of both.
 This problem is not unique to attribute macros. In both cases, the standard
 solution is to parse one while carrying along the other.
 
+We could leave out support for writing a function-like macro and an attribute
+macro with the same name. However, this would prevent crates from preserving
+backwards compatibility when adding attribute support to an existing
+function-like macro.
+
 Instead of or in addition to marking the individual rules, we could mark the
 whole macro with `#[attribute_macro]` or similar, and allow having an attribute
 macro and a non-attribute macro with the same name.
@@ -132,7 +160,31 @@ demonstrating a demand for this. This feature would allow defining such
 attributes without requiring proc macros at all, and would support the same
 invocation syntax as a proc macro.
 
+# Unresolved questions
+[unresolved-questions]: #unresolved-questions
+
+Is an attribute macro allowed to recursively invoke itself by emitting the
+attriute in its output? If there is no technical issue with allowing this, then
+we should do so, to allow simle recursion (e.g. handling defaults by invoking
+the same rule as if they were explicitly specified).
+
 # Future possibilities
 [future-possibilities]: #future-possibilities
 
 We should provide a way to define `derive` macros declaratively, as well.
+
+We should provide a way for `macro_rules!` macros to provide better error
+reporting, with spans, rather than just pointing to the macro.
+
+As people test this feature and run into limitations of `macro_rules!` parsing,
+we should consider additional features to make this easier to use for various
+use cases.
+
+Some use cases involve multiple attribute macros that users expect to be able
+to apply in any order. For instance, `#[test]` and `#[should_panic]` can appear
+on the same function in any order. Implementing that via this mechanism for
+attribute macros would require making both of those attributes into macros that
+both do all the parsing regardless of which got invoked first, likely by
+invoking a common helper. We should consider if we consider that mechanism
+sufficient, or if we should provide another mechanism for a set of related
+attribute macros to appear in any order.