macros: improve 1.0/2.0 interaction
This PR supports using unhygienic macros from hygienic macros without breaking the latter's hygiene.
```rust
// crate A:
#[macro_export]
macro_rules! m1 { () => {
f(); // unhygienic: this macro needs `f` in its environment
fn g() {} // (1) unhygienic: `g` is usable outside the macro definition
} }
// crate B:
#![feature(decl_macro)]
extern crate A;
use A::m1;
macro m2() {
fn f() {} // (2)
m1!(); // After this PR, `f()` in the expansion resolves to (2), not (3)
g(); // After this PR, this resolves to `fn g() {}` from the above expansion.
// Today, it is a resolution error.
}
fn test() {
fn f() {} // (3)
m2!(); // Today, `m2!()` can see (3) even though it should be hygienic.
fn g() {} // Today, this conflicts with `fn g() {}` from the expansion, even though it should be hygienic.
}
```
Once this PR lands, you can make an existing unhygienic macro hygienic by wrapping it in a hygienic macro. There is an [example](b766fa887d) of this in the tests.
r? @nrc
Proc macro spans serve two mostly unrelated purposes: controlling name
resolution and controlling error messages. It can be useful to mix the
name resolution behavior of one span with the line/column error message
locations of a different span.
In particular, consider the case of a trait brought into scope within
the def_site of a custom derive. I want to invoke trait methods on the
fields of the user's struct. If the field type does not implement the
right trait, I want the error message to underline the corresponding
struct field.
Generating the method call with the def_site span is not ideal -- it
compiles and runs but error messages sadly always point to the derive
attribute like we saw with Macros 1.1.
```
|
4 | #[derive(HeapSize)]
| ^^^^^^^^
```
Generating the method call with the same span as the struct field's
ident or type is not correct -- it shows the right underlines but fails
to resolve to the trait in scope at the def_site.
```
|
7 | bad: std:🧵:Thread,
| ^^^^^^^^^^^^^^^^^^^^^^^^
```
The correct span for the method call is one that combines the def_site's
name resolution with the struct field's line/column.
```
field.span.resolved_at(Span::def_site())
// equivalently
Span::def_site().located_at(field.span)
```
Adding both because which one is more natural will depend on context.
Expose the line and column fields from the proc_macro::LineColumn struct
Right now the `LineColumn` struct is pretty useless because the fields are private.
This patch just marks the fields as public, which seems like the easiest solution.
Add ..= to the parser
Add ..= to libproc_macro
Add ..= to ICH
Highlight ..= in rustdoc
Update impl Debug for RangeInclusive to ..=
Replace `...` to `..=` in range docs
Make the dotdoteq warning point to the ...
Add warning for ... in expressions
Updated more tests to the ..= syntax
Updated even more tests to the ..= syntax
Updated the inclusive_range entry in unstable book
Right now the HIR contains raw `syntax::ast::Attribute` structure but nowadays
these can contain arbitrary tokens. One variant of the `Token` enum is an
"interpolated" token which basically means to shove all the tokens for a
nonterminal in this position. A "nonterminal" in this case is roughly analagous
to a macro argument:
macro_rules! foo {
($a:expr) => {
// $a is a nonterminal as an expression
}
}
Currently nonterminals contain namely items and expressions, and this poses a
problem for incremental compilation! With incremental we want a stable hash of
all HIR items, but this means we may transitively need a stable hash *of the
entire AST*, which is certainly not stable w/ node ids and whatnot. Hence today
there's a "bug" where the "stable hash" of an AST is just the raw hash value of
the AST, and this only arises with interpolated nonterminals. The downside of
this approach, however, is that a bunch of errors get spewed out during
compilation about how this isn't a great idea.
This PR is focused at fixing these warnings, basically deleting them from the
compiler. The implementation here is to alter attributes as they're lowered from
the AST to HIR, expanding all nonterminals in-place as we see them. This code
for expanding a nonterminal to a token stream already exists for the
`proc_macro` crate, so we basically just reuse the same implementation there.
After this PR it's considered a bug to have an `Interpolated` token and hence
the stable hash implementation simply uses `bug!` in this location.
Closes#40946
Initial diagnostic API for proc-macros.
This commit introduces the ability to create and emit `Diagnostic` structures from proc-macros, allowing for proc-macro authors to emit warning, error, note, and help messages just like the compiler does.
The API is somewhat based on the diagnostic API already present in `rustc` with several changes that improve usability. The entry point into the diagnostic API is a new `Diagnostic` type which is primarily created through new `error`, `warning`, `help`, and `note` methods on `Span`. The `Diagnostic` type records the diagnostic level, message, and optional `Span` for the top-level diagnostic and contains a `Vec` of all of the child diagnostics. Child diagnostics can be added through builder methods on `Diagnostic`.
A typical use of the API may look like:
```rust
let token = parse_token();
let val = parse_val();
val.span
.error(format!("expected A but found {}", val))
.span_note(token.span, "because of this token")
.help("consider using a different token")
.emit();
```
cc @jseyfried @nrc @dtolnay @alexcrichton
This commit introduces the ability to create and emit `Diagnostic`
structures from proc-macros, allowing for proc-macro authors to emit
warning, error, note, and help messages just like the compiler does.
libproc_macro docs: fix brace and bracket mixup
The documentation indicates that brace is `[`.
Brace is mapped token::Brace which (expectedly) is `{`.
So the documentation is simply confusing brace and bracket there.
Even though it's just a very small issue, it can lead to quite some confusion.
This is then later used by `proc_macro` to generate a new
`proc_macro::TokenTree` which preserves span information. Unfortunately this
isn't a bullet-proof approach as it doesn't handle the case when there's still
other attributes on the item, especially inner attributes.
Despite this the intention here is to solve the primary use case for procedural
attributes, attached to functions as outer attributes, likely bare. In this
situation we should be able to now yield a lossless stream of tokens to preserve
span information.
This partly resolves the `FIXME` located in `src/libproc_macro/lib.rs` when
interpreting interpolated tokens. All instances of `ast::Item` which have a list
of tokens attached to them now use that list of tokens to losslessly get
converted into a `TokenTree` instead of going through stringification and losing
span information.
cc #43081
This commit fills out the remaining integer literal constructors on the
`proc_macro::Literal` type with `isize` and `usize`. (I think these were just
left out by accident)
This commit fixes#38749 by building documentation for the `proc_macro` crate by
default for configured hosts. Unfortunately did not turn out to be a trivial
fix. Currently rustbuild generates documentation into multiple locations: one
for std, one for test, and one for rustc. The initial fix for this issue simply
actually executed `cargo doc -p proc_macro` which was otherwise completely
elided before.
Unfortunately rustbuild was the left to merge two documentation trees together.
One for the standard library and one for the rustc tree (which only had docs for
the `proc_macro` crate). Rustdoc itself knows how to merge documentation files
(specifically around search indexes, etc) but rustbuild was unaware of this, so
an initial fix ended up destroying the sidebar and the search bar from the
libstd docs.
To solve this issue the method of documentation has been tweaked slightly in
rustbuild. The build system will not use symlinks (or directory junctions on
Windows) to generate all documentation into the same location initially. This'll
rely on rustdoc's logic to weave together all the output and ensure that it ends
up all consistent.
Closes#38749
Implement function-like procedural macros ( `#[proc_macro]`)
Adds the `#[proc_macro]` attribute, which expects bare functions of the kind `fn(TokenStream) -> TokenStream`, which can be invoked like `my_macro!()`.
cc rust-lang/rfcs#1913, #38356
r? @jseyfried
cc @nrc
Remove not(stage0) from deny(warnings)
Historically this was done to accommodate bugs in lints, but there hasn't been a
bug in a lint since this feature was added which the warnings affected. Let's
completely purge warnings from all our stages by denying warnings in all stages.
This will also assist in tracking down `stage0` code to be removed whenever
we're updating the bootstrap compiler.
These are some bare-bones documentation for custom derive, needed
to stabilize "macros 1.1",
https://github.com/rust-lang/rust/issues/35900
The book chapter is based off of a blog post by @cbreeden,
https://cbreeden.github.io/Macros11/
Normally, we have a policy of not mentioning external crates in
documentation. However, given that syn/quote are basically neccesary
for properly using macros 1.1, I feel that not including them here
would make the documentation very bad. So the rules should be bent
in this instance.
This commit stabilizes the `proc_macro` and `proc_macro_lib` features in the
compiler to stabilize the "Macros 1.1" feature of the language. Many more
details can be found on the tracking issue, #35900.
Closes#35900
