From 68854f473a6559834664d7e76b8398c499778896 Mon Sep 17 00:00:00 2001 From: Nick Cameron Date: Tue, 19 Apr 2016 17:28:27 +1200 Subject: [PATCH 1/3] Macros by example 2.0 (macro!) Macros by example 2.0. A replacement for `macro_rules!`. This is mostly a placeholder RFC since many of the issues affecting the new macro system are (or will be) addressed in other RFCs. This RFC may be expanded at a later date. --- text/0000-macros.md | 141 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 text/0000-macros.md diff --git a/text/0000-macros.md b/text/0000-macros.md new file mode 100644 index 00000000000..7d70981f60f --- /dev/null +++ b/text/0000-macros.md @@ -0,0 +1,141 @@ +- Feature Name: macro +- Start Date: 2016-04-17 +- RFC PR: (leave this empty) +- Rust Issue: (leave this empty) + +# Summary +[summary]: #summary + +Macros by example 2.0. A replacement for `macro_rules!`. This is mostly a +placeholder RFC since many of the issues affecting the new macro system are +(or will be) addressed in other RFCs. This RFC may be expanded at a later date. + +Currently in this RFC: + +* That we should have a new macro by example system, +* a new keyword for declaring macros. + +In other RFCs: + +* Naming and modularisation (#1561). + +May be added to this RFC later (or might be separate RFCs): + +* more detailed syntax proposal, +* hygiene improvements. + +Note this RFC does not involve procedural macros (aka syntax extensions). + + +# Motivation +[motivation]: #motivation + +There are several changes to the macro by example system which are desirable but +backwards compatible (See [RFC 1561](https://github.com/rust-lang/rfcs/pull/1561) +for some changes to macro naming and modularisation, I would also like to +propose improvements to hygiene in macros, and some improved syntax). + +In order to maintain Rust's backwards compatibility guarantees, we cannot change +the existing system (`macro_rules!`) to accommodate these changes. I therefore +propose a new macro by example system to live alongside `macro_rules!`. + +Example (possible) improvements: + +```rust +// Naming (RFC 1561) + +fn main() { + a::foo!(...); +} + +mod a { + // Macro privacy (TBA) + pub macro! foo { ... } +} +``` + +```rust +// Relative paths (part of hygiene reform, TBA) + +mod a { + pub macro! foo { ... bar() ... } + fn bar() { ... } +} + +fn main() { + a::foo!(...); // Expansion calls a::bar +} +``` + +```rust +// Syntax (TBA) + +macro! foo($a: ident) => { + return $a + 1; +} +``` + +I believe it is extremely important that moving to the new macro system is as +straightforward as possible for both macro users and authors. This must be the +case so that users make the transition to the new system and we are not left +with two systems forever. + +A goal of this design is that for macro users, there is no difference in using +the two systems other than how macros are named. For macro authors, most macros +that work in the old system should work in the new system with minimal changes. +Macros which will need some adjustment are those that exploit holes in the +current hygiene system. + + +# Detailed design +[design]: #detailed-design + +There will be a new system of macros by example using similar syntax and +semantics to the current `macro_rules!` system. + +A macro by example is declared using the `macro` keyword with the `!` +operator. For example, where a macro `foo` is declared today as `macro_rules! +foo { ... }`, it will be declared using `macro! foo { ... }`. I leave the syntax +of the macro body for later specification. + + +# Drawbacks +[drawbacks]: #drawbacks + +There is a risk that `macro_rules!` is good enough for most users and there is +low adoption of the new system. Possibly worse would be that there is high +adoption but little migration from the old system, leading to us having to +support two systems forever. + + +# Alternatives +[alternatives]: #alternatives + +Make backwards incompatible changes to `macro_rules!`. This is probably a +non-starter due to our stability guarantees. We might be able to make something +work if this was considered desirable. + +Limit ourselves to backwards compatible changes to `macro_rules!`. I don't think +this is worthwhile. It's not clear we can make meaningful improvements without +breaking backwards compatibility. + +Don't use a keyword - either make `macro` not a keyword or use a different word +for the macros by example syntax. + +Use `macro` instead of `macro!` (we might want to use bare `macro` for +procedural macros, not clear if the overlap will be a problem). + +Live with the existing system. + + +# Unresolved questions +[unresolved]: #unresolved-questions + +What to do with `macro_rules`? We will need to maintain it at least until `macro!` +is stable. Hopefully, we can then deprecate it (some time will be required to +migrate users to the new system). Eventually, I hope we can remove `macro_rules!`. +That will take a long time, and would require a 2.0 version of Rust to strictly +adhere to our stability guarantees. + +There are many questions still to be answered as this RFC and some sister RFCs +are developed. From f6f5c41639be75997785c67fe71969e09ec4f28e Mon Sep 17 00:00:00 2001 From: Nick Cameron Date: Fri, 11 Nov 2016 16:45:22 +1300 Subject: [PATCH 2/3] Update the RFC Only major change is moving from `macro!` to `macro` to declare a macro. --- text/0000-macros.md | 31 ++++++++++++++----------------- 1 file changed, 14 insertions(+), 17 deletions(-) diff --git a/text/0000-macros.md b/text/0000-macros.md index 7d70981f60f..0786a3d430f 100644 --- a/text/0000-macros.md +++ b/text/0000-macros.md @@ -1,4 +1,4 @@ -- Feature Name: macro +- Feature Name: macro_2_0 - Start Date: 2016-04-17 - RFC PR: (leave this empty) - Rust Issue: (leave this empty) @@ -19,10 +19,11 @@ In other RFCs: * Naming and modularisation (#1561). -May be added to this RFC later (or might be separate RFCs): +To come in separate RFCs: * more detailed syntax proposal, -* hygiene improvements. +* hygiene improvements, +* more ... Note this RFC does not involve procedural macros (aka syntax extensions). @@ -50,7 +51,7 @@ fn main() { mod a { // Macro privacy (TBA) - pub macro! foo { ... } + pub macro foo { ... } } ``` @@ -58,7 +59,7 @@ mod a { // Relative paths (part of hygiene reform, TBA) mod a { - pub macro! foo { ... bar() ... } + pub macro foo { ... bar() ... } fn bar() { ... } } @@ -70,7 +71,7 @@ fn main() { ```rust // Syntax (TBA) -macro! foo($a: ident) => { +macro foo($a: ident) => { return $a + 1; } ``` @@ -93,10 +94,10 @@ current hygiene system. There will be a new system of macros by example using similar syntax and semantics to the current `macro_rules!` system. -A macro by example is declared using the `macro` keyword with the `!` -operator. For example, where a macro `foo` is declared today as `macro_rules! -foo { ... }`, it will be declared using `macro! foo { ... }`. I leave the syntax -of the macro body for later specification. +A macro by example is declared using the `macro` keyword. For example, where a +macro `foo` is declared today as `macro_rules! foo { ... }`, it will be declared +using `macro foo { ... }`. I leave the syntax of the macro body for later +specification. # Drawbacks @@ -119,23 +120,19 @@ Limit ourselves to backwards compatible changes to `macro_rules!`. I don't think this is worthwhile. It's not clear we can make meaningful improvements without breaking backwards compatibility. +Use `macro!` instead of `macro` (proposed in an earlier version of this RFC). + Don't use a keyword - either make `macro` not a keyword or use a different word for the macros by example syntax. -Use `macro` instead of `macro!` (we might want to use bare `macro` for -procedural macros, not clear if the overlap will be a problem). - Live with the existing system. # Unresolved questions [unresolved]: #unresolved-questions -What to do with `macro_rules`? We will need to maintain it at least until `macro!` +What to do with `macro_rules`? We will need to maintain it at least until `macro` is stable. Hopefully, we can then deprecate it (some time will be required to migrate users to the new system). Eventually, I hope we can remove `macro_rules!`. That will take a long time, and would require a 2.0 version of Rust to strictly adhere to our stability guarantees. - -There are many questions still to be answered as this RFC and some sister RFCs -are developed. From 7dcb7374aee3281c261510ca5af53399a3df60f5 Mon Sep 17 00:00:00 2001 From: Nick Cameron Date: Tue, 31 Jan 2017 09:27:52 +1300 Subject: [PATCH 3/3] Use 'declarative macro' and add note on nomenclature --- text/0000-macros.md | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/text/0000-macros.md b/text/0000-macros.md index 0786a3d430f..cf2a66deed5 100644 --- a/text/0000-macros.md +++ b/text/0000-macros.md @@ -6,14 +6,14 @@ # Summary [summary]: #summary -Macros by example 2.0. A replacement for `macro_rules!`. This is mostly a +Decalrative macros 2.0. A replacement for `macro_rules!`. This is mostly a placeholder RFC since many of the issues affecting the new macro system are (or will be) addressed in other RFCs. This RFC may be expanded at a later date. Currently in this RFC: -* That we should have a new macro by example system, -* a new keyword for declaring macros. +* That we should have a new declarative macro system, +* a new keyword for declaring macros (`macro`). In other RFCs: @@ -31,14 +31,14 @@ Note this RFC does not involve procedural macros (aka syntax extensions). # Motivation [motivation]: #motivation -There are several changes to the macro by example system which are desirable but -backwards compatible (See [RFC 1561](https://github.com/rust-lang/rfcs/pull/1561) +There are several changes to the declarative macro system which are desirable but +not backwards compatible (See [RFC 1561](https://github.com/rust-lang/rfcs/pull/1561) for some changes to macro naming and modularisation, I would also like to propose improvements to hygiene in macros, and some improved syntax). In order to maintain Rust's backwards compatibility guarantees, we cannot change the existing system (`macro_rules!`) to accommodate these changes. I therefore -propose a new macro by example system to live alongside `macro_rules!`. +propose a new declarative macro system to live alongside `macro_rules!`. Example (possible) improvements: @@ -91,14 +91,24 @@ current hygiene system. # Detailed design [design]: #detailed-design -There will be a new system of macros by example using similar syntax and +There will be a new system of declarative macros using similar syntax and semantics to the current `macro_rules!` system. -A macro by example is declared using the `macro` keyword. For example, where a +A declarative macro is declared using the `macro` keyword. For example, where a macro `foo` is declared today as `macro_rules! foo { ... }`, it will be declared using `macro foo { ... }`. I leave the syntax of the macro body for later specification. +## Nomencalture + +Throughout this RFC, I use 'declarative macro' to refer to a macro declared +using declarative (and domain specific) syntax (such as the current +`macro_rules!` syntax). The 'declarative macros' name is in opposition to +'procedural macros', which are declared as Rust programs. The specific +declarative syntax using pattern matching and templating is often referred to as +'macros by example'. + +'Pattern macro' has been suggested as an alterantive for 'declarative macro'. # Drawbacks [drawbacks]: #drawbacks @@ -123,7 +133,7 @@ breaking backwards compatibility. Use `macro!` instead of `macro` (proposed in an earlier version of this RFC). Don't use a keyword - either make `macro` not a keyword or use a different word -for the macros by example syntax. +for declarative macros. Live with the existing system.