wip

Author: Wandalen

module/core/former/plan.md

@@ -151,15 +151,49 @@
     *   Test Matrix: Not applicable for this refactoring increment directly, but existing tests cover behavior.
     *   Commit Message: `refactor(former_meta): Improve unit variant handling using macro_tools`
 
-*   [⚫] **Increment 6: Implement Generalizations (New Utilities in `macro_tools`)**
+*   [⏳] **Increment 6: Implement Generalizations (New Utilities in `macro_tools`)**
     *   Target Crate(s): `macro_tools`
-    *   Pre-Analysis: Review the approved new utilities for `macro_tools` from Increment 4.
-    *   Detailed Plan Step 1: Implement the new general-purpose utilities in the appropriate modules within `macro_tools/src/`.
-    *   Detailed Plan Step 2: Add comprehensive unit tests for these new utilities within `macro_tools/tests/inc/`. Each new public function/method should have corresponding tests.
-    *   Detailed Plan Step 3: Update `macro_tools/src/lib.rs` and relevant module files (`mod.rs`) to correctly export the new utilities under the appropriate namespaces (`own`, `orphan`, `exposed`, `prelude`).
-    *   Detailed Plan Step 4: Add clear ///doc comments for all new public items in `macro_tools`.
-    *   Crucial Design Rules: [Traits: Encourage Modular Design], [Visibility: Keep Implementation Details Private], [Comments and Documentation].
-    *   Verification Strategy: User applies changes. `cargo test --package macro_tools` must pass. `cargo doc --package macro_tools --no-deps` should build successfully.
+    *   Pre-Analysis: Review the approved new utilities for `macro_tools` from Increment 4. These are:
+        1.  `macro_tools::ident::new_ident_from_cased_str`
+        2.  `macro_tools::generic_params::GenericsRef` enhanced methods:
+            *   `impl_generics_tokens_if_any()`
+            *   `ty_generics_tokens_if_any()`
+            *   `where_clause_tokens_if_any()`
+            *   `type_path_tokens_if_any()`
+            *   (And the conceptual private helper `split_for_impl_syn_components` or equivalent logic to access decomposed generic parts).
+    *   Detailed Plan Step 1: Implement these utilities in `module/core/macro_tools/src/ident.rs` and `module/core/macro_tools/src/generic_params.rs`.
+    *   Detailed Plan Step 2: Add comprehensive unit tests for these new utilities. This will involve creating new test files or extending existing ones in `module/core/macro_tools/tests/inc/` (e.g., a new `ident_general_tests.rs`, `generic_params_ref_tests.rs` or similar, and updating `module/core/macro_tools/tests/inc/mod.rs`).
+    *   Detailed Plan Step 3: Update `module/core/macro_tools/src/lib.rs` and relevant module files (`ident.rs`, `generic_params.rs` themselves if they define `pub` items, or their parent `mod.rs` if they are submodules) to correctly export the new public utilities.
+    *   Detailed Plan Step 4: Add clear `///doc` comments for all new public items in `macro_tools`.
+    *   Crucial Design Rules: [Traits: Encourage Modular Design], [Visibility: Keep Implementation Details Private], [Comments and Documentation], [Testing: Plan with a Test Matrix When Writing Tests].
+    *   Relevant Behavior Rules: N/A directly, but API design should be robust and adhere to Rust conventions.
+    *   Verification Strategy:
+        *   User applies changes to `macro_tools`.
+        *   `cargo check --package macro_tools` must pass.
+        *   `cargo test --package macro_tools` must pass.
+        *   `cargo doc --package macro_tools --no-deps` should build successfully.
+        *   `cargo clippy --package macro_tools --all-targets -- -D warnings` should pass.
+    *   Test Matrix:
+        *   **For `new_ident_from_cased_str` (in `macro_tools::ident`):**
+            *   ID: T6.1, Input: (`"normal_ident"`, `span`, `false`), Expected: `Ok(syn::Ident::new("normal_ident", span))`
+            *   ID: T6.2, Input: (`"fn"`, `span`, `false`), Expected: `Ok(syn::Ident::new_raw("fn", span))` (keyword becomes raw)
+            *   ID: T6.3, Input: (`"fn"`, `span`, `true`), Expected: `Ok(syn::Ident::new_raw("fn", span))` (original raw, cased is keyword)
+            *   ID: T6.4, Input: (`"my_raw_ident"`, `span`, `true`), Expected: `Ok(syn::Ident::new_raw("my_raw_ident", span))` (original raw, cased not keyword)
+            *   ID: T6.5, Input: (`""`, `span`, `false`), Expected: `Err(_)` (empty string)
+            *   ID: T6.6, Input: (`"with space"`, `span`, `false`), Expected: `Err(_)` (invalid ident chars)
+            *   ID: T6.7, Input: (`"ValidIdent"`, `span`, `false`), Expected: `Ok(syn::Ident::new("ValidIdent", span))` (function assumes input is already cased as desired for the ident name itself, only keyword/raw status is handled).
+        *   **For `GenericsRef` methods (in `macro_tools::generic_params`):**
+            *   (Setup: `let generics_std: syn::Generics = syn::parse_quote! { <T: Display + 'a, 'a, const N: usize> where T: Debug > };`)
+            *   (Setup: `let generics_empty: syn::Generics = syn::parse_quote! { };`)
+            *   (Setup: `let enum_name: syn::Ident = syn::parse_quote! { MyEnum };`)
+            *   ID: T6.8 (`impl_generics_tokens_if_any` with `generics_std`): Expected: `Ok(quote!( <T: Display + 'a, 'a, const N: usize> ))`
+            *   ID: T6.9 (`impl_generics_tokens_if_any` with `generics_empty`): Expected: `Ok(quote!( ))`
+            *   ID: T6.10 (`ty_generics_tokens_if_any` with `generics_std`): Expected: `Ok(quote!( <T, 'a, N> ))`
+            *   ID: T6.11 (`ty_generics_tokens_if_any` with `generics_empty`): Expected: `Ok(quote!( ))`
+            *   ID: T6.12 (`where_clause_tokens_if_any` with `generics_std`): Expected: `Ok(quote!( where T: Debug ))`
+            *   ID: T6.13 (`where_clause_tokens_if_any` with `generics_empty`): Expected: `Ok(quote!( ))`
+            *   ID: T6.14 (`type_path_tokens_if_any` with `generics_std`, `enum_name`): Expected: `Ok(quote!( MyEnum::<T, 'a, N> ))`
+            *   ID: T6.15 (`type_path_tokens_if_any` with `generics_empty`, `enum_name`): Expected: `Ok(quote!( MyEnum ))`
     *   Commit Message: `feat(macro_tools): Add new utilities generalized from former_meta enum handling`
 
 *   [⚫] **Increment 7: Final Verification and Documentation Update**

