chore(lib): add debug feature

This adds a debug feature, similar to what Clap does, as requested by #379.

The current implementation only debugs a few parts of the code, and it may be interesting to add more debug messages in the different crates.

Cargo.toml

@@ -42,6 +42,8 @@ shared-version = true
 bench = false
 
 [features]
+# Enables debug messages
+debug = ["logos-derive?/debug"]
 default = ["export_derive", "std"]
 # Re-exports the `Logos` derive macro, so that end user only needs to
 # import this crate and `use logos::Logos` to get both the trait and

logos-cli/Cargo.toml

@@ -10,6 +10,10 @@ assert_cmd = "2.0.4"
 assert_fs = "1.0.7"
 predicates = "2.1.1"
 
+[features]
+# Enables debug messages
+debug = ["logos-codegen/debug"]
+
 [package]
 name = "logos-cli"
 authors.workspace = true

logos-codegen/Cargo.toml

@@ -10,6 +10,10 @@ syn = { version = "2.0.13", features = ["full"] }
 [dev-dependencies]
 pretty_assertions = "1.4.0"
 
+[features]
+# Enables debug messages
+debug = []
+
 [lib]
 bench = false
 

logos-codegen/src/lib.rs

@@ -16,6 +16,10 @@ mod mir;
 mod parser;
 mod util;
 
+#[macro_use]
+#[allow(missing_docs)]
+mod macros;
+
 use generator::Generator;
 use graph::{DisambiguationError, Fork, Graph, Rope};
 use leaf::Leaf;
@@ -36,6 +40,8 @@ const REGEX_ATTR: &str = "regex";
 
 /// Generate a `Logos` implementation for the given struct, provided as a stream of rust tokens.
 pub fn generate(input: TokenStream) -> TokenStream {
+    debug!("Reading input token streams");
+
     let mut item: ItemEnum = syn::parse2(input).expect("Logos can be only be derived for enums");
 
     let name = &item.ident;
@@ -72,6 +78,8 @@ pub fn generate(input: TokenStream) -> TokenStream {
         }
     }
 
+    debug!("Iterating through enum variants");
+
     for variant in &mut item.variants {
         let field = match &mut variant.fields {
             Fields::Unit => MaybeVoid::Void,
@@ -200,6 +208,8 @@ pub fn generate(input: TokenStream) -> TokenStream {
 
     let mut root = Fork::new();
 
+    debug!("Parsing additional options (extras, source, ...)");
+
     let error_type = parser.error_type.take();
     let extras = parser.extras.take();
     let source = parser
@@ -251,6 +261,8 @@ pub fn generate(input: TokenStream) -> TokenStream {
             break;
         }
     }
+
+    debug!("Checking if any two tokens have the same priority");
 
     for &DisambiguationError(a, b) in graph.errors() {
         let a = graph[a].unwrap_leaf();
@@ -283,6 +295,8 @@ pub fn generate(input: TokenStream) -> TokenStream {
 
     graph.shake(root);
 
+    debug!("Generating code from graph: {graph:#?}");
+
     let generator = Generator::new(name, &this, root, &graph);
 
     let body = generator.generate();

logos-codegen/src/macros.rs

@@ -0,0 +1,12 @@
+#[cfg(feature = "debug")]
+macro_rules! debug {
+    ($($arg:tt)*) => {
+        eprint!("[{}:{}:{}] ", file!(), line!(), column!());
+        eprintln!($($arg)*)
+    }
+}
+
+#[cfg(not(feature = "debug"))]
+macro_rules! debug {
+    ($($arg:tt)*) => {};
+}

logos-derive/Cargo.toml

@@ -1,6 +1,10 @@
 [dependencies]
 logos-codegen = {version = "0.14.0", path = "../logos-codegen"}
 
+[features]
+# Enables debug messages
+debug = ["logos-codegen/debug"]
+
 [lib]
 bench = false
 proc-macro = true