Skip to content

Commit ebc0a85

Browse files
author
Keegan McAllister
committed
Rename attributes per meeting
1 parent a503fb4 commit ebc0a85

File tree

1 file changed

+25
-22
lines changed

1 file changed

+25
-22
lines changed

text/0000-macro-reform.md

Lines changed: 25 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -67,14 +67,14 @@ However, the exclamation point is really part of the invocation syntax, not the
6767
name, and some syntax extensions are invoked with no exclamation point, for
6868
example item decorators like `deriving`.
6969

70-
We introduce an attribute `use_macros` to specify which macros from an external
70+
We introduce an attribute `macro_use` to specify which macros from an external
7171
crate should be imported to the syntax environment:
7272

7373
```rust
74-
#[use_macros(vec, panic="fail")]
74+
#[macro_use(vec, panic="fail")]
7575
extern crate std;
7676

77-
#[use_macros]
77+
#[macro_use]
7878
extern crate core;
7979
```
8080

@@ -97,17 +97,17 @@ hard error.
9797
Many macros expand using other "helper macros" as an implementation detail.
9898
For example, librustc's `declare_lint!` uses `lint_initializer!`. The client
9999
should not know about this macro, although it still needs to be exported for
100-
cross-crate use. For this reason we allow `#[use_macros]` on a macro
100+
cross-crate use. For this reason we allow `#[macro_use]` on a macro
101101
definition.
102102

103103
```rust
104104
/// Not to be imported directly.
105-
#[export]
105+
#[macro_export]
106106
macro_rules! lint_initializer { ... }
107107

108108
/// Declare a lint.
109-
#[export]
110-
#[use_macros(lint_initializer)]
109+
#[macro_export]
110+
#[macro_use(lint_initializer)]
111111
macro_rules! declare_lint {
112112
($name:ident, $level:ident, $desc:expr) => (
113113
static $name: &'static $crate::lint::Lint
@@ -120,7 +120,7 @@ The macro `lint_initializer!`, imported from the same crate as `declare_lint!`,
120120
will be visible only during further expansion of the result of invoking
121121
`declare_lint!`.
122122

123-
`use_macros` on `macro_rules` is an optional part of this proposal that will be
123+
`macro_use` on `macro_rules` is an optional part of this proposal that will be
124124
implemented for 1.0 only if time permits. Without it, libraries that use
125125
helper macros will need to list them in documentation so that users can import
126126
them.
@@ -132,39 +132,42 @@ that's an unstable internal API, so it's outside the scope of this RFC.
132132

133133
We also clean up macro syntax in a way that complements the semantic changes above.
134134

135-
## `#[use_macros(...)] mod`
135+
## `#[macro_use(...)] mod`
136136

137-
The `use_macros` attribute can be applied to a `mod` item as well. The
137+
The `macro_use` attribute can be applied to a `mod` item as well. The
138138
specified macros will "escape" the module and become visible throughout the
139139
rest of the enclosing module, including any child modules. A crate might start
140140
with
141141

142142
```rust
143-
#[use_macros]
143+
#[macro_use]
144144
mod macros;
145145
```
146146

147147
to define some macros for use by the whole crate, without putting those
148148
definitions in `lib.rs`.
149149

150-
Note that `#[use_macros]` (without a list of names) is equivalent to the
150+
Note that `#[macro_use]` (without a list of names) is equivalent to the
151151
current `#[macro_escape]`. However, the new convention is to use an outer
152152
attribute, in the file whose syntax environment is affected, rather than an
153153
inner attribute in the file defining the macros.
154154

155155
## Macro export and re-export
156156

157-
A macro definition qualified by `#[export]` becomes available to other crates.
158-
That is, it can be the target of `#[use_macros]`. Or put another way,
159-
`#[export] macro_rules!` works the way `#[macro_export] macro_rules!` does
160-
today. Adding `#[export]` has no effect on the syntax environment for the
161-
current crate.
157+
Currently in Rust, a macro definition qualified by `#[macro_export]` becomes
158+
available to other crates. We keep this behavior in the new system. A macro
159+
qualified by `#[macro_export]` can be the target of `#[macro_use(...)]`, and
160+
will be imported automatically when `#[macro_use]` is given with no list of
161+
names.
162+
163+
`#[macro_export]` has no effect on the syntax environment for the current
164+
crate.
162165

163166
We can also re-export macros that were imported from another crate. For
164167
example, libcollections defines a `vec!` macro, which would now look like:
165168

166169
```rust
167-
#[export]
170+
#[macro_export]
168171
macro_rules! vec {
169172
($($e:expr),*) => ({
170173
let mut _temp = $crate::vec::Vec::new();
@@ -178,7 +181,7 @@ Currently, libstd duplicates this macro in its own `macros.rs`. Now it could
178181
do
179182

180183
```rust
181-
#[reexport_macros(vec)]
184+
#[macro_reexport(vec)]
182185
extern crate collections;
183186
```
184187

@@ -271,9 +274,9 @@ reform. Two ways this could work out:
271274

272275
# Unresolved questions
273276

274-
Should we forbid `$crate` in non-`#[export]`ed macros? It seems useless,
275-
however I think we should allow it anyway, to encourage the habit of writing
276-
`$crate::` for any references to the local crate.
277+
Should we forbid `$crate` in non-exported macros? It seems useless, however I
278+
think we should allow it anyway, to encourage the habit of writing `$crate::`
279+
for any references to the local crate.
277280

278281
# Acknowledgements
279282

0 commit comments

Comments
 (0)