Adding `macro_tools` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add macro_tools

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

macro_tools = "0.81.0"

The macro_tools library will be automatically available globally. Read the macro_tools library documentation.

Back to the crate overview.

Readme

Module :: `proc_macro_tools`

A comprehensive toolkit for writing robust and maintainable procedural macros in Rust.

Why macro_tools?

Writing procedural macros can be challenging due to:

Complex token stream manipulation - Manually handling token streams is error-prone and verbose
Boilerplate-heavy code - Common patterns require significant repetitive code
Poor error handling - Difficult to generate helpful error messages for macro users
Limited type introspection - Extracting type information from parsed syntax trees is complex

macro_tools solves these problems by providing:

🛠️ High-level utilities for token stream manipulation
🔍 Advanced parsers for attributes, generics, and types
🎯 Precise error reporting with span-aware messages
📦 Zero-dependency core - Only depends on syn, quote, and proc-macro2
🚀 Proven in production - Battle-tested in real-world macro systems

Quick Start

Add macro_tools to your Cargo.toml:

[dependencies]
macro_tools = "0.24.0"

Example: Extract Type Parameters

use macro_tools::{ typ, qt };

// Parse a type and extract its parameters
let code = qt!( Option< i32 > );
let tree_type = syn::parse2::< syn::Type >( code ).unwrap();

