Merge pull request #4 from ggwpez/dev

v0.4.0

Author: ggwpez

.github/workflows/rust.yml

@@ -26,11 +26,14 @@ jobs:
     - name: Format
       run: cargo fmt --all -- --check
 
+    - name: Check no-std
+      run: cargo check --all-targets --no-default-features # still broken --locked
+
     - name: Build
-      run: cargo build --all-targets --all-features # --locked TODO
+      run: cargo build --all-targets --all-features --locked
 
     - name: Test
-      run: cargo test --locked --all-targets --all-features
+      run: TRYBUILD=overwrite cargo test --locked --all-targets --all-features
 
     - name: Clippy
       run: cargo clippy --locked --all-targets --all-features -- -D warnings

.gitignore

@@ -1,3 +1,7 @@
 /target/
+**/target
+
 Cargo.lock
 **/*.rs.bk
+
+.vscode/

Cargo.toml

@@ -1,18 +1,7 @@
-[package]
-name = "proc-macro-warning"
-version = "0.3.1"
-edition = "2021"
-license = "GPL-3.0 OR Apache-2.0"
-authors = ["Oliver Tale-Yazdi <[email protected]>"]
-description = "Emit warnings from inside proc macros."
-repository = "https://github.com/ggwpez/proc-macro-warning"
+[workspace]
 
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
-
-[dependencies]
-proc-macro2 = { version = "1.0.56", default-features = false }
-quote = { version = "1.0.26", default-features = false }
-syn = { version = "2.0.15", default-features = false }
-
-[features]
-default = []
+members = [
+	"proc-macro-warning",
+	"ui-tests/derive",
+	"ui-tests/ui",
+]

README.md

@@ -24,6 +24,7 @@ Building a warning is easy with the builder pattern.
 
 ```rust
 use proc_macro_warning::Warning;
+
 let warning = Warning::new_deprecated("my_macro")
 	.old("my_macro()")
 	.new("my_macro::new()")
@@ -35,11 +36,45 @@ let warning = Warning::new_deprecated("my_macro")
 let tokens = quote::quote!(#warning);
 ```
 
+This works in derive-macros, but you **must** set a span; otherwise it will not show up in the compile output.
+
+The difference to a `#[deprecated]` attribute is that it emits the warning either way. For example when creating a custom `Deprecated` derive macro, it will warn without the struct being constructed.
+
+```rust
+#[derive(derive::Deprecated)]
+struct Test {}
+
+fn main() {
+  // Warning triggers although we never used `Test`.  
+  // Otherwise use a normal `#[deprecated]`.
+}
+```
+
+## Un-opinionated Formatting
+
+The normal aforementioned way of creating a warning will impose specific unified grammar and formatting rules.  
+You can opt out of this and use your own instead by using `FormattedWarning::new_deprecated`:  
+
+```rust
+use proc_macro_warning::FormattedWarning;
+
+let warning = FormattedWarning::new_deprecated(
+      "my_macro",
+      "looooooooooooooooooooooooooooooong line that will not be brokeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeen ;)",
+      proc_macro2::Span::call_site(),
+    );
+
+// Use the warning in a proc macro
+let tokens = quote::quote!(#warning);
+```
+
+The output of a [similar example](ui-tests/derive/src/lib.rs) is in [derive_raw.stderr](ui-tests/ui/src/warn/derive_raw.stderr).
+
 ## Used In 
 
-Substrate (since [#13798](https://github.com/paritytech/substrate/pull/13798)) uses this to emit warnings for its FRAME eDSL on deprecated behaviour.
+Substrate uses it to emit warnings for its eDSL (FRAME) on deprecated behaviour. The integration was done in [#13798](https://github.com/paritytech/substrate/pull/13798) and shows how to use these warnings in macro expansion.
 
-For example not putting a `call_index` on your functions produces:
+The warnings are uniformly formatted and have consistent grammar:
 ```pre
 warning: use of deprecated constant `pallet::warnings::ImplicitCallIndex_0::_w`:
                  It is deprecated to use implicit call indices.
@@ -55,7 +90,7 @@ warning: use of deprecated constant `pallet::warnings::ImplicitCallIndex_0::_w`:
      |
 ```
 
-Or using a hard-coded weight:
+A different one:
 ```pre
 warning: use of deprecated constant `pallet::warnings::ConstantWeight_0::_w`:
                  It is deprecated to use hard-coded constant as call weight.
@@ -69,13 +104,12 @@ warning: use of deprecated constant `pallet::warnings::ConstantWeight_0::_w`:
      |                          
 ```
 
-
 ## License
 
 Licensed under either of at your own choice:
 
-* GNU GENERAL PUBLIC LICENSE, Version 3 ([LICENSE-GPL3](./LICENSE-GPL3) or https://www.gnu.org/licenses/gpl-3.0.txt)
-* Apache License, Version 2.0 ([LICENSE-APACHE2](/LICENSE-APACHE2) or https://www.apache.org/licenses/LICENSE-2.0.txt).
+* GNU GENERAL PUBLIC LICENSE, Version 3 ([LICENSE-GPL3](./LICENSE-GPL3) or [gnu.org](https://www.gnu.org/licenses/gpl-3.0.txt>))
+* Apache License, Version 2.0 ([LICENSE-APACHE2](/LICENSE-APACHE2) or [apache.org](https://www.apache.org/licenses/LICENSE-2.0.txt>)).
 
 ### Contribution
 

proc-macro-warning/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "proc-macro-warning"
+version = "0.4.0"
+edition = "2021"
+license = "GPL-3.0 OR Apache-2.0"
+authors = ["Oliver Tale-Yazdi <[email protected]>"]
+description = "Emit warnings from inside proc macros."
+repository = "https://github.com/ggwpez/proc-macro-warning"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+proc-macro2 = { version = "1.0.56", default-features = false }
+quote = { version = "1.0.27", default-features = false }
+syn = { version = "2.0.16", default-features = false }
+
+[dev-dependencies]
+derive = { path = "../ui-tests/derive" }
+
+[features]
+default = []

src/lib.rs proc-macro-warning/src/lib.rssrc/lib.rs renamed to proc-macro-warning/src/lib.rs

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: (GPL-3.0 or Apache-2.0)
  */
 
