bjoernager/rust
bjoernager/rust
1
Fork 0
Code Issues Pull requests Activity

Document Token{Stream,Tree}::Display more thoroughly.

Browse source 
To expressly warn against the kind of proc macro implementation that was
broken in #119875.
This commit is contained in:
Nicholas Nethercote 2024-01-22 13:31:52 +11:00
parent ef71f1047e
commit c4fc9ff0d3
1 changed files with 16 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

16
library/proc_macro/src/lib.rs
View file

@ -191,6 +191,14 @@ impl ToString for TokenStream {
/// Prints the token stream as a string that is supposed to be losslessly convertible back /// Prints the token stream as a string that is supposed to be losslessly convertible back
/// into the same token stream (modulo spans), except for possibly `TokenTree::Group`s /// into the same token stream (modulo spans), except for possibly `TokenTree::Group`s
/// with `Delimiter::None` delimiters and negative numeric literals. /// with `Delimiter::None` delimiters and negative numeric literals.
///
/// Note: the exact form of the output is subject to change, e.g. there might
/// be changes in the whitespace used between tokens. Therefore, you should
/// *not* do any kind of simple substring matching on the output string (as
/// produced by `to_string`) to implement a proc macro, because that matching
/// might stop working if such changes happen. Instead, you should work at the
/// `TokenTree` level, e.g. matching against `TokenTree::Ident`,
/// `TokenTree::Punct`, or `TokenTree::Literal`.
#[stable(feature = "proc_macro_lib", since = "1.15.0")] #[stable(feature = "proc_macro_lib", since = "1.15.0")]
impl fmt::Display for TokenStream { impl fmt::Display for TokenStream {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
@ -758,6 +766,14 @@ impl ToString for TokenTree {
/// Prints the token tree as a string that is supposed to be losslessly convertible back /// Prints the token tree as a string that is supposed to be losslessly convertible back
/// into the same token tree (modulo spans), except for possibly `TokenTree::Group`s /// into the same token tree (modulo spans), except for possibly `TokenTree::Group`s
/// with `Delimiter::None` delimiters and negative numeric literals. /// with `Delimiter::None` delimiters and negative numeric literals.
///
/// Note: the exact form of the output is subject to change, e.g. there might
/// be changes in the whitespace used between tokens. Therefore, you should
/// *not* do any kind of simple substring matching on the output string (as
/// produced by `to_string`) to implement a proc macro, because that matching
/// might stop working if such changes happen. Instead, you should work at the
/// `TokenTree` level, e.g. matching against `TokenTree::Ident`,
/// `TokenTree::Punct`, or `TokenTree::Literal`.
#[stable(feature = "proc_macro_lib2", since = "1.29.0")] #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl fmt::Display for TokenTree { impl fmt::Display for TokenTree {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {