This commit stabilizes some of the `proc_macro` language feature as well as a
number of APIs in the `proc_macro` crate as [previously discussed][1]. This
means that on stable Rust you can now define custom procedural macros which
operate as attributes attached to items or `macro_rules!`-like bang-style
invocations. This extends the suite of currently stable procedural macros,
custom derives, with custom attributes and custom bang macros.
Note though that despite the stabilization in this commit procedural macros are
still not usable on stable Rust. To stabilize that we'll need to stabilize at
least part of the `use_extern_macros` feature. Currently you can define a
procedural macro attribute but you can't import it to call it!
A summary of the changes made in this PR (as well as the various consequences)
is:
* The `proc_macro` language and library features are now stable.
* Other APIs not stabilized in the `proc_macro` crate are now named under a
different feature, such as `proc_macro_diagnostic` or `proc_macro_span`.
* A few checks in resolution for `proc_macro` being enabled have switched over
to `use_extern_macros` being enabled. This means that code using
`#![feature(proc_macro)]` today will likely need to move to
`#![feature(use_extern_macros)]`.
It's intended that this PR, once landed, will be followed up with an attempt to
stabilize a small slice of `use_extern_macros` just for procedural macros to
make this feature 100% usable on stable.
[1]: https://internals.rust-lang.org/t/help-stabilize-a-subset-of-macros-2-0/7252
This commit adds explicit imp blocks to ensure that all publicly exported types
(except simple enums) are not `Send` nor `Sync` in the `proc_macro` crate.
cc #38356
proc_macro: Generalize `FromIterator` impl
While never intended to be stable we forgot that trait impls are insta-stable!
This construction of `FromIterator` wasn't our first choice of how to stabilize
the impl but our hands are tied at this point, so revert back to the original
definition of `FromIterator` before #49597Closes#49725
A span covering a single byte, such as for an operator `+` token, should
print as e.g. `80..81` rather than `80...81`. The lo end of the range is
inclusive and the hi end is exclusive.
This commit improves the `fmt::Debug` output of `proc_macro` data structures by
primarily focusing on the representation exposed by `proc_macro` rather than the
compiler's own internal representation. This cuts down quite a bit on assorted
wrapper types and ensure a relatively clean output.
Closes#49720
While never intended to be stable we forgot that trait impls are insta-stable!
This construction of `FromIterator` wasn't our first choice of how to stabilize
the impl but our hands are tied at this point, so revert back to the original
definition of `FromIterator` before #49597Closes#49725
* Expand `!` tokens for inner doc comments
* Trim leading doc comment decoration in the string literal
Both of these should help bring the expansion inline with what `macro_rules!`
already does.
Closes#49655Closes#49656
This commit is a reorganization of the `proc_macro` crate's public user-facing
API. This is the result of a number of discussions at the recent Rust All-Hands
where we're hoping to get the `proc_macro` crate into ship shape for
stabilization of a subset of its functionality in the Rust 2018 release.
The reorganization here is motivated by experiences from the `proc-macro2`,
`quote`, and `syn` crates on crates.io (and other crates which depend on them).
The main focus is future flexibility along with making a few more operations
consistent and/or fixing bugs. A summary of the changes made from today's
`proc_macro` API is:
* The `TokenNode` enum has been removed and the public fields of `TokenTree`
have also been removed. Instead the `TokenTree` type is now a public enum
(what `TokenNode` was) and each variant is an opaque struct which internally
contains `Span` information. This makes the various tokens a bit more
consistent, require fewer wrappers, and otherwise provides good
future-compatibility as opaque structs are easy to modify later on.
* `Literal` integer constructors have been expanded to be unambiguous as to what
they're doing and also allow for more future flexibility. Previously
constructors like `Literal::float` and `Literal::integer` were used to create
unsuffixed literals and the concrete methods like `Literal::i32` would create
a suffixed token. This wasn't immediately clear to all users (the
suffixed/unsuffixed aspect) and having *one* constructor for unsuffixed
literals required us to pick a largest type which may not always be true. To
fix these issues all constructors are now of the form
`Literal::i32_unsuffixed` or `Literal::i32_suffixed` (for all integral types).
This should allow future compatibility as well as being immediately clear
what's suffixed and what isn't.
* Each variant of `TokenTree` internally contains a `Span` which can also be
configured via `set_span`. For example `Literal` and `Term` now both
internally contain a `Span` rather than having it stored in an auxiliary
location.
* Constructors of all tokens are called `new` now (aka `Term::intern` is gone)
and most do not take spans. Manufactured tokens typically don't have a fresh
span to go with them and the span is purely used for error-reporting
**except** the span for `Term`, which currently affects hygiene. The default
spans for all these constructed tokens is `Span::call_site()` for now.
The `Term` type's constructor explicitly requires passing in a `Span` to
provide future-proofing against possible hygiene changes. It's intended that a
first pass of stabilization will likely only stabilize `Span::call_site()`
which is an explicit opt-in for "I would like no hygiene here please". The
intention here is to make this explicit in procedural macros to be
forwards-compatible with a hygiene-specifying solution.
* Some of the conversions for `TokenStream` have been simplified a little.
* The `TokenTreeIter` iterator was renamed to `token_stream::IntoIter`.
Overall the hope is that this is the "final pass" at the API of `TokenStream`
and most of `TokenTree` before stabilization. Explicitly left out here is any
changes to `Span`'s API which will likely need to be re-evaluated before
stabilization.
All changes in this PR have already been reflected to the [`proc-macro2`],
`quote`, and `syn` crates. New versions of all these crates have also been
published to crates.io.
Once this lands in nightly I plan on making an internals post again summarizing
the changes made here and also calling on all macro authors to give the APIs a
spin and see how they work. Hopefully pending no major issues we can then have
an FCP to stabilize later this cycle!
[`proc-macro2`]: https://docs.rs/proc-macro2/0.3.1/proc_macro2/
This commit tweaks the tokenization of a doc comment to use `#[doc = "..."]`
like `macro_rules!` does (instead of treating it as a `Literal` token).
Additionally it fixes treatment of negative literals in the compiler, for
exapmle `Literal::i32(-1)`. The current fix is a bit of a hack around the
current compiler implementation, providing a fix at the proc-macro layer rather
than the libsyntax layer.