// Extract type parameters
let params = typ::type_parameters( &tree_type, 0..=0 );
params.iter().for_each( |param| println!( "{}", qt!( #param ) ) );
// Output: i32

Try out cargo run --example macro_tools_extract_type_parameters.
See code.

Example: Parse Attributes with Properties

This example shows the structure of attribute parsing. For a complete working example with all trait implementations, see the full example file.

use macro_tools::exposed::*;

// Define a custom attribute with properties
#[ derive( Debug ) ]
pub struct CustomAttribute
{
  pub enabled : AttributePropertyBoolean,
  pub name : AttributePropertyOptionalSyn< syn::LitStr >,
}

// After implementing required traits (AttributeComponent, Parse, etc.)
// you can parse attributes like this:
// let attr : syn::Attribute = syn::parse_quote!( #[ custom( enabled = true, name = "example" ) ] );
// let parsed = CustomAttribute::from_meta( &attr )?;
// assert!( parsed.enabled.value() );

Try out cargo run --example macro_tools_parse_attributes.
See code.

Features

🎯 Type Analysis Tools

Extract and analyze type information:

typ - Type parsing and parameter extraction utilities
Extract nested generic parameters
Parse complex type expressions
Handle path types, arrays, tuples, and more

🔧 Generic Parameter Utilities

Advanced generic parameter manipulation:

generic_params - Tools for working with syn::Generics
- Decompose generics for different contexts
- Merge generic parameters from multiple sources
- Filter and transform generic parameters
- Generate appropriate tokens for impl blocks

📝 Attribute Parsing Framework

Powerful attribute parsing with derive-macro-like experience:

attr - Attribute parsing utilities
- Parse structured attributes with properties
- Support for optional, boolean, and custom property types
- Generate helpful error messages
- Composable attribute parsing with the Assign trait

🔍 Syntax Tree Helpers

Work with Rust syntax trees effectively:

struct_like - Parse and manipulate struct-like items
item_struct - Struct-specific utilities
quantifier - Extract quantifiers from type expressions
name - Name and path manipulation
punctuated - Work with punctuated sequences

🛠️ Token Stream Utilities

Core utilities for procedural macros:

tokens - Token stream manipulation
equation - Parse and generate equations
diag - Enhanced diagnostics with custom error formatting

Advanced Example: Generic Function Implementation

The purpose of typ::type_parameters is to extract type parameters from a given Rust type. In this example, we generate a type core::option::Option<i8, i16, i32, i64> and extract its type parameters.

#[ cfg( not( all( feature = "enabled", feature = "typ" ) ) ) ]
fn main(){}
#[ cfg( all( feature = "enabled", feature = "typ" ) ) ]
fn main()
{
  // Import necessary macros and modules from the `macro_tools` crate.
  use macro_tools::{ typ, qt };

  // Generate a token stream representing the type `core::option::Option<i8, i16, i32, i64>`.
  let code = qt!( core::option::Option< i8, i16, i32, i64 > );

  // Parse the generated token stream into a `syn::Type` object.
  // `syn::Type` is a syntax tree node representing a Rust type.
  let tree_type = syn::parse2::< syn::Type >( code ).unwrap();

  // Extract type parameters from the parsed type.
  // `typ::type_parameters` takes a reference to a `syn::Type` and a range.
  // It returns a vector of type parameters within the specified range.
  // Here, `0..=2` specifies that we are interested in the first three type parameters.
  let got = typ::type_parameters( &tree_type, 0..=2 );

  // Iterate over the extracted type parameters and print each one.
  // The `qt!` macro is used to convert the type parameter back to a token stream for printing.
  got.iter().for_each( | e | println!( "{}", qt!( #e ) ) );

  /* Expected output:
     i8
     i16
     i32
  */
}

Try out cargo run --example macro_tools_trivial.
See code.

Example: Attribute Properties

This example demonstrates an approach to parsing attributes and their properties. The attributes are collected into a struct that aggregates them, and attribute properties are parsed using reusable components from a library. The example shows how to use AttributePropertyBoolean for parsing boolean properties and the roles of the traits AttributePropertyComponent and AttributeComponent. The Assign trait is also used to simplify the logic of assigning fields.

Attributes are collected into a ItemAttributes struct, and attribute properties are parsed using reusable components like AttributePropertyBoolean.

AttributeComponent: A trait that defines how an attribute should be parsed from a syn::Attribute.
AttributePropertyComponent: A trait that defines a marker for attribute properties.
Assign: A trait that simplifies the logic of assigning fields to a struct. Using a component-based approach requires each field to have a unique type, which aligns with the strengths of strongly-typed languages. This method ensures that the logic of assigning values to fields is encapsulated within the fields themselves, promoting modularity and reusability.

The reusable property components from the library come with parameters that distinguish different properties of the same type. This is useful when an attribute has multiple boolean properties, for instance. Such an approach helps to avoid limitations where it is always possible to define traits for custom types, while it may not be possible for types defined in other crates.


#[ cfg( not( all( feature = "enabled", feature = "attr_prop", debug_assertions ) )  ) ]
fn main(){}
#[ cfg( all( feature = "enabled", feature = "attr_prop", debug_assertions )  ) ]
fn main()
{

  use macro_tools::
  {
    attr,
    ct,
    syn_err,
    return_syn_err,
    qt,
    Result,
    AttributeComponent,
    AttributePropertyComponent,
    AttributePropertyBoolean,
    AttributePropertySingletone,
    Assign,
  };

  /// Represents the attributes of a struct. Aggregates all its attributes.
  #[ derive( Debug, Default ) ]
  pub struct ItemAttributes
  {
    /// Attribute for customizing the mutation process.
    pub mutator : AttributeMutator,
  }

  impl ItemAttributes
  {
    /// Constructs a `ItemAttributes` instance from an iterator of attributes.
    ///
    /// This function parses the provided attributes and assigns them to the
    /// appropriate fields in the `ItemAttributes` struct.
    pub fn from_attrs< 'a >( attrs : impl Iterator< Item = & 'a syn::Attribute > ) -> Result< Self >
    {
      let mut result = Self::default();

      // Closure to generate an error message for unknown attributes.
      let error = | attr : & syn::Attribute | -> syn::Error
      {
        let known_attributes = ct::str::format!
        (
          "Known attributes are: {}, {}.",
          "debug",
          AttributeMutator::KEYWORD,
        );
        syn_err!
        (
          attr,
          "Expects an attribute of format '#[ attribute( key1 = val1, key2 = val2 ) ]'\n  {known_attributes}\n  But got: '{}'",
          qt! { #attr }
        )
      };

      for attr in attrs
      {
        let key_ident = attr.path().get_ident().ok_or_else( || error( attr ) )?;
        let key_str = format!( "{}", key_ident );
        match key_str.as_ref()
        {
          AttributeMutator::KEYWORD => result.assign( AttributeMutator::from_meta( attr )? ),
          "debug" => {},
          _ => {},
        }
      }

      Ok( result )
    }
  }

  /// Represents attributes for customizing the mutation process in a forming operation.
  ///
  /// ## Example of code
  ///
  /// ```ignore
  /// #[ mutator( custom = true, debug = true ) ]
  /// ```
  #[ derive( Debug, Default ) ]
  pub struct AttributeMutator
  {
    /// Indicates whether a custom mutator should be generated.
    /// Defaults to `false`, meaning no custom mutator is generated unless explicitly requested.
    pub custom : AttributePropertyCustom,
    /// Specifies whether to print code generated for the field.
    /// Defaults to `false`, which means no hint is provided unless explicitly requested.
    pub debug : AttributePropertyDebug,
  }

  impl AttributeComponent for AttributeMutator
  {
    const KEYWORD : & 'static str = "mutator";

    /// Parses a `syn::Attribute` into an `AttributeMutator`.
    fn from_meta( attr : & syn::Attribute ) -> Result< Self >
    {
      match attr.meta
      {
        syn::Meta::List( ref meta_list ) =>
        {
          return syn::parse2::< AttributeMutator >( meta_list.tokens.clone() );
        },
        syn::Meta::Path( ref _path ) =>
        {
          return Ok( Default::default() )
        },
        _ => return_syn_err!
        (
          attr,
          "Expects an attribute of format `#[ mutator( custom = true ) ]`. \nGot: {}",
          qt! { #attr }
        ),
      }
    }
  }

  // Implement `Assign` trait to allow assigning `AttributeMutator` to `ItemAttributes`.
  impl< IntoT > Assign< AttributeMutator, IntoT > for ItemAttributes
  where
    IntoT : Into< AttributeMutator >,
  {
    #[ inline( always ) ]
    fn assign( & mut self, component : IntoT )
    {
      self.mutator = component.into();
    }
  }

  // Implement `Assign` trait to allow assigning `AttributePropertyDebug` to `AttributeMutator`.
  impl< IntoT > Assign< AttributePropertyDebug, IntoT > for AttributeMutator
  where
    IntoT : Into< AttributePropertyDebug >,
  {
    #[ inline( always ) ]
    fn assign( & mut self, component : IntoT )
    {
      self.debug = component.into();
    }
  }

  // Implement `Assign` trait to allow assigning `AttributePropertyCustom` to `AttributeMutator`.
  impl< IntoT > Assign< AttributePropertyCustom, IntoT > for AttributeMutator
  where
    IntoT : Into< AttributePropertyCustom >,
  {
    #[ inline( always ) ]
    fn assign( & mut self, component : IntoT )
    {
      self.custom = component.into();
    }
  }

  impl syn::parse::Parse for AttributeMutator
  {
    fn parse( input : syn::parse::ParseStream< '_ > ) -> syn::Result< Self >
    {
      let mut result = Self::default();

      let error = | ident : & syn::Ident | -> syn::Error
      {
        let known = ct::str::format!
        (
          "Known entries of attribute {} are: {}, {}.",
          AttributeMutator::KEYWORD,
          AttributePropertyCustom::KEYWORD,
          AttributePropertyDebug::KEYWORD,
        );
        syn_err!
        (
          ident,
          r#"Expects an attribute of format '#[ mutator( custom = false ) ]'
    {known}
    But got: '{}'
  "#,
          qt! { #ident }
        )
      };

      while !input.is_empty()
      {
        let lookahead = input.lookahead1();
        if lookahead.peek( syn::Ident )
        {
          let ident : syn::Ident = input.parse()?;

          match ident.to_string().as_str()
          {
            AttributePropertyCustom::KEYWORD => result.assign( AttributePropertyCustom::parse( input )? ),
            AttributePropertyDebug::KEYWORD => result.assign( AttributePropertyDebug::from( true ) ),
            _ => return Err( error( & ident ) ),
          }
        }
        else
        {
          return Err( lookahead.error() );
        }

        // Optional comma handling
        if input.peek( syn::Token![,] )
        {
          input.parse::< syn::Token![,] >()?;
        }
      }

      Ok( result )
    }
  }

  // == Attribute properties

  /// Marker type for attribute property to specify whether to provide a sketch as a hint.
  /// Defaults to `false`, which means no hint is provided unless explicitly requested.
  #[ derive( Debug, Default, Clone, Copy ) ]
  pub struct AttributePropertyDebugMarker;

  impl AttributePropertyComponent for AttributePropertyDebugMarker
  {
    const KEYWORD : & 'static str = "debug";
  }

  /// Specifies whether to provide a sketch as a hint.
  /// Defaults to `false`, which means no hint is provided unless explicitly requested.
  pub type AttributePropertyDebug = AttributePropertySingletone< AttributePropertyDebugMarker >;

  // ==

  /// Marker type for attribute property to indicate whether a custom code should be generated.
  /// Defaults to `false`, meaning no custom code is generated unless explicitly requested.
  #[ derive( Debug, Default, Clone, Copy ) ]
  pub struct AttributePropertyCustomMarker;

  impl AttributePropertyComponent for AttributePropertyCustomMarker
  {
    const KEYWORD : & 'static str = "custom";
  }

  /// Indicates whether a custom code should be generated.
  /// Defaults to `false`, meaning no custom code is generated unless explicitly requested.
  pub type AttributePropertyCustom = AttributePropertyBoolean< AttributePropertyCustomMarker >;

  // == test code

  // Parse an attribute and construct a `ItemAttributes` instance.
  let input : syn::Attribute = syn::parse_quote!( #[ mutator( custom = true ) ] );
  let attrs : ItemAttributes = ItemAttributes::from_attrs( std::iter::once( & input ) ).unwrap();
  println!( "{:?}", attrs );

  // Test `AttributePropertyBoolean` functionality.
  let attr : AttributePropertyBoolean< AttributePropertyDebugMarker > = AttributePropertyBoolean::default();
  assert_eq!( attr.internal(), false );
  let attr : AttributePropertyBoolean< AttributePropertyDebugMarker > = true.into();
  assert_eq!( attr.internal(), true );
  let attr : AttributePropertyBoolean< AttributePropertyDebugMarker > = false.into();
  assert_eq!( attr.internal(), false );

}

Try out cargo run --example macro_tools_attr_prop.
See code.

Real-World Use Cases

macro_tools is ideal for:

Derive Macros - Building derive macros with proper error handling and type analysis
Attribute Macros - Parsing complex attributes with multiple properties
Code Generation - Generating boilerplate code based on type structure
DSL Implementation - Creating domain-specific languages with procedural macros

Documentation

For detailed documentation, visit:

Contributing

We welcome contributions! Please see our Contributing Guide.

License

Licensed under the MIT License. See LICENSE for details.

Repository

GitHub Repository

To add to your project

cargo add proc_macro_tools

Try out from the repository

git clone https://github.com/Wandalen/wTools
cd wTools
cd examples/macro_tools_trivial
cargo run

Adding macro_tools library as a dependency

Adding `macro_tools` library as a dependency