-//! Emit warnings from inside proc macros.
+#![doc = include_str!("../../README.md")]
 
 use core::ops::Deref;
 use proc_macro2::Span;
@@ -12,32 +12,74 @@ use quote::{quote_spanned, ToTokens};
 mod test;
 
 /// Creates a compile-time warning for proc macro use. See [DeprecatedWarningBuilder] for usage.
-pub struct Warning {
-	pub name: String,
-	pub index: Option<usize>,
-	pub message: String,
-	pub links: Vec<String>,
-	pub span: Span,
+#[derive(Clone)]
+pub enum Warning {
+	/// A *deprecation* warning that notifies users of outdated types and functions.
+	Deprecated {
+		name: String,
+		index: Option<usize>,
+		message: String,
+		links: Vec<String>,
+		span: Span,
+	},
 }
 
-/// Gradually build a "deprecated" `Warning`.
+/// A compile-time warning that was already subject to formatting.
+///
+/// Any content will be pasted as-is.
+#[derive(Clone)]
+pub enum FormattedWarning {
+	/// A *deprecation* warning.
+	Deprecated {
+		/// Unique name of this warning.
+		///
+		/// Must be unique in the case that multiple of these warnings are emitted, for example by
+		/// appending a counter.
+		name: syn::Ident,
+		/// The exact note to be used for `note = ""`.
+		note: String,
+		/// The span of the warning.
+		///
+		/// Should be set to the original location of where the warning should be emitted.
+		span: Option<Span>,
+	},
+}
+
+impl FormattedWarning {
+	/// Create a new deprecated warning that already was formatted by the caller.
+	#[must_use]
+	pub fn new_deprecated<'a, S, T>(name: S, note: T, span: Span) -> Self
+	where
+		S: Into<&'a str>,
+		T: Into<String>,
+	{
+		Self::Deprecated {
+			name: syn::Ident::new(name.into(), span),
+			note: note.into(),
+			span: Some(span),
+		}
+	}
+}
+
+/// Gradually build a *deprecation* `Warning`.
 ///
 /// # Example
-/// ```
+///
+/// ```rust
 /// use proc_macro_warning::Warning;
 ///
 /// let warning = Warning::new_deprecated("my_macro")
 ///     .old("my_macro()")
 ///     .new("my_macro::new()")
 ///     .help_link("https:://example.com")
+///     // Normally you use the input span, but this is an example:
 ///     .span(proc_macro2::Span::call_site())
 ///     .build();
 ///
-/// // Use the warning in a proc macro
-/// let tokens = quote::quote!(#warning);
+/// let mut warnings = vec![warning];
+/// // When adding more, you will need to build each with `.index`.
 ///
-/// let warnings = vec![warning];
-/// // In a proc macro you would expand them inside a module:
+/// // In a proc macro you can expand them in a private module:
 /// quote::quote! {
 ///     mod warnings {
 ///         #(
@@ -115,7 +157,7 @@ impl DeprecatedWarningBuilder {
 		let new = self.new.ok_or("Missing new")?;
 		let message = format!("It is deprecated to {}.\nPlease instead {}.", old, new);
 
-		Ok(Warning { name: title, index: self.index, message, links: self.links, span })
+		Ok(Warning::Deprecated { name: title, index: self.index, message, links: self.links, span })
 	}
 
 	/// Unwraps [`Self::maybe_build`] for convenience.
@@ -126,66 +168,80 @@ impl DeprecatedWarningBuilder {
 }
 
 impl Warning {
-	/// Create a new *raw* warnings.
-	pub fn new_raw(
-		name: String,
-		index: Option<usize>,
-		message: String,
-		help_links: Vec<String>,
-		span: Span,
-	) -> Warning {
-		Warning { name, index, message, links: help_links, span }
-	}
-
 	/// Create a new *deprecated* warning.
 	#[must_use]
 	pub fn new_deprecated(title: &str) -> DeprecatedWarningBuilder {
 		DeprecatedWarningBuilder::from_title(title)
 	}
 
 	/// Sanitize the warning message.
-	fn final_message(&self) -> String {
-		let lines = self.message.trim().lines().map(|line| line.trim_start());
+	fn final_deprecated_message(&self) -> String {
+		let (message, links) = match self {
+			Warning::Deprecated { message, links, .. } => (message, links),
+		};
+
+		let lines = message.trim().lines().map(|line| line.trim_start());
 		// Prepend two tabs to each line
 		let message = lines.map(|line| format!("\t\t{}", line)).collect::<Vec<_>>().join("\n");
 
-		if !self.links.is_empty() {
-			let link = self
-				.links
-				.iter()
-				.map(|l| format!("<{}>", l))
-				.collect::<Vec<_>>()
-				.join("\n\t\t\t");
+		if !links.is_empty() {
+			let link =
+				links.iter().map(|l| format!("<{}>", l)).collect::<Vec<_>>().join("\n\t\t\t");
 			format!("\n{}\n\n\t\tFor more info see:\n\t\t\t{}", message, link)
 		} else {
 			format!("\n{}", message)
 		}
 	}
 
 	/// Sanitize the warning name.
-	fn final_name(&self) -> syn::Ident {
-		let name = match self.index {
-			Some(i) => format!("{}_{}", self.name, i),
-			None => self.name.clone(),
+	fn final_deprecated_name(&self) -> syn::Ident {
+		let (index, name, span) = match self {
+			Warning::Deprecated { index, name, span, .. } => (*index, name, *span),
+		};
+
+		let name = match index {
+			Some(i) => format!("{}_{}", name, i),
+			None => name.clone(),
 		};
-		syn::Ident::new(&name, self.span)
+		syn::Ident::new(&name, span)
+	}
+}
+
+impl From<Warning> for FormattedWarning {
+	fn from(val: Warning) -> Self {
+		match val {
+			Warning::Deprecated { span, .. } => FormattedWarning::Deprecated {
+				name: val.final_deprecated_name(),
+				note: val.final_deprecated_message(),
+				span: Some(span),
+			},
+		}
 	}
 }
 
 impl ToTokens for Warning {
 	fn to_tokens(&self, stream: &mut proc_macro2::TokenStream) {
-		let name = self.final_name();
-		let message = self.final_message();
+		let formatted: FormattedWarning = self.clone().into();
+		formatted.to_tokens(stream);
+	}
+}
+
+impl ToTokens for FormattedWarning {
+	fn to_tokens(&self, stream: &mut proc_macro2::TokenStream) {
+		let (name, note, span) = match self {
+			FormattedWarning::Deprecated { name, note, span } => (name, note, span),
+		};
+		let span = span.unwrap_or_else(Span::call_site);
 
-		let q = quote_spanned!(self.span =>
+		let q = quote_spanned!(span =>
 			/// This function should not be called and only exists to emit a compiler warning.
 			///
-			/// It is a No-OP if you want try it anyway ;)
+			/// It is a No-OP in any case.
 			#[allow(dead_code)]
 			#[allow(non_camel_case_types)]
 			#[allow(non_snake_case)]
 			fn #name() {
-				#[deprecated(note = #message)]
+				#[deprecated(note = #note)]
 				#[allow(non_upper_case_globals)]
 				const _w: () = ();
 				let _ = _w;

src/test.rs proc-macro-warning/src/test.rssrc/test.rs renamed to proc-macro-warning/src/test.rs

@@ -22,7 +22,7 @@ fn example_works() {
 	let want_tokens = quote!(
 		/// This function should not be called and only exists to emit a compiler warning.
 		///
-		/// It is a No-OP if you want try it anyway ;)
+		/// It is a No-OP in any case.
 		#[allow(dead_code)]
 		#[allow(non_camel_case_types)]
 		#[allow(non_snake_case)]

ui-tests/Cargo.toml

@@ -0,0 +1,5 @@
+[workspace]
+members = [
+	"derive",
+	"ui"
+]

ui-tests/derive/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "derive"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[lib]
+proc-macro = true
+
+[dependencies]
+proc-macro-warning = { path = "../../proc-macro-warning" }
+quote = "1.0.27"
+syn = "2.0.16"