# Technical Specification: The `former` Derive Macro
### 1. Introduction & Core Concepts
* **1.1. Problem Solved:** The `former` derive macro simplifies the implementation of the Builder pattern in Rust. It automates the generation of fluent, readable, and maintainable APIs for object initialization, reducing boilerplate code for complex `struct` and `enum` types.
* **1.2. Guiding Principles:**
* **Clarity over Brevity:** The generated code and public APIs should be easy to understand and predictable.
* **Composition over Configuration:** Favor nested builders (subformers) for complex data structures to maintain a clear, hierarchical construction flow.
* **Convention over Configuration:** Provide sensible defaults for common patterns (e.g., handling of `Option<T>`, default collection formers) while allowing explicit overrides for customization.
* **Dependencies: Prefer `macro_tools`:** The macro's internal implementation **must** prefer the abstractions provided by the `macro_tools` crate over direct usage of `syn`, `quote`, and `proc-macro2`.
* **1.3. Key Terminology (Ubiquitous Language):**
* **Former:** The builder struct generated by the `#[derive(Former)]` macro (e.g., `MyStructFormer`).
* **Storage:** An internal, temporary struct (`...FormerStorage`) that holds the intermediate state of the object being built.
* **Definition:** A configuration struct (`...FormerDefinition`) that defines the types and `End` condition for a forming process.
* **Subformer:** A `Former` instance used to build a part of a larger object.
* **Target Type Categories:** The fundamental classification of Rust types the macro operates on (Structs vs Enums).
* **Variant Structure Types:** The three categories of enum variant syntax (Unit, Tuple, Named) that determine parsing and generation rules.
* **Behavioral Categories:** The five fundamental groupings that classify all possible Former macro usage patterns based on syntax structure and complexity. These categories drive macro implementation architecture, code generation strategies, and systematic validation (including test organization).
### 2. Core Behavioral Specification
This section defines the core user-facing contract of the `former` macro. The following logic tables and attribute definitions are the single source of truth for its behavior.
#### 2.1. Target Type Classification
The `former` macro operates on two fundamental **Target Type Categories**, each with distinct behavioral rules and test coverage families:
##### 2.1.1. Structural Type Categories
* **Structs** - Regular Rust structs with named fields (`struct MyStruct { field: T }`)
* **Enums** - Rust enums with variants, subdivided by **Variant Structure Types**:
##### 2.1.2. Enum Variant Structure Types
The macro classifies enum variants into three **Variant Structure Types** based on their field syntax:
* **Unit Variants** - No associated data (`Variant`)
* **Tuple Variants** - Positional fields (`Variant(T1, T2)` or `Variant()`)
* **Named Variants** - Named fields (`Variant { field: T }` or `Variant {}`)
Each Variant Structure Type has distinct parsing rules, generated code patterns, and behavioral specifications as defined in the rule tables below.
##### 2.1.3. Behavioral Categories
The macro architecture is organized around five fundamental **Behavioral Categories** that classify all Former usage patterns by syntax structure and complexity:
* **Struct Formers** - Regular Rust structs with named fields (foundational builder patterns)
* **Unit Variant Formers** - Enum variants with no associated data (simple enum cases)
* **Tuple Variant Formers** - Enum variants with positional fields (tuple-like syntax)
* **Named Variant Formers** - Enum variants with named fields (struct-like syntax)
* **Complex Scenario Formers** - Advanced combinations and cross-cutting patterns
Each Behavioral Category has distinct:
- **Implementation patterns** (parsing logic, code generation strategies)
- **API characteristics** (constructor types, setter methods, subformer behavior)
- **Rule coverage** (applicable specification rules and attribute combinations)
- **Validation approach** (systematic testing through corresponding test families)
##### 2.1.4. Implementation and Testing Organization
Each **Behavioral Category** corresponds to distinct implementation modules and systematic test validation:
| Struct Formers | Structs | N/A | All struct rules | Core builder patterns | `struct_tests` |
| Unit Variant Formers | Enums | Unit Variants | Rules 1a, 2a, 3a | Simple constructors | `enum_unit_tests` |
| Tuple Variant Formers | Enums | Tuple Variants | Rules 1b, 1d, 1f, 2b, 2d, 2f, 3b, 3d, 3f | Positional setters | `enum_unnamed_tests` |
| Named Variant Formers | Enums | Named Variants | Rules 1c, 1e, 1g, 2c, 2e, 2g, 3c, 3g | Named field setters | `enum_named_tests` |
| Complex Scenario Formers | Enums | Mixed/Advanced | Cross-cutting rules | Edge case handling | `enum_complex_tests` |
This **Behavioral Category** system provides:
- **Architectural guidance** for macro implementation organization
- **API design consistency** across similar usage patterns
- **Specification completeness** through systematic rule coverage
- **Quality assurance** via comprehensive test validation families
#### 2.2. Enum Variant Constructor Logic
The macro generates a static constructor method on the enum for each variant. The type of constructor is determined by the variant's **Variant Structure Type** and attributes according to the following rules:
| **1a** | Unit: `V` | `#[scalar]` or Default | Direct constructor: `Enum::v() -> Enum` |
| **1b** | Tuple: `V()` | `#[scalar]` or Default | Direct constructor: `Enum::v() -> Enum` |
| **1c** | Struct: `V {}` | `#[scalar]` | Direct constructor: `Enum::v() -> Enum` |
| **1d** | Tuple: `V(T1)` | `#[scalar]` | Scalar constructor: `Enum::v(T1) -> Enum` |
| **1e** | Struct: `V {f1:T1}` | `#[scalar]` | Scalar constructor: `Enum::v{f1:T1} -> Enum` |
| **1f** | Tuple: `V(T1, T2)` | `#[scalar]` | Scalar constructor: `Enum::v(T1, T2) -> Enum` |
| **1g** | Struct: `V {f1:T1, f2:T2}` | `#[scalar]` | Scalar constructor: `Enum::v{f1:T1, f2:T2} -> Enum` |
| **2a** | Unit: `V` | `#[subform_scalar]` | **Compile Error** |
| **2b** | Tuple: `V()` | `#[subform_scalar]` | **Compile Error** |
| **2c** | Struct: `V {}` | `#[subform_scalar]` | **Compile Error** |
| **2d** | Tuple: `V(T1)` | `#[subform_scalar]` or Default | Subformer for inner type: `Enum::v() -> T1::Former` |
| **2e** | Struct: `V {f1:T1}` | `#[subform_scalar]` or Default | Implicit variant former: `Enum::v() -> VFormer` |
| **2f** | Tuple: `V(T1, T2)` | `#[subform_scalar]` | **Compile Error** |
| **2g** | Struct: `V {f1:T1, f2:T2}` | `#[subform_scalar]` or Default | Implicit variant former: `Enum::v() -> VFormer` |
| **3c** | Struct: `V {}` | Default | **Compile Error** (Requires `#[scalar]`) |
| **3f** | Tuple: `V(T1, T2)` | Default | **Implicit variant former: `Enum::v() -> VFormer`** |
**Note on Rule 3f:** This rule is updated to reflect the implemented and tested behavior. The previous specification incorrectly stated this case would generate a scalar constructor. The actual behavior is to generate a subformer for the variant itself.
**Implementation Status Note:** Single-field tuple variants (Rule 2d) have a known issue where the handler attempts to use EntityToFormer trait integration, which fails for primitive types (u32, String, etc.) that don't implement Former. Current workaround is to use explicit `#[scalar]` attribute for primitive types.
**Enum Former Delegation Limitation:** Current enum Former implementation generates positional setters (e.g., `._0()`, `._1()`) for tuple fields rather than delegating to inner struct Former methods. This means:
- Test expecting `.field_name()` methods on enum variant formers will fail
- Complex enum-to-struct Former delegation is not fully implemented
- Workaround: Use positional setters or mark variants as `#[scalar]` for direct construction
#### 2.3. Standalone Constructor Behavior
When the `#[standalone_constructors]` attribute is applied to an item, the return type of the generated top-level function(s) is determined by the usage of `#[former_ignore]` on its fields:
* **Rule SC-1 (Full Construction):** If **no** fields of a struct or enum variant are marked with `#[former_ignore]`, the generated standalone constructor will take all fields as arguments and return the final, constructed instance (`Self`).
* **Rule SC-2 (Partial Construction):** If **any** fields of a struct or enum variant are marked with `#[former_ignore]`, the generated standalone constructor will take only the non-ignored fields as arguments and return an instance of the `Former` (`...Former`), pre-initialized with those arguments.
**⚠️ Breaking Change Notice**: This specification represents the current behavior. Previous versions may have implemented different patterns where standalone constructors always returned `Former` instances. Manual implementations following the old pattern need to be updated to match the new specification for consistency.
#### 2.4. Attribute Reference
The following attributes control the behavior defined in the logic tables above.
##### 2.4.1. Item-Level Attributes
| `#[storage_fields(..)]` | Defines extra fields exclusive to the `...FormerStorage` struct for intermediate calculations. |
| `#[mutator(custom)]` | Disables default `FormerMutator` implementation, requiring a manual `impl` block. |
| `#[perform(fn...)]` | Specifies a method on the original struct to be called by `.perform()` after forming. |
| `#[standalone_constructors]` | Generates top-level constructor functions. |
| `#[debug]` | Prints the macro's generated code to the console at compile time. |
##### 2.4.2. Field-Level / Variant-Level Attributes
| `#[former(default = ...)]` | Provides a default value for a field if its setter is not called. |
| `#[scalar]` | Forces the generation of a simple scalar setter (e.g., `.field(value)`). |
| `#[subform_scalar]` | Generates a method returning a subformer for a nested struct. The field's type must also derive `Former`. |
| `#[subform_collection]` | Generates a method returning a specialized collection subformer (e.g., `VectorFormer`). |
| `#[subform_entry]` | Generates a method returning a subformer for a single entry of a collection. |
| `#[former_ignore]` | Excludes a field from being a parameter in `#[standalone_constructors]` functions. The field will use its default value or remain unset. |
##### 2.4.3. Attribute Precedence and Interaction Rules
1. **Subform vs. Scalar:** Subform attributes (`#[subform_scalar]`, `#[subform_collection]`, `#[subform_entry]`) take precedence over `#[scalar]`. If both are present, the subform behavior is implemented, and a scalar setter is **not** generated unless explicitly requested via `#[scalar(setter = true)]`.
2. **Setter Naming:** If a `name` is provided (e.g., `#[scalar(name = new_name)]`), it overrides the default setter name derived from the field's identifier.
3. **Setter Disabling:** `setter = false` on any attribute (`scalar`, `subform_*`) will prevent the generation of that specific user-facing setter method. Internal helper methods (e.g., `_field_subform_entry()`) are still generated to allow for manual implementation of custom setters.
4. **`#[former(default = ...)]`:** This attribute is independent and can be combined with any setter type. It provides a fallback value if a field's setter is never called.
### 3. Generated Code Architecture
The `#[derive(Former)]` macro generates a consistent set of components to implement the behavior defined in Section 2.
* **`TFormer` (The Former)**
* **Purpose:** The public-facing builder.
* **Key Components:** A `storage` field, an `on_end` field, setter methods, and a `.form()` method.
* **`TFormerStorage` (The Storage)**
* **Purpose:** Internal state container.
* **Key Components:** A public, `Option`-wrapped field for each field in `T` and any `#[storage_fields]`.
* **`TFormerDefinition` & `TFormerDefinitionTypes` (The Definition)**
* **Purpose:** To make the forming process generic and customizable.
* **Key Associated Types:** `Storage`, `Context`, `Formed`, `End`.
### 4. Diagnostics & Debugging
* **Error Handling Strategy:** The macro must produce clear, concise, and actionable compile-time errors. Errors must be associated with the specific `span` of the code that caused the issue. The `trybuild` crate must be used to create a suite of compile-fail tests to verify error-handling behavior.
* **Debug Attribute Requirements:** Following the design principle "Proc Macros: Must Implement a 'debug' Attribute", the `#[debug]` item-level attribute must be provided with comprehensive debugging capabilities.
#### 4.1. Debug Attribute Specification
**Attribute Usage:**
```rust
// Standalone debug attribute
#[derive(Former)]
#[debug] // <-- Enables comprehensive debug output
pub struct MyStruct { field: String }
// Within #[former(...)] container
#[derive(Former)]
#[former(debug, standalone_constructors)] // <-- Debug with other attributes
pub struct MyStruct { field: String }
```
**Debug Output Requirements:**
When `#[debug]` is present and the `former_diagnostics_print_generated` feature is enabled, the macro must provide detailed information in four phases:
1. **Input Analysis Phase**:
- Target type information (name, kind, visibility)
- Generic parameters analysis (lifetimes, types, consts, where clauses)
- Field/variant analysis with types and attributes
- Complete attribute configuration breakdown
2. **Generic Classification Phase**:
- Classification results (lifetime-only, type-only, mixed, empty)
- Generated generic components (impl_generics, ty_generics, where_clause)
- Strategy explanation for code generation decisions
3. **Generated Components Analysis Phase**:
- Core component breakdown (FormerStorage, FormerDefinition, Former, etc.)
- Trait implementation overview
- Formation process workflow explanation
- Attribute-driven customizations impact
4. **Complete Generated Code Phase**:
- Final TokenStream output for compilation
- Integration points with existing code
**Feature Flag Integration:**
Debug output must be gated behind the `former_diagnostics_print_generated` feature flag to ensure zero impact on normal compilation.
**Development Workflow Integration:**
- Zero runtime cost (analysis only during compilation)
- Conditional compilation (debug code only with feature flag)
- IDE-friendly output format
- CI/CD pipeline compatibility
### 5. Lifecycle & Evolution
* **Versioning Strategy:** The `former` crate must adhere to Semantic Versioning 2.0.0.
* **Deprecation Strategy:** Features or attributes planned for removal must first be marked as deprecated via `#[deprecated]` for at least one minor release cycle before being removed in a subsequent major version.
### 6. Meta-Requirements
* **Ubiquitous Language:** All terms defined in the `Key Terminology` section must be used consistently.
* **Naming Conventions:** All generated asset names must use `snake_case`. Generated functions must follow a `noun_verb` pattern.
* **Single Source of Truth:** The Git repository is the single source of truth for all project artifacts.
### 7. Deliverables
* `specification.md`: This document.
* `spec_addendum.md`: A companion document for implementation-specific details.
### 8. Conformance Check Procedure
1. **Run Full Test Suite:** Execute `cargo test --workspace`.
2. **Check Linter:** Execute `cargo clippy --workspace --all-targets -- -D warnings`.
3. **Review Attribute Coverage:** Manually verify that every rule in the logic tables has a corresponding passing test.
4. **Review Documentation:** Manually verify that the `Readme.md` and `advanced.md` documents are consistent with this specification.
***
# Specification Addendum
### Purpose
This document is a companion to the main `specification.md`. It is intended to be completed by the **Developer** during the implementation of the `former` macro. While the main specification defines the "what" and "why" of the macro's public contract, this addendum captures the "how" of the final implementation.
### Instructions for the Developer
As you implement or modify the `former_meta` crate, please fill out the sections below with the relevant details. This creates a crucial record for future maintenance, debugging, and onboarding.
---
### Internal Module Overview
*A high-level description of the key modules within the `former_meta` crate and their responsibilities.*
| `derive_former` | Top-level entry point for the `#[derive(Former)]` macro. Dispatches to struct or enum handlers. |
| `derive_former::former_struct` | Contains the primary logic for generating all code components for `struct`s. |
| `derive_former::former_enum` | Contains the primary dispatch logic for `enum`s, routing to specific variant handlers based on the rules in the specification. |
| `derive_former::former_enum::*` | Individual handler modules for each combination of enum variant type and attribute (e.g., `unit_variant_handler`, `tuple_single_field_scalar`). |
| `derive_former::field_attrs` | Defines and parses all field-level and variant-level attributes (e.g., `#[scalar]`). |
| `derive_former::struct_attrs` | Defines and parses all item-level attributes (e.g., `#[storage_fields]`). |
### Key Internal Data Structures
*List the primary internal-only structs or enums used during the macro expansion process and their purpose.*
| `ItemAttributes` | `former_meta` | Holds the parsed attributes from the top-level `struct` or `enum`. |
| `FieldAttributes` | `former_meta` | Holds the parsed attributes for a single `struct` field or `enum` variant. |
| `FormerField` | `former_meta` | A unified representation of a field, combining its `syn::Field` data with parsed `FieldAttributes`. |
| `EnumVariantHandlerContext` | `former_meta` | A context object passed to enum variant handlers, containing all necessary information for code generation (AST nodes, attributes, generics, etc.). |
### Testing Strategy
*A description of the testing methodology for the macro.*
- **UI / Snapshot Testing (`trybuild`):** The `trybuild` crate is used to create a comprehensive suite of compile-fail tests. This ensures that invalid attribute combinations and incorrect usage patterns result in the expected compile-time errors, as defined in the specification.
- **Manual vs. Derive Comparison:** This is the primary strategy for verifying correctness. For each feature, a three-file pattern is used:
1. `_manual.rs`: A file containing a hand-written, correct implementation of the code that the macro *should* generate.
2. `_derive.rs`: A file that uses `#[derive(Former)]` on an identical data structure.
3. `_only_test.rs`: A file containing only `#[test]` functions that is `include!`d by both the `_manual.rs` and `_derive.rs` files. This guarantees that the exact same assertions are run against both the hand-written and macro-generated implementations, ensuring their behavior is identical.
### Finalized Library & Tool Versions
*List the critical libraries, frameworks, or tools used and their exact locked versions from `Cargo.lock`.*
- `rustc`: `1.78.0`
- `macro_tools`: `0.15.0`
- `convert_case`: `0.6.0`
---
### Enum Implementation Status and Critical Issues
#### Current Implementation Status
- **Total Tests Passing**: 227 tests (includes 12 enum tests across unit and tuple variants)
- **Handler Status**: Most handlers working, with one critical fix applied to `tuple_multi_fields_subform`
- **Feature Coverage**: Unit variants, basic tuple variants, multi-field scalar patterns all functional
#### Critical Handler Issues Resolved
**1. tuple_multi_fields_subform Handler - Major Syntax Errors (FIXED)**
- **Issue**: Critical compilation failures preventing multi-field tuple subform usage
- **Root Causes**: Invalid Rust syntax in generated code (`#end_name::#ty_generics::default()`), missing PhantomData angle brackets
- **Solution**: Fixed turbo fish syntax and PhantomData generic handling with conditional support for non-generic enums
- **Impact**: Enabled all multi-field tuple subform functionality, adding 3+ new passing tests
#### Known Limitations and Workarounds
**1. Single-Field Tuple Subform Handler (tuple_single_field_subform)**
- **Issue**: Handler assumes field types implement Former trait via EntityToFormer, fails for primitive types
- **Root Cause**: Generates code like `< u32 as EntityToFormer< u32FormerDefinition > >::Former` for primitives
- **Workaround**: Use explicit `#[scalar]` attribute for primitive field types
- **Status**: Needs architectural redesign or auto-routing to scalar handlers
**2. Unimplemented Features**
- **`#[arg_for_constructor]` Attribute**: Not yet implemented, prevents direct parameter standalone constructors
- **Raw Identifiers**: Variants like `r#break` have method name generation issues
#### Handler Reliability Spectrum
1. **Fully Reliable**: `tuple_zero_fields_handler`, `tuple_*_scalar` handlers
2. **Fixed and Reliable**: `tuple_multi_fields_subform` (after syntax fixes)
3. **Complex but Workable**: Struct variant handlers
4. **Problematic**: `tuple_single_field_subform` (requires explicit `#[scalar]` for primitives)
5. **Unimplemented**: Attribute-driven standalone constructors with direct parameters
#### Testing and Development Insights
- **Effective Strategy**: Enable one test at a time, derive-first approach more reliable than manual implementations
- **Common Issues**: Inner doc comments in shared test files cause E0753 compilation errors
- **Performance**: Scalar handlers compile fast, subform handlers generate substantial code and compile slower
This knowledge preserves critical implementation insights and provides guidance for future enum development work.