module/core/former_meta/src/derive_former/former_enum/unit_variant_handler.rs

@@ -5,7 +5,7 @@ use macro_tools::
   diag, // For diag::return_syn_err!
   generic_params::GenericsRef, // For enhanced generics handling
   ident, // For proposed ident::new_ident_from_cased_str
-  tokens::qt, // For qt! macro, if preferred over quote::quote!
+  qt, // For qt! macro, if preferred over quote::quote!
   syn,
   quote::quote_spanned, // Keep for specific span control if needed, or replace with qt!
 };

module/core/macro_tools/src/generic_params.rs

@@ -93,6 +93,204 @@ mod private
     }
   }
 
+  /// A wrapper around a reference to `syn::Generics` to provide convenient helper methods
+  /// for generating token streams related to generic parameters.
+  ///
+  /// This is particularly useful in procedural macros for constructing parts of function
+  /// signatures, type paths, and where clauses that involve generics.
+  #[derive(Debug, Clone, Copy)]
+  pub struct GenericsRef<'a>
+  {
+    syn_generics: &'a syn::Generics,
+  }
+
+  impl<'a> GenericsRef<'a>
+  {
+    /// Creates a new `GenericsRef` from a reference to `syn::Generics`.
+    #[must_use]
+    pub fn new_borrowed(syn_generics: &'a syn::Generics) -> Self
+    {
+      Self { syn_generics }
+    }
+
+    /// Returns the `impl_generics` part (e.g., `<T: Trait, 'b, const C: usize>`)
+    /// as a `TokenStream` if generics are present, otherwise an empty `TokenStream`.
+    ///
+    /// This is suitable for use in `impl <#impl_generics> Struct ...` contexts.
+    /// It includes bounds and lifetimes.
+    ///
+    /// # Errors
+    ///
+    /// Currently, this method is not expected to return an error, but returns `Result`
+    /// for future-proofing and consistency with other token-generating methods.
+    pub fn impl_generics_tokens_if_any(&self) -> Result<proc_macro2::TokenStream>
+    {
+      if self.syn_generics.params.is_empty()
+      {
+        return Ok(quote::quote! {});
+      }
+      let (_, impl_g, _, _) = decompose_item_soft(self.syn_generics);
+      Ok(quote::quote! { < #impl_g > })
+    }
+
+    /// Returns the `ty_generics` part (e.g., `<T, 'b, C>`) as a `TokenStream`
+    /// if generics are present, otherwise an empty `TokenStream`.
+    ///
+    /// This is suitable for use in type paths like `Struct::<#ty_generics>`.
+    /// It includes only the identifiers of the generic parameters (types, lifetimes, consts).
+    ///
+    /// # Errors
+    ///
+    /// Currently, this method is not expected to return an error, but returns `Result`
+    /// for future-proofing and consistency.
+    pub fn ty_generics_tokens_if_any(&self) -> Result<proc_macro2::TokenStream>
+    {
+      if self.syn_generics.params.is_empty()
+      {
+        return Ok(quote::quote! {});
+      }
+      let (_, _, ty_g, _) = decompose_item_soft(self.syn_generics);
+      Ok(quote::quote! { < #ty_g > })
+    }
+
+    /// Returns the `where_clause` (e.g., `where T: Trait`) as a `TokenStream`
+    /// if a where clause is present in the original generics, otherwise an empty `TokenStream`.
+    ///
+    /// # Errors
+    ///
+    /// Currently, this method is not expected to return an error, but returns `Result`
+    /// for future-proofing and consistency.
+    pub fn where_clause_tokens_if_any(&self) -> Result<proc_macro2::TokenStream>
+    {
+      let (_, _, _, where_c_punctuated) = decompose_item_soft(self.syn_generics);
+      if where_c_punctuated.is_empty() {
+        Ok(quote::quote! {})
+      } else {
+        Ok(quote::quote! { where #where_c_punctuated })
+      }
+    }
+
+    /// Returns a token stream representing a path to a type, including its generic arguments
+    /// if present (e.g., `MyType::<T, U>`). If no generics are present, it returns
+    /// just the `base_ident`.
+    ///
+    /// # Arguments
+    ///
+    /// * `base_ident`: The identifier of the base type (e.g., `MyType`).
+    ///
+    /// # Errors
+    ///
+    /// Currently, this method is not expected to return an error, but returns `Result`
+    /// for future-proofing and consistency.
+    pub fn type_path_tokens_if_any(&self, base_ident: &syn::Ident) -> Result<proc_macro2::TokenStream>
+    {
+      if self.syn_generics.params.is_empty()
+      {
+        Ok(quote::quote! { #base_ident })
+      } else
+      {
+        let (_, _, ty_g, _) = decompose_item_soft(self.syn_generics);
+        Ok(quote::quote! { #base_ident ::< #ty_g > })
+      }
+    }
+  }
+
+  // Helper function similar to the original `decompose`.
+  #[allow(clippy::type_complexity)]
+  fn decompose_item_soft
+  (
+    generics: &syn::Generics,
+  ) ->
+  (
+    syn::punctuated::Punctuated<syn::GenericParam, syn::token::Comma>, // with_defaults
+    syn::punctuated::Punctuated<syn::GenericParam, syn::token::Comma>, // for_impl
+    syn::punctuated::Punctuated<syn::GenericParam, syn::token::Comma>, // for_ty
+    syn::punctuated::Punctuated<syn::WherePredicate, syn::token::Comma>, // where_clause
+  )
+  {
+    let mut generics_with_defaults = generics.params.clone();
+    punctuated::ensure_trailing_comma(&mut generics_with_defaults);
+
+    let mut generics_for_impl = syn::punctuated::Punctuated::new();
+    let mut generics_for_ty = syn::punctuated::Punctuated::new();
+
+    for param in &generics.params {
+        match param {
+            syn::GenericParam::Type(type_param) => {
+                let impl_param = syn::GenericParam::Type(syn::TypeParam {
+                    attrs: vec![],
+                    ident: type_param.ident.clone(),
+                    colon_token: type_param.colon_token,
+                    bounds: type_param.bounds.clone(),
+                    eq_token: None,
+                    default: None,
+                });
+                generics_for_impl.push_value(impl_param);
+                generics_for_impl.push_punct(syn::token::Comma::default());
+
+                let ty_param = syn::GenericParam::Type(syn::TypeParam {
+                    attrs: vec![],
+                    ident: type_param.ident.clone(),
+                    colon_token: None,
+                    bounds: syn::punctuated::Punctuated::new(),
+                    eq_token: None,
+                    default: None,
+                });
+                generics_for_ty.push_value(ty_param);
+                generics_for_ty.push_punct(syn::token::Comma::default());
+            }
+            syn::GenericParam::Const(const_param) => {
+                let impl_param = syn::GenericParam::Const(syn::ConstParam {
+                    attrs: vec![],
+                    const_token: const_param.const_token,
+                    ident: const_param.ident.clone(),
+                    colon_token: const_param.colon_token,
+                    ty: const_param.ty.clone(),
+                    eq_token: None,
+                    default: None,
+                });
+                generics_for_impl.push_value(impl_param);
+                generics_for_impl.push_punct(syn::token::Comma::default());
+
+                let ty_param = syn::GenericParam::Type(syn::TypeParam { // Const params are represented by their idents for ty_generics
+                    attrs: vec![],
+                    ident: const_param.ident.clone(),
+                    colon_token: None,
+                    bounds: syn::punctuated::Punctuated::new(),
+                    eq_token: None,
+                    default: None,
+                });
+                generics_for_ty.push_value(ty_param);
+                generics_for_ty.push_punct(syn::token::Comma::default());
+            }
+            syn::GenericParam::Lifetime(lifetime_param) => {
+                generics_for_impl.push_value(syn::GenericParam::Lifetime(lifetime_param.clone()));
+                generics_for_impl.push_punct(syn::token::Comma::default());
+
+                let ty_param = syn::GenericParam::Lifetime(syn::LifetimeParam {
+                    attrs: vec![],
+                    lifetime: lifetime_param.lifetime.clone(),
+                    colon_token: None,
+                    bounds: syn::punctuated::Punctuated::new(),
+                });
+                generics_for_ty.push_value(ty_param);
+                generics_for_ty.push_punct(syn::token::Comma::default());
+            }
+        }
+    }
+
+    let generics_where = if let Some(where_clause) = &generics.where_clause {
+        let mut predicates = where_clause.predicates.clone();
+        punctuated::ensure_trailing_comma(&mut predicates);
+        predicates
+    } else {
+        syn::punctuated::Punctuated::new()
+    };
+
+    (generics_with_defaults, generics_for_impl, generics_for_ty, generics_where)
+  }
+
+
   /// Merges two `syn::Generics` instances into a new one.
   ///
   /// This function takes two references to `syn::Generics` and combines their
@@ -147,7 +345,6 @@ mod private
     };
 
     // Merge params
-    // result.params.extend( a.params.iter().chain( b.params.iter() ) );
     for param in &a.params
     {
       result.params.push( param.clone() );
@@ -213,7 +410,6 @@ mod private
   #[ must_use ]
   pub fn only_names( generics : &syn::Generics ) -> syn::Generics
   {
-    // use syn::{ Generics, GenericParam, LifetimeDef, TypeParam, ConstParam };
     use syn::{ Generics, GenericParam, LifetimeParam, TypeParam, ConstParam };
 
     let result = Generics
@@ -291,11 +487,6 @@ mod private
   #[ must_use ]
   pub fn names( generics : &syn::Generics )
   -> impl IterTrait< '_, &syn::Ident >
-  // -> std::iter::Map
-  // <
-  //   syn::punctuated::Iter< 'a, syn::GenericParam >,
-  //   impl FnMut( &'a syn::GenericParam ) -> &'a syn::Ident + 'a,
-  // >
   {
     generics.params.iter().map( | param | match param
     {
@@ -531,6 +722,7 @@ pub mod own
     only_names,
     names,
     decompose,
+    GenericsRef,
   };
 }
 

module/core/macro_tools/src/ident.rs

@@ -44,6 +44,67 @@ mod private
       ident.clone()
     }
   }
+
+  /// Creates a `syn::Ident` from a string that is already in the target case.
+  /// Handles Rust keywords and original raw identifier status.
+  /// If `cased_name_str` is a keyword, or if `source_had_raw_prefix` is true,
+  /// `syn::Ident::new_raw` is used. Otherwise, `syn::Ident::new` is used.
+  ///
+  /// Returns an error if `cased_name_str` is empty or an invalid identifier.
+  pub fn new_ident_from_cased_str
+  (
+    cased_name_str: &str,
+    span: proc_macro2::Span,
+    source_had_raw_prefix: bool
+  ) -> Result<syn::Ident> // Use local Result<T> alias
+  {
+    if cased_name_str.is_empty() {
+      return Err(syn::Error::new(span, "Cannot create identifier from empty string"));
+    }
+
+    // Comprehensive list of Rust 2021 keywords that are problematic as idents.
+    // Based on https://doc.rust-lang.org/reference/keywords.html
+    const RUST_KEYWORDS: &[&str] = &[
+      // Strict keywords
+      "as", "break", "const", "continue", "crate", "else", "enum", "extern", "false", "fn",
+      "for", "if", "impl", "in", "let", "loop", "match", "mod", "move", "mut", "pub",
+      "ref", "return", "self", "Self", "static", "struct", "super", "trait", "true",
+      "type", "unsafe", "use", "where", "while",
+      // Reserved keywords
+      "abstract", "async", "await", "become", "box", "do", "final", "macro", "override",
+      "priv", "try", "typeof", "unsized", "virtual", "yield",
+      // Weak keywords
+      "dyn", "union",
+    ];
+
+    let is_keyword = RUST_KEYWORDS.contains(&cased_name_str);
+
+    if source_had_raw_prefix || is_keyword {
+      // Validate if the string is permissible for new_raw, even if it's a keyword.
+      // For example, "123" is not a keyword but also not valid for new_raw("123", span).
+      // A simple validation is to check if it would parse if it *weren't* a keyword.
+      // This is tricky because `syn::parse_str` would fail for actual keywords.
+      // Let's rely on `syn::Ident::new_raw` to do its job, but catch obvious non-ident chars.
+      if cased_name_str.chars().any(|c| !c.is_alphanumeric() && c != '_') {
+         if !( cased_name_str.starts_with('_') && cased_name_str.chars().skip(1).all(|c| c.is_alphanumeric() || c == '_') ) && cased_name_str != "_" {
+            return Err(syn::Error::new(span, format!("Invalid characters in identifier string for raw creation: {}", cased_name_str)));
+         }
+      }
+      Ok(syn::Ident::new_raw(cased_name_str, span))
+    } else {
+      // Not a keyword and source was not raw. Try to create a normal identifier.
+      // syn::Ident::new would panic on keywords, but we've established it's not a keyword.
+      // It will also panic on other invalid idents like "123" or "with space".
+      // To provide a Result, we attempt to parse it.
+      match syn::parse_str::<syn::Ident>(cased_name_str) {
+        Ok(ident) => Ok(ident),
+        Err(_e) => {
+          // Construct a new error, because the error from parse_str might not have the right span or context.
+          Err(syn::Error::new(span, format!("Invalid identifier string: '{}'", cased_name_str)))
+        }
+      }
+    }
+  }
 }
 
 #[ doc( inline ) ]
@@ -59,7 +120,9 @@ pub mod own
   #[ doc( inline ) ]
   pub use orphan::*;
   #[ doc( inline ) ]
-  pub use private::ident_maybe_raw; // Export the renamed function
+  pub use private::ident_maybe_raw;
+  #[ doc( inline ) ]
+  pub use private::new_ident_from_cased_str;
 }
 
 /// Orphan namespace of the module.