From c4fc9ff0d30a56dae9ca1ba44e407d20f21e6516 Mon Sep 17 00:00:00 2001 From: Nicholas Nethercote Date: Mon, 22 Jan 2024 13:31:52 +1100 Subject: [PATCH] Document `Token{Stream,Tree}::Display` more thoroughly. To expressly warn against the kind of proc macro implementation that was broken in #119875. --- library/proc_macro/src/lib.rs | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/library/proc_macro/src/lib.rs b/library/proc_macro/src/lib.rs index ca83e2be5c147..87e89a464bc1a 100644 --- a/library/proc_macro/src/lib.rs +++ b/library/proc_macro/src/lib.rs @@ -191,6 +191,14 @@ impl ToString for TokenStream { /// 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 /// 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")] impl fmt::Display for TokenStream { 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 /// into the same token tree (modulo spans), except for possibly `TokenTree::Group`s /// 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")] impl fmt::Display for TokenTree { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {